@limrun/ui 0.14.3 → 0.15.1

package/src/core/ax-fetcher.ts

@@ -51,10 +51,15 @@ 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;
   // Optional: notified on every status transition (deduplicated — no
   // self-loops are emitted). `error` provides the error message when the
   // status is `error` or `unavailable`.
@@ -81,6 +86,7 @@ export class AxFetcher {
   private readonly onStatusChange?: (status: AxStatus, error?: string) => void;
   private readonly baseIntervalMs: number;
   private readonly maxBackoffMs: number;
+  private readonly androidElementTreeOptions?: AndroidElementTreeOptions;
   private readonly pending: Map<string, PendingResolver> = new Map();
 
   private running = false;
@@ -108,6 +114,7 @@ export class AxFetcher {
     this.onStatusChange = opts.onStatusChange;
     this.baseIntervalMs = opts.baseIntervalMs ?? DEFAULT_BASE_INTERVAL_MS;
     this.maxBackoffMs = opts.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
+    this.androidElementTreeOptions = opts.androidElementTreeOptions;
     this.currentInterval = this.baseIntervalMs;
   }
 
@@ -257,16 +264,19 @@ export class AxFetcher {
     if (this.platform === 'ios') {
       return { type: 'elementTree', id };
     }
-    return { type: 'getElementTree', id };
+    return { type: 'getElementTree', id, ...this.androidElementTreeOptions };
   }
 
   private async requestOnce(): Promise<AxSnapshot> {
     const id = generateRequestId();
     return new Promise<AxSnapshot>((resolve, reject) => {
-      const timer = window.setTimeout(() => {
-        this.pending.delete(id);
-        reject(new Error('elementTree request timed out'));
-      }, REQUEST_TIMEOUT_MS);
+      const timer = window.setTimeout(
+        () => {
+          this.pending.delete(id);
+          reject(new Error('elementTree request timed out'));
+        },
+        REQUEST_TIMEOUT_MS + (this.androidElementTreeOptions?.waitForIdleTimeoutMs ?? 0),
+      );
       this.pending.set(id, { resolve, reject, timer });
       const ok = this.send(this.buildRequest(id));
       if (!ok) {

package/src/core/camera.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, test, vi } from 'vitest';
+import {
+  CameraOperationCoordinator,
+  cameraCaptureConstraints,
+  createGrantedCameraResult,
+  parseCameraRequest,
+  shouldReacquireCamera,
+} from './camera';
+
+describe('parseCameraRequest', () => {
+  test('parses active camera facing', () => {
+    expect(
+      parseCameraRequest({
+        type: 'cameraRequest',
+        active: true,
+        facingMode: 'environment',
+      }),
+    ).toEqual({
+      active: true,
+      facingMode: 'environment',
+    });
+  });
+
+  test('rejects messages without a boolean active field', () => {
+    expect(parseCameraRequest({ type: 'cameraRequest', active: 'true' })).toBeNull();
+    expect(parseCameraRequest({ type: 'other', active: true })).toBeNull();
+  });
+});
+
+describe('cameraCaptureConstraints', () => {
+  test('uses ideal facing and frame-rate preferences without geometry', () => {
+    const constraints = cameraCaptureConstraints({
+      active: true,
+      facingMode: 'environment',
+    });
+
+    expect(constraints).toEqual({
+      frameRate: { ideal: 30, max: 30 },
+      facingMode: { ideal: 'environment' },
+    });
+  });
+});
+
+describe('shouldReacquireCamera', () => {
+  test('reuses an existing track only for the same facing', () => {
+    expect(shouldReacquireCamera({ facingMode: 'user' }, { facingMode: 'user' })).toBe(false);
+    expect(shouldReacquireCamera({}, {})).toBe(false);
+  });
+
+  test('reacquires when facing changes', () => {
+    expect(shouldReacquireCamera({ facingMode: 'user' }, { facingMode: 'environment' })).toBe(true);
+    expect(shouldReacquireCamera(undefined, { facingMode: 'user' })).toBe(true);
+  });
+});
+
+describe('CameraOperationCoordinator', () => {
+  test('invalidates suspended work before serially starting the next operation', async () => {
+    const coordinator = new CameraOperationCoordinator();
+    const events: string[] = [];
+    let releaseFirst!: () => void;
+    let markFirstStarted!: () => void;
+    const firstStarted = new Promise<void>((resolve) => {
+      markFirstStarted = resolve;
+    });
+    const firstDeferred = new Promise<void>((resolve) => {
+      releaseFirst = resolve;
+    });
+
+    const first = coordinator.enqueue(async ({ isCurrent }) => {
+      events.push('first:start');
+      markFirstStarted();
+      await firstDeferred;
+      events.push(isCurrent() ? 'first:commit' : 'first:stale');
+    });
+    await firstStarted;
+
+    const second = coordinator.enqueue(async ({ isCurrent }) => {
+      events.push('second:start');
+      events.push(isCurrent() ? 'second:commit' : 'second:stale');
+    });
+    const endedCleanup = coordinator.enqueueCurrent(async ({ isCurrent }) => {
+      events.push('ended:start');
+      events.push(isCurrent() ? 'ended:current' : 'ended:stale');
+    });
+
+    expect(events).toEqual(['first:start']);
+    expect(coordinator.currentGeneration).toBe(2);
+    releaseFirst();
+    await Promise.all([first, second, endedCleanup]);
+    expect(events).toEqual([
+      'first:start',
+      'first:stale',
+      'second:start',
+      'second:commit',
+      'ended:start',
+      'ended:current',
+    ]);
+  });
+
+  test('continues serial processing after an operation rejects', async () => {
+    const coordinator = new CameraOperationCoordinator();
+    await expect(
+      coordinator.enqueue(async () => {
+        throw new Error('capture failed');
+      }),
+    ).rejects.toThrow('capture failed');
+
+    const operation = vi.fn();
+    await coordinator.enqueue(async () => operation());
+    expect(operation).toHaveBeenCalledOnce();
+  });
+
+  test('marks non-invalidating work stale when a later request arrives', async () => {
+    const coordinator = new CameraOperationCoordinator();
+    let release!: () => void;
+    const deferred = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const first = coordinator.enqueue(async () => deferred);
+    const cleanup = coordinator.enqueueCurrent(async ({ isCurrent }) => {
+      expect(isCurrent()).toBe(false);
+    });
+    const newerRequest = coordinator.enqueue(async ({ isCurrent }) => {
+      expect(isCurrent()).toBe(true);
+    });
+
+    release();
+    await Promise.all([first, cleanup, newerRequest]);
+  });
+});
+
+describe('camera result metadata', () => {
+  test('reads settings afresh for every acknowledgement', () => {
+    const getSettings = vi
+      .fn()
+      .mockReturnValueOnce({ width: 1280, height: 720, deviceId: 'front' })
+      .mockReturnValueOnce({ width: 720, height: 1280, deviceId: 'front' });
+    const track = {
+      getSettings,
+      label: 'Built-in Camera',
+    } as unknown as MediaStreamTrack;
+
+    expect(createGrantedCameraResult(track).camera).toMatchObject({
+      width: 1280,
+      height: 720,
+      label: 'Built-in Camera',
+    });
+    expect(createGrantedCameraResult(track).camera).toMatchObject({
+      width: 720,
+      height: 1280,
+      label: 'Built-in Camera',
+    });
+    expect(getSettings).toHaveBeenCalledTimes(2);
+  });
+});

package/src/core/camera.ts

@@ -0,0 +1,133 @@
+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 class CameraOperationCoordinator {
+  private generation = 0;
+  private tail: Promise<void> = Promise.resolve();
+
+  get currentGeneration(): number {
+    return this.generation;
+  }
+
+  enqueue(operation: (context: CameraOperationContext) => Promise<void>): Promise<void> {
+    const generation = ++this.generation;
+    return this.append(generation, operation);
+  }
+
+  /**
+   * 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> {
+    return this.append(this.generation, operation);
+  }
+
+  private append(
+    generation: number,
+    operation: (context: CameraOperationContext) => Promise<void>,
+  ): Promise<void> {
+    const context: CameraOperationContext = {
+      generation,
+      isCurrent: () => generation === this.generation,
+    };
+    const next = this.tail.then(() => operation(context));
+    this.tail = next.catch(() => undefined);
+    return next;
+  }
+
+  invalidate(): void {
+    ++this.generation;
+  }
+}
+
+export function parseCameraRequest(message: unknown): CameraRequest | null {
+  if (!message || typeof message !== 'object') return null;
+  const value = message as Record<string, unknown>;
+  if (value.type !== 'cameraRequest' || typeof value.active !== 'boolean') return null;
+
+  const request: CameraRequest = { active: value.active };
+  if (value.facingMode === 'user' || value.facingMode === 'environment') {
+    request.facingMode = value.facingMode;
+  }
+  return request;
+}
+
+/**
+ * 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 function cameraCaptureConstraints(request: CameraRequest): MediaTrackConstraints {
+  const constraints: MediaTrackConstraints = {
+    frameRate: { ideal: 30, max: 30 },
+  };
+
+  if (request?.facingMode) {
+    constraints.facingMode = { ideal: request.facingMode };
+  }
+  return constraints;
+}
+
+export function shouldReacquireCamera(
+  current: Pick<CameraRequest, 'facingMode'> | undefined,
+  requested: Pick<CameraRequest, 'facingMode'>,
+): boolean {
+  return !current || current.facingMode !== requested.facingMode;
+}
+
+export function cameraCaptureInfoFromTrack(track: MediaStreamTrack): CameraCaptureInfo {
+  const settings = track.getSettings();
+  return {
+    width: settings.width,
+    height: settings.height,
+    frameRate: settings.frameRate,
+    deviceId: settings.deviceId,
+    label: track.label || undefined,
+    facingMode: settings.facingMode,
+  };
+}
+
+export function createGrantedCameraResult(track: MediaStreamTrack): CameraResult {
+  return {
+    type: 'cameraResult',
+    granted: true,
+    camera: cameraCaptureInfoFromTrack(track),
+  };
+}

package/src/index.ts

@@ -1,11 +1,17 @@
 export { RemoteControl } from './components/remote-control';
-export type { RemoteControlHandle, MicrophoneState } from './components/remote-control';
+export type {
+  RemoteControlProps,
+  RemoteControlHandle,
+  MicrophoneState,
+  CameraStreamStats,
+} from './components/remote-control';
+export type { CameraCaptureInfo, CameraFacingMode, CameraRequest, CameraResult } from './core/camera';
 
 // Accessibility / inspect-mode types and helpers. Exported so customers can
 // build their own side panels, search UIs, or agent-driven inspectors on top
 // of the snapshots delivered via `onAxSnapshotChange`.
 export type { AxSnapshot, AxElement, AxRect, AxSelectors, AxPlatform } from './core/ax-tree';
-export type { AxStatus } from './core/ax-fetcher';
+export type { AndroidElementTreeOptions, AxStatus } from './core/ax-fetcher';
 export {
   axElementAtPoint,
   axElementSelectorExpression,