fix studio expose reliability

Author: DjDeveloperr

README.md

@@ -84,7 +84,8 @@ profile (`1170` longest edge, dynamic up to `60` fps). Use
 `--stream-quality quality|balanced|fast|smooth|economy|ci-software` to override it,
 or pass `--video-codec hardware` when a dedicated hardware encoder is preferable.
 The remote viewer renders live video with the browser's native video element;
-the canvas is only used for input geometry.
+the canvas is only used for input geometry. Remote viewers can choose 15, 30,
+or 60 fps in the browser stream menu.
 
 CLI commands automatically use the same warm daemon:
 

client/src/app/AppShell.tsx

@@ -98,7 +98,7 @@ const LOCAL_STREAM_DEFAULTS: StreamConfig = {
   quality: "quality",
 };
 const REMOTE_STREAM_DEFAULTS: StreamConfig = {
-  encoder: "auto",
+  encoder: "software",
   fps: 30,
   quality: "balanced",
 };
@@ -1462,6 +1462,7 @@ export function AppShell({
         onToggleTouchOverlay={() =>
           setTouchOverlayVisible((current) => !current)
         }
+        remoteStream={remoteStream}
         search={search}
         selectedSimulator={selectedSimulator}
         selectedSimulatorIdentifier={selectedSimulatorDetail}

client/src/features/simulators/SimulatorMenu.tsx

@@ -29,6 +29,7 @@ interface SimulatorMenuProps {
   onToggleDebug: () => void;
   onToggleMenu: () => void;
   onToggleTouchOverlay: () => void;
+  remoteStream?: boolean;
   search: string;
   selectedSimulator: SimulatorMetadata | null;
   setSelectedUDID: (udid: string) => void;
@@ -56,12 +57,17 @@ export function SimulatorMenu({
   onToggleDebug,
   onToggleMenu,
   onToggleTouchOverlay,
+  remoteStream = false,
   search,
   selectedSimulator,
   setSelectedUDID,
   streamConfig,
   touchOverlayVisible,
 }: SimulatorMenuProps) {
+  const fpsOptions = remoteStream
+    ? REMOTE_STREAM_FPS_OPTIONS
+    : LOCAL_STREAM_FPS_OPTIONS;
+
   return (
     <div className="menu-wrap" ref={menuRef}>
       <button
@@ -124,7 +130,7 @@ export function SimulatorMenu({
                   ))}
                 </div>
                 <div aria-label="Frame rate" className="menu-segment">
-                  {STREAM_FPS_OPTIONS.map((option) => (
+                  {fpsOptions.map((option) => (
                     <button
                       className={`menu-option ${streamConfig.fps === option.value ? "active" : ""}`}
                       key={option.value}
@@ -208,12 +214,18 @@ const STREAM_ENCODERS: Array<{ label: string; value: StreamEncoder }> = [
   { label: "Software", value: "software" },
 ];
 
-const STREAM_FPS_OPTIONS: Array<{ label: string; value: StreamFps }> = [
+const LOCAL_STREAM_FPS_OPTIONS: Array<{ label: string; value: StreamFps }> = [
   { label: "30", value: 30 },
   { label: "60", value: 60 },
   { label: "120", value: 120 },
 ];
 
+const REMOTE_STREAM_FPS_OPTIONS: Array<{ label: string; value: StreamFps }> = [
+  { label: "15", value: 15 },
+  { label: "30", value: 30 },
+  { label: "60", value: 60 },
+];
+
 const STREAM_QUALITY_OPTIONS: Array<{
   label: string;
   value: StreamQualityPreset;

client/src/features/stream/streamTypes.ts

@@ -8,7 +8,7 @@ export interface StreamConnectTarget {
 }
 
 export type StreamEncoder = "auto" | "hardware" | "software";
-export type StreamFps = 30 | 60 | 120;
+export type StreamFps = 15 | 30 | 60 | 120;
 export type StreamQualityPreset = "quality" | "balanced" | "fast";
 
 export interface StreamConfig {

client/src/features/stream/streamWorkerClient.ts

@@ -16,7 +16,8 @@ const WEBRTC_FIRST_FRAME_TIMEOUT_MS = 10000;
 const WEBRTC_STALLED_FRAME_TIMEOUT_MS = 3000;
 const WEBRTC_LOCAL_RECEIVER_BUFFER_SECONDS = 0.001;
 const WEBRTC_REMOTE_RECEIVER_BUFFER_SECONDS = 0.06;
-const WEBRTC_DISCONNECTED_GRACE_MS = 1000;
+const WEBRTC_LOCAL_DISCONNECTED_GRACE_MS = 1000;
+const WEBRTC_REMOTE_DISCONNECTED_GRACE_MS = 10000;
 const WEBRTC_RECONNECT_BASE_DELAY_MS = 250;
 const WEBRTC_RECONNECT_MAX_DELAY_MS = 1000;
 
@@ -551,7 +552,7 @@ class WebRtcStreamClient implements StreamClientBackend {
         generation,
         new Error("WebRTC connection disconnected."),
       );
-    }, WEBRTC_DISCONNECTED_GRACE_MS);
+    }, disconnectedGraceMs(target));
   }
 
   private scheduleReconnect(target: StreamConnectTarget, generation: number) {
@@ -611,11 +612,8 @@ class WebRtcStreamClient implements StreamClientBackend {
           return;
         }
         if (frameAgeMs > WEBRTC_STALLED_FRAME_TIMEOUT_MS) {
-          this.handleConnectionError(
-            target,
-            generation,
-            new Error("WebRTC video stalled after rendering frames."),
-          );
+          this.sendControl({ snapshot: true, type: "streamControl" });
+          this.scheduleFrameWatchdog(target, generation);
           return;
         }
         this.scheduleFrameWatchdog(target, generation);
@@ -1105,6 +1103,12 @@ function receiverBufferSeconds(target: StreamConnectTarget): number | null {
     : WEBRTC_LOCAL_RECEIVER_BUFFER_SECONDS;
 }
 
+function disconnectedGraceMs(target: StreamConnectTarget): number {
+  return target.remote
+    ? WEBRTC_REMOTE_DISCONNECTED_GRACE_MS
+    : WEBRTC_LOCAL_DISCONNECTED_GRACE_MS;
+}
+
 function configureReceiverCodecPreferences(transceiver: RTCRtpTransceiver) {
   if (!transceiver.setCodecPreferences) {
     return;

client/src/features/stream/useLiveStream.ts

@@ -309,8 +309,9 @@ export function useLiveStream({
       const latestStatus = latestStatusRef.current;
       const now = Date.now();
       if (
+        !remote &&
         now - lastVisualArtifactSampleAtRef.current >=
-        VISUAL_ARTIFACT_TELEMETRY_INTERVAL_MS
+          VISUAL_ARTIFACT_TELEMETRY_INTERVAL_MS
       ) {
         lastVisualArtifactSampleAtRef.current = now;
         const visualSample = await workerClientRef.current

client/src/features/toolbar/Toolbar.tsx

@@ -34,6 +34,7 @@ interface ToolbarProps {
   onToggleHierarchy: () => void;
   onToggleMenu: () => void;
   onToggleTouchOverlay: () => void;
+  remoteStream?: boolean;
   search: string;
   selectedSimulator: SimulatorMetadata | null;
   selectedSimulatorIdentifier: string;
@@ -75,6 +76,7 @@ export function Toolbar({
   onToggleHierarchy,
   onToggleMenu,
   onToggleTouchOverlay,
+  remoteStream = false,
   search,
   selectedSimulator,
   selectedSimulatorIdentifier,
@@ -135,6 +137,7 @@ export function Toolbar({
           onToggleDebug={onToggleDebug}
           onToggleMenu={onToggleMenu}
           onToggleTouchOverlay={onToggleTouchOverlay}
+          remoteStream={remoteStream}
           search={search}
           selectedSimulator={selectedSimulator}
           setSelectedUDID={setSelectedUDID}

docs/guide/video.md

@@ -32,7 +32,7 @@ It is CLI-only because it is meant for less capable machines where freshness
 matters more than maximum smoothness.
 
 The requested encoder mode is reported to clients in the JSON `videoCodec` field on `GET /api/health`.
-The browser UI exposes stream controls for encoder, FPS, and quality. Local browser sessions default to hardware H.264, 120 fps, and `quality`/full resolution; remote browser sessions default to software H.264, 30 fps, and `balanced`.
+The browser UI exposes stream controls for encoder, FPS, and quality. Local browser sessions default to hardware H.264, 120 fps, and `quality`/full resolution with FPS choices of 30, 60, and 120. Remote browser sessions default to software H.264, 30 fps, and `balanced` with FPS choices of 15, 30, and 60.
 
 ## Remote WebRTC ICE