@smileid/usesmileid 12.0.0-beta01

package/src/presentation/flow/graph/screen_renderer.tsx

@@ -0,0 +1,35 @@
+import type { ScreenSpec } from "../dsl/builder/screens_builder";
+import { OrchestratedCaptureScreen } from "../screen/orchestrated_capture_screen";
+import { OrchestratedConsentScreen } from "../screen/orchestrated_consent_screen";
+import { OrchestratedInstructionsScreen } from "../screen/orchestrated_instructions_screen";
+import { OrchestratedPreviewScreen } from "../screen/orchestrated_preview_screen";
+import { OrchestratedProcessingScreen } from "../screen/orchestrated_processing_screen";
+
+export type ScreenRendererProps = {
+  readonly step: ScreenSpec;
+};
+
+/**
+ * Internal switch-on-kind dispatcher. Routes the active step's
+ * configuration to the matching `OrchestratedXxxScreen` — which then
+ * wraps the visual screen in a `UseSmileIDOrchestratedScreenHost`
+ * and wires the navigation manager callbacks.
+ *
+ * Theme + localization providers are mounted higher up in
+ * `<UseSmileIDBuilder>` so every orchestrated screen reads them via
+ * context.
+ */
+export function ScreenRenderer({ step }: ScreenRendererProps) {
+  switch (step.kind) {
+    case "instructions":
+      return <OrchestratedInstructionsScreen configuration={step.config} />;
+    case "consent":
+      return <OrchestratedConsentScreen configuration={step.config} />;
+    case "capture":
+      return <OrchestratedCaptureScreen configuration={step.config} />;
+    case "preview":
+      return <OrchestratedPreviewScreen configuration={step.config} />;
+    case "processing":
+      return <OrchestratedProcessingScreen configuration={step.config} />;
+  }
+}

package/src/presentation/flow/job_submission_state.ts

@@ -0,0 +1,17 @@
+import type { JobSubmissionResponse } from "../../data/model/job_submission_response";
+
+/**
+ * In-flight job-submission state owned by `FlowNavigationManager`.
+ *
+ * `notAttempted` is the freshly-mounted state that
+ * `beginSubmissionIfNeeded()` guards on for idempotency. `loading`
+ * is set the moment submission kicks off so re-renders don't re-fire
+ * the request. `success` carries the server response so the
+ * processing screen can display the message; `failure` carries the
+ * already-mapped `Error` from `UseSmileIDRepositoryImpl._mapError`.
+ */
+export type JobSubmissionState =
+  | { readonly kind: "notAttempted" }
+  | { readonly kind: "loading" }
+  | { readonly kind: "success"; readonly response: JobSubmissionResponse }
+  | { readonly kind: "failure"; readonly error: Error };

package/src/presentation/flow/model/instruction_guideline.ts

@@ -0,0 +1,15 @@
+import type { FC } from "react";
+import type { UseSmileIDLocalizations } from "../../../l10n/use_smile_id_localizations";
+
+/** Whether a guideline depicts an allowed condition or a blocked one. */
+export type GuidelineStatus = "allowed" | "blocked";
+
+/**
+ * A capture-guideline tile's data. `label` is a resolver (not a string) so the
+ * shared default list can be allocated once without a render context.
+ */
+export type InstructionGuideline = {
+  readonly image: FC<{ readonly width?: number; readonly height?: number }>;
+  readonly label: (localizations: UseSmileIDLocalizations) => string;
+  readonly status: GuidelineStatus;
+};

package/src/presentation/flow/model/instructions_defaults.ts

