Stabilize runtime codec switching

Author: DjDeveloperr

LICENSE

@@ -1,13 +1,19 @@
-Copyright 2026 Dj
+Copyright OpenJS Foundation and other contributors, https://openjsf.org
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-    http://www.apache.org/licenses/LICENSE-2.0
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1,7 +1,23 @@
-# SimDeck
+<p align="center">
+  <img width="180" src="./client/public/simdeck.png">
 
-SimDeck is a developer tool built for streamlining mobile app development for coding agents.
-Drive iOS Simulator apps from the CLI, browser, and automated tests on macOS.
+  <h1 align="center">SimDeck</h1>
+
+  <p align="center">
+    SimDeck is a developer tool built for streamlining mobile app development for coding agents.
+    Drive Simulator from the CLI using agents, browser, and automated tests on macOS.
+  </p>
+</p>
+
+<hr/>
+
+## Try it out
+
+```sh
+npx simdeck
+```
+
+Install the CLI globally for agentic-use:
 
 ```sh
 npm i -g simdeck@latest
@@ -11,25 +27,24 @@ After installing the CLI, install the Codex skill so agents know the stable
 SimDeck workflow:
 
 ```sh
-npx skills add NativeScript/SimDeck --skill simdeck -a codex -g
+npx skills add NativeScript/SimDeck --skill simdeck -g
 ```
 
-For VS Code, install the `nativescript.simdeck` extension to open the simulator
+For VS Code, install the `nativescript.simdeck-vscode` extension to open the simulator
 view inside the editor.
 
 ## Features
 
-- WebTransport streaming server in Rust, plus experimental WebRTC media previews, using HEVC or H.264 video
-- Simulator control & inspection using private accessibility APIs
+- Local simulator video stream over WebTransport or WebRTC, hardware-encoded in full resolution
+- Full simulator control & inspection using private accessibility APIs
 - CoreSimulator chrome asset rendering for device bezels
-- NativeScript and React Native runtime inspector plugins, plus a native UIKit inspector framework for other apps
-- Project daemon reuse: normal CLI commands automatically start and reuse one warm native host per project.
-- Optional macOS LaunchAgent service for an always-on local SimDeck daemon.
+- NativeScript, React Native, UIKit and SwiftUI runtime inspector plugins to view app's view hierarchy live
 - `simdeck/test` for fast JS/TS app tests that can query accessibility state and drive simulator controls.
+- SimDeck Studio for automatic PR deployments to on-demand simulators
 
 ## Documentation
 
-Full documentation lives at [simdeck.nativescript.org](https://simdeck.nativescript.org/), with guides, the CLI reference, the REST API, the WebTransport video pipeline, and the inspector protocols.
+Full documentation lives at [simdeck.nativescript.org](https://simdeck.nativescript.org/), with guides, the CLI reference, the REST API, the video pipeline, and the inspector protocols.
 
 ## Quick start
 
@@ -66,32 +81,7 @@ simdeck daemon status
 simdeck daemon stop
 ```
 
-`simdeck daemon` manages the normal per-project warm process. For an always-on
-daemon that is available after login, use the macOS user service commands:
-
-```sh
-simdeck service on
-simdeck service off
-```
-
-This uses a LaunchAgent, keeps the server bound to localhost by default, and is
-best for agents or editor integrations that should be able to open SimDeck
-without first starting a project daemon.
-
-Use software H.264 when macOS screen recording starves the hardware encoder:
-
-```sh
-simdeck daemon start --video-codec h264-software
-```
-
-The browser reads `/api/health` and automatically selects the WebRTC media
-transport for software H.264.
-
-For LAN browser access:
-
-```sh
-simdeck ui --bind 0.0.0.0 --advertise-host 192.168.1.50 --open
-```
+`simdeck daemon` manages the normal per-project warm process.
 
 Restart the CoreSimulator service layer when `simctl` reports a stale service
 version or the live display gets stuck before the first frame:
@@ -156,59 +146,6 @@ lower-token hierarchy dumps. Coordinate commands accept screen coordinates from
 the accessibility tree by default; pass `--normalized` to send `0.0..1.0`
 coordinates directly.
 
