@smileid/usesmileid 12.0.0-beta01 → 12.0.1

package/src/__tests__/snapshots/screens_structural.test.tsx

@@ -0,0 +1,230 @@
+import { describe, it, expect } from "vitest";
+import * as React from "react";
+import { View } from "react-native";
+import { act, create as createRenderer } from "react-test-renderer";
+import { CaptureType } from "../../core/models/ml_config";
+import { UseSmileIDCaptureContent } from "../../presentation/components/use_smile_id_capture_content";
+import type { UseSmileIDCaptureContentState } from "../../presentation/components/use_smile_id_capture_content";
+import { UseSmileIDConsentScreen } from "../../presentation/screen/use_smile_id_consent_screen";
+import { UseSmileIDDocumentBackInstructions } from "../../presentation/screen/use_smile_id_document_back_instructions";
+import { UseSmileIDDocumentPreviewScreen } from "../../presentation/screen/use_smile_id_document_preview_screen";
+import { UseSmileIDInstructionsScreen } from "../../presentation/screen/use_smile_id_instructions_screen";
+import { UseSmileIDPreviewScreen } from "../../presentation/screen/use_smile_id_preview_screen";
+import { UseSmileIDProcessingScreen } from "../../presentation/screen/use_smile_id_processing_screen";
+import { UseSmileIDFaceOverlay } from "../../presentation/components/use_smile_id_face_overlay";
+import { UseSmileIDDocumentOverlay } from "../../presentation/components/use_smile_id_document_overlay";
+import {
+  OVERLAY_STATE_COUNT,
+  UseSmileIDOverlayState,
+} from "../../presentation/state/use_smile_id_overlay_state";
+
+/**
+ * Structural snapshots: pin the rendered element tree, not pixels (pixels are
+ * the Detox lane's job). Keys follow the `<flow>/<screen>/<state>` contract.
+ */
+
+function render(element: React.ReactElement) {
+  let tree!: ReturnType<typeof createRenderer>;
+  act(() => {
+    tree = createRenderer(element);
+  });
+  return tree;
+}
+
+const CONTAINER = { containerWidth: 390, containerHeight: 520 } as const;
+
+const DOCUMENT_STATES = Object.values(UseSmileIDOverlayState).filter((s) =>
+  s.startsWith("DOCUMENT_"),
+);
+const FACE_STATES = Object.values(UseSmileIDOverlayState).filter(
+  (s) => !s.startsWith("DOCUMENT_"),
+);
+
+describe("structural snapshots", () => {
+  it("pins the overlay state inventory", () => {
+    expect(FACE_STATES.length + DOCUMENT_STATES.length).toBe(
+      OVERLAY_STATE_COUNT,
+    );
+  });
+
+  describe("selfie/instructions", () => {
+    it("selfie/instructions/default", () => {
+      const tree = render(
+        <UseSmileIDInstructionsScreen
+          onBack={() => {}}
+          onContinue={() => {}}
+        />,
+      );
+      expect(tree.toJSON()).toMatchSnapshot();
+    });
+  });
+
+  describe("selfie/capture overlay", () => {
+    it.each(FACE_STATES)("selfie/capture/%s", (state) => {
+      const tree = render(
+        <UseSmileIDFaceOverlay state={state} progress={0.5} {...CONTAINER} />,
+      );
+      expect(tree.toJSON()).toMatchSnapshot();
+    });
+  });
+
+  describe("document/capture overlay", () => {
+    it.each(DOCUMENT_STATES)("document/capture/%s", (state) => {
+      const tree = render(
+        <UseSmileIDDocumentOverlay state={state} {...CONTAINER} />,
+      );
+      expect(tree.toJSON()).toMatchSnapshot();
+    });
+  });
+
+  describe("consent", () => {
+    it("consent/default", () => {
+      const tree = render(
+        <UseSmileIDConsentScreen
+          partnerName="Acme Bank"
+          partnerPrivacyPolicyUrl="https://usesmileid.com/privacy"
+          onAllow={() => {}}
+          onDeny={() => {}}
+        />,
+      );
+      expect(tree.toJSON()).toMatchSnapshot();
+    });
+  });
+
+  describe("document/back_instructions", () => {
+    it("document/back_instructions/default", () => {
+      const tree = render(
+        <UseSmileIDDocumentBackInstructions
+          documentTypeDisplayName="National ID"
+          onCaptureBack={() => {}}
+          allowSkip
+          onSkip={() => {}}
+          onBack={() => {}}
+        />,
+      );
+      expect(tree.toJSON()).toMatchSnapshot();
+    });
+  });
+
+  describe("document/preview", () => {
+    it("document/preview/default", () => {
+      const tree = render(
+        <UseSmileIDDocumentPreviewScreen
+          documentAspectRatio={1.586}
+          onAccept={() => {}}
+          onReject={() => {}}
+          onClose={() => {}}
+        />,
+      );
+      expect(tree.toJSON()).toMatchSnapshot();
+    });
+  });
+
+  // Composed capture screen: camera slot + overlay + feedback + controls.
+  function renderCaptureContent(
+    overrides: Partial<UseSmileIDCaptureContentState>,
+  ) {
+    return render(
+      <UseSmileIDCaptureContent
+        state={{
+          captureType: CaptureType.selfie,
+          overlayState: UseSmileIDOverlayState.INSTRUCTION,
+          enableEnhancedLiveness: false,
+          animationDirection: null,
+          poseMatched: false,
+          feedbackKey: null,
+          showCaptureButton: false,
+          ...overrides,
+        }}
+        captureProgress={0}
+        cameraPreview={<View testID="camera-slot" />}
+        onStartCapture={() => {}}
+        startCaptureEnabled={true}
+        showAttribution={true}
+        onManualShutter={() => {}}
+        onGalleryUpload={() => {}}
+      />,
+    );
+  }
+
+  describe("selfie/capture content", () => {
+    it("selfie/capture/start_button", () => {
+      const tree = renderCaptureContent({
+        overlayState: UseSmileIDOverlayState.INSTRUCTION,
+        feedbackKey: "si_start_capture_instruction",
+        showCaptureButton: true,
+      });
+      expect(tree.toJSON()).toMatchSnapshot();
+    });
+  });
+
+  describe("document/capture content", () => {
+    const DOCUMENT_VARIANTS: ReadonlyArray<
+      [string, Partial<UseSmileIDCaptureContentState>]
+    > = [
+      ["card_front", { documentTypeKind: "genericDocument" }],
+      ["card_back", { documentTypeKind: "genericDocument", isBackSide: true }],
+      // TD3 passport data page ratio (125×88 mm).
+      ["passport", { documentTypeKind: "passport", knownIdAspectRatio: 1.42 }],
+      ["green_book", { documentTypeKind: "southAfricaGreenBook" }],
+    ];
+
+    it.each(DOCUMENT_VARIANTS)("document/capture/%s", (_name, overrides) => {
+      const tree = renderCaptureContent({
+        captureType: CaptureType.document,
+        overlayState: UseSmileIDOverlayState.IDLE,
+        knownIdAspectRatio: 1.586,
+        showGalleryUpload: true,
+        ...overrides,
+      });
+      expect(tree.toJSON()).toMatchSnapshot();
+    });
+
+    it("document/capture/manual_shutter", () => {
+      const tree = renderCaptureContent({
+        captureType: CaptureType.document,
+        overlayState: UseSmileIDOverlayState.DOCUMENT_TOO_FAR,
+        feedbackKey: "si_document_too_far",
+        documentTypeKind: "genericDocument",
+        knownIdAspectRatio: 1.586,
+        showManualShutter: true,
+        showGalleryUpload: true,
+      });
+      expect(tree.toJSON()).toMatchSnapshot();
+    });
+  });
+
+  describe("selfie/preview", () => {
+    it("selfie/preview/default", () => {
+      const tree = render(<UseSmileIDPreviewScreen />);
+      expect(tree.toJSON()).toMatchSnapshot();
+    });
+  });
+
+  describe("selfie/processing", () => {
+    it("selfie/processing/loading", () => {
+      const tree = render(
+        <UseSmileIDProcessingScreen state={{ kind: "loading" }} />,
+      );
+      expect(tree.toJSON()).toMatchSnapshot();
+    });
+
+    it("selfie/processing/success", () => {
+      const tree = render(
+        <UseSmileIDProcessingScreen
+          state={{ kind: "success", message: "Verification submitted" }}
+        />,
+      );
+      expect(tree.toJSON()).toMatchSnapshot();
+    });
+
+    it("selfie/processing/failed", () => {
+      const tree = render(
+        <UseSmileIDProcessingScreen
+          state={{ kind: "failed", errorMessage: "Network unavailable" }}
+        />,
+      );
+      expect(tree.toJSON()).toMatchSnapshot();
+    });
+  });
+});

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

