@limrun/ui 0.14.0-rc.1 → 0.14.0-rc.2

package/dist/components/remote-control.d.ts

@@ -14,6 +14,18 @@ interface RemoteControlProps {
     openUrl?: string;
     showFrame?: boolean;
     autoReconnect?: boolean;
+    /**
+     * Fires once when the component concludes the instance is permanently
+     * gone rather than suffering a recoverable connection blip.
+     *
+     * After a drop, the component probes the instance endpoint over HTTP;
+     * a 404 means the instance no longer exists (terminated/deleted). When
+     * that happens the component stops reconnecting and renders a built-in
+     * "terminated" message in place of the "Retry" button, and invokes this
+     * callback so the host can react (navigate away, surface its own UI,
+     * etc.). It is not called for ordinary network drops.
+     */
+    onTerminated?: () => void;
     /**
      * Enable the inspect overlay. When set, the component starts polling the
      * accessibility tree and draws boxes over each element on top of the
@@ -93,6 +105,150 @@ interface RemoteControlProps {
      * @default 2000
      */
     axMaxBackoffMs?: number;
+    /**
+     * Fires whenever the iOS simulator's camera demand state changes —
+     * i.e. an app inside the sim called
+     * `[AVCaptureSession startRunning]` or `[stopRunning]`. The
+     * component handles the `navigator.mediaDevices.getUserMedia` prompt
+     * and SDP plumbing internally; this callback is purely so the host
+     * UI can render a status indicator ("simulator is using your
+     * camera", etc.).
+     *
+     * `active` reflects whether the sim is currently asking for
+     * frames. `granted` is set only on the call that follows a
+     * `getUserMedia` attempt: `true` when the user accepted the
+     * browser prompt, `false` when they denied or the call failed
+     * (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, 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 {
     dataUri: string;