@smileid/usesmileid 12.0.0-beta01

package/src/__tests__/theme.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from "vitest";
+import {
+  defaultDarkTheme,
+  defaultLightTheme,
+} from "../presentation/theme/theme";
+
+const REQUIRED_COLOR_TOKENS = [
+  // Brand
+  "primary",
+  "primaryForeground",
+  "secondary",
+  "accent",
+  // Surfaces
+  "background",
+  "cardBackground",
+  "instructionCardBackground",
+  // Text
+  "titleText",
+  "cardText",
+  // Disabled / inactive
+  "disabledBackground",
+  "disabledForeground",
+  // Borders
+  "stroke",
+  // Semantic
+  "warningFill",
+  "warningIcon",
+  "warningStroke",
+  "successFill",
+  "successIcon",
+  // Capture overlay
+  "captureOverlayBackground",
+  "documentOverlayScrim",
+  "captureOverlayStroke",
+  "captureFeedbackBackground",
+  "captureFeedbackText",
+  "captureProgressIndicator",
+  // Oval
+  "ovalDefault",
+  "ovalActive",
+  "ovalWarning",
+  // Preview
+  "previewAcceptBackground",
+  "previewAcceptIcon",
+  "previewRejectBackground",
+  "previewRejectIcon",
+  // Branding
+  "smileIdYellow",
+  "offBlack",
+  "offWhite",
+] as const;
+
+const REQUIRED_TYPOGRAPHY_STYLES = [
+  "pageHeading",
+  "sectionHeading",
+  "subHeading",
+  "cardTitle",
+  "cardSubTitle",
+  "body",
+  "button",
+] as const;
+
+describe("theme defaults", () => {
+  it("exposes both light and dark variants with identical structure", () => {
+    expect(Object.keys(defaultLightTheme).sort()).toEqual(
+      Object.keys(defaultDarkTheme).sort(),
+    );
+    expect(Object.keys(defaultLightTheme.colors).sort()).toEqual(
+      Object.keys(defaultDarkTheme.colors).sort(),
+    );
+  });
+
+  it("uses the same typography / spacing / shape scale across variants", () => {
+    // Concrete scenario: a partner overrides `colors` only and keeps
+    // the SDK's typography. If a future change accidentally diverges
+    // the typography between light and dark, partners using mixed
+    // overrides would see inconsistent text sizes between themes.
+    expect(defaultDarkTheme.typography).toEqual(defaultLightTheme.typography);
+    expect(defaultDarkTheme.spacing).toEqual(defaultLightTheme.spacing);
+    expect(defaultDarkTheme.shapes).toEqual(defaultLightTheme.shapes);
+  });
+
+  it("emits canonical RGB or RGBA hex values for every documented colour token", () => {
+    // 6 hex digits = opaque, 8 hex digits = with alpha. Either is
+    // valid in React Native; reject anything else (named colours,
+    // rgba() strings) so partner-overridden palettes round-trip.
+    const HEX = /^#[0-9A-F]{6}([0-9A-F]{2})?$/i;
+    for (const [key, value] of Object.entries(defaultLightTheme.colors)) {
+      expect(value, `light.${key}`).toMatch(HEX);
+    }
+    for (const [key, value] of Object.entries(defaultDarkTheme.colors)) {
+      expect(value, `dark.${key}`).toMatch(HEX);
+    }
+  });
+
+  it("contains every documented colour token", () => {
+    // Concrete scenario: a future refactor drops a token (e.g.
+    // `captureOverlayStroke`) — capture screen would render with an
+    // undefined border colour. Pin every documented token here.
+    for (const token of REQUIRED_COLOR_TOKENS) {
+      expect(defaultLightTheme.colors).toHaveProperty(token);
+      expect(defaultDarkTheme.colors).toHaveProperty(token);
+    }
+  });
+
+  it("pins canonical brand colours", () => {
+    // Concrete scenario: drift in `primary` would mean a partner's
+    // RN app suddenly displays a different brand colour from one
+    // release to the next.
+    expect(defaultLightTheme.colors.primary).toBe("#151F72");
+    expect(defaultDarkTheme.colors.primary).toBe("#4D88FF");
+    expect(defaultLightTheme.colors.captureOverlayStroke).toBe("#151F72");
+    expect(defaultDarkTheme.colors.captureOverlayStroke).toBe("#4D88FF");
+  });
+
+  it("exposes the 7 canonical typography styles", () => {
+    for (const style of REQUIRED_TYPOGRAPHY_STYLES) {
+      expect(defaultLightTheme.typography).toHaveProperty(style);
+      const v = (defaultLightTheme.typography as Record<string, unknown>)[
+        style
+      ];
+      expect(v).toMatchObject({
+        fontSize: expect.any(Number),
+        lineHeight: expect.any(Number),
+        fontWeight: expect.any(String),
+      });
+    }
+  });
+
+  it("pins button radius to 32", () => {
+    // Concrete scenario: drift back to 8 would render rounded
+    // squares instead of pills — visible on every screen with
+    // a button.
+    expect(defaultLightTheme.shapes.buttonRadius).toBe(32);
+    expect(defaultDarkTheme.shapes.buttonRadius).toBe(32);
+  });
+
+  it("pins card radius to 12 across both themes", () => {
+    expect(defaultLightTheme.shapes.cardRadius).toBe(16);
+    expect(defaultDarkTheme.shapes.cardRadius).toBe(16);
+  });
+
+  it("pins canonical spacing scale (8 / 12 / 16 / 24 / 40)", () => {
+    // Concrete failure mode: if these drift, partner visual
+    // styling tied to the spacing scale degrades silently.
+    const expected = {
+      extraSmall: 8,
+      small: 12,
+      medium: 16,
+      large: 24,
+      extraLarge: 40,
+    };
+    expect(defaultLightTheme.spacing).toEqual(expected);
+    expect(defaultDarkTheme.spacing).toEqual(expected);
+  });
+});