@@ -0,0 +1,120 @@
+import type { AnimationObject } from "lottie-react-native";
+import {
+  SiGuidelineAccessories,
+  SiGuidelineDocumentGood,
+  SiGuidelineDocumentNotBlurry,
+  SiGuidelineDocumentNotCropped,
+  SiGuidelineDocumentNotReflective,
+  SiGuidelineGood,
+  SiGuidelineMultipleFaces,
+  SiGuidelinePoorLighting,
+} from "../../components/icons";
+import type { DocumentType } from "../../../core/models/document_type";
+import type { InstructionGuideline } from "./instruction_guideline";
+
+/** Lottie source accepted for the instructions hero animation. */
+export type HeroAnimationSource =
+  | AnimationObject
+  | string
+  | { readonly uri: string };
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+export const SELFIE_HERO_ANIMATION =
+  require("../../assets/si_selfie_hero_animation.json") as AnimationObject;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+export const ESS_HERO_ANIMATION =
+  require("../../assets/si_ess_animation_all_directions.json") as AnimationObject;
+
+// Document hero animations — per-document-type front instruction heroes, plus
+// the back-of-ID (flip) hero shown on the back-capture interstitial.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+export const DOCUMENT_HERO_ANIMATION =
+  require("../../assets/si_document_hero_animation.json") as AnimationObject;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+export const DOCUMENT_PASSPORT_HERO_ANIMATION =
+  require("../../assets/si_document_passport_hero_animation.json") as AnimationObject;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+export const DOCUMENT_GREEN_BOOK_HERO_ANIMATION =
+  require("../../assets/si_document_green_book_hero_animation.json") as AnimationObject;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+export const DOCUMENT_HERO_BACK_ANIMATION =
+  require("../../assets/si_document_hero_back_animation.json") as AnimationObject;
+
+const SELFIE_GUIDELINE_ENTRIES: InstructionGuideline[] = [
+  {
+    image: SiGuidelineGood,
+    label: (localizations) => localizations.siInstructionsGuidelineGood,
+    status: "allowed",
+  },
+  {
+    image: SiGuidelineAccessories,
+    label: (localizations) => localizations.siInstructionsGuidelineAccessories,
+    status: "blocked",
+  },
+  {
+    image: SiGuidelineMultipleFaces,
+    label: (localizations) =>
+      localizations.siInstructionsGuidelineMultipleFaces,
+    status: "blocked",
+  },
+  {
+    image: SiGuidelinePoorLighting,
+    label: (localizations) => localizations.siInstructionsGuidelinePoorLighting,
+    status: "blocked",
+  },
+];
+
+/**
+ * Default Smart Selfie capture guidelines — allocated once and deeply frozen
+ * (array + each entry) so the shared default never churns and can't be
+ * mutated by a caller.
+ */
+export const SELFIE_GUIDELINES: readonly InstructionGuideline[] = Object.freeze(
+  SELFIE_GUIDELINE_ENTRIES.map((guideline) => Object.freeze(guideline)),
+);
+
+const DOCUMENT_GUIDELINE_ENTRIES: InstructionGuideline[] = [
+  {
+    image: SiGuidelineDocumentGood,
+    label: (localizations) => localizations.siDocumentGuidelineGood,
+    status: "allowed",
+  },
+  {
+    image: SiGuidelineDocumentNotCropped,
+    label: (localizations) => localizations.siDocumentGuidelineNotCropped,
+    status: "blocked",
+  },
+  {
+    image: SiGuidelineDocumentNotBlurry,
+    label: (localizations) => localizations.siDocumentGuidelineNotBlurry,
+    status: "blocked",
+  },
+  {
+    image: SiGuidelineDocumentNotReflective,
+    label: (localizations) => localizations.siDocumentGuidelineNotReflective,
+    status: "blocked",
+  },
+];
+
+/** Default document-capture guidelines — allocated once and deeply frozen. */
+export const DOCUMENT_GUIDELINES: readonly InstructionGuideline[] =
+  Object.freeze(
+    DOCUMENT_GUIDELINE_ENTRIES.map((guideline) => Object.freeze(guideline)),
+  );
+
+/**
+ * Resolve the document hero animation for a document type. Falls back to the
+ * generic document hero when the type is unset or has no dedicated animation.
+ */
+export function documentHeroAnimation(
+  documentType: DocumentType | undefined,
+): AnimationObject {
+  switch (documentType?.kind) {
+    case "southAfricaGreenBook":
+      return DOCUMENT_GREEN_BOOK_HERO_ANIMATION;
+    case "passport":
+      return DOCUMENT_PASSPORT_HERO_ANIMATION;
+    default:
+      return DOCUMENT_HERO_ANIMATION;
+  }
+}

