From 7f74f829ee635db420e1f1d5169c48f72d5b78f0 Mon Sep 17 00:00:00 2001
From: DjDeveloperr <hey@djdev.me>
Date: Sat, 2 May 2026 18:14:39 -0400
Subject: [PATCH 1/5] Improve stream reconnect handling

---
 client/src/features/stream/streamTypes.ts     |  1 +
 .../src/features/stream/streamWorkerClient.ts | 20 +++++++++++--------
 client/src/features/stream/useLiveStream.ts   |  7 ++++++-
 docs/guide/video.md                           |  2 +-
 server/src/logging.rs                         |  2 +-
 server/src/transport/webrtc.rs                | 12 +++++++++++
 6 files changed, 33 insertions(+), 11 deletions(-)

diff --git a/client/src/features/stream/streamTypes.ts b/client/src/features/stream/streamTypes.ts
index 5ed03b7..ba07a6e 100644
--- a/client/src/features/stream/streamTypes.ts
+++ b/client/src/features/stream/streamTypes.ts
@@ -1,6 +1,7 @@
 import type { Size } from "../viewport/types";
 
 export interface StreamConnectTarget {
+  clientId?: string;
   remote?: boolean;
   udid: string;
 }
diff --git a/client/src/features/stream/streamWorkerClient.ts b/client/src/features/stream/streamWorkerClient.ts
index f08fb78..8f93467 100644
--- a/client/src/features/stream/streamWorkerClient.ts
+++ b/client/src/features/stream/streamWorkerClient.ts
@@ -12,8 +12,9 @@ const HAVE_CURRENT_DATA = 2;
 const WEBRTC_CONTROL_CHANNEL_LABEL = "simdeck-control";
 const WEBRTC_TELEMETRY_CHANNEL_LABEL = "simdeck-telemetry";
 const WEBRTC_FIRST_FRAME_TIMEOUT_MS = 10000;
-const WEBRTC_STALLED_FRAME_TIMEOUT_MS = 8000;
-const WEBRTC_DISCONNECTED_GRACE_MS = 8000;
+const WEBRTC_STALLED_FRAME_TIMEOUT_MS = 60000;
+const WEBRTC_RECEIVER_BUFFER_SECONDS = 0.06;
+const WEBRTC_DISCONNECTED_GRACE_MS = 30000;
 const WEBRTC_RECONNECT_BASE_DELAY_MS = 3000;
 const WEBRTC_RECONNECT_MAX_DELAY_MS = 10000;
 
