@limrun/ui 0.15.0 → 0.16.0

package/README.md

@@ -6,6 +6,33 @@ types and helpers for building inspect, search, and agent interfaces.
 
 See [examples](../../examples/) to see how it can be used.
 
+## Frameless embeds
+
+`@limrun/ui` bundles Limrun's device frames and boot logos as inline images, about
+600 KB. Embeds that render the bare screen can import `@limrun/ui/lite` instead: the same
+`RemoteControl` API without any artwork, so `showFrame` has nothing to draw and the boot
+logo is omitted. Pass your own images through the `assets` prop if you want frames back.
+
+`onConnectionStateChange` reports `connecting`, `connected`, `reconnecting`, `failed`, and
+`terminated` so a host can show status text without tracking the retry logic.
+
+## Simulated cameras
+
+`RemoteControl` responds automatically when an app in the instance opens,
+closes, or switches a virtual camera. Camera facing is a preference: the
+component requests the browser's `user` or `environment` camera with an
+`ideal` constraint and falls back to an available input. Repeated requests for
+the same facing reuse the live track. Facing changes restart capture so mobile
+browsers can release one camera before opening the other.
+
+WebRTC and the browser choose the capture resolution. The simulated camera's
+host output follows the decoded frame dimensions, including width/height swaps
+when captured video rotates. `onCameraDemandChange` receives fresh
+`MediaStreamTrack.getSettings()` status metadata after track changes.
+
+Camera API types (`CameraRequest`, `CameraResult`, `CameraFacingMode`,
+`CameraCaptureInfo`, and `CameraStreamStats`) are exported from `@limrun/ui`.
+
 Related browser workflow packages are published separately:
 
 - `@limrun/apple-auth` handles Apple ID login, signing credentials, and App

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

@@ -0,0 +1,2 @@
+import { RemoteControlHandle, RemoteControlProps } from './remote-control';
+export declare const RemoteControl: import('react').ForwardRefExoticComponent<RemoteControlProps & import('react').RefAttributes<RemoteControlHandle>>;

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

@@ -1,12 +1,14 @@
 import { default as React } from 'react';
-import { AxStatus } from '../core/ax-fetcher';
+import { AxStatus, AndroidElementTreeOptions } from '../core/ax-fetcher';
 import { AxElement, AxSnapshot } from '../core/ax-tree';
+import { CameraCaptureInfo } from '../core/camera';
+export type { CameraCaptureInfo, CameraFacingMode, CameraRequest, CameraResult } from '../core/camera';
 declare global {
     interface Window {
         debugRemoteControl?: boolean;
     }
 }