package/src/presentation/flow/screen/helpers/__tests__/face_session_config.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+import type { FaceConfig } from "@smileid/usesmileid_bridge";
+import { EnhancedSmartSelfieConfig } from "@smileid/usesmileid_bridge";
+import { resolveFaceSessionConfig } from "../face_session_config";
+import type { SdkConfig } from "../../../../../data/model/sdk_config";
+
+const baseConfig: FaceConfig = {
+  analyzerFactoryKey: "mlkit-face",
+  selfieCaptureTimeout: 100_000,
+  numSamples: 8,
+  sampleInterval: 350,
+};
+
+describe("resolveFaceSessionConfig", () => {
+  it("keeps the profile-driven numSamples on the standard path", () => {
+    const resolved = resolveFaceSessionConfig(baseConfig, false);
+    expect(resolved.numSamples).toBe(8);
+    expect(resolved.enableEnhancedLiveness).toBe(false);
+  });
+
+  it("forces numSamples to the hold-still count under Enhanced Smart Selfie", () => {
+    // The native session adds the head-turn stills on top of numSamples.
+    const resolved = resolveFaceSessionConfig(baseConfig, true);
+    expect(resolved.numSamples).toBe(
+      EnhancedSmartSelfieConfig.HOLD_STILL_SAMPLE_COUNT,
+    );
+    expect(resolved.enableEnhancedLiveness).toBe(true);
+  });
+
+  it("preserves every other field of the base config", () => {
+    const resolved = resolveFaceSessionConfig(baseConfig, true);
+    expect(resolved.analyzerFactoryKey).toBe("mlkit-face");
+    expect(resolved.selfieCaptureTimeout).toBe(100_000);
+    expect(resolved.sampleInterval).toBe(350);
+  });
+
+  it("does not mutate the base config", () => {
+    resolveFaceSessionConfig(baseConfig, true);
+    expect(baseConfig.numSamples).toBe(8);
+    expect(baseConfig.enableEnhancedLiveness).toBeUndefined();
+  });
+});
+
+describe("resolveFaceSessionConfig — sdk_config overrides", () => {
+  const sdkConfig: SdkConfig = {
+    selfie: { width: 640, height: 480, quality: 90 },
+    liveness: { width: 320, height: 240, quality: 70 },
+    livenessImageCount: 5,
+  };
+
+  it("applies selfie dimensions from sdk_config", () => {
+    const resolved = resolveFaceSessionConfig(baseConfig, false, sdkConfig);
+    expect(resolved.selfieImageWidth).toBe(640);
+    expect(resolved.selfieImageHeight).toBe(480);
+  });
+
+  it("applies selfie JPEG quality from sdk_config", () => {
+    const resolved = resolveFaceSessionConfig(baseConfig, false, sdkConfig);
+    expect(resolved.selfieJpegQuality).toBe(90);
+  });
+
+  it("applies liveness dimensions from sdk_config", () => {
+    const resolved = resolveFaceSessionConfig(baseConfig, false, sdkConfig);
+    expect(resolved.livenessImageWidth).toBe(320);
+    expect(resolved.livenessImageHeight).toBe(240);
+  });
+
+  it("applies liveness JPEG quality from sdk_config", () => {
+    const resolved = resolveFaceSessionConfig(baseConfig, false, sdkConfig);
+    expect(resolved.livenessJpegQuality).toBe(70);
+  });
+
+  it("applies livenessImageCount as numSamples (+1) when not ESS", () => {
+    // livenessImageCount: 5 → numSamples = 6
+    const resolved = resolveFaceSessionConfig(baseConfig, false, sdkConfig);
+    expect(resolved.numSamples).toBe(6);
+  });
+
+  it("suppresses livenessImageCount override under Enhanced Smart Selfie", () => {
+    // ESS manages its own capture count — the sdk_config override must
+    // not bleed through and change numSamples.
+    const resolved = resolveFaceSessionConfig(baseConfig, true, sdkConfig);
+    expect(resolved.numSamples).toBe(
+      EnhancedSmartSelfieConfig.HOLD_STILL_SAMPLE_COUNT,
+    );
+  });
+
+  it("omits selfie dimension fields when the pair rule fails (width-only)", () => {
+    const halfConfig: SdkConfig = { selfie: { width: 640 } };
+    const resolved = resolveFaceSessionConfig(baseConfig, false, halfConfig);
+    expect(resolved.selfieImageWidth).toBeUndefined();
+    expect(resolved.selfieImageHeight).toBeUndefined();
+  });
+
+  it("falls back to base numSamples when livenessImageCount is absent", () => {
+    const noCount: SdkConfig = { selfie: { quality: 85 } };
+    const resolved = resolveFaceSessionConfig(baseConfig, false, noCount);
+    // Base config has numSamples: 8 — should be preserved.
+    expect(resolved.numSamples).toBe(8);
+  });
+
+  it("does not set dimension fields when sdk_config is undefined", () => {
+    const resolved = resolveFaceSessionConfig(baseConfig, false, undefined);
+    expect(resolved.selfieImageWidth).toBeUndefined();
+    expect(resolved.selfieImageHeight).toBeUndefined();
+    expect(resolved.livenessImageWidth).toBeUndefined();
+    expect(resolved.livenessImageHeight).toBeUndefined();
+  });
+
+  it("does not mutate the base config when sdk_config is supplied", () => {
+    resolveFaceSessionConfig(baseConfig, false, sdkConfig);
+    expect(baseConfig.numSamples).toBe(8);
+    expect(baseConfig.selfieImageWidth).toBeUndefined();
+  });
+});

