@smileid/usesmileid 12.0.0 → 12.0.2

package/src/presentation/flow/screen/__tests__/orchestrated_capture_screen.test.tsx

@@ -0,0 +1,836 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import * as React from "react";
+import { create as createRenderer, act } from "react-test-renderer";
+
+// `vi.mock` is hoisted above the imports, so anything its factory closes over
+// must be created with `vi.hoisted` or it is still in the TDZ when the factory
+// runs.
+const {
+  captureScreenProps,
+  backInstructionsProps,
+  orientationLockCalls,
+  setContext,
+  finalize,
+  signals,
+} = vi.hoisted(() => ({
+  captureScreenProps: {
+    current: undefined as Record<string, unknown> | undefined,
+  },
+  backInstructionsProps: {
+    current: undefined as Record<string, unknown> | undefined,
+  },
+  orientationLockCalls: { current: [] as unknown[][] },
+  setContext: vi.fn(),
+  finalize: vi.fn(),
+  signals: vi.fn(),
+}));
+
+vi.mock("@smileid/usesmileid_bridge", async () => {
+  const actual = await vi.importActual<
+    typeof import("@smileid/usesmileid_bridge")
+  >("@smileid/usesmileid_bridge");
+  return { ...actual, DeviceIntegrityProvider: { signals } };
+});
+
+vi.mock("@smileid/usesmileid_bridge/src/exif/smile_exif_tagger", () => ({
+  SmileExifTagger: { setContext, finalize },
+}));
+
+// The real hook drives `expo-screen-orientation`; stand in for it so the
+// orientation the orchestrator *asks* for is observable without a device.
+vi.mock("../../../screen/helpers/use_capture_orientation_lock", () => ({
+  useCaptureOrientationLock: (...args: unknown[]) => {
+    orientationLockCalls.current.push(args);
+  },
+}));
+
+// Stand in for the leaf screens so these tests exercise the orchestration
+// (analyzer lifecycle, side tracking, EXIF + persistence, navigation) rather
+// than re-testing the camera UI, which has its own component suite.
+vi.mock("../../../screen/use_smile_id_capture_screen", () => ({
+  UseSmileIDCaptureScreen: (props: Record<string, unknown>) => {
+    captureScreenProps.current = props;
+    return null;
+  },
+}));
+
+vi.mock("../../../screen/use_smile_id_document_back_instructions", () => ({
+  UseSmileIDDocumentBackInstructions: (props: Record<string, unknown>) => {
+    backInstructionsProps.current = props;
+    return null;
+  },
+}));
+
+import {
+  CaptureReadyEventKind,
+  DocumentSide,
+  ImageType,
+} from "@smileid/usesmileid_bridge";
+import type { CaptureReadyEvent } from "@smileid/usesmileid_bridge";
+import { OrchestratedCaptureScreen } from "../orchestrated_capture_screen";
+import { FlowNavigationProvider } from "../../flow_navigation_context";
+import {
+  CaptureConfigBuilder,
+  CaptureType,
+} from "../../dsl/builder/screens_builder";
+import { DocumentType } from "../../../../core/models/document_type";
+import type { FlowNavigationManager } from "../../flow_navigation_manager";
+
+type Fn = ReturnType<typeof vi.fn>;
+
+type FakeManager = FlowNavigationManager & {
+  navigateToNext: Fn;
+  navigateBack: Fn;
+  exit: Fn;
+  setCapturedSelfie: Fn;
+  setCapturedFrontDocument: Fn;
+  setCapturedBackDocument: Fn;
+  skipDocumentBack: Fn;
+  recordDocumentImageOrigin: Fn;
+  recordSelfieCaptureTelemetry: Fn;
+  recordDocumentCaptureTelemetry: Fn;
+  documentPreviewFollowsCapture: Fn;
+};
+
+function makeAnalyzer(key?: string) {
+  const analyzer: Record<string, unknown> = {
+    configure: vi.fn(() => Promise.resolve()),
+    close: vi.fn(() => Promise.resolve()),
+  };
+  if (key !== undefined) analyzer.key = key;
+  return analyzer as { configure: Fn; close: Fn };
+}
+
+type ManagerOverrides = {
+  readonly selfieAnalyzer?: unknown;
+  readonly documentAnalyzer?: unknown;
+  readonly selfieConfig?: Record<string, unknown>;
+  readonly frontDocumentPath?: string;
+  readonly previewFollows?: boolean;
+  readonly resolvedSdkConfig?: Record<string, unknown>;
+  readonly exitOrientations?: unknown;
+};
+
+function makeManager(overrides: ManagerOverrides = {}): FakeManager {
+  const analyzers: Record<string, unknown> = {};
+  if (overrides.selfieAnalyzer !== undefined) {
+    analyzers.selfie = overrides.selfieAnalyzer;
+  }
+  if (overrides.documentAnalyzer !== undefined) {
+    analyzers.document = overrides.documentAnalyzer;
+  }
+  if (overrides.selfieConfig !== undefined) {
+    analyzers.selfieConfig = overrides.selfieConfig;
+  }
+  return {
+    navigateToNext: vi.fn(),
+    navigateBack: vi.fn(),
+    exit: vi.fn(),
+    setCapturedSelfie: vi.fn(),
+    setCapturedFrontDocument: vi.fn(),
+    setCapturedBackDocument: vi.fn(),
+    skipDocumentBack: vi.fn(),
+    recordDocumentImageOrigin: vi.fn(),
+    recordSelfieCaptureTelemetry: vi.fn(),
+    recordDocumentCaptureTelemetry: vi.fn(),
+    documentPreviewFollowsCapture: vi.fn(
+      () => overrides.previewFollows ?? false,
+    ),
+    partnerId: "002",
+    resolvedSdkConfig: overrides.resolvedSdkConfig,
+    captured: {
+      ...(overrides.frontDocumentPath !== undefined
+        ? { frontDocumentPath: overrides.frontDocumentPath }
+        : {}),
+    },
+    configuration: {
+      ml: { analyzers },
+      config:
+        overrides.exitOrientations !== undefined
+          ? { exitOrientations: overrides.exitOrientations }
+          : {},
+    },
+  } as unknown as FakeManager;
+}
+
+function selfieConfiguration(
+  block: (selfie: {
+    allowAgentMode: boolean;
+    enableEnhancedLiveness: boolean;
+  }) => void = () => {},
+): CaptureConfigBuilder {
+  const configuration = new CaptureConfigBuilder();
+  configuration.captureType = CaptureType.selfie;
+  configuration.selfie(block);
+  return configuration;
+}
+
+function documentConfiguration(
+  block: (document: {
+    documentType?: unknown;
+    captureBothSides: boolean;
+    allowSkipBack: boolean;
+    allowGalleryUpload: boolean;
+    knownIdAspectRatio?: number;
+  }) => void,
+): CaptureConfigBuilder {
+  const configuration = new CaptureConfigBuilder();
+  configuration.captureType = CaptureType.document;
+  configuration.document(
+    block as unknown as Parameters<CaptureConfigBuilder["document"]>[0],
+  );
+  return configuration;
+}
+
+function renderWith(
+  manager: FlowNavigationManager,
+  configuration: CaptureConfigBuilder,
+) {
+  let renderer!: ReturnType<typeof createRenderer>;
+  act(() => {
+    renderer = createRenderer(
+      <FlowNavigationProvider manager={manager}>
+        <OrchestratedCaptureScreen configuration={configuration} />
+      </FlowNavigationProvider>,
+    );
+  });
+  return renderer;
+}
+
+/** Drain the EXIF tagging promise chain kicked off by `onCaptureComplete`. */
+async function settle() {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
+function readCaptureProps(): Record<string, unknown> {
+  const props = captureScreenProps.current;
+  if (!props) throw new Error("UseSmileIDCaptureScreen was not rendered");
+  return props;
+}
+
+function readBackInstructionsProps(): Record<string, unknown> {
+  const props = backInstructionsProps.current;
+  if (!props) {
+    throw new Error("UseSmileIDDocumentBackInstructions was not rendered");
+  }
+  return props;
+}
+
+async function completeCapture(
+  events: readonly CaptureReadyEvent[],
+  telemetry: Record<string, unknown> = { durationMs: 1200, retries: 0 },
+) {
+  const onCaptureComplete = readCaptureProps().onCaptureComplete as (
+    events: readonly CaptureReadyEvent[],
+    telemetry: unknown,
+  ) => void;
+  await act(async () => {
+    onCaptureComplete(events, telemetry);
+  });
+  await settle();
+}
+
+const selfieEvent = {
+  kind: CaptureReadyEventKind.Selfie,
+  url: "file:///selfie.jpg",
+} as CaptureReadyEvent;
+const livenessEvents = [
+  { kind: CaptureReadyEventKind.Liveness, url: "file:///liveness-0.jpg" },
+  { kind: CaptureReadyEventKind.Liveness, url: "file:///liveness-1.jpg" },
+] as CaptureReadyEvent[];
+const documentEvent = {
+  kind: CaptureReadyEventKind.Document,
+  url: "file:///document.jpg",
+} as CaptureReadyEvent;
+
+beforeEach(() => {
+  captureScreenProps.current = undefined;
+  backInstructionsProps.current = undefined;
+  orientationLockCalls.current = [];
+  setContext.mockReset();
+  setContext.mockResolvedValue(undefined);
+  finalize.mockReset();
+  finalize.mockResolvedValue(undefined);
+  signals.mockReset();
+  signals.mockResolvedValue({ fingerprint: "device-fp" });
+});
+
+describe("OrchestratedCaptureScreen — selfie", () => {
+  it("configures the selfie analyzer with the screen's enhanced-liveness flag", () => {
+    const analyzer = makeAnalyzer("vision-face");
+    const manager = makeManager({ selfieAnalyzer: analyzer });
+
+    renderWith(
+      manager,
+      selfieConfiguration((selfie) => {
+        selfie.enableEnhancedLiveness = true;
+      }),
+    );
+
+    expect(analyzer.configure).toHaveBeenCalledTimes(1);
+    const [config] = analyzer.configure.mock.calls[0] as [
+      Record<string, unknown>,
+    ];
+    expect(config.enableEnhancedLiveness).toBe(true);
+    expect(config.analyzerFactoryKey).toBe("vision-face");
+  });
+
+  it("merges the registry-built base selfie config rather than replacing it", () => {
+    const analyzer = makeAnalyzer("vision-face");
+    const manager = makeManager({
+      selfieAnalyzer: analyzer,
+      selfieConfig: { analyzerFactoryKey: "vision-face", numSamples: 8 },
+    });
+
+    renderWith(manager, selfieConfiguration());
+
+    const [config] = analyzer.configure.mock.calls[0] as [
+      Record<string, unknown>,
+    ];
+    expect(config.numSamples).toBe(8);
+    expect(config.enableEnhancedLiveness).toBe(false);
+  });
+
+  it("closes the analyzer when the screen unmounts", () => {
+    const analyzer = makeAnalyzer("vision-face");
+    const renderer = renderWith(
+      makeManager({ selfieAnalyzer: analyzer }),
+      selfieConfiguration(),
+    );
+
+    expect(analyzer.close).not.toHaveBeenCalled();
+    act(() => {
+      renderer.unmount();
+    });
+    expect(analyzer.close).toHaveBeenCalledTimes(1);
+  });
+
+  it("locks portrait for selfie capture", () => {
+    renderWith(
+      makeManager({ selfieAnalyzer: makeAnalyzer("vision-face") }),
+      selfieConfiguration(),
+    );
+
+    expect(orientationLockCalls.current[0]?.[0]).toBe("Portrait");
+  });
+
+  it("threads the partner's exitOrientations into the orientation lock", () => {
+    renderWith(
+      makeManager({
+        selfieAnalyzer: makeAnalyzer("vision-face"),
+        exitOrientations: 5,
+      }),
+      selfieConfiguration(),
+    );
+
+    expect(orientationLockCalls.current[0]?.[1]).toEqual({ exitLock: 5 });
+  });
+
+  it("persists the selfie plus its liveness frames, then advances", async () => {
+    const manager = makeManager({
+      selfieAnalyzer: makeAnalyzer("vision-face"),
+    });
+    renderWith(manager, selfieConfiguration());
+
+    await completeCapture([selfieEvent, ...livenessEvents], {
+      durationMs: 900,
+      retries: 2,
+    });
+
+    expect(manager.setCapturedSelfie).toHaveBeenCalledWith(
+      "file:///selfie.jpg",
+      ["file:///liveness-0.jpg", "file:///liveness-1.jpg"],
+    );
+    expect(manager.recordSelfieCaptureTelemetry).toHaveBeenCalledWith({
+      durationMs: 900,
+      retries: 2,
+    });
+    expect(manager.navigateToNext).toHaveBeenCalledTimes(1);
+  });
+
+  it("stamps EXIF on the selfie and on every liveness frame", async () => {
+    renderWith(
+      makeManager({ selfieAnalyzer: makeAnalyzer("vision-face") }),
+      selfieConfiguration(),
+    );
+
+    await completeCapture([selfieEvent, ...livenessEvents]);
+
+    expect(setContext).toHaveBeenCalledWith({
+      partnerId: "002",
+      fingerprint: "device-fp",
+    });
+    expect(finalize).toHaveBeenCalledWith(
+      "file:///selfie.jpg",
+      ImageType.Selfie,
+    );
+    expect(finalize).toHaveBeenCalledWith(
+      "file:///liveness-0.jpg",
+      ImageType.Liveness,
+    );
+    expect(finalize).toHaveBeenCalledWith(
+      "file:///liveness-1.jpg",
+      ImageType.Liveness,
+    );
+  });
+
+  it("omits a blank device fingerprint so it can't shadow a real one", async () => {
+    signals.mockResolvedValue({ fingerprint: "" });
+    renderWith(
+      makeManager({ selfieAnalyzer: makeAnalyzer("vision-face") }),
+      selfieConfiguration(),
+    );
+
+    await completeCapture([selfieEvent]);
+
+    expect(setContext).toHaveBeenCalledWith({ partnerId: "002" });
+  });
+
+  it("stays on the screen when the pipeline emits no selfie artifact", async () => {
+    const manager = makeManager({
+      selfieAnalyzer: makeAnalyzer("vision-face"),
+    });
+    renderWith(manager, selfieConfiguration());
+
+    await completeCapture(livenessEvents);
+
+    expect(manager.setCapturedSelfie).not.toHaveBeenCalled();
+    expect(manager.navigateToNext).not.toHaveBeenCalled();
+    expect(setContext).not.toHaveBeenCalled();
+  });
+
+  it("still persists and advances when EXIF tagging rejects (fail-open)", async () => {
+    finalize.mockRejectedValue(new Error("native tagger unavailable"));
+    const manager = makeManager({
+      selfieAnalyzer: makeAnalyzer("vision-face"),
+    });
+    renderWith(manager, selfieConfiguration());
+
+    await completeCapture([selfieEvent]);
+
+    expect(manager.setCapturedSelfie).toHaveBeenCalledWith(
+      "file:///selfie.jpg",
+      [],
+    );
+    expect(manager.navigateToNext).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwards agent mode and enhanced liveness to the capture screen", () => {
+    renderWith(
+      makeManager({ selfieAnalyzer: makeAnalyzer("vision-face") }),
+      selfieConfiguration((selfie) => {
+        selfie.allowAgentMode = true;
+        selfie.enableEnhancedLiveness = true;
+      }),
+    );
+
+    const props = readCaptureProps();
+    expect(props.allowAgentMode).toBe(true);
+    expect(props.enableEnhancedLiveness).toBe(true);
+    expect(props.captureType).toBe(CaptureType.selfie);
+  });
+
+  it("does not pass document-only props on a selfie capture", () => {
+    renderWith(
+      makeManager({ selfieAnalyzer: makeAnalyzer("vision-face") }),
+      selfieConfiguration(),
+    );
+
+    const props = readCaptureProps();
+    expect("documentSide" in props).toBe(false);
+    expect("knownIdAspectRatio" in props).toBe(false);
+    expect("onClose" in props).toBe(false);
+  });
+
+  it("omits the startButton slot when the partner supplies none", () => {
+    renderWith(
+      makeManager({ selfieAnalyzer: makeAnalyzer("vision-face") }),
+      selfieConfiguration(),
+    );
+
+    expect("startButton" in readCaptureProps()).toBe(false);
+  });
+
+  it("passes a partner startButton slot straight through", () => {
+    const startButton = vi.fn(() => null);
+    const configuration = selfieConfiguration();
+    configuration.startButton =
+      startButton as unknown as CaptureConfigBuilder["startButton"];
+
+    renderWith(
+      makeManager({ selfieAnalyzer: makeAnalyzer("vision-face") }),
+      configuration,
+    );
+
+    expect(readCaptureProps().startButton).toBe(startButton);
+  });
+
+  it("back on a selfie capture rewinds the flow", () => {
+    const manager = makeManager({
+      selfieAnalyzer: makeAnalyzer("vision-face"),
+    });
+    renderWith(manager, selfieConfiguration());
+
+    act(() => {
+      (readCaptureProps().onBack as () => void)();
+    });
+
+    expect(manager.navigateBack).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("OrchestratedCaptureScreen — single-sided document", () => {
+  const greenBook = DocumentType.GenericDocument({
+    displayName: "Booklet",
+    hasBackSide: false,
+    orientation: "Portrait",
+  });
+
+  function singleSided() {
+    return documentConfiguration((document) => {
+      document.documentType = greenBook;
+      document.captureBothSides = false;
+    });
+  }
+
+  it("configures the document analyzer for the front side", () => {
+    const analyzer = makeAnalyzer();
+    renderWith(makeManager({ documentAnalyzer: analyzer }), singleSided());
+
+    expect(analyzer.configure).toHaveBeenCalledWith({
+      documentSide: DocumentSide.Front,
+    });
+  });
+
+  it("applies the sdk_config document JPEG quality when it is in range", () => {
+    const analyzer = makeAnalyzer();
+    renderWith(
+      makeManager({
+        documentAnalyzer: analyzer,
+        resolvedSdkConfig: { document: { quality: 72 } },
+      }),
+      singleSided(),
+    );
+
+    expect(analyzer.configure).toHaveBeenCalledWith({
+      documentSide: DocumentSide.Front,
+      documentJpegQuality: 72,
+    });
+  });
+
+  it("locks the document type's own orientation", () => {
+    renderWith(
+      makeManager({ documentAnalyzer: makeAnalyzer() }),
+      singleSided(),
+    );
+
+    expect(orientationLockCalls.current[0]?.[0]).toBe("Portrait");
+  });
+
+  it("persists the front document and advances", async () => {
+    const manager = makeManager({ documentAnalyzer: makeAnalyzer() });
+    renderWith(manager, singleSided());
+
+    await completeCapture([documentEvent], { durationMs: 400, retries: 1 });
+
+    expect(finalize).toHaveBeenCalledWith(
+      "file:///document.jpg",
+      ImageType.DocumentFront,
+    );
+    expect(manager.recordDocumentCaptureTelemetry).toHaveBeenCalledWith(
+      DocumentSide.Front,
+      { durationMs: 400, retries: 1 },
+    );
+    expect(manager.setCapturedFrontDocument).toHaveBeenCalledWith(
+      "file:///document.jpg",
+    );
+    expect(manager.setCapturedBackDocument).not.toHaveBeenCalled();
+    expect(manager.navigateToNext).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back to the orientation default when the type has no known ratio", () => {
+    renderWith(
+      makeManager({ documentAnalyzer: makeAnalyzer() }),
+      singleSided(),
+    );
+
+    expect(readCaptureProps().knownIdAspectRatio).toBeCloseTo(0.65, 5);
+  });
+
+  it("prefers the document type's known aspect ratio", () => {
+    renderWith(
+      makeManager({ documentAnalyzer: makeAnalyzer() }),
+      documentConfiguration((document) => {
+        document.documentType = DocumentType.Passport;
+        document.captureBothSides = false;
+      }),
+    );
+
+    expect(readCaptureProps().knownIdAspectRatio).toBeCloseTo(356 / 272, 5);
+  });
+
+  it("passes the document kind through so the frame can specialise", () => {
+    renderWith(
+      makeManager({ documentAnalyzer: makeAnalyzer() }),
+      documentConfiguration((document) => {
+        document.documentType = DocumentType.Passport;
+        document.captureBothSides = false;
+      }),
+    );
+
+    expect(readCaptureProps().documentTypeKind).toBe("passport");
+  });
+
+  it("records the image origin against the side being captured", () => {
+    const manager = makeManager({ documentAnalyzer: makeAnalyzer() });
+    renderWith(manager, singleSided());
+
+    (readCaptureProps().onDocumentOrigin as (origin: string) => void)(
+      "gallery",
+    );
+
+    expect(manager.recordDocumentImageOrigin).toHaveBeenCalledWith(
+      DocumentSide.Front,
+      "gallery",
+    );
+  });
+
+  it("closing the document capture exits the flow", () => {
+    const manager = makeManager({ documentAnalyzer: makeAnalyzer() });
+    renderWith(manager, singleSided());
+
+    (readCaptureProps().onClose as () => void)();
+
+    expect(manager.exit).toHaveBeenCalledTimes(1);
+  });
+
+  it("stays on the screen when the pipeline emits no document artifact", async () => {
+    const manager = makeManager({ documentAnalyzer: makeAnalyzer() });
+    renderWith(manager, singleSided());
+
+    await completeCapture([selfieEvent]);
+
+    expect(manager.setCapturedFrontDocument).not.toHaveBeenCalled();
+    expect(manager.navigateToNext).not.toHaveBeenCalled();
+  });
+});
+
+describe("OrchestratedCaptureScreen — two-sided document, in-screen flip", () => {
+  function twoSided(allowSkipBack = false) {
+    return documentConfiguration((document) => {
+      document.documentType = DocumentType.Passport;
+      document.captureBothSides = true;
+      document.allowSkipBack = allowSkipBack;
+    });
+  }
+
+  it("shows the flip interstitial after the front capture instead of advancing", async () => {
+    const manager = makeManager({ documentAnalyzer: makeAnalyzer() });
+    renderWith(manager, twoSided());
+
+    await completeCapture([documentEvent]);
+
+    expect(manager.setCapturedFrontDocument).toHaveBeenCalledWith(
+      "file:///document.jpg",
+    );
+    expect(manager.navigateToNext).not.toHaveBeenCalled();
+    expect(readBackInstructionsProps().documentTypeDisplayName).toBe(
+      "Passport",
+    );
+  });
+
+  it("forces portrait while the flip interstitial shows, then reverts", async () => {
+    renderWith(makeManager({ documentAnalyzer: makeAnalyzer() }), twoSided());
+    expect(orientationLockCalls.current[0]?.[0]).toBe("Landscape");
+
+    await completeCapture([documentEvent]);
+    expect(orientationLockCalls.current.at(-1)?.[0]).toBe("Portrait");
+
+    act(() => {
+      (readBackInstructionsProps().onCaptureBack as () => void)();
+    });
+    expect(orientationLockCalls.current.at(-1)?.[0]).toBe("Landscape");
+  });
+
+  it("reconfigures the analyzer for the back side so it can't overwrite the front", async () => {
+    const analyzer = makeAnalyzer();
+    renderWith(makeManager({ documentAnalyzer: analyzer }), twoSided());
+
+    await completeCapture([documentEvent]);
+    act(() => {
+      (readBackInstructionsProps().onCaptureBack as () => void)();
+    });
+
+    expect(analyzer.configure).toHaveBeenLastCalledWith({
+      documentSide: DocumentSide.Back,
+    });
+    expect(analyzer.close).toHaveBeenCalled();
+  });
+
+  it("persists the back document and advances after the second capture", async () => {
+    const manager = makeManager({ documentAnalyzer: makeAnalyzer() });
+    renderWith(manager, twoSided());
+
+    await completeCapture([documentEvent]);
+    act(() => {
+      (readBackInstructionsProps().onCaptureBack as () => void)();
+    });
+    await completeCapture([
+      { kind: CaptureReadyEventKind.Document, url: "file:///back.jpg" },
+    ] as CaptureReadyEvent[]);
+
+    expect(finalize).toHaveBeenCalledWith(
+      "file:///back.jpg",
+      ImageType.DocumentBack,
+    );
+    expect(manager.setCapturedBackDocument).toHaveBeenCalledWith(
+      "file:///back.jpg",
+    );
+    expect(manager.recordDocumentCaptureTelemetry).toHaveBeenLastCalledWith(
+      DocumentSide.Back,
+      { durationMs: 1200, retries: 0 },
+    );
+    expect(manager.navigateToNext).toHaveBeenCalledTimes(1);
+  });
+
+  it("hides the skip action unless the partner opted in", async () => {
+    renderWith(makeManager({ documentAnalyzer: makeAnalyzer() }), twoSided());
+    await completeCapture([documentEvent]);
+
+    expect(readBackInstructionsProps().allowSkip).toBe(false);
+  });
+
+  it("skipping the back routes past its capture and preview", async () => {
+    const manager = makeManager({ documentAnalyzer: makeAnalyzer() });
+    renderWith(manager, twoSided(true));
+    await completeCapture([documentEvent]);
+
+    expect(readBackInstructionsProps().allowSkip).toBe(true);
+    act(() => {
+      (readBackInstructionsProps().onSkip as () => void)();
+    });
+
+    expect(manager.skipDocumentBack).toHaveBeenCalledTimes(1);
+    expect(manager.navigateToNext).toHaveBeenCalledTimes(1);
+    expect(manager.setCapturedBackDocument).not.toHaveBeenCalled();
+  });
+
+  it("back from the flip interstitial re-captures the front in place", async () => {
+    const manager = makeManager({ documentAnalyzer: makeAnalyzer() });
+    renderWith(manager, twoSided());
+    await completeCapture([documentEvent]);
+
+    act(() => {
+      (readBackInstructionsProps().onBack as () => void)();
+    });
+
+    expect(manager.navigateBack).not.toHaveBeenCalled();
+    expect(readCaptureProps().documentSide).toBe(DocumentSide.Front);
+  });
+
+  it("back from the back-side capture returns to the flip interstitial", async () => {
+    const manager = makeManager({ documentAnalyzer: makeAnalyzer() });
+    renderWith(manager, twoSided());
+    await completeCapture([documentEvent]);
+    act(() => {
+      (readBackInstructionsProps().onCaptureBack as () => void)();
+    });
+    expect(readCaptureProps().documentSide).toBe(DocumentSide.Back);
+
+    backInstructionsProps.current = undefined;
+    act(() => {
+      (readCaptureProps().onBack as () => void)();
+    });
+
+    expect(manager.navigateBack).not.toHaveBeenCalled();
+    expect(readBackInstructionsProps().documentTypeDisplayName).toBe(
+      "Passport",
+    );
+  });
+
+  it("records back-side telemetry against the back, not the front", async () => {
+    const manager = makeManager({ documentAnalyzer: makeAnalyzer() });
+    renderWith(manager, twoSided());
+    await completeCapture([documentEvent], { durationMs: 100, retries: 0 });
+    act(() => {
+      (readBackInstructionsProps().onCaptureBack as () => void)();
+    });
+    await completeCapture([documentEvent], { durationMs: 250, retries: 3 });
+
+    expect(manager.recordDocumentCaptureTelemetry.mock.calls).toEqual([
+      [DocumentSide.Front, { durationMs: 100, retries: 0 }],
+      [DocumentSide.Back, { durationMs: 250, retries: 3 }],
+    ]);
+  });
+});
+
+describe("OrchestratedCaptureScreen — two-sided document with a preview between sides", () => {
+  function twoSided() {
+    return documentConfiguration((document) => {
+      document.documentType = DocumentType.Passport;
+      document.captureBothSides = true;
+    });
+  }
+
+  it("exits to the front preview instead of flipping in-screen", async () => {
+    const manager = makeManager({
+      documentAnalyzer: makeAnalyzer(),
+      previewFollows: true,
+    });
+    renderWith(manager, twoSided());
+
+    await completeCapture([documentEvent]);
+
+    expect(manager.setCapturedFrontDocument).toHaveBeenCalledWith(
+      "file:///document.jpg",
+    );
+    expect(manager.navigateToNext).toHaveBeenCalledTimes(1);
+    expect(backInstructionsProps.current).toBeUndefined();
+  });
+
+  it("re-entry with the front already captured starts on the back with the flip prompt", () => {
+    const analyzer = makeAnalyzer();
+    renderWith(
+      makeManager({
+        documentAnalyzer: analyzer,
+        previewFollows: true,
+        frontDocumentPath: "file:///document.jpg",
+      }),
+      twoSided(),
+    );
+
+    expect(analyzer.configure).toHaveBeenCalledWith({
+      documentSide: DocumentSide.Back,
+    });
+    expect(readBackInstructionsProps().documentTypeDisplayName).toBe(
+      "Passport",
+    );
+    expect(captureScreenProps.current).toBeUndefined();
+  });
+
+  it("back from the flip prompt rewinds to the front preview", () => {
+    const manager = makeManager({
+      documentAnalyzer: makeAnalyzer(),
+      previewFollows: true,
+      frontDocumentPath: "file:///document.jpg",
+    });
+    renderWith(manager, twoSided());
+
+    act(() => {
+      (readBackInstructionsProps().onBack as () => void)();
+    });
+
+    expect(manager.navigateBack).toHaveBeenCalledTimes(1);
+    expect(captureScreenProps.current).toBeUndefined();
+  });
+});
+
+describe("OrchestratedCaptureScreen — missing analyzer", () => {
+  it("fails loudly rather than rendering an empty preview", () => {
+    expect(() => renderWith(makeManager(), selfieConfiguration())).toThrow(
+      /no selfie analyzer registered/,
+    );
+  });
+});