@@ -0,0 +1,103 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * Boundary characterization for `UseSmileIDCameraSystem`'s lifecycle state machine
+ * (permission gating, running/streaming flags, lens config, listener fan-out). The
+ * frame loop is a vision-camera worklet pinned separately by
+ * `use_smile_id_frame_stream.test.ts`. Must hold byte-identically across any
+ * camera-implementation swap.
+ */
+const permissions = vi.hoisted(() => ({
+  getStatus: vi.fn(),
+  request: vi.fn(),
+}));
+
+vi.mock("../camera_permissions", () => ({
+  getCameraPermissionStatus: permissions.getStatus,
+  requestCameraPermission: permissions.request,
+}));
+
+import { CameraLens } from "../camera_lens";
+import { UseSmileIDCameraSystem } from "../use_smile_id_camera_system";
+
+describe("UseSmileIDCameraSystem — boundary characterization", () => {
+  beforeEach(() => {
+    permissions.getStatus.mockReset();
+    permissions.request.mockReset();
+  });
+
+  it("starts idle with the configured lens", () => {
+    const system = new UseSmileIDCameraSystem(CameraLens.back);
+    const state = system.getState();
+    expect(state.isCameraRunning).toBe(false);
+    expect(state.isStreaming).toBe(false);
+    expect(state.hasPermission).toBe(false);
+    expect(state.currentLens).toBe(CameraLens.back);
+  });
+
+  it("start() runs + streams when permission is already granted (no re-prompt)", async () => {
+    permissions.getStatus.mockResolvedValue("granted");
+    const system = new UseSmileIDCameraSystem();
+    await system.start();
+    const state = system.getState();
+    expect(state.isCameraRunning).toBe(true);
+    expect(state.isStreaming).toBe(true);
+    expect(state.hasPermission).toBe(true);
+    expect(permissions.request).not.toHaveBeenCalled();
+  });
+
+  it("start() prompts when undetermined, then runs on grant", async () => {
+    permissions.getStatus.mockResolvedValue("undetermined");
+    permissions.request.mockResolvedValue("granted");
+    const system = new UseSmileIDCameraSystem();
+    await system.start();
+    expect(permissions.request).toHaveBeenCalledTimes(1);
+    expect(system.getState().isCameraRunning).toBe(true);
+  });
+
+  it("start() stays off when permission is denied", async () => {
+    permissions.getStatus.mockResolvedValue("undetermined");
+    permissions.request.mockResolvedValue("denied");
+    const system = new UseSmileIDCameraSystem();
+    await system.start();
+    const state = system.getState();
+    expect(state.isCameraRunning).toBe(false);
+    expect(state.hasPermission).toBe(false);
+  });
+
+  it("start() after release() throws — a released system is unusable", async () => {
+    permissions.getStatus.mockResolvedValue("granted");
+    const system = new UseSmileIDCameraSystem();
+    system.release();
+    await expect(system.start()).rejects.toThrow(/after release/);
+  });
+
+  it("stop() pauses running + streaming without releasing (re-startable)", async () => {
+    permissions.getStatus.mockResolvedValue("granted");
+    const system = new UseSmileIDCameraSystem();
+    await system.start();
+    system.stop();
+    const state = system.getState();
+    expect(state.isCameraRunning).toBe(false);
+    expect(state.isStreaming).toBe(false);
+  });
+
+  it("configure() swaps the lens and notifies subscribers", () => {
+    const system = new UseSmileIDCameraSystem(CameraLens.front);
+    const seenLenses: CameraLens[] = [];
+    system.subscribe((state) => seenLenses.push(state.currentLens));
+    system.configure({ lens: CameraLens.back });
+    expect(system.getState().currentLens).toBe(CameraLens.back);
+    expect(seenLenses).toContain(CameraLens.back);
+  });
+
+  it("unsubscribe stops further notifications", async () => {
+    permissions.getStatus.mockResolvedValue("granted");
+    const system = new UseSmileIDCameraSystem();
+    const listener = vi.fn();
+    const unsubscribe = system.subscribe(listener);
+    unsubscribe();
+    await system.start();
+    expect(listener).not.toHaveBeenCalled();
+  });
+});

