@limrun/ui 0.9.0-rc.14 → 0.9.0-rc.15

package/src/components/remote-control.tsx

@@ -157,10 +157,144 @@ interface RemoteControlProps {
    * (in which case the limulator side switches to a black-frame
    * fallback so the app keeps ticking).
    *
+   * `camera` (optional, only meaningful when `granted === true`)
+   * carries what `MediaStreamTrack.getSettings()` reported for the
+   * active capture: resolution, framerate, device label, facing
+   * mode. Use it to render a richer status indicator (e.g.
+   * "Camera · 1920×1080 · 30 fps · FaceTime HD").
+   *
    * Only iOS instances ever fire this callback; Android instances
    * have no camera-injector path and stay silent.
    */
-  onCameraDemandChange?: (active: boolean, granted?: boolean) => void;
+  onCameraDemandChange?: (
+    active: boolean,
+    granted?: boolean,
+    camera?: CameraCaptureInfo,
+  ) => void;
+
+  /**
+   * Periodically (~1Hz) fires with a snapshot of the outbound
+   * camera stream's live WebRTC stats — codec, encoder
+   * implementation, hardware acceleration, encoded fps, bitrate,
+   * round-trip-time, and the encoder's
+   * `qualityLimitationReason` (which is what Meet/Zoom use to
+   * decide whether to show "Bandwidth limited" or "CPU limited"
+   * banners).
+   *
+   * Only fires while the simulator is actively pulling the
+   * camera AND `getUserMedia` was granted. `null` is emitted
+   * once when the stream goes back to idle so consumers can
+   * clear their UI without having to maintain their own
+   * timeout. The host app does not need to poll `getStats()`
+   * itself — this is the canonical place.
+   */
+  onCameraStats?: (stats: CameraStreamStats | null) => void;
+
+  /**
+   * Optional resolution cap for outbound camera capture.
+   *
+   * - `'auto'` (default): no extra constraint. The browser captures
+   *   at its webcam's native max; WebRTC's quality scaler may step
+   *   down resolution on the encoder side under bandwidth pressure
+   *   while still feeding the simulator at the pool's native size.
+   * - `'1080p'` / `'720p'` / `'480p'`: hard cap applied via
+   *   `getUserMedia` constraints (for new captures) and
+   *   `track.applyConstraints` (for the currently-active track),
+   *   matching the way Meet/Zoom expose a "Send resolution" picker.
+   *
+   * Bumping or lowering the cap mid-stream is supported; the
+   * change takes effect within a frame or two as the webcam
+   * re-negotiates.
+   */
+  cameraResolutionCap?: CameraResolutionCap;
+  /**
+   * Aspect ratio the simulator's virtual camera should report to apps.
+   * Picking a value here triggers a `cameraAspect` WS message to the
+   * host, which rebuilds its IOSurface ring at the matching dimensions
+   * (16:9 → 1920×1080, 4:3 → 1440×1080, 1:1 → 1080×1080, 9:16 →
+   * 1080×1920) and signals the in-sim dylib to re-handshake. iOS apps
+   * see CMSampleBuffers at the new dimensions within a frame or two.
+   *
+   * The browser still captures whatever the webcam offers; the host
+   * aspect-fills (cover, center-crop) into the new pool. Switching
+   * aspect at runtime is intentionally cheap so users can A/B preview
+   * styles without restarting the simulator.
+   *
+   * `undefined` leaves the pool untouched (the host's boot default —
+   * 16:9 / 1920×1080 — applies).
+   */
+  cameraAspect?: CameraAspect;
+}
+
+/**
+ * Resolution caps a host app can request on the outbound camera.
+ * `'auto'` is "let the browser decide" (no constraints beyond the
+ * 30 fps ceiling); the other options clamp width/height to the
+ * named target. Aspect ratio is preserved.
+ */
+export type CameraResolutionCap = 'auto' | '1080p' | '720p' | '480p';
+
+/**
+ * Aspect ratios exposed to the operator for the simulated camera.
+ * The host maps each label to concrete IOSurface dimensions; values
+ * the host doesn't recognise are silently ignored.
+ */
+export type CameraAspect = '16:9' | '4:3' | '1:1' | '9:16';
+
+/**
+ * Snapshot of the browser's webcam capture, mirrored from
+ * `MediaStreamTrack.getSettings()`. Forwarded to the host alongside
+ * `cameraResult` and exposed to the host app via
+ * `onCameraDemandChange` so it can render a status indicator without
+ * having to call `getStats()` itself.
+ */
+export interface CameraCaptureInfo {
+  width?: number;
+  height?: number;
+  frameRate?: number;
+  deviceId?: string;
+  label?: string;
+  facingMode?: string;
+}
+
+/**
+ * Live outbound-camera quality snapshot. Derived from
+ * `RTCPeerConnection.getStats()` and rate-derived deltas, sampled
+ * once per second while the camera is sending. All fields optional:
+ * some browsers omit fields (Safari rarely reports
+ * `encoderImplementation`), and the first sample after camera start
+ * has no delta-derived numbers yet.
+ */
+export interface CameraStreamStats {
+  /** "H264", "HEVC"/"H265", "VP9", "VP8", "AV1", etc. (uppercased). */
+  codec?: string;
+  /** e.g. "VideoToolbox" (hw), "OpenH264" (sw), "ExternalEncoder". */
+  encoderImplementation?: string;
+  /**
+   * Browser-reported hardware-acceleration hint. Some Chromium
+   * versions expose this via `powerEfficientEncoder`; we mirror it
+   * here so consumers don't have to know the spec quirk.
+   */
+  hardwareAccelerated?: boolean;
+  /** Outbound encoded fps over the last sample window. */
+  framesPerSecond?: number;
+  /** Cumulative encoded frame count. */
+  framesEncoded?: number;
+  /** Outbound encoded bitrate (bits/s) over the last window. */
+  bitrateBps?: number;
+  /** Width/height the encoder is currently producing. */
+  width?: number;
+  height?: number;
+  /**
+   * One of `'none' | 'cpu' | 'bandwidth' | 'other'`. Mirrors
+   * Meet/Zoom's "limited by …" banners. Anything other than
+   * `'none'` means the encoder dropped resolution to keep up.
+   */
+  qualityLimitationReason?: string;
+  /** Round-trip time in milliseconds, from the matching RTCP. */
+  rttMs?: number;
+  /** Packet-loss percentage over the last sample window (0..100). */
+  packetsLostPct?: number;
 }
 
 interface ScreenshotData {
@@ -360,6 +494,9 @@ export const RemoteControl = forwardRef<RemoteControlHandle, RemoteControlProps>
       axPollIntervalMs,
       axMaxBackoffMs,
       onCameraDemandChange,
+      onCameraStats,
+      cameraResolutionCap = 'auto',
+      cameraAspect,
     }: RemoteControlProps,
     ref,
   ) => {
@@ -403,11 +540,36 @@ export const RemoteControl = forwardRef<RemoteControlHandle, RemoteControlProps>
     // green light.
     const outboundCameraSenderRef = useRef<RTCRtpSender | null>(null);
     const outboundLocalStreamRef = useRef<MediaStream | null>(null);
+    const cameraResolutionCapRef = useRef(cameraResolutionCap);
+    cameraResolutionCapRef.current = cameraResolutionCap;
+    // The aspect prop also rides a ref so the WS `onopen` reconnect
+    // path can replay the operator's last pick without depending on
+    // an in-flight render cycle. We mutate it inline (same render-
+    // time pattern as the cap ref) so a parent prop change is visible
+    // to closures captured during the next render; the useEffect
+    // below handles the actual "send to host" side-effect.
+    const cameraAspectRef = useRef<CameraAspect | undefined>(cameraAspect);
+    cameraAspectRef.current = cameraAspect;
     // Mirror the demand-change callback into a ref so the WS message
     // handler always sees the freshest customer callback even when the
     // parent re-renders mid-session.
     const onCameraDemandChangeRef = useRef(onCameraDemandChange);
     onCameraDemandChangeRef.current = onCameraDemandChange;
+    const onCameraStatsRef = useRef(onCameraStats);
+    onCameraStatsRef.current = onCameraStats;
+    // Active outbound-camera stats poller. While the camera is
+    // sending we sample `RTCPeerConnection.getStats()` once per
+    // second, derive deltas (bitrate, fps, packet loss) from the
+    // previous sample, and push the result through `onCameraStats`.
+    // Cleared on teardown so we never leak the timer.
+    const cameraStatsTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+    const cameraStatsPrevRef = useRef<{
+      timestamp: number;
+      framesEncoded?: number;
+      bytesSent?: number;
+      packetsSent?: number;
+      packetsLost?: number;
+    } | null>(null);
     const firstFrameShownRef = useRef(false);
     const pendingScreenshotResolversRef = useRef<
       Map<string, (value: ScreenshotData | PromiseLike<ScreenshotData>) => void>
@@ -1506,6 +1668,150 @@ export const RemoteControl = forwardRef<RemoteControlHandle, RemoteControlProps>
       stopMediaStream(stream);
     };
 
