@smileid/usesmileid 12.0.1 → 12.0.2

package/src/camera/__tests__/use_smile_id_camera_preview.test.tsx

@@ -0,0 +1,461 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import * as React from "react";
+import { create as createRenderer, act } from "react-test-renderer";
+import { Pressable, View } from "react-native";
+import * as VisionCamera from "react-native-vision-camera";
+import { FrameProcessorPluginNotRegisteredException } from "@smileid/usesmileid_bridge";
+
+import { UseSmileIDCameraPreview } from "../use_smile_id_camera_preview";
+import { UseSmileIDCameraSystem } from "../use_smile_id_camera_system";
+import { CameraLens } from "../camera_lens";
+import { CameraDefaults } from "../camera_defaults";
+import type { CameraSystemState } from "../camera_configuration";
+import type { FocusState } from "../focus_state";
+
+/**
+ * Component-level tests for `<UseSmileIDCameraPreview>` — the seam
+ * between the camera orchestrator and vision-camera. The native
+ * bindings are mocked in `setup_react_native.ts`; these tests drive
+ * the boundary the preview owns: ref attach/detach, subscription
+ * fan-out, plugin initialisation + the missing-plugin error, the
+ * frame-processor worklet body, layout-normalised tap-to-focus, and
+ * the function-as-children overlay contract.
+ */
+
+const mockedUseCameraDevice = vi.mocked(VisionCamera.useCameraDevice);
+const mockedUseCameraFormat = vi.mocked(VisionCamera.useCameraFormat);
+const mockedUseFrameProcessor = vi.mocked(VisionCamera.useFrameProcessor);
+const mockedInitPlugin = vi.mocked(
+  VisionCamera.VisionCameraProxy.initFrameProcessorPlugin,
+);
+
+type CameraDevice = ReturnType<typeof VisionCamera.useCameraDevice>;
+
+const fakeDevice = {
+  id: "test-front",
+  position: "front" as const,
+  hasFlash: false,
+  hasTorch: false,
+  formats: [],
+  isMultiCam: false,
+  supportsRawCapture: false,
+  supportsLowLightBoost: false,
+  supportsFocus: true,
+  name: "Front Camera (test)",
+} as unknown as CameraDevice;
+
+function render(element: React.ReactElement) {
+  let tree!: ReturnType<typeof createRenderer>;
+  act(() => {
+    tree = createRenderer(element);
+  });
+  return tree;
+}
+
+type CameraProps = {
+  readonly isActive: boolean;
+  readonly fps: number;
+  readonly photo: boolean;
+  readonly device: unknown;
+  readonly outputOrientation: string;
+  readonly format?: unknown;
+  readonly frameProcessor?: unknown;
+  readonly onOutputOrientationChanged: (orientation: string) => void;
+};
+
+function cameraProps(root: ReturnType<typeof render>["root"]): CameraProps {
+  return root.findByType(VisionCamera.Camera).props as unknown as CameraProps;
+}
+
+function findCameras(root: ReturnType<typeof render>["root"]) {
+  return root.findAllByType(VisionCamera.Camera);
+}
+
+/** Drives `onLayout` on the preview's root `<View>` so taps normalise. */
+function layout(
+  root: ReturnType<typeof render>["root"],
+  width: number,
+  height: number,
+) {
+  const view = root.findAllByType(View)[0];
+  act(() => {
+    (
+      view.props as {
+        onLayout: (event: {
+          nativeEvent: { layout: { width: number; height: number } };
+        }) => void;
+      }
+    ).onLayout({ nativeEvent: { layout: { width, height } } });
+  });
+}
+
+function tap(
+  root: ReturnType<typeof render>["root"],
+  locationX: number,
+  locationY: number,
+) {
+  const pressable = root.findAllByType(Pressable)[0];
+  act(() => {
+    (
+      pressable.props as {
+        onPress: (event: {
+          nativeEvent: { locationX: number; locationY: number };
+        }) => void;
+      }
+    ).onPress({ nativeEvent: { locationX, locationY } });
+  });
+}
+
+describe("UseSmileIDCameraPreview", () => {
+  beforeEach(() => {
+    mockedUseCameraDevice.mockReset();
+    mockedUseCameraDevice.mockReturnValue(fakeDevice);
+    mockedUseCameraFormat.mockReset();
+    mockedUseCameraFormat.mockReturnValue(
+      undefined as unknown as ReturnType<typeof VisionCamera.useCameraFormat>,
+    );
+    mockedUseFrameProcessor.mockReset();
+    mockedUseFrameProcessor.mockImplementation(
+      (worklet) =>
+        worklet as unknown as ReturnType<typeof VisionCamera.useFrameProcessor>,
+    );
+    mockedInitPlugin.mockReset();
+    mockedInitPlugin.mockReturnValue({
+      call: vi.fn(() => ({})),
+    } as unknown as ReturnType<
+      typeof VisionCamera.VisionCameraProxy.initFrameProcessorPlugin
+    >);
+  });
+
+  it("renders the camera for the system's current lens", () => {
+    const system = new UseSmileIDCameraSystem(CameraLens.back);
+    const { root } = render(<UseSmileIDCameraPreview cameraSystem={system} />);
+
+    expect(mockedUseCameraDevice).toHaveBeenCalledWith(CameraLens.back);
+    expect(cameraProps(root).photo).toBe(true);
+    expect(cameraProps(root).outputOrientation).toBe("device");
+  });
+
+  it("omits the camera entirely when no device is available", () => {
+    mockedUseCameraDevice.mockReturnValue(
+      undefined as unknown as CameraDevice as CameraDevice,
+    );
+    const system = new UseSmileIDCameraSystem();
+    const { root } = render(<UseSmileIDCameraPreview cameraSystem={system} />);
+
+    expect(findCameras(root)).toHaveLength(0);
+    // The tap surface still mounts so overlays render without a device.
+    expect(root.findAllByType(Pressable)).toHaveLength(1);
+  });
+
+  it("drives isActive off the system's streaming state", async () => {
+    const system = new UseSmileIDCameraSystem();
+    const { root } = render(<UseSmileIDCameraPreview cameraSystem={system} />);
+    expect(cameraProps(root).isActive).toBe(false);
+
+    await act(async () => {
+      await system.start();
+    });
+    expect(cameraProps(root).isActive).toBe(true);
+
+    act(() => {
+      system.stop();
+    });
+    expect(cameraProps(root).isActive).toBe(false);
+  });
+
+  it("pins the default fps and honours a configured override", () => {
+    const system = new UseSmileIDCameraSystem();
+    const first = render(<UseSmileIDCameraPreview cameraSystem={system} />);
+    expect(cameraProps(first.root).fps).toBe(CameraDefaults.analysisTargetFps);
+
+    const configured = new UseSmileIDCameraSystem();
+    configured.configure({ fps: 24 });
+    const second = render(
+      <UseSmileIDCameraPreview cameraSystem={configured} />,
+    );
+    expect(cameraProps(second.root).fps).toBe(24);
+  });
+
+  it("requests a 4:3 30fps analysis format and forwards it when resolved", () => {
+    const format = { videoWidth: 640, videoHeight: 480 };
+    mockedUseCameraFormat.mockReturnValue(
+      format as unknown as ReturnType<typeof VisionCamera.useCameraFormat>,
+    );
+    const system = new UseSmileIDCameraSystem();
+    const { root } = render(<UseSmileIDCameraPreview cameraSystem={system} />);
+
+    expect(mockedUseCameraFormat).toHaveBeenCalledWith(fakeDevice, [
+      { videoAspectRatio: 4 / 3 },
+      {
+        videoResolution: {
+          width: CameraDefaults.analysisTargetResolution.width,
+          height: CameraDefaults.analysisTargetResolution.height,
+        },
+      },
+      { fps: CameraDefaults.analysisTargetFps },
+    ]);
+    expect(cameraProps(root).format).toBe(format);
+  });
+
+  it("omits the format key entirely when none resolves", () => {
+    const system = new UseSmileIDCameraSystem();
+    const { root } = render(<UseSmileIDCameraPreview cameraSystem={system} />);
+    expect("format" in cameraProps(root)).toBe(false);
+  });
+
+  it("attaches the camera ref on mount and detaches it on unmount", () => {
+    const system = new UseSmileIDCameraSystem();
+    const attachRef = vi.spyOn(system, "attachRef");
+    const tree = render(<UseSmileIDCameraPreview cameraSystem={system} />);
+
+    expect(attachRef).toHaveBeenCalledTimes(1);
+    expect(attachRef.mock.calls[0]?.[0]).not.toBeNull();
+
+    act(() => {
+      tree.unmount();
+    });
+    expect(attachRef).toHaveBeenLastCalledWith(null);
+  });
+
+  it("unsubscribes from the system on unmount", () => {
+    const system = new UseSmileIDCameraSystem();
+    const unsubscribe = vi.fn();
+    vi.spyOn(system, "subscribe").mockReturnValue(unsubscribe);
+
+    const tree = render(<UseSmileIDCameraPreview cameraSystem={system} />);
+    expect(unsubscribe).not.toHaveBeenCalled();
+
+    act(() => {
+      tree.unmount();
+    });
+    expect(unsubscribe).toHaveBeenCalledTimes(1);
+  });
+
+  it("passes live state and focus state to function-as-children overlays", async () => {
+    const system = new UseSmileIDCameraSystem();
+    const seen: Array<{ state: CameraSystemState; focusState: FocusState }> =
+      [];
+    render(
+      <UseSmileIDCameraPreview cameraSystem={system}>
+        {(args) => {
+          seen.push(args);
+          return null;
+        }}
+      </UseSmileIDCameraPreview>,
+    );
+
+    expect(seen[0]?.state.isStreaming).toBe(false);
+    expect(seen[0]?.focusState.kind).toBe("unspecified");
+
+    await act(async () => {
+      await system.start();
+    });
+    const latest = seen[seen.length - 1];
+    expect(latest?.state.isStreaming).toBe(true);
+  });
+
+  it("renders plain node children inside the tap surface", () => {
+    const system = new UseSmileIDCameraSystem();
+    const { root } = render(
+      <UseSmileIDCameraPreview cameraSystem={system}>
+        <View testID="si_overlay" />
+      </UseSmileIDCameraPreview>,
+    );
+    expect(
+      root.findAllByProps({ testID: "si_overlay" }).length,
+    ).toBeGreaterThan(0);
+  });
+
+  it("normalises a tap into [0..1] focus coordinates after layout", () => {
+    const system = new UseSmileIDCameraSystem();
+    const tapToFocus = vi
+      .spyOn(system, "tapToFocus")
+      .mockResolvedValue(undefined);
+    const { root } = render(<UseSmileIDCameraPreview cameraSystem={system} />);
+
+    layout(root, 200, 400);
+    tap(root, 50, 100);
+
+    expect(tapToFocus).toHaveBeenCalledWith({ x: 0.25, y: 0.25 });
+  });
+
+  it("ignores taps before the preview has been laid out", () => {
+    const system = new UseSmileIDCameraSystem();
+    const tapToFocus = vi
+      .spyOn(system, "tapToFocus")
+      .mockResolvedValue(undefined);
+    const { root } = render(<UseSmileIDCameraPreview cameraSystem={system} />);
+
+    tap(root, 50, 100);
+    expect(tapToFocus).not.toHaveBeenCalled();
+
+    // A zero-height layout is still degenerate — division would be Infinity.
+    layout(root, 200, 0);
+    tap(root, 50, 100);
+    expect(tapToFocus).not.toHaveBeenCalled();
+  });
+
+  it("skips plugin initialisation when no frame analysis is supplied", () => {
+    const system = new UseSmileIDCameraSystem();
+    const { root } = render(<UseSmileIDCameraPreview cameraSystem={system} />);
+
+    expect(mockedInitPlugin).not.toHaveBeenCalled();
+    expect("frameProcessor" in cameraProps(root)).toBe(false);
+  });
+
+  it("initialises the named plugin and attaches a frame processor", () => {
+    const system = new UseSmileIDCameraSystem();
+    const onResult = vi.fn();
+    const { root } = render(
+      <UseSmileIDCameraPreview
+        cameraSystem={system}
+        frameAnalysis={{ pluginName: "UseSmileIDFaceScan", onResult }}
+      />,
+    );
+
+    expect(mockedInitPlugin).toHaveBeenCalledWith("UseSmileIDFaceScan", {});
+    expect(cameraProps(root).frameProcessor).toBeTypeOf("function");
+  });
+
+  it("forwards each frame's raw result to onResult with the device rotation", () => {
+    const call = vi.fn(() => ({ state: { type: "initial" } }));
+    mockedInitPlugin.mockReturnValue({ call } as unknown as ReturnType<
+      typeof VisionCamera.VisionCameraProxy.initFrameProcessorPlugin
+    >);
+    const system = new UseSmileIDCameraSystem();
+    const onResult = vi.fn();
+    const { root } = render(
+      <UseSmileIDCameraPreview
+        cameraSystem={system}
+        frameAnalysis={{ pluginName: "UseSmileIDFaceScan", onResult }}
+      />,
+    );
+
+    act(() => {
+      cameraProps(root).onOutputOrientationChanged("landscape-left");
+    });
+
+    const frame = { width: 640, height: 480 };
+    const worklet = cameraProps(root).frameProcessor as (
+      frame: unknown,
+    ) => void;
+    worklet(frame);
+
+    expect(call).toHaveBeenCalledWith(frame, { rotation: 90 });
+    expect(onResult).toHaveBeenCalledWith({ state: { type: "initial" } });
+  });
+
+  it("frame processor is inert when the plugin failed to initialise", () => {
+    mockedInitPlugin.mockReturnValue(
+      null as unknown as ReturnType<
+        typeof VisionCamera.VisionCameraProxy.initFrameProcessorPlugin
+      >,
+    );
+    const system = new UseSmileIDCameraSystem();
+    const onResult = vi.fn();
+    render(
+      <UseSmileIDCameraPreview
+        cameraSystem={system}
+        frameAnalysis={{ pluginName: "UseSmileIDFaceScan", onResult }}
+      />,
+    );
+
+    const worklet = mockedUseFrameProcessor.mock.calls[0]?.[0] as (
+      frame: unknown,
+    ) => void;
+    expect(() => worklet({ width: 1, height: 1 })).not.toThrow();
+    expect(onResult).not.toHaveBeenCalled();
+  });
+
+  it("reports a missing native plugin exactly once through onError", () => {
+    mockedInitPlugin.mockReturnValue(
+      null as unknown as ReturnType<
+        typeof VisionCamera.VisionCameraProxy.initFrameProcessorPlugin
+      >,
+    );
+    const system = new UseSmileIDCameraSystem();
+    const onError = vi.fn();
+    const frameAnalysis = {
+      pluginName: "UseSmileIDMissingPlugin",
+      onResult: vi.fn(),
+      onError,
+    };
+    const tree = render(
+      <UseSmileIDCameraPreview
+        cameraSystem={system}
+        frameAnalysis={frameAnalysis}
+      />,
+    );
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError.mock.calls[0]?.[0]).toBeInstanceOf(
+      FrameProcessorPluginNotRegisteredException,
+    );
+
+    // A re-render with the same plugin name must not re-fire.
+    act(() => {
+      tree.update(
+        <UseSmileIDCameraPreview
+          cameraSystem={system}
+          frameAnalysis={frameAnalysis}
+        />,
+      );
+    });
+    expect(onError).toHaveBeenCalledTimes(1);
+  });
+
+  it("stays silent when the plugin resolves", () => {
+    const system = new UseSmileIDCameraSystem();
+    const onError = vi.fn();
+    render(
+      <UseSmileIDCameraPreview
+        cameraSystem={system}
+        frameAnalysis={{
+          pluginName: "UseSmileIDFaceScan",
+          onResult: vi.fn(),
+          onError,
+        }}
+      />,
+    );
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it("picks up a swapped onError handler without re-firing the effect", () => {
+    mockedInitPlugin.mockReturnValue(
+      null as unknown as ReturnType<
+        typeof VisionCamera.VisionCameraProxy.initFrameProcessorPlugin
+      >,
+    );
+    const system = new UseSmileIDCameraSystem();
+    const first = vi.fn();
+    const second = vi.fn();
+    const onResult = vi.fn();
+    const tree = render(
+      <UseSmileIDCameraPreview
+        cameraSystem={system}
+        frameAnalysis={{
+          pluginName: "UseSmileIDMissingPlugin",
+          onResult,
+          onError: first,
+        }}
+      />,
+    );
+    expect(first).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      tree.update(
+        <UseSmileIDCameraPreview
+          cameraSystem={system}
+          frameAnalysis={{
+            pluginName: "UseSmileIDMissingPlugin",
+            onResult,
+            onError: second,
+          }}
+        />,
+      );
+    });
+    expect(second).not.toHaveBeenCalled();
+    expect(first).toHaveBeenCalledTimes(1);
+  });
+});