package/src/camera/camera_defaults.ts

@@ -1,23 +1,25 @@
 /** Static camera tuning defaults. */
 export const CameraDefaults = {
-  /** Focus running indicator visibility duration in ms. */
+  /** Focus running indicator visibility duration (ms). */
   focusRunningDurationMs: 600,
-  /** Focus settled indicator visibility duration in ms. */
+  /** Focus settled indicator visibility duration (ms). */
   focusSettledDurationMs: 500,
 
-  /** Pinned analysis-stream frame rate. 30 fps keeps head motion smooth and per-frame exposure low-ISO. */
+  /** Pinned analysis-stream frame rate; 30 fps keeps motion smooth at low ISO. */
   analysisTargetFps: 30,
-  /** Analysis-stream resolution (landscape). Matches the scan sessions' tuned input; higher stutters the frame-processor thread without improving detection. */
+  /** Selfie analysis resolution (4:3 — the face/smile heuristics are calibrated on it). */
   analysisTargetResolution: { width: 640, height: 480 } as const,
+  /** Document analysis resolution (16:9, matched to the visible preview so the guide-rect crop stays aligned). */
+  documentAnalysisResolution: { width: 1280, height: 720 } 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. */
+  /** Longest-edge ceiling (px) for an imported document image; downscale-only. */
   documentMaxDimension: 1600,
-  /** JPEG compression quality (0.0–1.0, `expo-image-manipulator`'s `compress`) for imported document images; matches the auto-capture artifact quality. */
+  /** JPEG quality (0–1) for imported document images. */
   documentJpegQuality: 0.85,
-  /** Minimum shortest-edge (px) for a gallery document image; smaller is rejected pre-resample since upscaling yields unreadable artifacts. */
+  /** Minimum shortest-edge (px) for a gallery document image; smaller is rejected. */
   minGalleryDocumentDimensionPx: 600,
-  /** Default selfie JPEG width (px) when no `sdk_config` override is present; also the `image_width` metadata fallback. */
+  /** Default selfie JPEG width (px); 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. */
+  /** Default selfie JPEG height (px); also the `image_height` metadata fallback. */
   selfieJpegTargetHeight: 640,
 } as const;