-interface RemoteControlProps {
+export interface RemoteControlProps {
     url: string;
     token: string;
     className?: string;
@@ -26,6 +28,15 @@ interface RemoteControlProps {
      * etc.). It is not called for ordinary network drops.
      */
     onTerminated?: () => void;
+    /**
+     * Device frame and boot-logo images. The default export bundles Limrun's
+     * frames; `@limrun/ui/lite` omits them so a frameless embed stays small.
+     */
+    assets?: RemoteControlAssets;
+    /**
+     * Coarse connection lifecycle, for status UI outside the component.
+     */
+    onConnectionStateChange?: (state: RemoteControlConnectionState) => void;
     /**
      * Enable the inspect overlay. When set, the component starts polling the
      * accessibility tree and draws boxes over each element on top of the
@@ -105,6 +116,7 @@ interface RemoteControlProps {
      * @default 2000
      */
     axMaxBackoffMs?: number;
+    androidElementTreeOptions?: AndroidElementTreeOptions;
     /**
      * Fires whenever the iOS simulator's camera demand state changes —
      * i.e. an app inside the sim called
@@ -114,12 +126,10 @@ interface RemoteControlProps {
      * 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).
+     * `active` reflects whether the sim is currently asking for frames.
+     * `granted` is set on capture acknowledgements: `true` after a new
+     * track, reused track, or constraint update; `false` when capture
+     * fails. The host switches to black frames after a failure.
      *
      * `camera` (optional, only meaningful when `granted === true`)
      * carries what `MediaStreamTrack.getSettings()` reported for the
@@ -149,40 +159,6 @@ interface RemoteControlProps {
      * 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;
     /**
      * When true, capture the user's microphone via
      * `getUserMedia({ audio: true })` and stream it live into the
@@ -218,34 +194,6 @@ export interface MicrophoneState {
     /** Device label of the captured microphone, when available. */
     label?: string;
 }
-/**
- * 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
@@ -308,6 +256,15 @@ export interface RemoteControlHandle {
     setInspectSelection: (element: AxElement | null) => void;
     getAxStatus: () => AxStatus;
 }
+type DevicePlatform = 'ios' | 'android';
 export declare const withAuthenticationToken: (url: string, token: string) => string;
+export type RemoteControlConnectionState = 'connecting' | 'connected' | 'reconnecting' | 'failed' | 'terminated';
+export type RemoteControlPlatformAssets = {
+    frame?: string;
+    frameLandscape?: string;
+    tabletFrame?: string;
+    tabletFrameLandscape?: string;
+    loadingLogo?: string;
+};
+export type RemoteControlAssets = Partial<Record<DevicePlatform, RemoteControlPlatformAssets>>;
 export declare const RemoteControl: React.ForwardRefExoticComponent<RemoteControlProps & React.RefAttributes<RemoteControlHandle>>;
-export {};

package/dist/core/ax-fetcher.d.ts

@@ -1,10 +1,14 @@
 import { AxPlatform, AxSnapshot } from './ax-tree';
 export type AxStatus = 'idle' | 'starting' | 'ready' | 'unavailable' | 'error';
 export type AxFetcherSendFn = (payload: Record<string, unknown>) => boolean;
+export interface AndroidElementTreeOptions {
+    waitForIdleTimeoutMs?: number;
+}
 export interface AxFetcherOptions {
     platform: AxPlatform;
     send: AxFetcherSendFn;
     onSnapshot: (snapshot: AxSnapshot | null) => void;
+    androidElementTreeOptions?: AndroidElementTreeOptions;
     onStatusChange?: (status: AxStatus, error?: string) => void;
     baseIntervalMs?: number;
     maxBackoffMs?: number;
@@ -16,6 +20,7 @@ export declare class AxFetcher {
     private readonly onStatusChange?;
     private readonly baseIntervalMs;
     private readonly maxBackoffMs;
+    private readonly androidElementTreeOptions?;
     private readonly pending;
     private running;
     private timer;

package/dist/core/camera.d.ts

@@ -0,0 +1,58 @@
+export type CameraFacingMode = 'user' | 'environment';
+/** Camera selection requested by the instance host. */
+export interface CameraRequest {
+    active: boolean;
+    facingMode?: CameraFacingMode;
+}
+/** Browser capture metadata returned to the instance host. */
+export interface CameraCaptureInfo {
+    width?: number;
+    height?: number;
+    frameRate?: number;
+    deviceId?: string;
+    label?: string;
+    facingMode?: string;
+}
+/** Acknowledgement sent after camera capture changes or is reused. */
+export interface CameraResult {
+    type: 'cameraResult';
+    granted: boolean;
+    camera?: CameraCaptureInfo;
+}
+export interface CameraOperationContext {
+    generation: number;
+    isCurrent: () => boolean;
+}
+/**
+ * Serializes camera mutations while invalidating queued or suspended work.
+ *
+ * `enqueue` increments the generation before returning, so an operation
+ * waiting on browser permission becomes stale as soon as a newer request
+ * arrives, even though the newer operation has not started yet.
+ */
+export declare class CameraOperationCoordinator {
+    private generation;
+    private tail;
+    get currentGeneration(): number;
+    enqueue(operation: (context: CameraOperationContext) => Promise<void>): Promise<void>;
+    /**
+     * Queues related work without superseding an already queued request.
+     *
+     * The operation retains the generation current at enqueue time and becomes
+     * stale if a later camera request increments it before this work starts.
+     */
+    enqueueCurrent(operation: (context: CameraOperationContext) => Promise<void>): Promise<void>;
+    private append;
+    invalidate(): void;
+}
+export declare function parseCameraRequest(message: unknown): CameraRequest | null;
+/**
+ * Builds best-effort capture constraints.
+ *
+ * Facing is a preference so browsers can fall back when a phone-facing label
+ * or exact mode is unavailable. The browser chooses capture dimensions.
+ */
+export declare function cameraCaptureConstraints(request: CameraRequest): MediaTrackConstraints;
+export declare function shouldReacquireCamera(current: Pick<CameraRequest, 'facingMode'> | undefined, requested: Pick<CameraRequest, 'facingMode'>): boolean;
+export declare function cameraCaptureInfoFromTrack(track: MediaStreamTrack): CameraCaptureInfo;
+export declare function createGrantedCameraResult(track: MediaStreamTrack): CameraResult;

package/dist/frame-assets.d.ts

@@ -0,0 +1,2 @@
+import { RemoteControlAssets } from './components/remote-control';
+export declare const defaultRemoteControlAssets: RemoteControlAssets;