package/src/presentation/flow/screen/helpers/face_session_config.ts

@@ -0,0 +1,77 @@
+import type { FaceConfig } from "@smileid/usesmileid_bridge";
+import { enhancedSmartSelfieNumSamples } from "@smileid/usesmileid_bridge";
+import type { SdkConfig } from "../../../../data/model/sdk_config";
+import { numSamplesOverride } from "../../../../data/model/sdk_config";
+import {
+  resolveDimensions,
+  resolveJpegQuality,
+} from "../../../../data/model/sdk_config_capture";
+
+/**
+ * Merge the screen-level Enhanced Smart Selfie flag and any decoded
+ * `sdk_config` settings into the registry-built base config.
+ *
+ * Applied overrides (when `sdkConfig` is present):
+ *   - Selfie capture dimensions (`selfieImageWidth` / `selfieImageHeight`):
+ *     pair-fallback rule — both must be present and `> 0`.
+ *   - Selfie JPEG quality (`selfieJpegQuality`): integer `1..100`.
+ *   - Liveness capture dimensions (`livenessImageWidth` / `livenessImageHeight`):
+ *     same pair rule.
+ *   - Liveness JPEG quality (`livenessJpegQuality`): integer `1..100`.
+ *   - `numSamples` from `livenessImageCount + 1`: suppressed when ESS is
+ *     active (head-turn manages its own count). Falls back to the base
+ *     config's `numSamples` (set from `ScanPerformanceProfile`) when the
+ *     claim is absent or invalid.
+ *
+ * `faceConfigSchema` re-applies the ESS frame-count pin at every
+ * `configure()` boundary, so direct `analyzer.configure()` callers are
+ * equally safe; applying the pin here keeps the orchestrator's resolved
+ * config honest for logging and tests.
+ */
+export function resolveFaceSessionConfig(
+  baseConfig: FaceConfig,
+  enableEnhancedLiveness: boolean,
+  sdkConfig?: SdkConfig,
+): FaceConfig {
+  const selfieDims = resolveDimensions(sdkConfig?.selfie);
+  const livenessDims = resolveDimensions(sdkConfig?.liveness);
+  const selfieQuality = resolveJpegQuality(sdkConfig?.selfie);
+  const livenessQuality = resolveJpegQuality(sdkConfig?.liveness);
+
+  // Suppress the liveness-count override when ESS is active — the
+  // head-turn flow manages its own capture count internally.
+  const resolvedNumSamples =
+    (!enableEnhancedLiveness ? numSamplesOverride(sdkConfig) : undefined) ??
+    baseConfig.numSamples;
+
+  return enhancedSmartSelfieNumSamples({
+    ...baseConfig,
+    enableEnhancedLiveness,
+    // Selfie dimensions — spread only when the pair resolves.
+    ...(selfieDims !== undefined
+      ? {
+          selfieImageWidth: selfieDims.width,
+          selfieImageHeight: selfieDims.height,
+        }
+      : {}),
+    // Selfie JPEG quality — spread only when the value is in range.
+    ...(selfieQuality !== undefined
+      ? { selfieJpegQuality: selfieQuality }
+      : {}),
+    // Liveness dimensions — spread only when the pair resolves.
+    ...(livenessDims !== undefined
+      ? {
+          livenessImageWidth: livenessDims.width,
+          livenessImageHeight: livenessDims.height,
+        }
+      : {}),
+    // Liveness JPEG quality — spread only when the value is in range.
+    ...(livenessQuality !== undefined
+      ? { livenessJpegQuality: livenessQuality }
+      : {}),
+    // numSamples from sdk_config (suppressed for ESS; falls back to profile).
+    ...(resolvedNumSamples !== undefined
+      ? { numSamples: resolvedNumSamples }
+      : {}),
+  });
+}

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