+    // Translate the user-facing resolution cap into a
+    // MediaTrackConstraints fragment we can feed `getUserMedia`
+    // or `applyConstraints`. Always returns a 30 fps ceiling so
+    // a 60 fps webcam doesn't double our encoder cost for no
+    // visible win (the simulator pool is paced at 30).
+    //
+    // We use `ideal` rather than `max` so that a webcam with a
+    // native 720p mode still hands us 720p when the user picks
+    // 1080p — instead of refusing the constraint outright. The
+    // browser's NotReadableError on a too-strict `max` is the
+    // most common camera-permission gotcha in the wild.
+    const cameraCapToConstraints = (cap: CameraResolutionCap): MediaTrackConstraints => {
+      const base: MediaTrackConstraints = {
+        frameRate: { ideal: 30, max: 30 },
+      };
+      switch (cap) {
+        case '1080p':
+          return { ...base, width: { ideal: 1920 }, height: { ideal: 1080 } };
+        case '720p':
+          return { ...base, width: { ideal: 1280 }, height: { ideal: 720 } };
+        case '480p':
+          return { ...base, width: { ideal: 854 }, height: { ideal: 480 } };
+        case 'auto':
+        default:
+          return base;
+      }
+    };
+
+    // Convert the codec mime type (e.g. "video/H264" or "video/HEVC")
+    // into a short uppercase label suitable for a status badge.
+    const shortenCodecMime = (mime: string | undefined): string | undefined => {
+      if (!mime) return undefined;
+      const slash = mime.indexOf('/');
+      const tail = slash >= 0 ? mime.slice(slash + 1) : mime;
+      const upper = tail.toUpperCase();
+      if (upper === 'HEVC') return 'H265';
+      return upper;
+    };
+
+    // Sample outbound-camera stats once and push a normalised
+    // snapshot through `onCameraStats`. Skips silently if the sender
+    // has been torn down between intervals.
+    const sampleOutboundCameraStats = async () => {
+      const sender = outboundCameraSenderRef.current;
+      const handler = onCameraStatsRef.current;
+      if (!sender || !handler) return;
+      let report: RTCStatsReport;
+      try {
+        report = await sender.getStats();
+      } catch {
+        return;
+      }
+      let outbound: any | undefined;
+      let codecMime: string | undefined;
+      let remoteInbound: any | undefined;
+      report.forEach((entry: any) => {
+        if (entry.type === 'outbound-rtp' && entry.kind === 'video') {
+          outbound = entry;
+        } else if (entry.type === 'remote-inbound-rtp' && entry.kind === 'video') {
+          remoteInbound = entry;
+        }
+      });
+      if (outbound?.codecId) {
+        const codec = report.get(outbound.codecId);
+        if (codec) codecMime = (codec as any).mimeType;
+      }
+      if (!outbound) return;
+      const now = (outbound.timestamp as number) ?? Date.now();
+      const prev = cameraStatsPrevRef.current;
+      let fps: number | undefined;
+      let bitrate: number | undefined;
+      let lossPct: number | undefined;
+      if (prev && now > prev.timestamp) {
+        const dt = (now - prev.timestamp) / 1000;
+        if (
+          typeof outbound.framesEncoded === 'number' &&
+          typeof prev.framesEncoded === 'number'
+        ) {
+          fps = Math.max(0, (outbound.framesEncoded - prev.framesEncoded) / dt);
+        }
+        if (typeof outbound.bytesSent === 'number' && typeof prev.bytesSent === 'number') {
+          bitrate = Math.max(0, ((outbound.bytesSent - prev.bytesSent) * 8) / dt);
+        }
+        if (
+          typeof outbound.packetsSent === 'number' &&
+          typeof prev.packetsSent === 'number' &&
+          remoteInbound &&
+          typeof remoteInbound.packetsLost === 'number' &&
+          typeof prev.packetsLost === 'number'
+        ) {
+          const sent = outbound.packetsSent - prev.packetsSent;
+          const lost = remoteInbound.packetsLost - prev.packetsLost;
+          if (sent > 0) lossPct = Math.max(0, Math.min(100, (lost / sent) * 100));
+        }
+      }
+      cameraStatsPrevRef.current = {
+        timestamp: now,
+        framesEncoded: outbound.framesEncoded,
+        bytesSent: outbound.bytesSent,
+        packetsSent: outbound.packetsSent,
+        packetsLost: remoteInbound?.packetsLost,
+      };
+      const stats: CameraStreamStats = {
+        codec: shortenCodecMime(codecMime),
+        encoderImplementation: outbound.encoderImplementation,
+        hardwareAccelerated:
+          typeof outbound.powerEfficientEncoder === 'boolean'
+            ? outbound.powerEfficientEncoder
+            : undefined,
+        framesPerSecond: fps,
+        framesEncoded: outbound.framesEncoded,
+        bitrateBps: bitrate,
+        width: outbound.frameWidth,
+        height: outbound.frameHeight,
+        qualityLimitationReason: outbound.qualityLimitationReason,
+        rttMs:
+          typeof remoteInbound?.roundTripTime === 'number'
+            ? remoteInbound.roundTripTime * 1000
+            : undefined,
+        packetsLostPct: lossPct,
+      };
+      safeInvoke('onCameraStats', onCameraStatsRef.current, stats);
+    };
+
+    const startCameraStatsPoller = () => {
+      if (cameraStatsTimerRef.current !== null) return;
+      cameraStatsPrevRef.current = null;
+      // First sample fires after one interval — the very first
+      // sample has no deltas to compare against, which is fine: the
+      // codec/encoder identity is still useful on its own.
+      cameraStatsTimerRef.current = setInterval(() => {
+        void sampleOutboundCameraStats();
+      }, 1000);
+    };
+
+    const stopCameraStatsPoller = () => {
+      if (cameraStatsTimerRef.current !== null) {
+        clearInterval(cameraStatsTimerRef.current);
+        cameraStatsTimerRef.current = null;
+      }
+      cameraStatsPrevRef.current = null;
+      safeInvoke('onCameraStats', onCameraStatsRef.current, null);
+    };
+
     const teardownConnection = () => {
       clearConnectionSuccessTimeout();
       clearIceDisconnectedGrace();
@@ -1517,6 +1823,7 @@ export const RemoteControl = forwardRef<RemoteControlHandle, RemoteControlProps>
       // Drop any active outbound camera before the PC dies so the
       // browser doesn't leave the camera indicator lit between
       // reconnects.
+      stopCameraStatsPoller();
       stopOutboundLocalStream();
       outboundCameraSenderRef.current = null;
       // A scheduled cursor flush would otherwise call setState on a
@@ -1644,6 +1951,21 @@ export const RemoteControl = forwardRef<RemoteControlHandle, RemoteControlProps>
             if (!isCurrentAttempt() || wsRef.current !== ws) {
               return;
             }
+            // Replay the saved camera aspect for fresh connections
+            // (initial mount, autoreconnect, sim reboot). The host's
+            // streamer starts at its boot default (16:9 / 1920×1080)
+            // and a missing message would mean the operator's pick
+            // silently reverts on reconnect. We always send something
+            // when the prop is set, even if it matches the host
+            // default — the host short-circuits no-op rebuilds.
+            const initialAspect = cameraAspectRef.current;
+            if (initialAspect) {
+              try {
+                ws.send(JSON.stringify({ type: 'cameraAspect', aspect: initialAspect }));
+              } catch (err) {
+                debugWarn('initial cameraAspect send failed:', err);
+              }
+            }
             settle(resolve);
           };
 
