@smileid/usesmileid 12.0.0-beta01 → 12.0.1

package/src/presentation/screen/__tests__/ess_turn_haptics.test.ts

@@ -1,16 +1,16 @@
 import { describe, expect, it, vi, beforeEach } from "vitest";
 import * as Haptics from "expo-haptics";
-import type { ScanState } from "@smileid/usesmileid_bridge";
-import { ScanStateType } from "@smileid/usesmileid_bridge";
+import type { UseSmileIDScanState } from "@smileid/usesmileid_bridge";
+import { UseSmileIDScanStateType } from "@smileid/usesmileid_bridge";
 import {
   essTurnHaptic,
   triggerEssTurnHaptic,
 } from "../helpers/ess_turn_haptics";
 
-const headTurn = (direction?: "left" | "right" | "up"): ScanState =>
+const headTurn = (direction?: "left" | "right" | "up"): UseSmileIDScanState =>
   direction === undefined
-    ? { type: ScanStateType.HeadTurn }
-    : { type: ScanStateType.HeadTurn, currentDirection: direction };
+    ? { type: UseSmileIDScanStateType.HeadTurn }
+    : { type: UseSmileIDScanStateType.HeadTurn, currentDirection: direction };
 
 describe("essTurnHaptic", () => {
   it("fires intermediate when the requested direction advances", () => {
@@ -24,9 +24,9 @@ describe("essTurnHaptic", () => {
 
   it("fires final when leaving the head-turn phase toward capture", () => {
     for (const next of [
-      ScanStateType.Found,
-      ScanStateType.Satisfied,
-      ScanStateType.Finished,
+      UseSmileIDScanStateType.Found,
+      UseSmileIDScanStateType.Satisfied,
+      UseSmileIDScanStateType.Finished,
     ] as const) {
       expect(essTurnHaptic(headTurn("up"), { type: next })).toBe("final");
     }
@@ -34,10 +34,14 @@ describe("essTurnHaptic", () => {
 
   it("never fires on a reset (head turn abandoned to initial / timeout)", () => {
     expect(
-      essTurnHaptic(headTurn("left"), { type: ScanStateType.Initial }),
+      essTurnHaptic(headTurn("left"), {
+        type: UseSmileIDScanStateType.Initial,
+      }),
     ).toBeNull();
     expect(
-      essTurnHaptic(headTurn("left"), { type: ScanStateType.Timeout }),
+      essTurnHaptic(headTurn("left"), {
+        type: UseSmileIDScanStateType.Timeout,
+      }),
     ).toBeNull();
   });
 
@@ -48,7 +52,7 @@ describe("essTurnHaptic", () => {
   it("does not fire when the previous state was not a directed head turn", () => {
     // Entering a head turn is not completing one.
     expect(
-      essTurnHaptic({ type: ScanStateType.Found }, headTurn("left")),
+      essTurnHaptic({ type: UseSmileIDScanStateType.Found }, headTurn("left")),
     ).toBeNull();
     // A head turn with no direction yet has nothing to complete.
     expect(essTurnHaptic(headTurn(), headTurn("left"))).toBeNull();

package/src/presentation/screen/__tests__/instructions_screen_helpers.test.ts

@@ -6,7 +6,9 @@ import {
 } from "../helpers/instructions_screen_helpers";
 import {
   DOCUMENT_GREEN_BOOK_HERO_ANIMATION,
-  DOCUMENT_GUIDELINES,
+  DOCUMENT_GUIDELINES_GENERIC,
+  DOCUMENT_GUIDELINES_GREEN_BOOK,
+  DOCUMENT_GUIDELINES_PASSPORT,
   DOCUMENT_HERO_ANIMATION,
   ESS_HERO_ANIMATION,
   SELFIE_GUIDELINES,
@@ -85,7 +87,7 @@ describe("resolveInstructionsConfig — document variant", () => {
       loc,
     );
     expect(resolved.titleEmphasis).toBe("Green Book");
-    expect(resolved.guidelines).toBe(DOCUMENT_GUIDELINES);
+    expect(resolved.guidelines).toBe(DOCUMENT_GUIDELINES_GREEN_BOOK);
     expect(resolved.heroSource).toBe(DOCUMENT_GREEN_BOOK_HERO_ANIMATION);
     expect(resolved.showHeroOval).toBe(false);
     expect(resolved.showHeroOvalProgress).toBe(false);
@@ -93,7 +95,7 @@ describe("resolveInstructionsConfig — document variant", () => {
     expect(resolved.titlePrefix).toBe(loc.siInstructionsTitlePrefix);
   });
 
-  it("falls back to the generic document hero for GenericDocument", () => {
+  it("falls back to the generic document hero + guidelines for GenericDocument", () => {
     const resolved = resolveInstructionsConfig(
       {},
       {
@@ -103,9 +105,19 @@ describe("resolveInstructionsConfig — document variant", () => {
       loc,
     );
     expect(resolved.heroSource).toBe(DOCUMENT_HERO_ANIMATION);
+    expect(resolved.guidelines).toBe(DOCUMENT_GUIDELINES_GENERIC);
     expect(resolved.titleEmphasis).toBe("Document");
   });
 
+  it("uses the passport guidelines for a passport document", () => {
+    const resolved = resolveInstructionsConfig(
+      {},
+      { enhancedLivenessEnabled: false, documentType: DocumentType.Passport },
+      loc,
+    );
+    expect(resolved.guidelines).toBe(DOCUMENT_GUIDELINES_PASSPORT);
+  });
+
   it("respects partner title/guideline overrides but always hides the oval for documents", () => {
     const customGuidelines: InstructionGuideline[] = [SELFIE_GUIDELINES[0]!];
     const resolved = resolveInstructionsConfig(

package/src/presentation/screen/__tests__/scan_state_to_overlay_state.test.ts

@@ -1,13 +1,13 @@
 import { describe, expect, it } from "vitest";
-import { ScanStateType } from "@smileid/usesmileid_bridge";
-import type { ScanState } from "@smileid/usesmileid_bridge";
+import { UseSmileIDScanStateType } from "@smileid/usesmileid_bridge";
+import type { UseSmileIDScanState } from "@smileid/usesmileid_bridge";
 import { mapScanStateToOverlayState } from "../helpers/scan_state_to_overlay_state";
 import { UseSmileIDOverlayState } from "../../state/use_smile_id_overlay_state";
 import { CaptureType } from "../../../core/models/ml_config";
 
 /**
  * Pure-logic tests for the helper that translates the analyzer's
- * `ScanState` machine into the SDK's visual overlay enum. These cover
+ * `UseSmileIDScanState` machine into the SDK's visual overlay enum. These cover
  * what the legacy screen tests pinned via the now-removed
  * `overlayState=` prop — the screen now derives overlay state from
  * `scanState` per frame, so testing the mapping in isolation gives the
@@ -15,14 +15,18 @@ import { CaptureType } from "../../../core/models/ml_config";
  */
 describe("mapScanStateToOverlayState", () => {
   it("maps the initial state to INSTRUCTION for selfie", () => {
-    const state: ScanState = { type: ScanStateType.Initial };
+    const state: UseSmileIDScanState = {
+      type: UseSmileIDScanStateType.Initial,
+    };
     expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
       UseSmileIDOverlayState.INSTRUCTION,
     );
   });
 
   it("maps the initial state to INSTRUCTION for document", () => {
-    const state: ScanState = { type: ScanStateType.Initial };
+    const state: UseSmileIDScanState = {
+      type: UseSmileIDScanStateType.Initial,
+    };
     expect(mapScanStateToOverlayState(state, CaptureType.document)).toBe(
       UseSmileIDOverlayState.INSTRUCTION,
     );
@@ -32,7 +36,9 @@ describe("mapScanStateToOverlayState", () => {
     // READY drives the bottom-to-top fill animation on the face oval —
     // the analyzer signalling "satisfied" means the pipeline is about
     // to emit captured frames.
-    const state: ScanState = { type: ScanStateType.Satisfied };
+    const state: UseSmileIDScanState = {
+      type: UseSmileIDScanStateType.Satisfied,
+    };
     expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
       UseSmileIDOverlayState.READY,
     );
@@ -42,21 +48,27 @@ describe("mapScanStateToOverlayState", () => {
     // CAPTURING is the yellow-solid state — the analyzer has emitted
     // its captured artifacts and the orchestrator is about to call
     // flush().
-    const state: ScanState = { type: ScanStateType.Finished };
+    const state: UseSmileIDScanState = {
+      type: UseSmileIDScanStateType.Finished,
+    };
     expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
       UseSmileIDOverlayState.CAPTURING,
     );
   });
 
   it("maps the headTurn state to HEAD_TURN", () => {
-    const state: ScanState = { type: ScanStateType.HeadTurn };
+    const state: UseSmileIDScanState = {
+      type: UseSmileIDScanStateType.HeadTurn,
+    };
     expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
       UseSmileIDOverlayState.HEAD_TURN,
     );
   });
 
   it("maps timeout back to IDLE so the overlay returns to the gray pre-capture state", () => {
-    const state: ScanState = { type: ScanStateType.Timeout };
+    const state: UseSmileIDScanState = {
+      type: UseSmileIDScanStateType.Timeout,
+    };
     expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
       UseSmileIDOverlayState.IDLE,
     );
@@ -87,8 +99,8 @@ describe("mapScanStateToOverlayState", () => {
 
     for (const [feedbackKey, expected] of cases) {
       it(`maps found+${feedbackKey} to ${expected}`, () => {
-        const state: ScanState = {
-          type: ScanStateType.Found,
+        const state: UseSmileIDScanState = {
+          type: UseSmileIDScanStateType.Found,
           feedback: feedbackKey,
         };
         expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
@@ -98,7 +110,9 @@ describe("mapScanStateToOverlayState", () => {
     }
 
     it("falls back to FACE_DETECTED when found has no feedback key", () => {
-      const state: ScanState = { type: ScanStateType.Found };
+      const state: UseSmileIDScanState = {
+        type: UseSmileIDScanStateType.Found,
+      };
       expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
         UseSmileIDOverlayState.FACE_DETECTED,
       );
@@ -109,8 +123,8 @@ describe("mapScanStateToOverlayState", () => {
       // si_capture_* key the JS side hasn't been updated for. The
       // overlay should stay alive (green-solid) rather than throwing
       // or rendering an empty state.
-      const state: ScanState = {
-        type: ScanStateType.Found,
+      const state: UseSmileIDScanState = {
+        type: UseSmileIDScanStateType.Found,
         feedback: "si_capture_future_feedback_key",
       };
       expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
@@ -121,8 +135,8 @@ describe("mapScanStateToOverlayState", () => {
 
   describe("unsatisfied + reason (selfie)", () => {
     it("uses the reason key to drive the orange-solid overlay", () => {
-      const state: ScanState = {
-        type: ScanStateType.Unsatisfied,
+      const state: UseSmileIDScanState = {
+        type: UseSmileIDScanStateType.Unsatisfied,
         reason: "si_capture_too_close",
       };
       expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
@@ -131,7 +145,9 @@ describe("mapScanStateToOverlayState", () => {
     });
 
     it("falls back to FACE_NOT_CENTERED on a missing reason key", () => {
-      const state: ScanState = { type: ScanStateType.Unsatisfied };
+      const state: UseSmileIDScanState = {
+        type: UseSmileIDScanStateType.Unsatisfied,
+      };
       expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
         UseSmileIDOverlayState.FACE_NOT_CENTERED,
       );
@@ -140,15 +156,17 @@ describe("mapScanStateToOverlayState", () => {
 
   describe("document capture mappings", () => {
     it("maps found+document key to DOCUMENT_READY by default", () => {
-      const state: ScanState = { type: ScanStateType.Found };
+      const state: UseSmileIDScanState = {
+        type: UseSmileIDScanStateType.Found,
+      };
       expect(mapScanStateToOverlayState(state, CaptureType.document)).toBe(
         UseSmileIDOverlayState.DOCUMENT_READY,
       );
     });
 
     it("maps the si_document_too_close key to DOCUMENT_TOO_CLOSE", () => {
-      const state: ScanState = {
-        type: ScanStateType.Found,
+      const state: UseSmileIDScanState = {
+        type: UseSmileIDScanStateType.Found,
         feedback: "si_document_too_close",
       };
       expect(mapScanStateToOverlayState(state, CaptureType.document)).toBe(
@@ -161,8 +179,8 @@ describe("mapScanStateToOverlayState", () => {
       // si_document_* key or the shared si_capture_* one. Map both
       // to the document overlay enum so the bottom-feedback bubble
       // stays accurate either way.
-      const state: ScanState = {
-        type: ScanStateType.Found,
+      const state: UseSmileIDScanState = {
+        type: UseSmileIDScanStateType.Found,
         feedback: "si_capture_too_close",
       };
       expect(mapScanStateToOverlayState(state, CaptureType.document)).toBe(
@@ -171,15 +189,17 @@ describe("mapScanStateToOverlayState", () => {
     });
 
     it("maps unsatisfied+missing reason to DOCUMENT_NOT_CENTERED", () => {
-      const state: ScanState = { type: ScanStateType.Unsatisfied };
+      const state: UseSmileIDScanState = {
+        type: UseSmileIDScanStateType.Unsatisfied,
+      };
       expect(mapScanStateToOverlayState(state, CaptureType.document)).toBe(
         UseSmileIDOverlayState.DOCUMENT_NOT_CENTERED,
       );
     });
 
     it("maps si_document_hold_still to DOCUMENT_HOLD_STILL", () => {
-      const state: ScanState = {
-        type: ScanStateType.Found,
+      const state: UseSmileIDScanState = {
+        type: UseSmileIDScanStateType.Found,
         feedback: "si_document_hold_still",
       };
       expect(mapScanStateToOverlayState(state, CaptureType.document)).toBe(
@@ -191,8 +211,8 @@ describe("mapScanStateToOverlayState", () => {
       // `si_document_center` is the key the native side actually emits
       // for an off-centre document (the former `si_document_not_centered`
       // was never emitted).
-      const state: ScanState = {
-        type: ScanStateType.Found,
+      const state: UseSmileIDScanState = {
+        type: UseSmileIDScanStateType.Found,
         feedback: "si_document_center",
       };
       expect(mapScanStateToOverlayState(state, CaptureType.document)).toBe(

package/src/presentation/screen/__tests__/use_smile_id_capture_screen.test.tsx

@@ -11,19 +11,37 @@ import * as Brightness from "expo-brightness";
 import { StatusBar } from "react-native";
 import { UseSmileIDCaptureScreen } from "../use_smile_id_capture_screen";
 import { CaptureType } from "../../../core/models/ml_config";
+import { DocumentCaptureMode } from "../../../core/models/document_capture_mode";
+import { mockedTakePhoto } from "../../../__tests__/setup_react_native";
 import { enStrings } from "../../../l10n/strings_en";
 import {
-  ScanStateType,
+  UseSmileIDScanStateType,
   CaptureReadyEventKind,
 } from "@smileid/usesmileid_bridge";
 import type {
-  ScanState,
+  UseSmileIDScanState,
   CaptureReadyEvent,
   FaceScanResult,
 } from "@smileid/usesmileid_bridge";
+import { scriptedFaceScanResults } from "../../../testing/scripted_scan_results";
+import { parseScriptedScenario } from "../../../testing/scenario_loader";
 import { isSessionBoundary } from "../helpers/capture_ui_state";
 import { UseSmileIDFeedbackDebouncer } from "../helpers/feedback_debouncer";
 import { UseSmileIDMotion } from "../../theme/use_smile_id_motion";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+// The shared scenario set lives at the repo root (e2e/scenarios/), outside this
+// package's tsc rootDir (./src), so the test reads selfie-happy-path.json at run
+// time. These minimal ambient decls keep the read typed without pulling
+// @types/node in (which would collide with react-native's global timer types).
+declare module "node:fs" {
+  export function readFileSync(path: string, encoding: "utf8"): string;
+}
+declare module "node:path" {
+  export function dirname(path: string): string;
+  export function join(...parts: string[]): string;
+}
 
 // Capture the screen's per-frame `onResult` so tests can drive synthetic
 // sequences — the vision-camera worklet can't run in vitest, and `onResult`
@@ -195,6 +213,18 @@ describe("UseSmileIDCaptureScreen", () => {
     expect(mockedUseCameraDevice).toHaveBeenCalledWith("back");
   });
 
+  it("uses the back lens for an agent-mode selfie capture", () => {
+    const { root } = render(
+      <UseSmileIDCaptureScreen
+        analyzer={fakeAnalyzer}
+        captureType={CaptureType.selfie}
+        allowAgentMode
+      />,
+    );
+    expect(findByTestID(root, "si_capture_camera_preview")).not.toBeNull();
+    expect(mockedUseCameraDevice).toHaveBeenCalledWith("back");
+  });
+
   it("shows a placeholder (not the camera) when permission is undetermined", () => {
     const requestPermission = vi.fn(async () => true);
     mockedUseCameraPermission.mockReturnValue({
@@ -278,9 +308,9 @@ describe("UseSmileIDCaptureScreen", () => {
   // NOTE: the legacy `overlayState` / `captureProgress` prop-driven tests
   // were removed in Phase 3 of the per-frame migration. The capture
   // screen now owns its overlay state internally (derived from the
-  // analyzer's per-frame ScanState), so there's no external prop to
+  // analyzer's per-frame UseSmileIDScanState), so there's no external prop to
   // pin against. Phase 4 follow-up re-authors these as analyzer-driven
-  // tests that feed synthetic ScanState transitions through a mock
+  // tests that feed synthetic UseSmileIDScanState transitions through a mock
   // analyzer + frame stream.
 
   it("forwards the back tap to onBack when the back button is supplied", () => {
@@ -331,7 +361,7 @@ describe("UseSmileIDCaptureScreen", () => {
   });
 
   // Removed in Phase 3 — feedback text is now driven by the analyzer's
-  // ScanState rather than a partner-supplied overlayState prop. Phase 4
+  // UseSmileIDScanState rather than a partner-supplied overlayState prop. Phase 4
   // re-authors this against a mock analyzer that yields a synthetic
   // "found + feedback=si_capture_low_light" result through the
   // frame stream.
@@ -507,22 +537,22 @@ describe("UseSmileIDCaptureScreen", () => {
     // Stale events → unsatisfied reset (drops them) → fresh events → finished.
     emit({
       output,
-      state: { type: ScanStateType.Found },
+      state: { type: UseSmileIDScanStateType.Found },
       capturedEvents: [staleSelfie, staleLiveness],
     });
     emit({
       output,
-      state: { type: ScanStateType.Unsatisfied },
+      state: { type: UseSmileIDScanStateType.Unsatisfied },
       capturedEvents: [],
     });
     emit({
       output,
-      state: { type: ScanStateType.Found },
+      state: { type: UseSmileIDScanStateType.Found },
       capturedEvents: [freshSelfie, freshLiveness],
     });
     emit({
       output,
-      state: { type: ScanStateType.Finished },
+      state: { type: UseSmileIDScanStateType.Finished },
       capturedEvents: [],
     });
 
@@ -534,10 +564,64 @@ describe("UseSmileIDCaptureScreen", () => {
 
     expect(onCaptureComplete).toHaveBeenCalledTimes(1);
     // Only the post-reset events survive — the stale ones were cleared.
-    expect(onCaptureComplete).toHaveBeenCalledWith([
-      freshSelfie,
-      freshLiveness,
-    ]);
+    // The capture telemetry (duration + retries) travels as a second argument;
+    // the retry count reflects the one unsatisfied reset observed above.
+    expect(onCaptureComplete).toHaveBeenCalledWith(
+      [freshSelfie, freshLiveness],
+      expect.objectContaining({ retries: 1 }),
+    );
+  });
+
+  it("replays the shared selfie scenario to a full capture completion", async () => {
+    // Drives the capture gap headlessly through the frame stream's onResult
+    // seam: the shared scenario replayed to `finished` must reach
+    // onCaptureComplete with the scripted selfie + liveness events.
+    const onCaptureComplete = vi.fn();
+    const analyzer = makeFakeAnalyzer();
+    capturedOnResult = null;
+    render(
+      <UseSmileIDCaptureScreen
+        analyzer={analyzer}
+        captureType={CaptureType.selfie}
+        onCaptureComplete={onCaptureComplete}
+      />,
+    );
+    expect(capturedOnResult).not.toBeNull();
+
+    // Consume the real shared scenario (not a hand-written copy) so a drift in
+    // the canonical script is caught here rather than silently diverging.
+    const scenarioDir = dirname(import.meta.url.replace(/^file:\/\//, ""));
+    const scenario = parseScriptedScenario(
+      JSON.parse(
+        readFileSync(
+          join(
+            scenarioDir,
+            "../../../../../e2e/scenarios/selfie-happy-path.json",
+          ),
+          "utf8",
+        ),
+      ),
+    );
+    for (const result of scriptedFaceScanResults(scenario, {
+      livenessCount: 2,
+    })) {
+      act(() => {
+        capturedOnResult!(result);
+      });
+    }
+    await act(async () => {
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(onCaptureComplete).toHaveBeenCalledTimes(1);
+    const events = onCaptureComplete.mock.calls[0][0] as CaptureReadyEvent[];
+    expect(
+      events.filter((e) => e.kind === CaptureReadyEventKind.Selfie),
+    ).toHaveLength(1);
+    expect(
+      events.filter((e) => e.kind === CaptureReadyEventKind.Liveness),
+    ).toHaveLength(2);
   });
 });
 
@@ -564,9 +648,9 @@ describe("session-boundary epoch reset — debouncer regression", () => {
       isImmediate: () => false,
     });
 
-    let previousScanState: ScanState | null = null;
+    let previousScanState: UseSmileIDScanState | null = null;
     const processTransition = (
-      nextScanState: ScanState,
+      nextScanState: UseSmileIDScanState,
       nextFeedbackKey: string,
     ) => {
       const boundary =
@@ -583,7 +667,7 @@ describe("session-boundary epoch reset — debouncer regression", () => {
 
     // found — smile key settles after the debounce window.
     processTransition(
-      { type: ScanStateType.Found, feedback: "si_capture_smile" },
+      { type: UseSmileIDScanStateType.Found, feedback: "si_capture_smile" },
       "si_capture_smile",
     );
     vi.advanceTimersByTime(UseSmileIDMotion.feedbackDebounce);
@@ -591,7 +675,7 @@ describe("session-boundary epoch reset — debouncer regression", () => {
 
     // Entering unsatisfied is not a boundary — no reset.
     processTransition(
-      { type: ScanStateType.Unsatisfied },
+      { type: UseSmileIDScanStateType.Unsatisfied },
       "si_selfie_capture_unsatisfied",
     );
     vi.advanceTimersByTime(UseSmileIDMotion.feedbackDebounce);
@@ -603,7 +687,7 @@ describe("session-boundary epoch reset — debouncer regression", () => {
     // Leaving unsatisfied is a boundary — without the reset the repeated
     // smile key would be suppressed as a duplicate.
     processTransition(
-      { type: ScanStateType.Found, feedback: "si_capture_smile" },
+      { type: UseSmileIDScanStateType.Found, feedback: "si_capture_smile" },
       "si_capture_smile",
     );
     // seed() emits synchronously; no timer advance needed.
@@ -613,4 +697,84 @@ describe("session-boundary epoch reset — debouncer regression", () => {
       "si_capture_smile",
     ]);
   });
+
+  // Document capture has no Start button, so a scan timeout has to leave the
+  // user a way forward — the sibling SDKs surface the manual shutter as the
+  // recovery affordance (their shared scan state sets `showCaptureButton` on
+  // the timeout state). Without these, a timed-out flow is a dead end: only
+  // Back and ✕ remain.
+  describe("document capture timeout recovery", () => {
+    function renderDocumentScreen(props: {
+      readonly captureMode: ReturnType<typeof DocumentCaptureMode.AutoCapture>;
+      readonly allowGalleryUpload?: boolean;
+    }) {
+      const tree = render(
+        <UseSmileIDCaptureScreen
+          analyzer={fakeAnalyzer}
+          captureType={CaptureType.document}
+          captureMode={props.captureMode}
+          allowGalleryUpload={props.allowGalleryUpload ?? true}
+        />,
+      );
+      // The overlay and its controls only mount once the canvas is measured;
+      // `onLayout` never fires under the test renderer, so drive it (landscape,
+      // as a document capture screen is).
+      act(() => {
+        findByTestID(tree.root, "si_capture_screen")!.props.onLayout({
+          nativeEvent: { layout: { width: 800, height: 400 } },
+        });
+      });
+      return tree;
+    }
+
+    function emitTimeout() {
+      expect(capturedOnResult).not.toBeNull();
+      act(() => {
+        capturedOnResult!({
+          output: { faces: [], brightness: 0 },
+          state: { type: UseSmileIDScanStateType.Timeout },
+          capturedEvents: [],
+        });
+      });
+    }
+
+    it("offers the manual shutter after a timeout, in every capture mode", () => {
+      const { root } = renderDocumentScreen({
+        captureMode: DocumentCaptureMode.AutoCapture,
+      });
+
+      emitTimeout();
+
+      expect(findByTestID(root, "si_document_manual_shutter")).not.toBeNull();
+    });
+
+    it("keeps the gallery button available after a timeout", () => {
+      const { root } = renderDocumentScreen({
+        captureMode: DocumentCaptureMode.AutoCaptureWithManualFallback({
+          activateManualAfterMs: 3000,
+        }),
+      });
+
+      emitTimeout();
+
+      expect(findByTestID(root, "si_document_gallery_upload")).not.toBeNull();
+    });
+
+    it("leaves the manual shutter usable after a timeout", () => {
+      const { root } = renderDocumentScreen({
+        captureMode: DocumentCaptureMode.ManualCapture,
+      });
+
+      emitTimeout();
+
+      const shutter = findByTestID(root, "si_document_manual_shutter");
+      expect(shutter).not.toBeNull();
+      // The timeout must not latch the one-shot delivery gate, or the button
+      // renders but does nothing.
+      act(() => {
+        shutter!.props.onPress();
+      });
+      expect(mockedTakePhoto).toHaveBeenCalledTimes(1);
+    });
+  });
 });

package/src/presentation/screen/__tests__/use_smile_id_document_back_instructions.test.tsx

@@ -104,7 +104,7 @@ describe("UseSmileIDDocumentBackInstructions", () => {
     const skip = findByTestID(root, "si_document_skip_back_button");
     expect(skip).not.toBeNull();
     act(() => {
-      (skip!.props.onPress as () => void)();
+      (skip!.props.onClick as () => void)();
     });
     expect(onSkip).toHaveBeenCalledTimes(1);
   });