package/src/camera/__tests__/camera_defaults.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { CameraDefaults } from "../camera_defaults";
+
+describe("CameraDefaults", () => {
+  it("pins focus-indicator durations", () => {
+    expect(CameraDefaults.focusRunningDurationMs).toBe(600);
+    expect(CameraDefaults.focusSettledDurationMs).toBe(500);
+  });
+
+  it("pins the analysis-stream frame rate at 30 fps", () => {
+    // Concrete scenario: a refactor drifts the analysis fps to 15
+    // (motion-blurry head turns) or 60 (high-ISO noise from shorter
+    // per-frame exposure). 30 fps is the documented sweet spot for
+    // selfie / face-tracking ML pipelines. Pin it here.
+    expect(CameraDefaults.analysisTargetFps).toBe(30);
+  });
+
+  it("pins the analysis-stream resolution at 640×480", () => {
+    // Concrete scenario: a refactor bumps the analysis resolution to
+    // 720p+. Every analyzed frame is plane-copied and scanned while
+    // the frame-processor thread blocks, so per-frame latency scales
+    // linearly with pixel count — at 720p (3× the pixels) the camera
+    // pipeline visibly stutters. 640×480 is the scan sessions' tuned
+    // input size; the preview stream stays high-res independently.
+    expect(CameraDefaults.analysisTargetResolution.width).toBe(640);
+    expect(CameraDefaults.analysisTargetResolution.height).toBe(480);
+  });
+});

package/src/camera/__tests__/camera_lens.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { CameraLens } from "../camera_lens";
+
+describe("CameraLens", () => {
+  it("exposes the two canonical lens values", () => {
+    expect(CameraLens.front).toBe("front");
+    expect(CameraLens.back).toBe("back");
+  });
+
+  it("values are the strings useCameraDevice expects as its position argument", () => {
+    // Concrete scenario: a future rename to capitalised 'Front' would
+    // silently break `useCameraDevice(CameraLens.front)` because
+    // vision-camera's position type is the lowercase string union
+    // `'front' | 'back' | 'external'`. Pin the wire format here.
+    expect(CameraLens.front).toBe("front");
+    expect(CameraLens.back).toBe("back");
+  });
+});