@@ -1758,6 +2080,59 @@ export const RemoteControl = forwardRef<RemoteControlHandle, RemoteControlProps>
           }
         }
 
+        // Pin the outbound camera transceiver's codec order with
+        // negotiation-time fallback. Preference order:
+        //   1. H.265 / HEVC  — VideoToolbox HW on M-series + recent
+        //      Chrome. ~30% less bitrate at equal quality. If the
+        //      answerer (limulator) supports HEVC, this wins.
+        //   2. H.264 with VideoToolbox-friendly profile-level-ids
+        //      (42e01f / 42e028 / 640c1f). Universally HW-accelerated
+        //      on every Mac since 2009. SDP-time fallback when HEVC
+        //      isn't in the answer.
+        //   3. Any other H.264 profile. Often resolves to OpenH264
+        //      (software) so we keep it explicitly last among H.264
+        //      to avoid Chrome's default pick.
+        //   4. VP9 / VP8 (libvpx software on Mac). Last resort.
+        //
+        // Caveat: this is *negotiation* fallback. If HEVC HW encoder
+        // init fails at session start or gets demoted mid-stream,
+        // Chrome falls back to *software* HEVC, not H.264 — no spec
+        // hook for runtime re-negotiation. The host-side stats
+        // logger will surface this as decoder=ffmpeg / hw=false.
+        if (RTCRtpSender.getCapabilities) {
+          const senderCaps = RTCRtpSender.getCapabilities('video');
+          if (senderCaps && senderCaps.codecs) {
+            const vtH264Profiles = new Set(['42e01f', '42e028', '640c1f']);
+            const score = (c: { mimeType: string; sdpFmtpLine?: string }): number => {
+              const mime = c.mimeType.toLowerCase();
+              const fmtp = (c.sdpFmtpLine || '').toLowerCase();
+              const profileMatch = fmtp.match(/profile-level-id=([0-9a-f]{6})/);
+              const profile = profileMatch ? profileMatch[1] : '';
+              if (mime === 'video/h265' || mime === 'video/hevc') return 1;
+              if (mime === 'video/h264' && vtH264Profiles.has(profile)) return 2;
+              if (mime === 'video/h264') return 3;
+              if (mime === 'video/vp9') return 4;
+              if (mime === 'video/vp8') return 5;
+              if (mime === 'video/rtx' || mime === 'video/red' || mime === 'video/ulpfec') {
+                return 0; // Keep RTX/FEC available alongside everything else.
+              }
+              return 6;
+            };
+            const sortedSendCodecs = [...senderCaps.codecs].sort((a, b) => score(a) - score(b));
+            try {
+              outboundCameraTransceiver.setCodecPreferences(sortedSendCodecs);
+              debugLog(
+                'Outbound camera codec preferences:',
+                sortedSendCodecs
+                  .map((c) => `${c.mimeType}${c.sdpFmtpLine ? `[${c.sdpFmtpLine}]` : ''}`)
+                  .join(', '),
+              );
+            } catch (err) {
+              debugWarn('Failed to set outbound camera codec preferences:', err);
+            }
+          }
+        }
+
         const dataChannel = peerConnection.createDataChannel('control', {
           ordered: true,
           negotiated: true,
@@ -2063,6 +2438,12 @@ export const RemoteControl = forwardRef<RemoteControlHandle, RemoteControlProps>
               break;
             case 'cameraRequest': {
               const active = message.active === true;
+              // Log unconditionally — this is one of the few places we
+              // hand control to the browser's permission UI, and a
+              // silent failure here looks identical to "limulator
+              // never asked" from the user's point of view.
+              // eslint-disable-next-line no-console
+              console.info('[RemoteControl] cameraRequest received, active=', active);
               if (!active) {
                 // Sim no longer wants frames. Drop our local track and
                 // shut the browser's camera green light off.
@@ -2074,6 +2455,7 @@ export const RemoteControl = forwardRef<RemoteControlHandle, RemoteControlProps>
                     debugWarn('replaceTrack(null) on camera detach failed:', err);
                   }
                 }
+                stopCameraStatsPoller();
                 stopOutboundLocalStream();
                 safeInvoke('onCameraDemandChange', onCameraDemandChangeRef.current, false);
                 break;
@@ -2083,14 +2465,40 @@ export const RemoteControl = forwardRef<RemoteControlHandle, RemoteControlProps>
               // `cameraResult` message so it can swap to a
               // black-frame fallback on denial.
               safeInvoke('onCameraDemandChange', onCameraDemandChangeRef.current, true);
+              if (!navigator.mediaDevices || typeof navigator.mediaDevices.getUserMedia !== 'function') {
+                // Likely an insecure context (http on a non-localhost
+                // origin) — Chrome strips `mediaDevices` off
+                // `navigator` in that case and the only signal is
+                // this undefined check.
+                // eslint-disable-next-line no-console
+                console.warn(
+                  '[RemoteControl] navigator.mediaDevices.getUserMedia unavailable. ' +
+                  'getUserMedia requires a secure context (https or http://localhost). ' +
+                  'Replying cameraResult granted=false so limulator falls back to black frames.',
+                );
+                ws.send(JSON.stringify({ type: 'cameraResult', granted: false }));
+                safeInvoke('onCameraDemandChange', onCameraDemandChangeRef.current, true, false);
+                break;
+              }
               let stream: MediaStream | null = null;
               try {
+                // Capture at the webcam's *native* resolution by
+                // default (no width/height constraints). When the
+                // host app has picked an explicit cap via
+                // `cameraResolutionCap`, we honour it here. Frame
+                // rate is always capped to 30 to match the
+                // simulator pool's pacing.
                 stream = await navigator.mediaDevices.getUserMedia({
-                  video: true,
+                  video: cameraCapToConstraints(cameraResolutionCapRef.current),
                   audio: false,
                 });
               } catch (err) {
-                debugWarn('getUserMedia denied/failed:', err);
+                // Surface unconditionally — the user is the only one
+                // who can fix this (permission denied, no device,
+                // dismissed prompt, etc.). `debugWarn` alone would
+                // hide it in normal builds.
+                // eslint-disable-next-line no-console
+                console.warn('[RemoteControl] getUserMedia denied/failed:', err);
               }
               if (!isCurrentAttempt() || wsRef.current !== ws) {
                 if (stream) stopMediaStream(stream);
@@ -2125,19 +2533,106 @@ export const RemoteControl = forwardRef<RemoteControlHandle, RemoteControlProps>
                 safeInvoke('onCameraDemandChange', onCameraDemandChangeRef.current, true, false);
                 break;
               }
+              // Tell the encoder this is real motion content (a
+              // physical camera), not text/slides. With `'motion'`
+              // VideoToolbox / libvpx pick latency-friendly tuning
+              // (no extra B-frames, shorter GoP smoothing). Set
+              // before the first frame so the encoder init reads it.
+              try {
+                videoTrack.contentHint = 'motion';
+              } catch {
+                /* older browsers don't support contentHint; ignore */
+              }
+              // Bound the outbound bitrate generously and let
+              // WebRTC's congestion control (BWE) find the floor.
+              // 8 Mbps is comfortable for native 1080p30 webcam
+              // content over LAN — the encoder will use far less when
+              // the scene is static, and BWE will throttle if a
+              // hop is constrained. Pair with
+              // `maintain-framerate` so the quality scaler steps
+              // down resolution before dropping frames, matching how
+              // Meet/Zoom degrade.
+              try {
+                const params = sender.getParameters();
+                if (!params.encodings || params.encodings.length === 0) {
+                  params.encodings = [{}];
+                }
+                params.encodings[0].maxBitrate = 8_000_000;
+                params.encodings[0].maxFramerate = 30;
+                params.degradationPreference = 'maintain-framerate';
+                await sender.setParameters(params);
+              } catch (err) {
+                debugWarn('setParameters on outbound camera failed:', err);
+              }
+              // Surface the actual captured geometry to the host so
+              // it can size its IOSurface pool / picture-format
+              // metadata to match. `getSettings()` returns what the
+              // browser actually picked — which may differ from any
+              // hints we sent in the constraints — including the
+              // selected `deviceId` / `label` (useful when a user has
+              // multiple cameras and we eventually expose a picker).
+              let cameraMetadata: {
+                width?: number;
+                height?: number;
+                frameRate?: number;
+                deviceId?: string;
+                label?: string;
+                facingMode?: string;
+              } = {};
+              try {
+                const settings = videoTrack.getSettings();
+                cameraMetadata = {
+                  width: settings.width,
+                  height: settings.height,
+                  frameRate: settings.frameRate,
+                  deviceId: settings.deviceId,
+                  label: videoTrack.label || undefined,
+                  facingMode: settings.facingMode,
+                };
+                // eslint-disable-next-line no-console
+                console.info(
+                  `[RemoteControl] camera capture: ${cameraMetadata.width}x${cameraMetadata.height}` +
+                  ` @ ${cameraMetadata.frameRate ?? '?'}fps` +
+                  (cameraMetadata.label ? ` — ${cameraMetadata.label}` : ''),
+                );
+              } catch (err) {
+                debugWarn('getSettings() on outbound camera track failed:', err);
+              }
               // If the browser revokes the track later (extension,
               // user clicks Stop in the camera tab UI, etc.), notify
               // the host so it can switch to black frames.
               videoTrack.onended = () => {
                 if (outboundLocalStreamRef.current !== stream) return;
+                stopCameraStatsPoller();
                 stopOutboundLocalStream();
                 if (wsRef.current === ws && ws.readyState === WebSocket.OPEN) {
                   ws.send(JSON.stringify({ type: 'cameraResult', granted: false }));
                 }
                 safeInvoke('onCameraDemandChange', onCameraDemandChangeRef.current, true, false);
               };
-              ws.send(JSON.stringify({ type: 'cameraResult', granted: true }));
-              safeInvoke('onCameraDemandChange', onCameraDemandChangeRef.current, true, true);
+              ws.send(JSON.stringify({
+                type: 'cameraResult',
+                granted: true,
+                // Forward what the browser actually captured so the
+                // host can size its IOSurface pool, log the device,
+                // and (eventually) surface a status pill / picker.
+                camera: cameraMetadata,
+              }));
+              safeInvoke(
+                'onCameraDemandChange',
+                onCameraDemandChangeRef.current,
+                true,
+                true,
+                cameraMetadata,
+              );
+              // Kick off the per-second outbound stats sampler. We do
+              // this *after* `setParameters` so the first sample
+              // already sees the encoder under its final bitrate /
+              // degradation policy, and *after* the host-side
+              // attachInboundTrack will have wired up (the
+              // cameraResult ACK is what triggers it on the host),
+              // so framesEncoded starts climbing immediately.
+              startCameraStatsPoller();
               break;
             }
             case 'terminateAppResult':
@@ -2227,6 +2722,41 @@ export const RemoteControl = forwardRef<RemoteControlHandle, RemoteControlProps>
       start();
     };
 