@@ -0,0 +1,296 @@
+import { useEffect, useState } from "react";
+import type {
+  DocumentAnalyzer,
+  FaceAnalyzer,
+} from "@smileid/usesmileid_platform_interface";
+import type {
+  CaptureReadyEvent,
+  ImageTypeId,
+} from "@smileid/usesmileid_bridge";
+import {
+  CaptureReadyEventKind,
+  DocumentSide,
+  ImageType,
+} from "@smileid/usesmileid_bridge";
+import { CaptureType } from "../../../core/models/ml_config";
+import { defaultFrameAspectRatio } from "../../../core/models/document_type";
+// Deep import: SmileExifTagger is SDK-internal, kept out of the public barrel.
+import { SmileExifTagger } from "@smileid/usesmileid_bridge/src/exif/smile_exif_tagger";
+import type { CaptureConfigBuilder } from "../dsl/builder/screens_builder";
+import { resolveFaceSessionConfig } from "./helpers/face_session_config";
+import { useCaptureOrientationLock } from "../../screen/helpers/use_capture_orientation_lock";
+import { resolveJpegQuality } from "../../../data/model/sdk_config_capture";
+import { UseSmileIDCaptureScreen } from "../../screen/use_smile_id_capture_screen";
+import { UseSmileIDDocumentBackInstructions } from "../../screen/use_smile_id_document_back_instructions";
+import { useFlowNavigation } from "../flow_navigation_context";
+import { UseSmileIDOrchestratedScreenHost } from "./use_smile_id_orchestrated_screen_host";
+
+export type OrchestratedCaptureScreenProps = {
+  readonly configuration: CaptureConfigBuilder;
+};
+
+/**
+ * Orchestrated capture screen — wraps `UseSmileIDCaptureScreen`, owns the
+ * analyzer lifecycle (configure on mount, close on unmount), and persists
+ * artifacts on the navigation manager before advancing. For two-sided
+ * document captures it tracks the active side: front → persist + flip to
+ * back, back → persist + advance.
+ */
+export function OrchestratedCaptureScreen({
+  configuration,
+}: OrchestratedCaptureScreenProps) {
+  const navigationManager = useFlowNavigation();
+
+  // Validator guarantees captureType is set before render (else
+  // InvalidMissingCaptureTypeException short-circuits to onResult.failure).
+  const captureType = configuration.captureType!;
+  const documentConfig = configuration.documentConfig;
+  const documentType = documentConfig?.documentType;
+  // Back captured only when the type has one AND both sides were asked for.
+  const capturesBack =
+    documentType?.hasBackSide === true &&
+    (documentConfig?.captureBothSides ?? false);
+  const allowSkipBack = documentConfig?.allowSkipBack ?? false;
+  // With a `preview {}` after capture, the front exits to that preview and the
+  // back is captured on re-entry; otherwise the front→back flip is in-screen.
+  const previewFollows = navigationManager.documentPreviewFollowsCapture();
+
+  // Side derived from what's already captured on (re)mount: fresh entry starts
+  // front; re-entry for the back (front already persisted via the per-side
+  // preview loop) starts back and shows the flip interstitial.
+  const frontAlreadyCaptured =
+    navigationManager.captured.frontDocumentPath !== undefined;
+  const [currentDocumentSide, setCurrentDocumentSide] = useState<DocumentSide>(
+    capturesBack && frontAlreadyCaptured
+      ? DocumentSide.Back
+      : DocumentSide.Front,
+  );
+  const [showBackInstructions, setShowBackInstructions] = useState(
+    capturesBack && frontAlreadyCaptured,
+  );
+
+  // Pin orientation: documents to their type (landscape ID / portrait booklet),
+  // selfie to portrait. The flip interstitial is a portrait instruction screen,
+  // so it must NOT inherit the document's landscape lock — force portrait while
+  // it shows, then revert to the document orientation for the back capture.
+  useCaptureOrientationLock(
+    captureType === CaptureType.document && !showBackInstructions
+      ? (documentType?.orientation ?? "Landscape")
+      : "Portrait",
+  );
+
+  // Selfie also pushes the registry-built wire FaceConfig; documents have no
+  // per-flow config payload yet (native session applies platform defaults).
+  const analyzer: FaceAnalyzer | DocumentAnalyzer | undefined =
+    captureType === CaptureType.selfie
+      ? navigationManager.configuration.ml?.analyzers.selfie
+      : navigationManager.configuration.ml?.analyzers.document;
+
+  useEffect(() => {
+    if (!analyzer) return;
+    if (captureType === CaptureType.selfie && "key" in analyzer) {
+      const baseConfig = navigationManager.configuration.ml?.analyzers
+        .selfieConfig ?? { analyzerFactoryKey: analyzer.key };
+      // enableEnhancedLiveness lives on the SCREEN config, not the analyzer;
+      // the resolver merges it, applies sdk_config overrides, and pins
+      // numSamples to the ESS hold-still count when ESS is active.
+      void analyzer.configure(
+        resolveFaceSessionConfig(
+          baseConfig,
+          configuration.selfieConfig?.enableEnhancedLiveness ?? false,
+          navigationManager.resolvedSdkConfig,
+        ),
+      );
+    } else if (captureType === CaptureType.document && !("key" in analyzer)) {
+      // Active side drives the native `document_front/back.jpg` filename.
+      // Reconfiguring on currentDocumentSide change (see deps) sets `back`
+      // before the second capture so it doesn't overwrite the front.
+      const documentJpegQuality = resolveJpegQuality(
+        navigationManager.resolvedSdkConfig?.document,
+      );
+      void analyzer.configure({
+        documentSide: currentDocumentSide,
+        ...(documentJpegQuality !== undefined ? { documentJpegQuality } : {}),
+      });
+    }
+    return () => {
+      void analyzer.close();
+    };
+  }, [
+    analyzer,
+    captureType,
+    navigationManager,
+    configuration,
+    currentDocumentSide,
+  ]);
+
+  return (
+    <UseSmileIDOrchestratedScreenHost
+      content={({ navigationManager, onBack, onNavigateNext }) => {
+        if (!analyzer) {
+          // Validator should have caught this; hard-fail loudly rather
+          // than render an empty preview.
+          throw new Error(
+            `OrchestratedCaptureScreen: no ${captureType} analyzer registered in the ML DSL`,
+          );
+        }
+        if (
+          captureType === CaptureType.document &&
+          capturesBack &&
+          showBackInstructions
+        ) {
+          // Flip interstitial between front and back captures.
+          return (
+            <UseSmileIDDocumentBackInstructions
+              documentTypeDisplayName={documentType?.displayName ?? ""}
+              allowSkip={allowSkipBack}
+              onCaptureBack={() => setShowBackInstructions(false)}
+              onSkip={() => {
+                // Front already persisted; route past the back capture +
+                // its preview, submission proceeds with no back image.
+                navigationManager.skipDocumentBack();
+                onNavigateNext();
+              }}
+              onBack={() => {
+                if (previewFollows) {
+                  // Re-entered via the per-side preview loop: back to the front preview.
+                  onBack();
+                  return;
+                }
+                // In-screen flip: re-capture the front.
+                setShowBackInstructions(false);
+                setCurrentDocumentSide(DocumentSide.Front);
+              }}
+            />
+          );
+        }
+        return (
+          <UseSmileIDCaptureScreen
+            captureType={captureType}
+            analyzer={analyzer}
+            enableEnhancedLiveness={
+              configuration.selfieConfig?.enableEnhancedLiveness ?? false
+            }
+            {...(captureType === CaptureType.document && documentConfig
+              ? {
+                  // Partner override wins, then the document type's own ratio,
+                  // then the orientation default (landscape ID / portrait card).
+                  knownIdAspectRatio:
+                    documentConfig.knownIdAspectRatio ??
+                    documentType?.knownAspectRatio ??
+                    defaultFrameAspectRatio(
+                      documentType?.orientation ?? "Landscape",
+                    ),
+                  captureMode: documentConfig.captureMode,
+                  allowGalleryUpload: documentConfig.allowGalleryUpload,
+                  documentSide: currentDocumentSide,
+                  onDocumentOrigin: (origin) =>
+                    navigationManager.recordDocumentImageOrigin(
+                      currentDocumentSide,
+                      origin,
+                    ),
+                  onClose: () => navigationManager.exit(),
+                }
+              : {})}
+            {...(configuration.startButton !== undefined
+              ? { startButton: configuration.startButton }
+              : {})}
+            onBack={() => {
+              // Back on the back-side capture returns to the flip interstitial.
+              if (
+                captureType === CaptureType.document &&
+                capturesBack &&
+                currentDocumentSide === DocumentSide.Back
+              ) {
+                setShowBackInstructions(true);
+                return;
+              }
+              onBack();
+            }}
+            onCaptureComplete={(events) => {
+              const primary = pickPrimaryCaptureUrl(events, captureType);
+              if (!primary) {
+                // Pipeline finished without the expected artifact — stay so the user can retry.
+                return;
+              }
+
+              // Stamp the Smile EXIF UserComment tag before persisting
+              // (blank partnerId → native no-op). Context is rebound per
+              // capture because partnerConfig may change across re-renders
+              // (partner builder closures are not memoised).
+              const partnerId =
+                navigationManager.configuration.network?.config?.partnerConfig
+                  ?.partnerId ?? "";
+              const imageTypeForCapture: ImageTypeId =
+                captureType === CaptureType.selfie
+                  ? ImageType.Selfie
+                  : capturesBack && currentDocumentSide === DocumentSide.Back
+                    ? ImageType.DocumentBack
+                    : ImageType.DocumentFront;
+
+              const livenessUrls = events
+                .filter(
+                  (event) => event.kind === CaptureReadyEventKind.Liveness,
+                )
+                .map((event) => event.url);
+
+              void SmileExifTagger.setContext({ partnerId })
+                .then(() =>
+                  SmileExifTagger.finalize(primary, imageTypeForCapture),
+                )
+                .finally(() => {
+                  if (captureType === CaptureType.selfie) {
+                    navigationManager.setCapturedSelfie(primary, livenessUrls);
+                    onNavigateNext();
+                    return;
+                  }
+                  if (
+                    capturesBack &&
+                    currentDocumentSide === DocumentSide.Front
+                  ) {
+                    navigationManager.setCapturedFrontDocument(primary);
+                    if (previewFollows) {
+                      // Exit to the front preview; manager loops back here
+                      // for the back (flip interstitial shows on re-entry).
+                      onNavigateNext();
+                    } else {
+                      setCurrentDocumentSide(DocumentSide.Back);
+                      setShowBackInstructions(true);
+                    }
+                    return;
+                  }
+                  if (
+                    capturesBack &&
+                    currentDocumentSide === DocumentSide.Back
+                  ) {
+                    navigationManager.setCapturedBackDocument(primary);
+                    onNavigateNext();
+                    return;
+                  }
+                  // Single-side document
+                  navigationManager.setCapturedFrontDocument(primary);
+                  onNavigateNext();
+                });
+            }}
+          />
+        );
+      }}
+    />
+  );
+}
+
+/**
+ * Pick the primary `file://` URL from `CaptureReadyEvent[]`: the
+ * `"selfie"` event for selfie flows (vs the N `"liveness"` frames), the
+ * `"document"` event for document flows. `undefined` when none found.
+ */
+function pickPrimaryCaptureUrl(
+  events: readonly CaptureReadyEvent[],
+  captureType: CaptureType,
+): string | undefined {
+  const targetKind =
+    captureType === CaptureType.selfie
+      ? CaptureReadyEventKind.Selfie
+      : CaptureReadyEventKind.Document;
+  return events.find((event) => event.kind === targetKind)?.url;
+}