package/src/camera/__tests__/document_resize_target.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { computeDocumentResizeTarget } from "../document_resize_target";
+
+const MAX = 1600;
+
+describe("computeDocumentResizeTarget", () => {
+  it("clamps the longest edge of a landscape image to the width", () => {
+    // 12 MP landscape still (4032×3024) → longest edge is the width.
+    expect(computeDocumentResizeTarget(4032, 3024, MAX)).toEqual({
+      width: MAX,
+    });
+  });
+
+  it("clamps the longest edge of a portrait image to the height", () => {
+    // Portrait booklet/passport still (3024×4032) → longest edge is the height.
+    expect(computeDocumentResizeTarget(3024, 4032, MAX)).toEqual({
+      height: MAX,
+    });
+  });
+
+  it("clamps a square image on the width (w >= h tie-break)", () => {
+    expect(computeDocumentResizeTarget(2000, 2000, MAX)).toEqual({
+      width: MAX,
+    });
+  });
+
+  it("never upscales an image already within bounds", () => {
+    // Concrete scenario: the native auto-capture frame is ~640×480; an
+    // imported still that is already small must NOT be blown up to 1600 —
+    // that would add bytes and blur and diverge from the auto artifact.
+    expect(computeDocumentResizeTarget(640, 480, MAX)).toBeNull();
+  });
+
+  it("returns null when the longest edge is exactly the ceiling", () => {
+    expect(computeDocumentResizeTarget(MAX, 900, MAX)).toBeNull();
+    expect(computeDocumentResizeTarget(900, MAX, MAX)).toBeNull();
+  });
+
+  it("treats degenerate dimensions defensively (no resize)", () => {
+    expect(computeDocumentResizeTarget(0, 0, MAX)).toBeNull();
+    expect(computeDocumentResizeTarget(-100, 200, MAX)).toBeNull();
+    expect(computeDocumentResizeTarget(Number.NaN, 3000, MAX)).toBeNull();
+  });
+});

package/src/camera/__tests__/focus_state.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { FocusStates, type FocusState } from "../focus_state";
+
+describe("FocusStates factory", () => {
+  it("produces an unspecified state with no point", () => {
+    const state = FocusStates.unspecified();
+    expect(state.kind).toBe("unspecified");
+    expect("point" in state).toBe(false);
+  });
+
+  it.each(["running", "success", "failure"] as const)(
+    "produces a %s state carrying the focus point",
+    (kind) => {
+      const point = { x: 0.4, y: 0.6 };
+      const state = FocusStates[kind](point);
+      expect(state.kind).toBe(kind);
+      // TS narrowing: `kind` is one of running/success/failure here,
+      // so `point` is in the union. Runtime check pins the contract.
+      if (state.kind !== "unspecified") {
+        expect(state.point).toEqual(point);
+      }
+    },
+  );
+
+  it("exhaustive switch over FocusState narrows correctly", () => {
+    // Concrete scenario: an orchestrator's reducer does
+    // `switch (state.kind)` to drive the focus reticle animation.
+    // A future variant added without updating the union would
+    // surface as a type error here (and a runtime fallthrough at
+    // partner sites). Pin the four-variant exhaustiveness.
+    const visit = (state: FocusState): string => {
+      switch (state.kind) {
+        case "unspecified":
+          return "idle";
+        case "running":
+          return `running@${state.point.x},${state.point.y}`;
+        case "success":
+          return `success@${state.point.x},${state.point.y}`;
+        case "failure":
+          return `failure@${state.point.x},${state.point.y}`;
+      }
+    };
+    expect(visit(FocusStates.unspecified())).toBe("idle");
+    expect(visit(FocusStates.running({ x: 0, y: 0 }))).toBe("running@0,0");
+    expect(visit(FocusStates.success({ x: 1, y: 0 }))).toBe("success@1,0");
+    expect(visit(FocusStates.failure({ x: 0, y: 1 }))).toBe("failure@0,1");
+  });
+});

package/src/camera/__tests__/orientation_degrees.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { orientationToDegrees } from "../orientation_degrees";
+
+/**
+ * Pins the VisionCamera Orientation → degree mapping the native scan
+ * sessions consume as device-orientation context. The native upright
+ * validator gates capture on `0` (physically upright portrait), so a
+ * wrong mapping here manifests as the capture flow permanently stuck
+ * on "keep your device upright" guidance.
+ */
+describe("orientationToDegrees", () => {
+  it("maps upright portrait to 0 — the only value the upright validator passes", () => {
+    expect(orientationToDegrees("portrait")).toBe(0);
+  });
+
+  it("maps the rotated orientations to their clockwise degrees", () => {
+    expect(orientationToDegrees("landscape-left")).toBe(90);
+    expect(orientationToDegrees("portrait-upside-down")).toBe(180);
+    expect(orientationToDegrees("landscape-right")).toBe(270);
+  });
+});