package/src/camera/orientation_degrees.ts

@@ -1,12 +1,11 @@
 import type { Orientation } from "react-native-vision-camera";
 
 /**
- * Map VisionCamera's gravity-derived device {@link Orientation} to the
- * clockwise degrees the native scan sessions expect (`0` = upright
- * portrait). Must reflect the physical device tilt — feed it from
- * `onOutputOrientationChanged` with `outputOrientation="device"`. Never
- * derive it from `frame.orientation`: that reports the sensor mounting,
- * not how the user is holding the phone.
+ * Map a VisionCamera {@link Orientation} to clockwise degrees (`0` = portrait).
+ * Feeds two callers: `onOutputOrientationChanged` (gravity tilt → the upright
+ * validator) and `onPreviewOrientationChanged` (locked viewport axis → the
+ * document `viewportOrientation` the frame processor uprights the capture to).
+ * Never use `frame.orientation` — that is the fixed sensor mounting.
  */
 export function orientationToDegrees(orientation: Orientation): number {
   switch (orientation) {

package/src/core/exception/__tests__/builder_validation_exceptions.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+
+import { DuplicateScreenTypeException } from "../duplicate_screen_type_exception";
+import { InvalidSelfieCaptureConfigException } from "../invalid_selfie_capture_config_exception";
+import { LivenessFrameCountException } from "../liveness_frame_count_exception";
+import { UseSmileIDErrorCode } from "../use_smile_id_error_code";
+
+/** Typed builder/validation exceptions: pin `errorCode`, message, and `errorDetails`. */
+describe("DuplicateScreenTypeException", () => {
+  it("names the duplicated type + indices and freezes the details", () => {
+    const exception = new DuplicateScreenTypeException({
+      screenType: "consent",
+      indices: [0, 3],
+    });
+
+    expect(exception).toBeInstanceOf(Error);
+    expect(exception.errorCode).toBe(
+      UseSmileIDErrorCode.Builder.DuplicateScreenType,
+    );
+    expect(exception.message).toContain("consent");
+    expect(exception.message).toContain("0, 3");
+    expect(exception.errorDetails).toEqual({
+      screenType: "consent",
+      indices: [0, 3],
+    });
+    expect(Object.isFrozen(exception.errorDetails?.["indices"])).toBe(true);
+  });
+});
+
+describe("LivenessFrameCountException", () => {
+  it("reports expected vs actual frame counts", () => {
+    const exception = new LivenessFrameCountException({
+      expected: 8,
+      actual: 3,
+    });
+
+    expect(exception.errorCode).toBe(
+      UseSmileIDErrorCode.Validation.ConstraintViolation,
+    );
+    expect(exception.message).toContain("8");
+    expect(exception.message).toContain("3");
+    expect(exception.errorDetails).toEqual({ expected: 8, actual: 3 });
+  });
+});
+
+describe("InvalidSelfieCaptureConfigException", () => {
+  it("omits the reason suffix and details when no reason is given", () => {
+    const exception = new InvalidSelfieCaptureConfigException();
+
+    expect(exception.errorCode).toBe(
+      UseSmileIDErrorCode.Builder.InvalidSelfieCaptureConfig,
+    );
+    expect(exception.message).toContain("configuration is missing");
+    expect(exception.errorDetails).toBeUndefined();
+  });
+
+  it("appends the reason and carries it in details when provided", () => {
+    const exception = new InvalidSelfieCaptureConfigException({
+      reason: "minConfidence out of range",
+    });
+
+    expect(exception.message).toContain("minConfidence out of range");
+    expect(exception.errorDetails).toEqual({
+      reason: "minConfidence out of range",
+    });
+  });
+});

package/src/core/exception/agent_mode_with_enhanced_liveness_exception.ts

@@ -0,0 +1,20 @@
+import { UseSmileIDBuilderException } from "./use_smile_id_builder_exception";
+import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
+
+/**
+ * Agent mode was combined with enhanced liveness. The head-turn challenge is
+ * validated for front-camera capture only, so the two options are mutually
+ * exclusive.
+ */
+export class AgentModeWithEnhancedLivenessException extends UseSmileIDBuilderException {
+  readonly errorCode =
+    UseSmileIDErrorCode.Builder.AgentModeWithEnhancedLiveness;
+
+  constructor() {
+    super({
+      message: "allowAgentMode is not supported with enableEnhancedLiveness",
+      suggestedFix:
+        "Disable one of them inside selfie { }: allowAgentMode for rear-camera agent capture, or enableEnhancedLiveness for the head-turn challenge",
+    });
+  }
+}

package/src/core/exception/capture_validation_exceptions.ts

@@ -3,6 +3,7 @@
  * Each concrete class lives in its own file; this module keeps the
  * legacy import path stable.
  */
+export { AgentModeWithEnhancedLivenessException } from "./agent_mode_with_enhanced_liveness_exception";
 export { InvalidSelfieCaptureConfigException } from "./invalid_selfie_capture_config_exception";
 export { InvalidDocumentCaptureConfigException } from "./invalid_document_capture_config_exception";
 export { InvalidMissingCaptureTypeException } from "./invalid_missing_capture_type_exception";

package/src/core/exception/index.ts

@@ -43,6 +43,7 @@ export { MissingCaptureForPreviewException } from "./missing_capture_for_preview
 export { DuplicateScreenTypeException } from "./duplicate_screen_type_exception";
 
 // Capture-config validation (`capture { }` block).
+export { AgentModeWithEnhancedLivenessException } from "./agent_mode_with_enhanced_liveness_exception";
 export { InvalidSelfieCaptureConfigException } from "./invalid_selfie_capture_config_exception";
 export { InvalidDocumentCaptureConfigException } from "./invalid_document_capture_config_exception";
 export { InvalidMissingCaptureTypeException } from "./invalid_missing_capture_type_exception";

package/src/core/exception/use_smile_id_error_code.ts

@@ -24,6 +24,7 @@ export const UseSmileIDErrorCode = {
     MissingScreenConfiguration: "BUILDER_MISSING_SCREEN_CONFIG",
     DuplicateScreenType: "BUILDER_DUPLICATE_SCREEN",
     InvalidSelfieCaptureConfig: "BUILDER_INVALID_SELFIE_CONFIG",
+    AgentModeWithEnhancedLiveness: "BUILDER_AGENT_MODE_WITH_ENHANCED_LIVENESS",
     InvalidDocumentCaptureConfig: "BUILDER_INVALID_DOCUMENT_CONFIG",
     MissingMLConfiguration: "BUILDER_MISSING_ML_CONFIG",
     MissingNetworkConfiguration: "BUILDER_MISSING_NETWORK_CONFIG",

package/src/core/models/__tests__/document_type.test.ts

@@ -5,21 +5,23 @@ import { DocumentType } from "../document_type";
 // / orientation drive both copy and capture behaviour). Pin them exactly so a
 // change forces a deliberate decision here and in the sibling SDKs.
 describe("DocumentType presets", () => {
-  it("SouthAfricaGreenBook is a portrait, two-sided document", () => {
+  it("SouthAfricaGreenBook is a portrait, single-sided document", () => {
     expect(DocumentType.SouthAfricaGreenBook).toEqual({
       kind: "southAfricaGreenBook",
       displayName: "Green Book",
-      hasBackSide: true,
+      hasBackSide: false,
       orientation: "Portrait",
+      knownAspectRatio: 320 / 428,
     });
   });
 
-  it("Passport is a portrait, single-sided document", () => {
+  it("Passport is a landscape, two-sided document", () => {
     expect(DocumentType.Passport).toEqual({
       kind: "passport",
       displayName: "Passport",
-      hasBackSide: false,
-      orientation: "Portrait",
+      hasBackSide: true,
+      orientation: "Landscape",
+      knownAspectRatio: 356 / 272,
     });
   });
 

package/src/core/models/__tests__/flow_models.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+
+import { FlowStep } from "../flow_step";
+import { HEAD_TURN_DIRECTIONS } from "../head_turn_direction";
+
+/** FlowStep + head-turn direction order is load-bearing (nav advances through it); pin it. */
+describe("flow model constants", () => {
+  it("FlowStep lists the steps in forward-navigation order", () => {
+    expect(FlowStep).toEqual([
+      "instructions",
+      "consent",
+      "permission",
+      "capture",
+      "preview",
+      "processing",
+    ]);
+  });
+
+  it("HEAD_TURN_DIRECTIONS enumerates the three challenge directions in order", () => {
+    expect(HEAD_TURN_DIRECTIONS).toEqual([
+      "look_left",
+      "look_right",
+      "look_up",
+    ]);
+  });
+});

package/src/core/models/config.ts

@@ -1,3 +1,6 @@
+import type * as ScreenOrientation from "expo-screen-orientation";
+import type { GlobalPrivacyControl } from "./global_privacy_control";
+
 /**
  * Global SDK configuration flags. Snapshot produced by
  * `UseSmileIDConfigBuilder.build()` — every field is populated, with
@@ -33,4 +36,23 @@ export type ConfigOptions = {
    * `docs/Architecture.md § Rollout`.
    */
   readonly allowOfflineMode: boolean;
+
+  /**
+   * Partner-declared consent posture (`global_privacy_control`).
+   * `GlobalPrivacyControl.OptOut` (the default) forces the opt-out consent
+   * layout universally; `OptIn` keeps the legacy regional mechanics.
+   */
+  readonly globalPrivacyControl: GlobalPrivacyControl;
+
+  /**
+   * Orientation lock the SDK applies when a capture screen leaves the screen.
+   * Defaults to `PORTRAIT_UP`, the posture most hosts pin at their root
+   * layout; multi-orientation hosts set `DEFAULT` so the flow releases the
+   * clamp instead of leaving the app portrait-only after verification.
+   *
+   * Optional so a hand-written `ConfigOptions` literal still compiles; the
+   * builder always populates it, and an absent value takes the same
+   * `PORTRAIT_UP` default at the capture screen.
+   */
+  readonly exitOrientations?: ScreenOrientation.OrientationLock;
 };

package/src/core/models/document_capture_mode.ts

@@ -44,3 +44,30 @@ export const DocumentCaptureMode = {
     });
   },
 } as const;
+
+/**
+ * The wire token the server expects for the `auto_capture_enabled` builder-configuration field,
+ * keyed off the mode's `kind`. Lives with {@link DocumentCaptureMode} — its single source of
+ * truth — so the metadata layer maps the partner's typed choice straight onto the wire without a
+ * parallel enum. These exact strings are the server contract; changing them is a wire-breaking
+ * change. Not part of the public package surface (not re-exported from `index.ts`).
+ */
+export function autoCaptureWireValue(
+  mode: DocumentCaptureMode | undefined,
+): string {
+  switch (mode?.kind) {
+    case "autoCapture":
+      return "auto_capture_only";
+    case "manualCapture":
+      return "manual";
+    case "autoCaptureWithManualFallback":
+    case undefined:
+      return "autocapture_default";
+    default: {
+      // Exhaustiveness guard: a new DocumentCaptureMode kind fails to compile here
+      // until it's handled above (`mode` narrows to `never` once all kinds are covered).
+      const exhaustive: never = mode;
+      return exhaustive;
+    }
+  }
+}

package/src/core/models/document_type.ts

@@ -26,15 +26,17 @@ export type DocumentType =
 const SOUTH_AFRICA_GREEN_BOOK: DocumentType = Object.freeze({
   kind: "southAfricaGreenBook",
   displayName: "Green Book",
-  hasBackSide: true,
+  hasBackSide: false,
   orientation: "Portrait",
+  knownAspectRatio: 320 / 428,
 });
 
 const PASSPORT: DocumentType = Object.freeze({
   kind: "passport",
   displayName: "Passport",
-  hasBackSide: false,
-  orientation: "Portrait",
+  hasBackSide: true,
+  orientation: "Landscape",
+  knownAspectRatio: 356 / 272,
 });
 
 /** Configurable fields for {@link DocumentType.GenericDocument}. */
@@ -47,9 +49,9 @@ export type GenericDocumentArgs = {
 
 /** Preset values and the `GenericDocument` factory for {@link DocumentType}. */
 export const DocumentType = {
-  /** South Africa Green Book — booklet-style, two-sided, portrait. */
+  /** South Africa Green Book — booklet-style, single-side, portrait. */
   SouthAfricaGreenBook: SOUTH_AFRICA_GREEN_BOOK,
-  /** Passport — single data page, no back side, portrait (provisional values). */
+  /** Passport — landscape data page followed by a back-side capture. */
   Passport: PASSPORT,
   /** Catch-all without a preset; defaults to a landscape, two-sided "Document". */
   GenericDocument(args: GenericDocumentArgs = {}): DocumentType {