+    // Re-apply the resolution cap on the currently-sending track
+    // whenever the host app changes its preference. Skips when no
+    // camera is active — the next `getUserMedia` will pick up the
+    // new value via `cameraCapToConstraints` automatically.
+    useEffect(() => {
+      const stream = outboundLocalStreamRef.current;
+      if (!stream) return;
+      const track = stream.getVideoTracks()[0];
+      if (!track) return;
+      const constraints = cameraCapToConstraints(cameraResolutionCap);
+      track.applyConstraints(constraints).catch((err) => {
+        debugWarn('applyConstraints for new camera cap failed:', err);
+      });
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [cameraResolutionCap]);
+
+    // Push the aspect preference to the host whenever it changes.
+    // The host rebuilds its IOSurface pool and bumps `pool_generation`
+    // on its end; the dylib re-handshakes on next sem_wait. No
+    // peer-connection renegotiation is needed — the aspect change is
+    // purely about the pixel buffer dimensions iOS apps observe, not
+    // about WebRTC track layout. The `cameraAspectRef` is mirrored
+    // higher up so the WS `onopen` reconnect path can replay the
+    // latest value on fresh connections.
+    useEffect(() => {
+      if (!cameraAspect) return;
+      const ws = wsRef.current;
+      if (!ws || ws.readyState !== WebSocket.OPEN) return;
+      try {
+        ws.send(JSON.stringify({ type: 'cameraAspect', aspect: cameraAspect }));
+      } catch (err) {
+        debugWarn('cameraAspect send failed:', err);
+      }
+    }, [cameraAspect]);
+
     useEffect(() => {
       // Reset video loaded state when connection params change
       setVideoLoaded(false);