package/src/camera/__tests__/use_smile_id_frame_stream.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, it, vi } from "vitest";
+import { ZodError } from "zod";
+import { FrameProcessingException } from "@smileid/usesmileid_bridge";
+
+import { dispatchFrameResult } from "../use_smile_id_frame_stream";
+
+/**
+ * Smallest schema-valid face wire payload — the shape the native
+ * frame processor plugin returns to the worklet. The dispatcher runs
+ * the real Zod parse, so these fixtures must satisfy
+ * `faceScanResultSchema` (unlike the pre-plugin suite, which stubbed
+ * the already-parsed result).
+ */
+const validFaceWirePayload = {
+  output: { faces: [], brightness: 0.5 },
+  state: { type: "initial" },
+  capturedEvents: [],
+};
+
+const validDocumentWirePayload = {
+  output: { documents: [], brightness: 0.5 },
+  state: { type: "found" },
+  capturedEvents: [],
+};
+
+const faceAnalyzer = { kind: "face" } as const;
+const documentAnalyzer = { kind: "document" } as const;
+
+function makeBusyHandle(initial = false) {
+  let value = initial;
+  return {
+    isBusy: () => value,
+    setBusy: (next: boolean) => {
+      value = next;
+    },
+    peek: () => value,
+  };
+}
+
+describe("dispatchFrameResult", () => {
+  it("is a no-op when analyzer is null", () => {
+    const onResult = vi.fn();
+    const onError = vi.fn();
+    const busy = makeBusyHandle();
+
+    dispatchFrameResult({
+      raw: validFaceWirePayload,
+      analyzer: null,
+      isBusy: busy.isBusy,
+      setBusy: busy.setBusy,
+      isMounted: () => true,
+      onResult,
+      onError,
+    });
+
+    expect(onResult).not.toHaveBeenCalled();
+    expect(onError).not.toHaveBeenCalled();
+    expect(busy.peek()).toBe(false);
+  });
+
+  it("drops the result when dispatch is already busy (re-entrancy guard)", () => {
+    const onResult = vi.fn();
+    const busy = makeBusyHandle(true);
+
+    dispatchFrameResult({
+      raw: validFaceWirePayload,
+      analyzer: faceAnalyzer,
+      isBusy: busy.isBusy,
+      setBusy: busy.setBusy,
+      isMounted: () => true,
+      onResult,
+    });
+
+    expect(onResult).not.toHaveBeenCalled();
+    expect(busy.peek()).toBe(true);
+  });
+
+  it("parses a valid face payload and routes the typed result to onResult", () => {
+    const onResult = vi.fn();
+    const onError = vi.fn();
+    const busy = makeBusyHandle();
+
+    dispatchFrameResult({
+      raw: validFaceWirePayload,
+      analyzer: faceAnalyzer,
+      isBusy: busy.isBusy,
+      setBusy: busy.setBusy,
+      isMounted: () => true,
+      onResult,
+      onError,
+    });
+
+    expect(onError).not.toHaveBeenCalled();
+    expect(onResult).toHaveBeenCalledTimes(1);
+    expect(onResult.mock.calls[0]![0]).toEqual(validFaceWirePayload);
+    expect(busy.peek()).toBe(false);
+  });
+
+  it("parses a valid document payload through the document schema", () => {
+    const onResult = vi.fn();
+    const onError = vi.fn();
+    const busy = makeBusyHandle();
+
+    dispatchFrameResult({
+      raw: validDocumentWirePayload,
+      analyzer: documentAnalyzer,
+      isBusy: busy.isBusy,
+      setBusy: busy.setBusy,
+      isMounted: () => true,
+      onResult,
+      onError,
+    });
+
+    expect(onError).not.toHaveBeenCalled();
+    expect(onResult).toHaveBeenCalledTimes(1);
+    expect(onResult.mock.calls[0]![0]).toEqual(validDocumentWirePayload);
+  });
+
+  it("rejects a malformed plugin result with a ZodError and releases the busy flag", () => {
+    const onResult = vi.fn();
+    const onError = vi.fn();
+    const busy = makeBusyHandle();
+
+    dispatchFrameResult({
+      // Face payload routed through the document schema is the classic
+      // provider-mismatch drift — must surface as a typed schema error.
+      raw: validFaceWirePayload,
+      analyzer: documentAnalyzer,
+      isBusy: busy.isBusy,
+      setBusy: busy.setBusy,
+      isMounted: () => true,
+      onResult,
+      onError,
+    });
+
+    expect(onResult).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError.mock.calls[0]![0]).toBeInstanceOf(ZodError);
+    expect(busy.peek()).toBe(false);
+  });
+
+  it("maps a native error marker to FrameProcessingException", () => {
+    const onResult = vi.fn();
+    const onError = vi.fn();
+    const busy = makeBusyHandle();
+
+    dispatchFrameResult({
+      raw: { error: "session_not_configured" },
+      analyzer: faceAnalyzer,
+      isBusy: busy.isBusy,
+      setBusy: busy.setBusy,
+      isMounted: () => true,
+      onResult,
+      onError,
+    });
+
+    expect(onResult).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledTimes(1);
+    const error = onError.mock.calls[0]![0];
+    expect(error).toBeInstanceOf(FrameProcessingException);
+    expect((error as FrameProcessingException).message).toContain(
+      "session_not_configured",
+    );
+    expect((error as FrameProcessingException).isRetryable()).toBe(true);
+    expect(busy.peek()).toBe(false);
+  });
+
+  it("treats a non-string error key as a schema problem, not a marker", () => {
+    const onResult = vi.fn();
+    const onError = vi.fn();
+    const busy = makeBusyHandle();
+
+    dispatchFrameResult({
+      // `error: 42` is not a native marker — the payload falls through
+      // to schema validation and fails there instead.
+      raw: { error: 42 },
+      analyzer: faceAnalyzer,
+      isBusy: busy.isBusy,
+      setBusy: busy.setBusy,
+      isMounted: () => true,
+      onResult,
+      onError,
+    });
+
+    expect(onResult).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError.mock.calls[0]![0]).toBeInstanceOf(ZodError);
+  });
+
+  it("swallows results after the component unmounts", () => {
+    const onResult = vi.fn();
+    const onError = vi.fn();
+    const busy = makeBusyHandle();
+
+    dispatchFrameResult({
+      raw: validFaceWirePayload,
+      analyzer: faceAnalyzer,
+      isBusy: busy.isBusy,
+      setBusy: busy.setBusy,
+      isMounted: () => false,
+      onResult,
+      onError,
+    });
+
+    expect(onResult).not.toHaveBeenCalled();
+    expect(onError).not.toHaveBeenCalled();
+    expect(busy.peek()).toBe(false);
+  });
+
+  it("swallows errors after the component unmounts", () => {
+    const onError = vi.fn();
+    const busy = makeBusyHandle();
+
+    dispatchFrameResult({
+      raw: { error: "scan_failed: native crashed" },
+      analyzer: faceAnalyzer,
+      isBusy: busy.isBusy,
+      setBusy: busy.setBusy,
+      isMounted: () => false,
+      onResult: vi.fn(),
+      onError,
+    });
+
+    expect(onError).not.toHaveBeenCalled();
+    expect(busy.peek()).toBe(false);
+  });
+});