package/src/camera/__tests__/use_smile_id_frame_stream_hook.test.tsx

@@ -0,0 +1,229 @@
+import { describe, expect, it, vi } from "vitest";
+import * as React from "react";
+import { create as createRenderer, act } from "react-test-renderer";
+import type {
+  DocumentScanResult,
+  FaceScanResult,
+} from "@smileid/usesmileid_bridge";
+import { FrameProcessingException } from "@smileid/usesmileid_bridge";
+
+import {
+  useSmileIDFrameStream,
+  type UseSmileIDFrameStream,
+} from "../use_smile_id_frame_stream";
+
+/**
+ * React-level companion to `use_smile_id_frame_stream.test.ts` (which
+ * pins the pure dispatcher). These tests mount the hook so the ref
+ * plumbing — analyzer / callback swaps between renders, the mounted
+ * gate, and the memoised handle identity — is actually exercised.
+ */
+
+const validFaceWirePayload = {
+  output: { faces: [], brightness: 0.5 },
+  state: { type: "initial" },
+  capturedEvents: [],
+};
+
+const validDocumentWirePayload = {
+  output: { documents: [], brightness: 0.5 },
+  state: { type: "found" },
+  capturedEvents: [],
+};
+
+type FaceAnalyzerStub = Parameters<typeof useSmileIDFrameStream>[0];
+
+const faceAnalyzer = { kind: "face" } as unknown as FaceAnalyzerStub;
+const documentAnalyzer = { kind: "document" } as unknown as FaceAnalyzerStub;
+
+type HarnessProps = {
+  readonly analyzer: FaceAnalyzerStub;
+  readonly onResult: (result: FaceScanResult) => void;
+  readonly onError?: (error: unknown) => void;
+  readonly onHandle: (handle: UseSmileIDFrameStream) => void;
+};
+
+function Harness({ analyzer, onResult, onError, onHandle }: HarnessProps) {
+  const handle = useSmileIDFrameStream(
+    analyzer,
+    onResult,
+    onError !== undefined ? { onError } : undefined,
+  );
+  onHandle(handle);
+  return null;
+}
+
+type Rendered = {
+  readonly tree: ReturnType<typeof createRenderer>;
+  readonly handles: UseSmileIDFrameStream[];
+  readonly latest: () => UseSmileIDFrameStream;
+};
+
+function mount(props: Omit<HarnessProps, "onHandle">): Rendered {
+  const handles: UseSmileIDFrameStream[] = [];
+  let tree!: ReturnType<typeof createRenderer>;
+  act(() => {
+    tree = createRenderer(
+      <Harness {...props} onHandle={(handle) => handles.push(handle)} />,
+    );
+  });
+  return {
+    tree,
+    handles,
+    latest: () => handles[handles.length - 1] as UseSmileIDFrameStream,
+  };
+}
+
+function update(
+  rendered: Rendered,
+  props: Omit<HarnessProps, "onHandle">,
+): void {
+  act(() => {
+    rendered.tree.update(
+      <Harness
+        {...props}
+        onHandle={(handle) => rendered.handles.push(handle)}
+      />,
+    );
+  });
+}
+
+describe("useSmileIDFrameStream", () => {
+  it("validates the raw wire payload and forwards the typed face result", () => {
+    const onResult = vi.fn();
+    const rendered = mount({ analyzer: faceAnalyzer, onResult });
+
+    act(() => {
+      rendered.latest().onFrameResult(validFaceWirePayload);
+    });
+
+    expect(onResult).toHaveBeenCalledTimes(1);
+    const result = onResult.mock.calls[0]?.[0] as FaceScanResult;
+    expect(result.state.type).toBe("initial");
+  });
+
+  it("parses against the document schema when the analyzer is a document one", () => {
+    const onResult = vi.fn();
+    const rendered = mount({
+      analyzer: documentAnalyzer,
+      onResult: onResult as unknown as (result: FaceScanResult) => void,
+    });
+
+    act(() => {
+      rendered.latest().onFrameResult(validDocumentWirePayload);
+    });
+
+    const result = onResult.mock.calls[0]?.[0] as DocumentScanResult;
+    expect(result.state.type).toBe("found");
+  });
+
+  it("keeps a stable handle across re-renders so the frame processor is not rebuilt", () => {
+    const onResult = vi.fn();
+    const rendered = mount({ analyzer: faceAnalyzer, onResult });
+    const first = rendered.latest();
+
+    update(rendered, { analyzer: faceAnalyzer, onResult: vi.fn() });
+
+    expect(rendered.latest()).toBe(first);
+    expect(rendered.latest().onFrameResult).toBe(first.onFrameResult);
+  });
+
+  it("routes results to the latest onResult after a swap", () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const rendered = mount({ analyzer: faceAnalyzer, onResult: first });
+
+    update(rendered, { analyzer: faceAnalyzer, onResult: second });
+    act(() => {
+      rendered.latest().onFrameResult(validFaceWirePayload);
+    });
+
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it("stops dispatching once the analyzer is detached", () => {
+    const onResult = vi.fn();
+    const rendered = mount({ analyzer: faceAnalyzer, onResult });
+
+    update(rendered, { analyzer: null, onResult });
+    act(() => {
+      rendered.latest().onFrameResult(validFaceWirePayload);
+    });
+
+    expect(onResult).not.toHaveBeenCalled();
+  });
+
+  it("reports a native error marker through the latest onError", () => {
+    const onResult = vi.fn();
+    const firstOnError = vi.fn();
+    const secondOnError = vi.fn();
+    const rendered = mount({
+      analyzer: faceAnalyzer,
+      onResult,
+      onError: firstOnError,
+    });
+
+    update(rendered, {
+      analyzer: faceAnalyzer,
+      onResult,
+      onError: secondOnError,
+    });
+    act(() => {
+      rendered.latest().onFrameResult({ error: "session crashed" });
+    });
+
+    expect(firstOnError).not.toHaveBeenCalled();
+    expect(secondOnError).toHaveBeenCalledTimes(1);
+    expect(secondOnError.mock.calls[0]?.[0]).toBeInstanceOf(
+      FrameProcessingException,
+    );
+    expect(onResult).not.toHaveBeenCalled();
+  });
+
+  it("swallows a schema rejection when no error handler is supplied", () => {
+    const onResult = vi.fn();
+    const rendered = mount({ analyzer: faceAnalyzer, onResult });
+
+    expect(() => {
+      act(() => {
+        rendered.latest().onFrameResult({ nonsense: true });
+      });
+    }).not.toThrow();
+    expect(onResult).not.toHaveBeenCalled();
+  });
+
+  it("drops results that arrive after unmount", () => {
+    const onResult = vi.fn();
+    const onError = vi.fn();
+    const rendered = mount({ analyzer: faceAnalyzer, onResult, onError });
+    const handle = rendered.latest();
+
+    act(() => {
+      rendered.tree.unmount();
+    });
+    handle.onFrameResult(validFaceWirePayload);
+    handle.onFrameResult({ error: "late failure" });
+
+    expect(onResult).not.toHaveBeenCalled();
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it("gates re-entrant dispatch while a frame is in flight", () => {
+    const seen: string[] = [];
+    let handle: UseSmileIDFrameStream | null = null;
+    const onResult = vi.fn(() => {
+      seen.push("outer");
+      // A second frame arriving mid-dispatch must be dropped, not recursed into.
+      handle?.onFrameResult(validFaceWirePayload);
+    });
+    const rendered = mount({ analyzer: faceAnalyzer, onResult });
+    handle = rendered.latest();
+
+    act(() => {
+      handle?.onFrameResult(validFaceWirePayload);
+    });
+
+    expect(seen).toEqual(["outer"]);
+  });
+});

package/src/camera/camera_defaults.ts

@@ -12,6 +12,9 @@ export const CameraDefaults = {
   /** Document analysis resolution (16:9, matched to the visible preview so the guide-rect crop stays aligned). */
   documentAnalysisResolution: { width: 1280, height: 720 } as const,
 
+  /** How long a streaming capture waits for its first analyzed frame before reporting the camera unavailable. */
+  firstFrameTimeoutMs: 10_000,
+
   /** Longest-edge ceiling (px) for an imported document image; downscale-only. */
   documentMaxDimension: 1600,
   /** JPEG quality (0–1) for imported document images. */