@@ -47,9 +48,9 @@ function sendDataChannelMessage(
 
 export function buildStreamTarget(
   udid: string,
-  options: { remote?: boolean } = {},
+  options: { clientId?: string; remote?: boolean } = {},
 ): StreamConnectTarget {
-  return { remote: options.remote, udid };
+  return { clientId: options.clientId, remote: options.remote, udid };
 }
 
 export function canUseWebRtc(): boolean {
@@ -431,7 +432,7 @@ class WebRtcStreamClient implements StreamClientBackend {
         const hasRenderedFrame = this.stats.renderedFrames > 0;
         const frameAgeMs =
           this.lastVideoFrameAt > 0 ? now - this.lastVideoFrameAt : Infinity;
-        if (!hasRenderedFrame || frameAgeMs > WEBRTC_STALLED_FRAME_TIMEOUT_MS) {
+        if (!hasRenderedFrame) {
           this.handleConnectionError(
             target,
             generation,
@@ -439,6 +440,9 @@ class WebRtcStreamClient implements StreamClientBackend {
           );
           return;
         }
+        if (frameAgeMs > WEBRTC_STALLED_FRAME_TIMEOUT_MS) {
+          this.postDiagnostics(target, "video-frame-watchdog-stalled");
+        }
         this.scheduleFrameWatchdog(target, generation);
       },
       this.stats.renderedFrames > 0
@@ -575,7 +579,7 @@ class WebRtcStreamClient implements StreamClientBackend {
   private postDiagnostics(target: StreamConnectTarget, detail: string) {
     const payload = {
       ...this.stats,
-      clientId: "webrtc-page",
+      clientId: target.clientId ?? "webrtc-page",
       connectionId: this.connectGeneration,
       detail,
       iceConnectionState: this.diagnostics.iceConnectionState,
@@ -784,10 +788,10 @@ function configureLowLatencyReceiver(receiver: RTCRtpReceiver) {
     playoutDelayHint?: number;
   };
   if ("jitterBufferTarget" in lowLatencyReceiver) {
-    lowLatencyReceiver.jitterBufferTarget = 0.001;
+    lowLatencyReceiver.jitterBufferTarget = WEBRTC_RECEIVER_BUFFER_SECONDS;
   }
   if ("playoutDelayHint" in lowLatencyReceiver) {
-    lowLatencyReceiver.playoutDelayHint = 0.001;
+    lowLatencyReceiver.playoutDelayHint = WEBRTC_RECEIVER_BUFFER_SECONDS;
   }
 }
 
diff --git a/client/src/features/stream/useLiveStream.ts b/client/src/features/stream/useLiveStream.ts
index 9852b5e..4b6fc62 100644
--- a/client/src/features/stream/useLiveStream.ts
+++ b/client/src/features/stream/useLiveStream.ts
@@ -242,7 +242,12 @@ export function useLiveStream({
       return;
     }
 
-    workerClient.connect(buildStreamTarget(simulator.udid, { remote }));
+    workerClient.connect(
+      buildStreamTarget(simulator.udid, {
+        clientId: clientTelemetryIdRef.current,
+        remote,
+      }),
+    );
     return () => {
       workerClient.disconnect();
     };
diff --git a/docs/guide/video.md b/docs/guide/video.md
index edcef47..cb1be82 100644
--- a/docs/guide/video.md
+++ b/docs/guide/video.md
@@ -78,7 +78,7 @@ The WebRTC path favors freshness: stale frames are dropped and the sender reques
 A few practical guidelines:
 
 - **Start on the default for local preview.** `auto` lets VideoToolbox choose without requiring the shared hardware encoder.
-- **Switch to `software` when the hardware encoder stalls or is unavailable.** The encoder scales the longest edge to 1600 pixels, can climb toward 60 fps, and backs off dynamically under encode latency.
+- **Switch to `software` when the hardware encoder stalls or is unavailable.** The encoder scales the longest edge to 1600 pixels, can climb toward 90 fps for local preview, and backs off dynamically under encode latency.
 - **Studio providers default to software H.264 plus `--stream-quality smooth`.** This profile uses a 1170-pixel longest edge, allows up to 60 fps, raises the bitrate budget to reduce compression artifacts, and lets multiple provider sessions share CPU cores without depending on one hardware encoder.
 - **The remote browser renders the live stream as a native `<video>` element.** The canvas remains for input geometry, but it is not in the live per-frame render path and does not preserve stale frames during reconnects.
 - **Use `--stream-quality ci-software` for denser virtualized CI Macs.** This profile uses software H.264 at a 960-pixel longest edge, targets 24 fps, lowers bitrate pressure, and favors fresh frames over full-resolution sharpness.
diff --git a/server/src/logging.rs b/server/src/logging.rs
index 3439cb5..4badfec 100644
--- a/server/src/logging.rs
+++ b/server/src/logging.rs
@@ -2,7 +2,7 @@ use tracing_subscriber::EnvFilter;
 
 pub fn init() {
     let filter = EnvFilter::try_from_env("SIMDECK_LOG")
-        .unwrap_or_else(|_| EnvFilter::new("error,webrtc=error,webrtc_ice=error"));
+        .unwrap_or_else(|_| EnvFilter::new("error,webrtc=error,webrtc_ice=error,webrtc_mdns=off"));
     tracing_subscriber::fmt()
         .with_env_filter(filter)
         .with_writer(std::io::stderr)
diff --git a/server/src/transport/webrtc.rs b/server/src/transport/webrtc.rs
index e89d63a..5aebf80 100644
--- a/server/src/transport/webrtc.rs
+++ b/server/src/transport/webrtc.rs
@@ -47,6 +47,7 @@ const WEBRTC_WRITE_TIMEOUT: Duration = Duration::from_millis(120);
 const WEBRTC_REALTIME_WRITE_TIMEOUT: Duration = Duration::from_millis(45);
 const WEBRTC_REALTIME_KEYFRAME_WRITE_TIMEOUT: Duration = Duration::from_millis(90);
 const WEBRTC_RTP_OUTBOUND_MTU: usize = 1200;
+const WEBRTC_PEER_DISCONNECTED_TIMEOUT: Duration = Duration::from_secs(45);
 static WEBRTC_MEDIA_STREAMS: OnceLock<Mutex<HashMap<String, Vec<broadcast::Sender<()>>>>> =
     OnceLock::new();
 const MAX_WEBRTC_MEDIA_STREAMS_PER_UDID: usize = 3;
@@ -690,6 +691,7 @@ impl WebRtcMediaStream {
         let mut adaptive_refresh_interval = refresh_floor;
         let mut bootstrap_frames_remaining = WEBRTC_BOOTSTRAP_KEYFRAME_REPEATS;
         let mut waiting_for_keyframe = false;
+        let mut peer_disconnected_since: Option<time::Instant> = None;
         let _guard = WebRtcMetricsGuard::new(state.metrics.clone());
 
         match write_frame_sample_with_timeout(
@@ -737,6 +739,16 @@ impl WebRtcMediaStream {
                         warn!("WebRTC media stream closing for {udid}: peer state {peer_state}");
                         break;
                     }
+                    if peer_state == RTCPeerConnectionState::Disconnected {
+                        let disconnected_since =
+                            peer_disconnected_since.get_or_insert_with(time::Instant::now);
+                        if disconnected_since.elapsed() >= WEBRTC_PEER_DISCONNECTED_TIMEOUT {
+                            warn!("WebRTC media stream closing for {udid}: peer state {peer_state}");
+                            break;
+                        }
+                    } else {
+                        peer_disconnected_since = None;
+                    }
                 }
                 _ = &mut bootstrap_sleep, if bootstrap_frames_remaining > 0 => {
                     match write_frame_sample_with_timeout(

From 125fccaa483aac1674779de5dccb92ec7aa12a56 Mon Sep 17 00:00:00 2001
From: DjDeveloperr <hey@djdev.me>
Date: Sat, 2 May 2026 18:17:33 -0400
Subject: [PATCH 2/5] Tighten local WebRTC recovery

---
 .../src/features/stream/streamWorkerClient.ts | 33 ++++++++++++++-----
 docs/guide/video.md                           |  2 +-
 2 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/client/src/features/stream/streamWorkerClient.ts b/client/src/features/stream/streamWorkerClient.ts
index 8f93467..c24571a 100644
--- a/client/src/features/stream/streamWorkerClient.ts
+++ b/client/src/features/stream/streamWorkerClient.ts
@@ -12,8 +12,8 @@ const HAVE_CURRENT_DATA = 2;
 const WEBRTC_CONTROL_CHANNEL_LABEL = "simdeck-control";
 const WEBRTC_TELEMETRY_CHANNEL_LABEL = "simdeck-telemetry";
 const WEBRTC_FIRST_FRAME_TIMEOUT_MS = 10000;
-const WEBRTC_STALLED_FRAME_TIMEOUT_MS = 60000;
-const WEBRTC_RECEIVER_BUFFER_SECONDS = 0.06;
+const WEBRTC_STALLED_FRAME_TIMEOUT_MS = 15000;
+const WEBRTC_REMOTE_RECEIVER_BUFFER_SECONDS = 0.06;
 const WEBRTC_DISCONNECTED_GRACE_MS = 30000;
 const WEBRTC_RECONNECT_BASE_DELAY_MS = 3000;
 const WEBRTC_RECONNECT_MAX_DELAY_MS = 10000;
@@ -146,7 +146,10 @@ class WebRtcStreamClient implements StreamClientBackend {
         direction: "recvonly",
       });
       configureReceiverCodecPreferences(transceiver);
-      configureLowLatencyReceiver(transceiver.receiver);
+      configureLowLatencyReceiver(
+        transceiver.receiver,
+        target.remote ? WEBRTC_REMOTE_RECEIVER_BUFFER_SECONDS : null,
+      );
       const controlChannel = peerConnection.createDataChannel(
         WEBRTC_CONTROL_CHANNEL_LABEL,
         {
@@ -181,7 +184,10 @@ class WebRtcStreamClient implements StreamClientBackend {
         }
         event.track.contentHint = "motion";
         for (const receiver of peerConnection.getReceivers()) {
-          configureLowLatencyReceiver(receiver);
+          configureLowLatencyReceiver(
+            receiver,
+            target.remote ? WEBRTC_REMOTE_RECEIVER_BUFFER_SECONDS : null,
+          );
         }
         const stream = event.streams[0] ?? new MediaStream([event.track]);
         const video = document.createElement("video");
@@ -441,7 +447,12 @@ class WebRtcStreamClient implements StreamClientBackend {
           return;
         }
         if (frameAgeMs > WEBRTC_STALLED_FRAME_TIMEOUT_MS) {
-          this.postDiagnostics(target, "video-frame-watchdog-stalled");
+          this.handleConnectionError(
+            target,
+            generation,
+            new Error("WebRTC video stalled after rendering frames."),
+          );
+          return;
         }
         this.scheduleFrameWatchdog(target, generation);
       },
@@ -782,16 +793,22 @@ function postWebRtcOffer(
   );
 }
 
-function configureLowLatencyReceiver(receiver: RTCRtpReceiver) {
+function configureLowLatencyReceiver(
+  receiver: RTCRtpReceiver,
+  bufferSeconds: number | null,
+) {
+  if (!bufferSeconds || bufferSeconds <= 0) {
+    return;
+  }
   const lowLatencyReceiver = receiver as RTCRtpReceiver & {
     jitterBufferTarget?: number;
     playoutDelayHint?: number;
   };
   if ("jitterBufferTarget" in lowLatencyReceiver) {
-    lowLatencyReceiver.jitterBufferTarget = WEBRTC_RECEIVER_BUFFER_SECONDS;
+    lowLatencyReceiver.jitterBufferTarget = bufferSeconds;
   }
   if ("playoutDelayHint" in lowLatencyReceiver) {
-    lowLatencyReceiver.playoutDelayHint = WEBRTC_RECEIVER_BUFFER_SECONDS;
+    lowLatencyReceiver.playoutDelayHint = bufferSeconds;
   }
 }
 
diff --git a/docs/guide/video.md b/docs/guide/video.md
index cb1be82..edcef47 100644
--- a/docs/guide/video.md
+++ b/docs/guide/video.md
@@ -78,7 +78,7 @@ The WebRTC path favors freshness: stale frames are dropped and the sender reques
 A few practical guidelines:
 
 - **Start on the default for local preview.** `auto` lets VideoToolbox choose without requiring the shared hardware encoder.
-- **Switch to `software` when the hardware encoder stalls or is unavailable.** The encoder scales the longest edge to 1600 pixels, can climb toward 90 fps for local preview, and backs off dynamically under encode latency.
+- **Switch to `software` when the hardware encoder stalls or is unavailable.** The encoder scales the longest edge to 1600 pixels, can climb toward 60 fps, and backs off dynamically under encode latency.
 - **Studio providers default to software H.264 plus `--stream-quality smooth`.** This profile uses a 1170-pixel longest edge, allows up to 60 fps, raises the bitrate budget to reduce compression artifacts, and lets multiple provider sessions share CPU cores without depending on one hardware encoder.
 - **The remote browser renders the live stream as a native `<video>` element.** The canvas remains for input geometry, but it is not in the live per-frame render path and does not preserve stale frames during reconnects.
 - **Use `--stream-quality ci-software` for denser virtualized CI Macs.** This profile uses software H.264 at a 960-pixel longest edge, targets 24 fps, lowers bitrate pressure, and favors fresh frames over full-resolution sharpness.

From 2da61ae195d068b8e8034e865e99d337164428ac Mon Sep 17 00:00:00 2001
From: DjDeveloperr <hey@djdev.me>
Date: Sat, 2 May 2026 18:45:56 -0400
Subject: [PATCH 3/5] Raise local stream cap to 120 fps

---
 README.md                      |   7 +++
 cli/XCWH264Encoder.m           | 112 ++++++++++++++++++++-------------
 docs/api/health.md             |   1 +
 docs/cli/commands.md           |  10 +--
 docs/cli/flags.md              |   1 +
 docs/guide/daemon.md           |   1 +
 docs/guide/video.md            |   1 +
 server/src/api/routes.rs       |   1 +
 server/src/main.rs             |  75 ++++++++++++++++++++++
 server/src/service.rs          |   4 ++
 server/src/transport/webrtc.rs |  17 ++++-
 skills/simdeck/SKILL.md        |   3 +
 12 files changed, 183 insertions(+), 50 deletions(-)

diff --git a/README.md b/README.md
index 009983a..c5050c5 100644
--- a/README.md
+++ b/README.md
@@ -116,6 +116,13 @@ more important than full-resolution smoothness:
 simdeck daemon start --video-codec software --low-latency
 ```
 
+Local browser streams default to 60 fps. On high-refresh local displays, opt in
+to a paced hardware stream up to 120 fps:
+
+```sh
+simdeck daemon restart --local-stream-fps 120
+```
+
 Restart the CoreSimulator service layer when `simctl` reports a stale service
 version or the live display gets stuck before the first frame:
 
diff --git a/cli/XCWH264Encoder.m b/cli/XCWH264Encoder.m
index e405e52..3f0a2ba 100644
--- a/cli/XCWH264Encoder.m
+++ b/cli/XCWH264Encoder.m
@@ -14,6 +14,8 @@
 static const int32_t XCWTargetRealTimeFrameRate = 60;
 static const int32_t XCWTargetRealtimeHardwareFrameRate = 30;
 static const int32_t XCWTargetSoftwareFrameRate = 60;
+static const int32_t XCWMinimumLocalStreamFrameRate = 15;
+static const int32_t XCWMaximumLocalStreamFrameRate = 120;
 static const int32_t XCWTargetLowLatencySoftwareFrameRate = 15;
 static const NSUInteger XCWMaximumInFlightFrames = 2;
 static const int32_t XCWMinimumAverageBitRate = 18000000;
@@ -137,6 +139,22 @@ static uint64_t XCWRealtimeMaximumFrameIntervalUs(void) {
     return MAX(XCWRealtimeFrameIntervalUs() * 2, XCWRealtimeFrameIntervalUs());
 }
 
+static int32_t XCWLocalStreamTargetFrameRate(void) {
+    return XCWIntFromEnvironment(@"SIMDECK_LOCAL_STREAM_FPS",
+                                 XCWTargetRealTimeFrameRate,
+                                 XCWMinimumLocalStreamFrameRate,
+                                 XCWMaximumLocalStreamFrameRate);
+}
+
+static uint64_t XCWLocalStreamFrameIntervalUs(void) {
+    int32_t fps = MAX(1, XCWLocalStreamTargetFrameRate());
+    return (uint64_t)llround(1000000.0 / (double)fps);
+}
+
+static uint64_t XCWLocalStreamMaximumFrameIntervalUs(void) {
+    return MAX(XCWSoftwareMaximumFrameIntervalUs, XCWLocalStreamFrameIntervalUs());
+}
+
 static int64_t XCWRealtimeBitsPerPixelBudgetValue(void) {
     return XCWInt64FromEnvironment(@"SIMDECK_REALTIME_BITS_PER_PIXEL",
                                    XCWRealtimeBitsPerPixelBudget,
@@ -490,10 +508,10 @@ @implementation XCWH264Encoder {
     uint64_t _lastSoftwareSubmissionUs;
     NSUInteger _softwarePacedFrameCount;
     NSUInteger _softwareHealthyFrameCount;
-    uint64_t _realtimeHardwareFrameIntervalUs;
-    uint64_t _lastRealtimeHardwareSubmissionUs;
-    NSUInteger _realtimeHardwarePacedFrameCount;
-    NSUInteger _realtimeHardwareHealthyFrameCount;
+    uint64_t _hardwareFrameIntervalUs;
+    uint64_t _lastHardwareSubmissionUs;
+    NSUInteger _hardwarePacedFrameCount;
+    NSUInteger _hardwareHealthyFrameCount;
     NSString *_selectedEncoderID;
     NSInteger _lastSessionStatus;
     NSInteger _lastPrepareStatus;
@@ -518,7 +536,7 @@ - (instancetype)initWithOutputHandler:(XCWH264EncoderOutputHandler)outputHandler
     _realtimeStreamMode = XCWRealtimeStreamModeFromEnvironment() || _lowLatencyMode;
     _codecType = XCWVideoCodecTypeForMode(_encoderMode);
     _softwareFrameIntervalUs = [self initialSoftwareFrameIntervalUsLocked];
-    _realtimeHardwareFrameIntervalUs = [self initialHardwareFrameIntervalUsLocked];
+    _hardwareFrameIntervalUs = [self initialHardwareFrameIntervalUsLocked];
     return self;
 }
 
@@ -568,9 +586,9 @@ - (void)reconfigureForStreamQualityChange {
         self->_softwareFrameIntervalUs = [self initialSoftwareFrameIntervalUsLocked];
         self->_softwarePacedFrameCount = 0;
         self->_softwareHealthyFrameCount = 0;
-        self->_realtimeHardwareFrameIntervalUs = [self initialHardwareFrameIntervalUsLocked];
-        self->_realtimeHardwarePacedFrameCount = 0;
-        self->_realtimeHardwareHealthyFrameCount = 0;
+        self->_hardwareFrameIntervalUs = [self initialHardwareFrameIntervalUsLocked];
+        self->_hardwarePacedFrameCount = 0;
+        self->_hardwareHealthyFrameCount = 0;
     });
 }
 
@@ -597,9 +615,13 @@ - (NSDictionary *)statsRepresentation {
             @"softwareFrameIntervalUs": @(self->_softwareFrameIntervalUs),
             @"softwareTargetFps": @(self->_softwareFrameIntervalUs > 0 ? (1000000.0 / (double)self->_softwareFrameIntervalUs) : 0.0),
             @"softwarePacedFrames": @(self->_softwarePacedFrameCount),
-            @"realtimeHardwareFrameIntervalUs": @(self->_realtimeHardwareFrameIntervalUs),
-            @"realtimeHardwareTargetFps": @(self->_realtimeHardwareFrameIntervalUs > 0 ? (1000000.0 / (double)self->_realtimeHardwareFrameIntervalUs) : 0.0),
-            @"realtimeHardwarePacedFrames": @(self->_realtimeHardwarePacedFrameCount),
+            @"localStreamTargetFps": @(XCWLocalStreamTargetFrameRate()),
+            @"hardwareFrameIntervalUs": @(self->_hardwareFrameIntervalUs),
+            @"hardwareTargetFps": @(self->_hardwareFrameIntervalUs > 0 ? (1000000.0 / (double)self->_hardwareFrameIntervalUs) : 0.0),
+            @"hardwarePacedFrames": @(self->_hardwarePacedFrameCount),
+            @"realtimeHardwareFrameIntervalUs": @(self->_hardwareFrameIntervalUs),
+            @"realtimeHardwareTargetFps": @(self->_hardwareFrameIntervalUs > 0 ? (1000000.0 / (double)self->_hardwareFrameIntervalUs) : 0.0),
+            @"realtimeHardwarePacedFrames": @(self->_hardwarePacedFrameCount),
             @"transportCodec": XCWCodecName(self->_codecType),
             @"encoderMode": XCWVideoEncoderModeName(self->_encoderMode),
             @"lowLatencyMode": @(self->_lowLatencyMode),
@@ -665,15 +687,15 @@ - (NSUInteger)softwareHealthyFrameWindowLocked {
 }
 
 - (uint64_t)minimumHardwareFrameIntervalUsLocked {
-    return _realtimeStreamMode ? XCWRealtimeFrameIntervalUs() : XCWSoftwareMinimumFrameIntervalUs;
+    return _realtimeStreamMode ? XCWRealtimeFrameIntervalUs() : XCWLocalStreamFrameIntervalUs();
 }
 
 - (uint64_t)initialHardwareFrameIntervalUsLocked {
-    return _realtimeStreamMode ? XCWRealtimeFrameIntervalUs() : XCWSoftwareInitialFrameIntervalUs;
+    return _realtimeStreamMode ? XCWRealtimeFrameIntervalUs() : XCWLocalStreamFrameIntervalUs();
 }
 
 - (uint64_t)maximumHardwareFrameIntervalUsLocked {
-    return _realtimeStreamMode ? XCWRealtimeMaximumFrameIntervalUs() : XCWSoftwareMaximumFrameIntervalUs;
+    return _realtimeStreamMode ? XCWRealtimeMaximumFrameIntervalUs() : XCWLocalStreamMaximumFrameIntervalUs();
 }
 
 - (int32_t)expectedFrameRateLocked {
@@ -686,24 +708,24 @@ - (int32_t)expectedFrameRateLocked {
     if (_realtimeStreamMode) {
         return XCWRealtimeTargetFrameRate();
     }
-    return XCWTargetRealTimeFrameRate;
+    return XCWLocalStreamTargetFrameRate();
 }
 
-- (BOOL)shouldPaceRealtimeHardwareFrameAtTimeUs:(uint64_t)nowUs {
-    if ((_encoderMode != XCWVideoEncoderModeAuto && _encoderMode != XCWVideoEncoderModeH264Hardware) || !_realtimeStreamMode || _needsKeyFrame) {
+- (BOOL)shouldPaceHardwareFrameAtTimeUs:(uint64_t)nowUs {
+    if ((_encoderMode != XCWVideoEncoderModeAuto && _encoderMode != XCWVideoEncoderModeH264Hardware) || _needsKeyFrame) {
         return NO;
     }
-    if (_realtimeHardwareFrameIntervalUs == 0) {
-        _realtimeHardwareFrameIntervalUs = [self initialHardwareFrameIntervalUsLocked];
+    if (_hardwareFrameIntervalUs == 0) {
+        _hardwareFrameIntervalUs = [self initialHardwareFrameIntervalUsLocked];
     }
-    if (_lastRealtimeHardwareSubmissionUs == 0) {
+    if (_lastHardwareSubmissionUs == 0) {
         return NO;
     }
-    uint64_t elapsedUs = nowUs >= _lastRealtimeHardwareSubmissionUs ? nowUs - _lastRealtimeHardwareSubmissionUs : 0;
-    if (elapsedUs >= _realtimeHardwareFrameIntervalUs) {
+    uint64_t elapsedUs = nowUs >= _lastHardwareSubmissionUs ? nowUs - _lastHardwareSubmissionUs : 0;
+    if (elapsedUs >= _hardwareFrameIntervalUs) {
         return NO;
     }
-    _realtimeHardwarePacedFrameCount += 1;
+    _hardwarePacedFrameCount += 1;
     return YES;
 }
 
@@ -764,41 +786,41 @@ - (void)adaptSoftwarePacingForLatencyUs:(uint64_t)latencyUs {
     _softwareHealthyFrameCount = 0;
 }
 
-- (void)adaptRealtimeHardwarePacingForLatencyUs:(uint64_t)latencyUs {
-    if ((_encoderMode != XCWVideoEncoderModeAuto && _encoderMode != XCWVideoEncoderModeH264Hardware) || !_realtimeStreamMode || latencyUs == 0) {
+- (void)adaptHardwarePacingForLatencyUs:(uint64_t)latencyUs {
+    if ((_encoderMode != XCWVideoEncoderModeAuto && _encoderMode != XCWVideoEncoderModeH264Hardware) || latencyUs == 0) {
         return;
     }
-    if (_realtimeHardwareFrameIntervalUs == 0) {
-        _realtimeHardwareFrameIntervalUs = [self initialHardwareFrameIntervalUsLocked];
+    if (_hardwareFrameIntervalUs == 0) {
+        _hardwareFrameIntervalUs = [self initialHardwareFrameIntervalUsLocked];
     }
 
     uint64_t minimumIntervalUs = [self minimumHardwareFrameIntervalUsLocked];
     uint64_t maximumIntervalUs = [self maximumHardwareFrameIntervalUsLocked];
-    if (latencyUs > _realtimeHardwareFrameIntervalUs) {
-        uint64_t nextIntervalUs = _realtimeHardwareFrameIntervalUs + XCWRealtimeHardwareFrameIntervalStepUs;
+    if (latencyUs > _hardwareFrameIntervalUs) {
+        uint64_t nextIntervalUs = _hardwareFrameIntervalUs + XCWRealtimeHardwareFrameIntervalStepUs;
         uint64_t latencyBoundIntervalUs = latencyUs + XCWRealtimeHardwareFrameIntervalStepUs;
         if (nextIntervalUs < latencyBoundIntervalUs) {
             nextIntervalUs = latencyBoundIntervalUs;
         }
-        _realtimeHardwareFrameIntervalUs = MIN(nextIntervalUs, maximumIntervalUs);
-        _realtimeHardwareHealthyFrameCount = 0;
+        _hardwareFrameIntervalUs = MIN(nextIntervalUs, maximumIntervalUs);
+        _hardwareHealthyFrameCount = 0;
         return;
     }
 
-    if (latencyUs < _realtimeHardwareFrameIntervalUs &&
-        _realtimeHardwareFrameIntervalUs > minimumIntervalUs) {
-        _realtimeHardwareHealthyFrameCount += 1;
-        if (_realtimeHardwareHealthyFrameCount >= XCWRealtimeHardwareHealthyFrameWindow) {
-            uint64_t nextIntervalUs = _realtimeHardwareFrameIntervalUs > XCWRealtimeHardwareFrameIntervalStepUs
-                ? _realtimeHardwareFrameIntervalUs - XCWRealtimeHardwareFrameIntervalStepUs
+    if (latencyUs < _hardwareFrameIntervalUs &&
+        _hardwareFrameIntervalUs > minimumIntervalUs) {
+        _hardwareHealthyFrameCount += 1;
+        if (_hardwareHealthyFrameCount >= XCWRealtimeHardwareHealthyFrameWindow) {
+            uint64_t nextIntervalUs = _hardwareFrameIntervalUs > XCWRealtimeHardwareFrameIntervalStepUs
+                ? _hardwareFrameIntervalUs - XCWRealtimeHardwareFrameIntervalStepUs
                 : minimumIntervalUs;
-            _realtimeHardwareFrameIntervalUs = MAX(nextIntervalUs, minimumIntervalUs);
-            _realtimeHardwareHealthyFrameCount = 0;
+            _hardwareFrameIntervalUs = MAX(nextIntervalUs, minimumIntervalUs);
+            _hardwareHealthyFrameCount = 0;
         }
         return;
     }
 
-    _realtimeHardwareHealthyFrameCount = 0;
+    _hardwareHealthyFrameCount = 0;
 }
 
 - (void)drainPendingFramesLocked {
@@ -839,7 +861,7 @@ - (BOOL)encodePixelBufferLocked:(CVPixelBufferRef)pixelBuffer {
     }
 
     uint64_t nowUs = (uint64_t)(CACurrentMediaTime() * 1000000.0);
-    if ([self shouldPaceSoftwareFrameAtTimeUs:nowUs] || [self shouldPaceRealtimeHardwareFrameAtTimeUs:nowUs]) {
+    if ([self shouldPaceSoftwareFrameAtTimeUs:nowUs] || [self shouldPaceHardwareFrameAtTimeUs:nowUs]) {
         return YES;
     }
 
@@ -885,8 +907,8 @@ - (BOOL)encodePixelBufferLocked:(CVPixelBufferRef)pixelBuffer {
     _submittedFrameCount += 1;
     if (_encoderMode == XCWVideoEncoderModeH264Software) {
         _lastSoftwareSubmissionUs = nowUs;
-    } else if ((_encoderMode == XCWVideoEncoderModeAuto || _encoderMode == XCWVideoEncoderModeH264Hardware) && _realtimeStreamMode) {
-        _lastRealtimeHardwareSubmissionUs = nowUs;
+    } else if (_encoderMode == XCWVideoEncoderModeAuto || _encoderMode == XCWVideoEncoderModeH264Hardware) {
+        _lastHardwareSubmissionUs = nowUs;
     }
     _maxInFlightFrameCount = MAX(_maxInFlightFrameCount, _inFlightFrameCount);
     if (_encoderMode == XCWVideoEncoderModeH264Software || !_realtimeStreamMode) {
@@ -1013,7 +1035,7 @@ - (void)invalidateCompressionSessionLocked {
     _timestampOriginUs = 0;
     _inFlightFrameCount = 0;
     _lastSoftwareSubmissionUs = 0;
-    _lastRealtimeHardwareSubmissionUs = 0;
+    _lastHardwareSubmissionUs = 0;
     _hardwareAccelerated = NO;
     _selectedEncoderID = nil;
     [self invalidateScalingResourcesLocked];
@@ -1203,7 +1225,7 @@ - (void)handleEncodedSampleBuffer:(CMSampleBufferRef)sampleBuffer
         uint64_t nowUs = (uint64_t)(CACurrentMediaTime() * 1000000.0);
         _latestEncodeLatencyUs = nowUs >= submittedAtUs ? nowUs - submittedAtUs : 0;
         [self adaptSoftwarePacingForLatencyUs:_latestEncodeLatencyUs];
-        [self adaptRealtimeHardwarePacingForLatencyUs:_latestEncodeLatencyUs];
+        [self adaptHardwarePacingForLatencyUs:_latestEncodeLatencyUs];
     }
     NSString *codec = nil;
     NSData *decoderConfig = nil;
diff --git a/docs/api/health.md b/docs/api/health.md
index d9397d8..91e3e34 100644
--- a/docs/api/health.md
+++ b/docs/api/health.md
@@ -28,6 +28,7 @@ Returns the static bootstrap information the browser client needs, plus a freshn
 | `videoCodec`                | Requested encoder mode. One of `auto`, `hardware`, or `software`. See [Video Pipeline](/guide/video). |
 | `lowLatency`                | `true` when software H.264 low-latency mode was enabled at daemon startup.                            |
 | `realtimeStream`            | `true` when the WebRTC stream is configured to favor freshness and realtime pacing.                   |
+| `localStreamFps`            | Local quality stream frame cap, from 15 to 120 fps. Defaults to 60.                                   |
 | `streamQuality`             | Active realtime quality profile and encoder limits such as `maxEdge`, `fps`, and bitrate.             |
 | `webRtc.iceServers`         | ICE servers the browser should use when creating the WebRTC peer connection.                          |
 | `webRtc.iceTransportPolicy` | Browser ICE transport policy. One of `all` or `relay`.                                                |
diff --git a/docs/cli/commands.md b/docs/cli/commands.md
index 9901622..0d34efa 100644
--- a/docs/cli/commands.md
+++ b/docs/cli/commands.md
@@ -32,7 +32,8 @@ Start or reuse the project daemon and serve the browser UI.
 ```sh
 simdeck ui [--port 4310] [--bind 127.0.0.1] [--advertise-host <host>]
            [--client-root <path>] [--video-codec auto|hardware|software]
-           [--low-latency] [--stream-quality <profile>] [--open]
+           [--low-latency] [--stream-quality <profile>]
+           [--local-stream-fps <15-120>] [--open]
 ```
 
 `--open` opens the authenticated local URL after the daemon is ready.
@@ -61,7 +62,7 @@ Start or reuse the project daemon without opening the browser:
 simdeck daemon start [--port 4310] [--bind 127.0.0.1]
                      [--advertise-host <host>] [--client-root <path>]
                      [--video-codec auto|hardware|software] [--low-latency]
-                     [--stream-quality <profile>]
+                     [--stream-quality <profile>] [--local-stream-fps <15-120>]
 ```
 
 Output:
@@ -97,7 +98,7 @@ options as `daemon start`:
 simdeck daemon restart [--port 4310] [--bind 127.0.0.1]
                        [--advertise-host <host>] [--client-root <path>]
                        [--video-codec auto|hardware|software] [--low-latency]
-                       [--stream-quality <profile>]
+                       [--stream-quality <profile>] [--local-stream-fps <15-120>]
 ```
 
 ### `daemon stop`
@@ -126,7 +127,8 @@ that starts after login and stays available.
 simdeck service on [--port 4310] [--bind 127.0.0.1]
                    [--advertise-host <host>] [--client-root <path>]
                    [--video-codec auto|hardware|software] [--low-latency]
-                   [--stream-quality <profile>] [--access-token <token>]
+                   [--stream-quality <profile>] [--local-stream-fps <15-120>]
+                   [--access-token <token>]
 simdeck service restart [same options as service on]
 simdeck service off
 ```
diff --git a/docs/cli/flags.md b/docs/cli/flags.md
index fafa451..9bbf9d9 100644
--- a/docs/cli/flags.md
+++ b/docs/cli/flags.md
@@ -37,6 +37,7 @@ Targets a specific running SimDeck daemon for commands that support the HTTP fas
 | `--video-codec`    | `auto`                | One of `auto`, `hardware`, or `software`. See [Video Pipeline](/guide/video).                           |
 | `--low-latency`    | `false`               | Software H.264 profile for slower runners: caps at 15 fps and favors freshness.                         |
 | `--stream-quality` | auto/default          | Optional realtime stream quality profile: `quality`, `balanced`, `smooth`, `economy`, or `ci-software`. |
+| `--local-stream-fps` | `60`                | Local quality stream frame cap, from 15 to 120 fps.                                                      |
 | `--open`           | `false`               | `ui` only. Open the browser after the daemon is ready.                                                  |
 
 `studio expose` defaults to software H.264. Pass `--video-codec hardware` to
diff --git a/docs/guide/daemon.md b/docs/guide/daemon.md
index a023214..2698a89 100644
--- a/docs/guide/daemon.md
+++ b/docs/guide/daemon.md
@@ -63,6 +63,7 @@ This starts or reuses the project daemon, serves the bundled browser client, and
 | `--video-codec`    | `auto`                | One of `auto`, `hardware`, or `software`. See [Video](/guide/video).                |
 | `--low-latency`    | `false`               | Software H.264 profile for slower runners; caps at 15 fps and drops stale frames.   |
 | `--stream-quality` | auto/default          | Optional realtime stream quality profile, including `ci-software` for CI providers. |
+| `--local-stream-fps` | `60`                | Local quality stream frame cap, from 15 to 120 fps.                                 |
 | `--open`           | `false`               | `ui` only. Open the browser after the daemon is ready.                              |
 
 Example:
diff --git a/docs/guide/video.md b/docs/guide/video.md
index edcef47..ed142a6 100644
--- a/docs/guide/video.md
+++ b/docs/guide/video.md
@@ -78,6 +78,7 @@ The WebRTC path favors freshness: stale frames are dropped and the sender reques
 A few practical guidelines:
 
 - **Start on the default for local preview.** `auto` lets VideoToolbox choose without requiring the shared hardware encoder.
+- **Use `--local-stream-fps 120` only for local high-refresh testing.** The local quality stream defaults to 60 fps; higher caps pace both capture refresh and hardware encode submission so the stream does not build delay by pushing unbounded frames.
 - **Switch to `software` when the hardware encoder stalls or is unavailable.** The encoder scales the longest edge to 1600 pixels, can climb toward 60 fps, and backs off dynamically under encode latency.
 - **Studio providers default to software H.264 plus `--stream-quality smooth`.** This profile uses a 1170-pixel longest edge, allows up to 60 fps, raises the bitrate budget to reduce compression artifacts, and lets multiple provider sessions share CPU cores without depending on one hardware encoder.
 - **The remote browser renders the live stream as a native `<video>` element.** The canvas remains for input geometry, but it is not in the live per-frame render path and does not preserve stale frames during reconnects.
diff --git a/server/src/api/routes.rs b/server/src/api/routes.rs
index 1d2e002..5660bd6 100644
--- a/server/src/api/routes.rs
+++ b/server/src/api/routes.rs
@@ -565,6 +565,7 @@ async fn health(State(state): State<AppState>) -> Json<Value> {
         "videoCodec": active_video_codec(&state.config),
         "lowLatency": state.config.low_latency,
         "realtimeStream": crate::transport::webrtc::realtime_stream_enabled(),
+        "localStreamFps": env_u32("SIMDECK_LOCAL_STREAM_FPS", 60, 15, 120),
         "streamQuality": stream_quality_state(),
         "webRtc": {
             "iceServers": crate::transport::webrtc::client_ice_servers(),
diff --git a/server/src/main.rs b/server/src/main.rs
index 130b3d4..c367f5c 100644
--- a/server/src/main.rs
+++ b/server/src/main.rs
@@ -85,6 +85,8 @@ enum Command {
         low_latency: bool,
         #[arg(long, value_enum)]
         stream_quality: Option<StreamQualityProfileArg>,
+        #[arg(long, value_parser = clap::value_parser!(u32).range(15..=120))]
+        local_stream_fps: Option<u32>,
         #[arg(long)]
         open: bool,
     },
@@ -112,6 +114,8 @@ enum Command {
         low_latency: bool,
         #[arg(long, value_enum)]
         stream_quality: Option<StreamQualityProfileArg>,
+        #[arg(long, value_parser = clap::value_parser!(u32).range(15..=120))]
+        local_stream_fps: Option<u32>,
         #[arg(long)]
         access_token: Option<String>,
         #[arg(long)]
@@ -386,6 +390,8 @@ enum DaemonCommand {
         low_latency: bool,
         #[arg(long, value_enum)]
         stream_quality: Option<StreamQualityProfileArg>,
+        #[arg(long, value_parser = clap::value_parser!(u32).range(15..=120))]
+        local_stream_fps: Option<u32>,
     },
     Restart {
         #[arg(long, default_value_t = 4310)]
@@ -402,6 +408,8 @@ enum DaemonCommand {
         low_latency: bool,
         #[arg(long, value_enum)]
         stream_quality: Option<StreamQualityProfileArg>,
+        #[arg(long, value_parser = clap::value_parser!(u32).range(15..=120))]
+        local_stream_fps: Option<u32>,
     },
     Stop,
     Killall,
@@ -426,6 +434,8 @@ enum DaemonCommand {
         low_latency: bool,
         #[arg(long, value_enum)]
         stream_quality: Option<StreamQualityProfileArg>,
+        #[arg(long, value_parser = clap::value_parser!(u32).range(15..=120))]
+        local_stream_fps: Option<u32>,
         #[arg(long)]
         access_token: String,
         #[arg(long)]
@@ -469,6 +479,8 @@ enum ServiceCommand {
         low_latency: bool,
         #[arg(long, value_enum)]
         stream_quality: Option<StreamQualityProfileArg>,
+        #[arg(long, value_parser = clap::value_parser!(u32).range(15..=120))]
+        local_stream_fps: Option<u32>,
         #[arg(long)]
         access_token: Option<String>,
     },
@@ -487,6 +499,8 @@ enum ServiceCommand {
         low_latency: bool,
         #[arg(long, value_enum)]
         stream_quality: Option<StreamQualityProfileArg>,
+        #[arg(long, value_parser = clap::value_parser!(u32).range(15..=120))]
+        local_stream_fps: Option<u32>,
         #[arg(long)]
         access_token: Option<String>,
     },
@@ -581,6 +595,8 @@ struct DaemonMetadata {
     realtime_stream: bool,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     stream_quality_profile: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    local_stream_fps: Option<u32>,
 }
 
 #[derive(Clone, Debug)]
@@ -593,6 +609,7 @@ struct DaemonLaunchOptions {
     low_latency: bool,
     realtime_stream: bool,
     stream_quality_profile: Option<String>,
+    local_stream_fps: Option<u32>,
 }
 
 struct StudioExposeOptions {
@@ -603,6 +620,7 @@ struct StudioExposeOptions {
     video_codec: VideoCodecMode,
     low_latency: bool,
     stream_quality: Option<StreamQualityProfileArg>,
+    local_stream_fps: Option<u32>,
 }
 
 impl VideoCodecMode {
@@ -716,6 +734,7 @@ impl Default for DaemonLaunchOptions {
             low_latency: false,
             realtime_stream: false,
             stream_quality_profile: None,
+            local_stream_fps: None,
         }
     }
 }
@@ -765,6 +784,10 @@ fn start_project_daemon(options: DaemonLaunchOptions) -> anyhow::Result<DaemonMe
     if options.low_latency {
         args.push("--low-latency".to_owned());
     }
+    if let Some(local_stream_fps) = options.local_stream_fps {
+        args.push("--local-stream-fps".to_owned());
+        args.push(local_stream_fps.to_string());
+    }
     if let Some(advertise_host) = options.advertise_host {
         args.push("--advertise-host".to_owned());
         args.push(advertise_host);
@@ -822,6 +845,9 @@ done
                 "0"
             },
         );
+    if let Some(local_stream_fps) = options.local_stream_fps {
+        command.env("SIMDECK_LOCAL_STREAM_FPS", local_stream_fps.to_string());
+    }
     if let Some(stream_quality_env) = stream_quality_env.as_ref() {
         command.env("SIMDECK_STREAM_QUALITY_PROFILE", stream_quality_env.profile);
         command.env(
@@ -857,6 +883,7 @@ done
         low_latency: options.low_latency,
         realtime_stream: options.realtime_stream || options.stream_quality_profile.is_some(),
         stream_quality_profile: options.stream_quality_profile,
+        local_stream_fps: options.local_stream_fps,
     };
     write_daemon_metadata(&metadata)?;
     wait_for_daemon(&metadata, Duration::from_secs(15))?;
@@ -999,6 +1026,7 @@ fn daemon_matches_launch_options(metadata: &DaemonMetadata, options: &DaemonLaun
         && metadata.realtime_stream
             == (options.realtime_stream || options.stream_quality_profile.is_some())
         && metadata.stream_quality_profile == options.stream_quality_profile
+        && metadata.local_stream_fps == options.local_stream_fps
 }
 
 fn read_daemon_metadata() -> anyhow::Result<Option<DaemonMetadata>> {
@@ -1216,6 +1244,7 @@ fn run_foreground_ui(selector: Option<String>) -> anyhow::Result<()> {
         low_latency,
         realtime_stream: false,
         stream_quality_profile: None,
+        local_stream_fps: None,
     };
     write_daemon_metadata(&metadata)?;
 
@@ -1238,6 +1267,7 @@ fn run_foreground_ui(selector: Option<String>) -> anyhow::Result<()> {
         video_codec,
         low_latency,
         None,
+        None,
         Some(access_token),
         Some(pairing_code),
     );
@@ -1289,6 +1319,7 @@ fn expose_to_studio(options: StudioExposeOptions) -> anyhow::Result<()> {
         low_latency: options.low_latency,
         realtime_stream: true,
         stream_quality_profile: stream_quality_profile.clone(),
+        local_stream_fps: options.local_stream_fps,
     })?;
     let selected = if let Some(selector) = options.simulator.as_deref() {
         select_studio_simulator(&metadata.http_url, selector)
@@ -1500,6 +1531,7 @@ fn main() -> anyhow::Result<()> {
             video_codec,
             low_latency,
             stream_quality,
+            local_stream_fps,
             open,
         } => {
             let (metadata, started) = ensure_project_daemon_with_status(DaemonLaunchOptions {
@@ -1512,6 +1544,7 @@ fn main() -> anyhow::Result<()> {
                 realtime_stream: false,
                 stream_quality_profile: stream_quality
                     .map(|profile| profile.as_profile_id().to_owned()),
+                local_stream_fps,
             })?;
             if open {
                 open_browser(&metadata.http_url)?;
@@ -1528,6 +1561,7 @@ fn main() -> anyhow::Result<()> {
                 video_codec,
                 low_latency,
                 stream_quality,
+                local_stream_fps,
             } => {
                 let (metadata, started) = ensure_project_daemon_with_status(DaemonLaunchOptions {
                     port,
@@ -1539,6 +1573,7 @@ fn main() -> anyhow::Result<()> {
                     realtime_stream: false,
                     stream_quality_profile: stream_quality
                         .map(|profile| profile.as_profile_id().to_owned()),
+                    local_stream_fps,
                 })?;
                 print_daemon_start_result(&metadata, started)
             }
@@ -1550,6 +1585,7 @@ fn main() -> anyhow::Result<()> {
                 video_codec,
                 low_latency,
                 stream_quality,
+                local_stream_fps,
             } => restart_detached_daemon(DaemonLaunchOptions {
                 port,
                 bind,
@@ -1560,6 +1596,7 @@ fn main() -> anyhow::Result<()> {
                 realtime_stream: false,
                 stream_quality_profile: stream_quality
                     .map(|profile| profile.as_profile_id().to_owned()),
+                local_stream_fps,
             }),
             DaemonCommand::Stop => stop_project_daemon(),
             DaemonCommand::Killall => kill_all_project_daemons(),
@@ -1574,9 +1611,13 @@ fn main() -> anyhow::Result<()> {
                 video_codec,
                 low_latency,
                 stream_quality,
+                local_stream_fps,
                 access_token,
                 pairing_code,
             } => {
+                if let Some(local_stream_fps) = local_stream_fps {
+                    env::set_var("SIMDECK_LOCAL_STREAM_FPS", local_stream_fps.to_string());
+                }
                 if let Some(stream_quality) = stream_quality {
                     apply_stream_quality_environment(stream_quality.as_profile_id())?;
                 }
@@ -1598,6 +1639,7 @@ fn main() -> anyhow::Result<()> {
                     realtime_stream: crate::transport::webrtc::realtime_stream_enabled()
                         || low_latency,
                     stream_quality_profile: env::var("SIMDECK_STREAM_QUALITY_PROFILE").ok(),
+                    local_stream_fps,
                 })?;
                 let result = serve_with_appkit(
                     port,
@@ -1607,6 +1649,7 @@ fn main() -> anyhow::Result<()> {
                     video_codec,
                     low_latency,
                     env::var("SIMDECK_STREAM_QUALITY_PROFILE").ok(),
+                    local_stream_fps,
                     Some(access_token),
                     pairing_code,
                 );
@@ -1635,6 +1678,7 @@ fn main() -> anyhow::Result<()> {
                 },
                 low_latency,
                 stream_quality,
+                local_stream_fps: None,
             }),
         },
         Command::Serve {
@@ -1645,6 +1689,7 @@ fn main() -> anyhow::Result<()> {
             video_codec,
             low_latency,
             stream_quality,
+            local_stream_fps,
             access_token,
             pairing_code,
         } => serve_with_appkit(
@@ -1655,6 +1700,7 @@ fn main() -> anyhow::Result<()> {
             video_codec,
             low_latency,
             stream_quality.map(|profile| profile.as_profile_id().to_owned()),
+            local_stream_fps,
             access_token,
             pairing_code,
         ),
@@ -1667,6 +1713,7 @@ fn main() -> anyhow::Result<()> {
                 video_codec,
                 low_latency,
                 stream_quality,
+                local_stream_fps,
                 access_token,
             } => service::enable(ServiceOptions {
                 port,
@@ -1677,6 +1724,7 @@ fn main() -> anyhow::Result<()> {
                 low_latency,
                 stream_quality_profile: stream_quality
                     .map(|profile| profile.as_profile_id().to_owned()),
+                local_stream_fps,
                 access_token,
                 pairing_code: None,
             }),
@@ -1688,6 +1736,7 @@ fn main() -> anyhow::Result<()> {
                 video_codec,
                 low_latency,
                 stream_quality,
+                local_stream_fps,
                 access_token,
             } => service::restart(ServiceOptions {
                 port,
@@ -1698,6 +1747,7 @@ fn main() -> anyhow::Result<()> {
                 low_latency,
                 stream_quality_profile: stream_quality
                     .map(|profile| profile.as_profile_id().to_owned()),
+                local_stream_fps,
                 access_token,
                 pairing_code: None,
             }),
@@ -2393,6 +2443,7 @@ struct ServiceOptions {
     video_codec: VideoCodecMode,
     low_latency: bool,
     stream_quality_profile: Option<String>,
+    local_stream_fps: Option<u32>,
     access_token: Option<String>,
     pairing_code: Option<String>,
 }
@@ -2406,11 +2457,17 @@ fn serve_with_appkit(
     video_codec: VideoCodecMode,
     low_latency: bool,
     stream_quality_profile: Option<String>,
+    local_stream_fps: Option<u32>,
     access_token: Option<String>,
     pairing_code: Option<String>,
 ) -> anyhow::Result<()> {
     std::env::set_var("SIMDECK_VIDEO_CODEC", video_codec.as_env_value());
     std::env::set_var("SIMDECK_LOW_LATENCY", if low_latency { "1" } else { "0" });
+    if let Some(local_stream_fps) = local_stream_fps {
+        std::env::set_var("SIMDECK_LOCAL_STREAM_FPS", local_stream_fps.to_string());
+    } else {
+        std::env::remove_var("SIMDECK_LOCAL_STREAM_FPS");
+    }
     if let Some(profile) = stream_quality_profile.as_deref() {
         apply_stream_quality_environment(profile)?;
     }
@@ -4812,6 +4869,24 @@ mod tests {
         }
     }
 
+    #[test]
+    fn local_daemon_start_accepts_local_stream_fps_range() {
+        let cli = Cli::parse_from(["simdeck", "daemon", "start", "--local-stream-fps", "120"]);
+        let Command::Daemon {
+            command: DaemonCommand::Start {
+                local_stream_fps, ..
+            },
+        } = cli.command
+        else {
+            panic!("expected daemon start command");
+        };
+        assert_eq!(local_stream_fps, Some(120));
+        assert!(
+            Cli::try_parse_from(["simdeck", "daemon", "start", "--local-stream-fps", "121"])
+                .is_err()
+        );
+    }
+
     #[test]
     fn legacy_h264_video_codec_modes_are_rejected() {
         assert!(
diff --git a/server/src/service.rs b/server/src/service.rs
index 387022b..a4efe26 100644
--- a/server/src/service.rs
+++ b/server/src/service.rs
@@ -187,6 +187,10 @@ fn plist_contents(
         program_arguments.push("--stream-quality".to_string());
         program_arguments.push(stream_quality_profile.clone());
     }
+    if let Some(local_stream_fps) = options.local_stream_fps {
+        program_arguments.push("--local-stream-fps".to_string());
+        program_arguments.push(local_stream_fps.to_string());
+    }
 
     if let Some(advertise_host) = options.advertise_host.as_ref() {
         program_arguments.push("--advertise-host".to_string());
diff --git a/server/src/transport/webrtc.rs b/server/src/transport/webrtc.rs
index 5aebf80..77c6230 100644
--- a/server/src/transport/webrtc.rs
+++ b/server/src/transport/webrtc.rs
@@ -41,6 +41,9 @@ const WEBRTC_BOOTSTRAP_KEYFRAME_INTERVAL: Duration = Duration::from_millis(150);
 const WEBRTC_BOOTSTRAP_KEYFRAME_REPEATS: u8 = 3;
 const WEBRTC_MIN_REFRESH_INTERVAL: Duration = Duration::from_millis(16);
 const WEBRTC_MAX_REFRESH_INTERVAL: Duration = Duration::from_millis(100);
+const WEBRTC_DEFAULT_LOCAL_STREAM_FPS: u32 = 60;
+const WEBRTC_MIN_LOCAL_STREAM_FPS: u32 = 15;
+const WEBRTC_MAX_LOCAL_STREAM_FPS: u32 = 120;
 const WEBRTC_LOW_LATENCY_REFRESH_INTERVAL: Duration = Duration::from_millis(67);
 const WEBRTC_LOW_LATENCY_MAX_REFRESH_INTERVAL: Duration = Duration::from_millis(250);
 const WEBRTC_WRITE_TIMEOUT: Duration = Duration::from_millis(120);
@@ -903,7 +906,7 @@ fn refresh_floor_for_low_latency(low_latency: bool) -> Duration {
     if low_latency {
         WEBRTC_LOW_LATENCY_REFRESH_INTERVAL
     } else {
-        WEBRTC_MIN_REFRESH_INTERVAL
+        local_stream_refresh_interval()
     }
 }
 
@@ -915,6 +918,18 @@ fn refresh_ceiling_for_low_latency(low_latency: bool) -> Duration {
     }
 }
 
+fn local_stream_refresh_interval() -> Duration {
+    let fps = std::env::var("SIMDECK_LOCAL_STREAM_FPS")
+        .ok()
+        .and_then(|value| value.trim().parse::<u32>().ok())
+        .unwrap_or(WEBRTC_DEFAULT_LOCAL_STREAM_FPS)
+        .clamp(WEBRTC_MIN_LOCAL_STREAM_FPS, WEBRTC_MAX_LOCAL_STREAM_FPS);
+    if fps == WEBRTC_DEFAULT_LOCAL_STREAM_FPS {
+        return WEBRTC_MIN_REFRESH_INTERVAL;
+    }
+    Duration::from_micros((1_000_000u64 / u64::from(fps)).max(1))
+}
+
 fn adaptive_interval_for_write(
     write_elapsed: Duration,
     refresh_floor: Duration,
diff --git a/skills/simdeck/SKILL.md b/skills/simdeck/SKILL.md
index 8b84b23..244ef2b 100644
--- a/skills/simdeck/SKILL.md
+++ b/skills/simdeck/SKILL.md
@@ -34,6 +34,9 @@ The browser uses WebRTC H.264 video for both hardware and software encoders.
 Add `--low-latency` on less capable runners to cap software H.264 at 15 fps,
 drop stale pending frames more aggressively, and cap the longest edge at 1170 px
 before latency piles up.
+For local high-refresh testing, pass `--local-stream-fps <15-120>` on `ui`,
+`daemon start`, or `daemon restart`. The default stays 60 fps; 120 fps is the
+maximum local cap.
 For remote browsers where Safari stalls but Chrome works, run the daemon with a
 TURN server and relay-only ICE:
 `SIMDECK_WEBRTC_ICE_SERVERS=turns:turn.example.com:5349?transport=tcp`,

From 47a32c30bd03fc60e6174e8f607855b1d76be6d6 Mon Sep 17 00:00:00 2001
From: DjDeveloperr <hey@djdev.me>
Date: Sat, 2 May 2026 18:51:58 -0400
Subject: [PATCH 4/5] Fix docs formatting for CI

---
 docs/cli/flags.md    | 22 +++++++++++-----------
 docs/guide/daemon.md | 22 +++++++++++-----------
 2 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/docs/cli/flags.md b/docs/cli/flags.md
index 9bbf9d9..dabccc9 100644
--- a/docs/cli/flags.md
+++ b/docs/cli/flags.md
@@ -28,17 +28,17 @@ Targets a specific running SimDeck daemon for commands that support the HTTP fas
 
 `ui`, `daemon start`, and `daemon restart` accept the same server options. `ui` also accepts `--open`.
 
-| Flag               | Default               | Description                                                                                             |
-| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------- |
-| `--port <u16>`     | `4310`                | HTTP port for the REST API, browser UI, and WebRTC offer endpoint.                                      |
-| `--bind <ip>`      | `127.0.0.1`           | Bind address (`0.0.0.0` for [LAN access](/guide/lan-access), `::` for IPv6).                            |
-| `--advertise-host` | matches local host    | Hostname or IP printed for LAN browser access.                                                          |
-| `--client-root`    | bundled `client/dist` | Override the static browser client directory.                                                           |
-| `--video-codec`    | `auto`                | One of `auto`, `hardware`, or `software`. See [Video Pipeline](/guide/video).                           |
-| `--low-latency`    | `false`               | Software H.264 profile for slower runners: caps at 15 fps and favors freshness.                         |
-| `--stream-quality` | auto/default          | Optional realtime stream quality profile: `quality`, `balanced`, `smooth`, `economy`, or `ci-software`. |
-| `--local-stream-fps` | `60`                | Local quality stream frame cap, from 15 to 120 fps.                                                      |
-| `--open`           | `false`               | `ui` only. Open the browser after the daemon is ready.                                                  |
+| Flag                 | Default               | Description                                                                                             |
+| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------- |
+| `--port <u16>`       | `4310`                | HTTP port for the REST API, browser UI, and WebRTC offer endpoint.                                      |
+| `--bind <ip>`        | `127.0.0.1`           | Bind address (`0.0.0.0` for [LAN access](/guide/lan-access), `::` for IPv6).                            |
+| `--advertise-host`   | matches local host    | Hostname or IP printed for LAN browser access.                                                          |
+| `--client-root`      | bundled `client/dist` | Override the static browser client directory.                                                           |
+| `--video-codec`      | `auto`                | One of `auto`, `hardware`, or `software`. See [Video Pipeline](/guide/video).                           |
+| `--low-latency`      | `false`               | Software H.264 profile for slower runners: caps at 15 fps and favors freshness.                         |
+| `--stream-quality`   | auto/default          | Optional realtime stream quality profile: `quality`, `balanced`, `smooth`, `economy`, or `ci-software`. |
+| `--local-stream-fps` | `60`                  | Local quality stream frame cap, from 15 to 120 fps.                                                     |
+| `--open`             | `false`               | `ui` only. Open the browser after the daemon is ready.                                                  |
 
 `studio expose` defaults to software H.264. Pass `--video-codec hardware` to
 opt into the hardware encoder when that is preferable.
diff --git a/docs/guide/daemon.md b/docs/guide/daemon.md
index 2698a89..b0334be 100644
--- a/docs/guide/daemon.md
+++ b/docs/guide/daemon.md
@@ -54,17 +54,17 @@ This starts or reuses the project daemon, serves the bundled browser client, and
 
 `daemon start`, `daemon restart`, and `ui` accept the same server options:
 
-| Flag               | Default               | Notes                                                                               |
-| ------------------ | --------------------- | ----------------------------------------------------------------------------------- |
-| `--port <u16>`     | `4310`                | HTTP port for the REST API, browser UI, and WebRTC offer endpoint.                  |
-| `--bind <ip>`      | `127.0.0.1`           | Bind address. Use `0.0.0.0` for [LAN access](/guide/lan-access).                    |
-| `--advertise-host` | matches local host    | Hostname or IP advertised to browser clients.                                       |
-| `--client-root`    | bundled `client/dist` | Override the static browser client directory.                                       |
-| `--video-codec`    | `auto`                | One of `auto`, `hardware`, or `software`. See [Video](/guide/video).                |
-| `--low-latency`    | `false`               | Software H.264 profile for slower runners; caps at 15 fps and drops stale frames.   |
-| `--stream-quality` | auto/default          | Optional realtime stream quality profile, including `ci-software` for CI providers. |
-| `--local-stream-fps` | `60`                | Local quality stream frame cap, from 15 to 120 fps.                                 |
-| `--open`           | `false`               | `ui` only. Open the browser after the daemon is ready.                              |
+| Flag                 | Default               | Notes                                                                               |
+| -------------------- | --------------------- | ----------------------------------------------------------------------------------- |
+| `--port <u16>`       | `4310`                | HTTP port for the REST API, browser UI, and WebRTC offer endpoint.                  |
+| `--bind <ip>`        | `127.0.0.1`           | Bind address. Use `0.0.0.0` for [LAN access](/guide/lan-access).                    |
+| `--advertise-host`   | matches local host    | Hostname or IP advertised to browser clients.                                       |
+| `--client-root`      | bundled `client/dist` | Override the static browser client directory.                                       |
+| `--video-codec`      | `auto`                | One of `auto`, `hardware`, or `software`. See [Video](/guide/video).                |
+| `--low-latency`      | `false`               | Software H.264 profile for slower runners; caps at 15 fps and drops stale frames.   |
+| `--stream-quality`   | auto/default          | Optional realtime stream quality profile, including `ci-software` for CI providers. |
+| `--local-stream-fps` | `60`                  | Local quality stream frame cap, from 15 to 120 fps.                                 |
+| `--open`             | `false`               | `ui` only. Open the browser after the daemon is ready.                              |
 
 Example:
 

From eff93c2f562335b8b5468ad2daaf261ad465bc68 Mon Sep 17 00:00:00 2001
From: DjDeveloperr <hey@djdev.me>
Date: Sat, 2 May 2026 19:22:31 -0400
Subject: [PATCH 5/5] Stabilize JS API text entry integration

---
 scripts/integration/js-api.mjs | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/scripts/integration/js-api.mjs b/scripts/integration/js-api.mjs
index cf84488..6582d97 100644
--- a/scripts/integration/js-api.mjs
+++ b/scripts/integration/js-api.mjs
@@ -202,7 +202,15 @@ async function main() {
       2_000,
     );
     await session.batch(simulatorUDID, [
-      { action: "type", text: "agent-ready", delayMs: 0 },
+      {
+        action: "tap",
+        selector: { id: "fixture.message" },
+        source: "native-ax",
+        maxDepth: 3,
+        waitTimeoutMs: 15_000,
+        durationMs: 30,
+      },
+      { action: "type", text: "agent-ready", delayMs: 12 },
       {
         action: "assert",
         selector: { id: "fixture.message" },