package/src/camera/camera_configuration.ts

@@ -0,0 +1,32 @@
+import type { CameraLens } from "./camera_lens";
+import type { CaptureType } from "../core/models/ml_config";
+
+/**
+ * Camera-system configuration applied when the orchestrator starts.
+ * All fields optional — see `CameraDefaults` for the values applied
+ * when omitted.
+ */
+export type CameraConfiguration = {
+  /** Front (default for selfie) or back. */
+  readonly lens?: CameraLens;
+  /** Hint to enable low-light boost on supported devices. */
+  readonly enableLowLightBoost?: boolean;
+  /** What we're capturing — drives default lens + still-capture mode. */
+  readonly captureType?: CaptureType;
+  /**
+   * Override the pinned frame rate. Partners normally accept the
+   * `CameraDefaults.analysisTargetFps` default (30 fps).
+   */
+  readonly fps?: number;
+};
+
+/**
+ * Public-facing snapshot of the camera system's runtime state.
+ * `subscribe()` on `UseSmileIDCameraSystem` notifies on every change.
+ */
+export type CameraSystemState = {
+  readonly isCameraRunning: boolean;
+  readonly isStreaming: boolean;
+  readonly currentLens: CameraLens;
+  readonly hasPermission: boolean;
+};

package/src/camera/camera_defaults.ts