-## Daemon
-
-Manage the project daemon explicitly when needed:
-
-```sh
-simdeck daemon start
-simdeck daemon status
-simdeck daemon stop
-```
-
-`simdeck daemon` manages the normal per-project warm process. For an always-on
-daemon that is available after login, use the macOS user service commands:
-
-```sh
-simdeck service on
-simdeck service off
-```
-
-This uses a LaunchAgent, keeps the server bound to localhost by default, and is
-best for agents or editor integrations that should be able to open SimDeck
-without first starting a project daemon.
-
-Use software H.264 when macOS screen recording starves the hardware encoder:
-
-```sh
-simdeck daemon start --video-codec h264-software
-```
-
-For LAN browser access:
-
-```sh
-simdeck ui --bind 0.0.0.0 --advertise-host 192.168.1.50 --open
-```
-
-Restart the CoreSimulator service layer when `simctl` reports a stale service
-version or the live display gets stuck before the first frame:
-
-```sh
-simdeck core-simulator restart
-```
-
-You can also start or stop the CoreSimulator service layer explicitly:
-
-```sh
-simdeck core-simulator start
-simdeck core-simulator shutdown
-```
-
-The daemon exposes HTTP on the requested port and WebTransport on `port + 1`.
-The browser bootstrap comes from `GET /api/health`, which returns the WebTransport URL template,
-certificate hash, and packet version needed by the client.
-The served browser UI receives the generated API access token automatically.
-
 ## JS/TS Tests
 
 ```ts
@@ -273,20 +210,15 @@ run `SimDeck: Open Simulator View` from the Command Palette. The extension
 opens the simulator inside a VS Code panel and auto-starts the local daemon
 when it is not already reachable.
 
-## SimDeck Cloud
-
-SimDeck Cloud uses the same server binary as its GitHub Actions provider. The
-provider workflow starts `simdeck serve` on the runner, exposes it through a
-tunnel, and lets the hosted control plane connect to the simulator with a
-one-time access token.
-
 ## Contributing
 
 Contributors should read [CONTRIBUTING.md](CONTRIBUTING.md) for local build
 instructions, the dev workflow, and architecture notes.
 
-## License
+## Copyright notice
+
+Copyright [OpenJS Foundation](https://openjsf.org) and `NativeScript` contributors. All rights reserved. The [OpenJS Foundation](https://openjsf.org) has registered trademarks and uses trademarks. For a list of trademarks of the [OpenJS Foundation](https://openjsf.org), please see our [Trademark Policy](https://trademark-policy.openjsf.org/) and [Trademark List](https://trademark-list.openjsf.org/). Trademarks and logos not indicated on the [list of OpenJS Foundation trademarks](https://trademark-list.openjsf.org) are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.
 
-Copyright 2026 Dj
+[The OpenJS Foundation](https://openjsf.org/) | [Terms of Use](https://terms-of-use.openjsf.org/) | [Privacy Policy](https://privacy-policy.openjsf.org/) | [OpenJS Foundation Bylaws](https://bylaws.openjsf.org/) | [Trademark Policy](https://trademark-policy.openjsf.org/) | [Trademark List](https://trademark-list.openjsf.org/) | [Cookie Policy](https://www.linuxfoundation.org/cookies/)
 
-Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).
+<h3 align="center">Made with ❤️</h3>

client/index.html

@@ -7,6 +7,7 @@
       content="width=device-width, initial-scale=1.0, user-scalable=no"
     />
     <meta name="color-scheme" content="light dark" />
+    <link rel="favicon" type="image/png" href="/simdeck.png" />
     <title>SimDeck</title>
     <script>
       try {

client/public/simdeck.png

@@ -98,6 +98,7 @@ const LOGICAL_INSPECTOR_MAX_DEPTH = 80;
 const AUTH_REQUIRED_MESSAGE = "SimDeck API access token is required.";
 const STREAM_TRANSPORT_STORAGE_KEY = "simdeck.streamTransport";
 const VIDEO_CODEC_STORAGE_KEY = "simdeck.videoCodec";
+const CODEC_SWITCH_SETTLE_MS = 180;
 
 clearLegacyVolatileUiState();
 
@@ -202,6 +203,10 @@ function readStoredVideoCodec(): VideoCodecMode {
   return isVideoCodecMode(stored) ? stored : "h264-software";
 }
 
+function sleep(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => window.setTimeout(resolve, milliseconds));
+}
+
 export function AppShell() {
   const [initialUiState] = useState(readPersistedUiState);
   const [initialSelectedUDID] = useState(
@@ -242,6 +247,7 @@ export function AppShell() {
   const [streamSettingsRevision, setStreamSettingsRevision] = useState(0);
   const [streamTransportMode, setStreamTransportMode] =
     useState<StreamTransportMode>(readStoredTransportMode);
+  const [streamPaused, setStreamPaused] = useState(false);
   const [videoCodec, setVideoCodec] =
     useState<VideoCodecMode>(readStoredVideoCodec);
   const [viewMode, setViewMode] = useState<ViewMode>(
@@ -294,6 +300,7 @@ export function AppShell() {
   const zoomAnimationTimeoutRef = useRef<number>(0);
   const touchIndicatorTimeoutRef = useRef<number>(0);
   const gestureStartZoomRef = useRef(1);
+  const codecSwitchInFlightRef = useRef(false);
   const accessibilityRequestIdRef = useRef(0);
   const accessibilityLoadingRef = useRef(false);
   const controlSocketRef = useRef<{
@@ -376,6 +383,7 @@ export function AppShell() {
     streamCanvasKey,
   } = useLiveStream({
     canvasElement: streamCanvasElement,
+    paused: streamPaused,
     simulator: selectedSimulator,
     streamRevision: streamSettingsRevision,
     transportMode: streamTransportMode,
@@ -1213,17 +1221,38 @@ export function AppShell() {
   }
 
   function handleSelectVideoCodec(codec: VideoCodecMode) {
-    if (!selectedSimulator) {
+    if (!selectedSimulator || codecSwitchInFlightRef.current) {
       return;
     }
     const udid = selectedSimulator.udid;
     setVideoCodec(codec);
-    void runAction(async () => {
-      const response = await setSimulatorVideoCodec(udid, codec);
-      setVideoCodec(response.videoCodec);
-      setStreamSettingsRevision((current) => current + 1);
-      setStreamStamp(Date.now());
-    }, false);
+    void (async () => {
+      codecSwitchInFlightRef.current = true;
+      setStreamPaused(true);
+      closeControlSocket();
+      try {
+        await sleep(CODEC_SWITCH_SETTLE_MS);
+        const ok = await runAction(async () => {
+          const response = await setSimulatorVideoCodec(udid, codec);
+          setVideoCodec(response.videoCodec);
+        }, false);
+        await sleep(CODEC_SWITCH_SETTLE_MS);
+        setStreamSettingsRevision((current) => current + 1);
+        setStreamStamp(Date.now());
+        if (!ok) {
+          void fetchHealth()
+            .then((health) => {
+              if (isVideoCodecMode(health.videoCodec)) {
+                setVideoCodec(health.videoCodec);
+              }
+            })
+            .catch(() => {});
+        }
+      } finally {
+        codecSwitchInFlightRef.current = false;
+        setStreamPaused(false);
+      }
+    })();
   }
 
   async function submitPairing(event: FormEvent<HTMLFormElement>) {

client/src/app/AppShell.tsx

@@ -27,6 +27,7 @@ const DEBUG_RENDERER_SOFTWARE_PATTERN = /swiftshader|software|llvmpipe/i;
 
 interface UseLiveStreamOptions {
   canvasElement: HTMLCanvasElement | null;
+  paused?: boolean;
   simulator: SimulatorMetadata | null;
   streamRevision: number;
   transportMode: StreamTransportMode;
@@ -126,6 +127,7 @@ function buildClientTelemetryUrl(): string {
 
 export function useLiveStream({
   canvasElement,
+  paused = false,
   simulator,
   streamRevision,
   transportMode,
@@ -194,6 +196,7 @@ export function useLiveStream({
   useEffect(() => {
     if (
       !streamBackendResolved ||
+      paused ||
       !canvasElement ||
       workerClientRef.current ||
       canvasElement.dataset.streamBackend !== transportBackend
@@ -282,7 +285,13 @@ export function useLiveStream({
       workerClient.destroy();
       workerClientRef.current = null;
     };
-  }, [canvasElement, streamBackendResolved, transportBackend, transportMode]);
+  }, [
+    canvasElement,
+    paused,
+    streamBackendResolved,
+    transportBackend,
+    transportMode,
+  ]);
 
   useEffect(() => {
     latestDecodedFramesRef.current = stats.decodedFrames;
@@ -400,7 +409,7 @@ export function useLiveStream({
     setError("");
     setFps(0);
 
-    if (!simulator?.isBooted) {
+    if (paused || !simulator?.isBooted) {
       workerClient.disconnect();
       workerClient.clear();
       return;
@@ -414,6 +423,7 @@ export function useLiveStream({
     canvasElement,
     simulator?.isBooted,
     simulator?.udid,
+    paused,
     streamBackendResolved,
     transportBackend,
   ]);