@@ -0,0 +1,23 @@
+/** Static camera tuning defaults. */
+export const CameraDefaults = {
+  /** Focus running indicator visibility duration in ms. */
+  focusRunningDurationMs: 600,
+  /** Focus settled indicator visibility duration in ms. */
+  focusSettledDurationMs: 500,
+
+  /** Pinned analysis-stream frame rate. 30 fps keeps head motion smooth and per-frame exposure low-ISO. */
+  analysisTargetFps: 30,
+  /** Analysis-stream resolution (landscape). Matches the scan sessions' tuned input; higher stutters the frame-processor thread without improving detection. */
+  analysisTargetResolution: { width: 640, height: 480 } as const,
+
+  /** Longest-edge ceiling (px) for an imported document image; downscale-only, never upscale. Matches the native auto-capture resample target so every upload shares one byte policy. */
+  documentMaxDimension: 1600,
+  /** JPEG compression quality (0.0–1.0, `expo-image-manipulator`'s `compress`) for imported document images; matches the auto-capture artifact quality. */
+  documentJpegQuality: 0.85,
+  /** Minimum shortest-edge (px) for a gallery document image; smaller is rejected pre-resample since upscaling yields unreadable artifacts. */
+  minGalleryDocumentDimensionPx: 600,
+  /** Default selfie JPEG width (px) when no `sdk_config` override is present; also the `image_width` metadata fallback. */
+  selfieJpegTargetWidth: 480,
+  /** Default selfie JPEG height (px) when no `sdk_config` override is present; also the `image_height` metadata fallback. */
+  selfieJpegTargetHeight: 640,
+} as const;

package/src/camera/camera_lens.ts

@@ -0,0 +1,13 @@
+/**
+ * Camera lens selector — `front` or `back`.
+ *
+ * The lowercase string values are what `useCameraDevice` from
+ * `react-native-vision-camera` accepts as its position argument, so
+ * the value passes through without translation.
+ */
+export const CameraLens = {
+  front: "front",
+  back: "back",
+} as const;
+
+export type CameraLens = (typeof CameraLens)[keyof typeof CameraLens];

package/src/camera/camera_permissions.ts

@@ -0,0 +1,36 @@
+import { Camera } from "react-native-vision-camera";
+
+/**
+ * Camera permission helpers.
+ *
+ * Wraps `react-native-vision-camera`'s permission API in a stable
+ * shape the system class consumes. Does NOT auto-request — the caller
+ * decides whether to prompt or fall through to a permission-denied
+ * screen.
+ */
+
+export type CameraPermissionStatus = "granted" | "denied" | "undetermined";
+
+/** Snapshot the current camera permission status without prompting. */
+export async function getCameraPermissionStatus(): Promise<CameraPermissionStatus> {
+  const status = Camera.getCameraPermissionStatus();
+  return mapPermissionStatus(status);
+}
+
+/**
+ * Request camera permission, prompting if necessary. Returns the
+ * resulting status; the caller should branch on `'granted'` before
+ * starting the camera.
+ */
+export async function requestCameraPermission(): Promise<CameraPermissionStatus> {
+  const status = await Camera.requestCameraPermission();
+  return mapPermissionStatus(status);
+}
+
+function mapPermissionStatus(
+  status: "granted" | "not-determined" | "denied" | "restricted",
+): CameraPermissionStatus {
+  if (status === "granted") return "granted";
+  if (status === "not-determined") return "undetermined";
+  return "denied";
+}

package/src/camera/camera_preview_image.ts

@@ -0,0 +1,19 @@
+/**
+ * Frame envelope. The frame-processor pipeline streams raw RGBA
+ * pixel buffers (`ArrayBuffer`) per frame; partners who want to
+ * thread additional metadata alongside the bytes can use this type
+ * to keep their call sites symmetric.
+ */
+
+export type ViewBounds = {
+  readonly width: number;
+  readonly height: number;
+};
+
+export type CameraPreviewImage<T> = {
+  readonly image: T;
+  /** Preview surface size at the moment the frame was sampled. */
+  readonly viewBounds?: ViewBounds;
+  /** Device orientation in degrees (0/90/180/270) at sample time. */
+  readonly rotationDegrees: number;
+};