@smileid/usesmileid 12.0.0-beta01 → 12.0.1

package/src/presentation/screen/helpers/use_capture_orientation_lock.ts

@@ -3,6 +3,14 @@ import * as ScreenOrientation from "expo-screen-orientation";
 import { UseSmileIDCrashReporting } from "@smileid/usesmileid_bridge";
 import type { DocumentOrientation } from "../../../core/models/document_type";
 
+export type CaptureOrientationOptions = {
+  /**
+   * Lock applied when the capture screen unmounts. Defaults to portrait-up;
+   * threaded from the builder's `exitOrientations`.
+   */
+  readonly exitLock?: ScreenOrientation.OrientationLock;
+};
+
 /**
  * Lock device orientation for a capture screen, scoped to its lifetime
  * (`"Landscape"` → landscape, `"Portrait"` → portrait-up).
@@ -10,26 +18,76 @@ import type { DocumentOrientation } from "../../../core/models/document_type";
  * Each screen asserts its OWN orientation on mount, so document → selfie
  * reverts deterministically rather than depending on the previous
  * screen's teardown winning a race against the next camera initialising.
- * Unmount restores portrait-up as a safety net.
  *
  * Locks are global: the host app must permit the locked orientations at
  * the OS level (iOS `UISupportedInterfaceOrientations`, Android activity
- * `screenOrientation`) for the lock to take effect.
+ * `screenOrientation`) for the lock to take effect — a host that does not
+ * is warned about and reported rather than silently staying upright.
  */
 export function useCaptureOrientationLock(
   orientation: DocumentOrientation,
+  {
+    exitLock = ScreenOrientation.OrientationLock.PORTRAIT_UP,
+  }: CaptureOrientationOptions = {},
 ): void {
   useEffect(() => {
     const target =
       orientation === "Landscape"
         ? ScreenOrientation.OrientationLock.LANDSCAPE
         : ScreenOrientation.OrientationLock.PORTRAIT_UP;
+    void reportIfLockUnsupported(target);
     void lockOrientation(target);
 
     return () => {
-      void lockOrientation(ScreenOrientation.OrientationLock.PORTRAIT_UP);
+      void lockOrientation(exitLock);
     };
-  }, [orientation]);
+  }, [orientation, exitLock]);
+}
+
+/**
+ * Surface a host build that cannot honour `target`. `lockAsync` resolves
+ * successfully in that case, so without this preflight the capture screen
+ * just stays in the wrong orientation with no signal. (Expo's `app.json`
+ * `orientation` value is not such a case: the module's app-delegate hook
+ * outranks the baked `Info.plist` on iOS — device-verified.)
+ */
+async function reportIfLockUnsupported(
+  target: ScreenOrientation.OrientationLock,
+): Promise<void> {
+  let supported: boolean;
+  try {
+    supported = await ScreenOrientation.supportsOrientationLockAsync(target);
+  } catch (error) {
+    reportOrientationFailure(error);
+    return;
+  }
+  if (supported) return;
+
+  // `typeof` guard: `__DEV__` is bundler-injected and absent outside Metro-like
+  // environments, where a bare reference throws rather than reading falsy.
+  const isDevBuild = typeof __DEV__ !== "undefined" && __DEV__;
+  if (isDevBuild && !warnedUnsupportedTargets.has(target)) {
+    warnedUnsupportedTargets.add(target);
+    console.warn(
+      "[UseSmileID] The capture screen needs to lock the device orientation, " +
+        "but this build does not permit it. Allow the required orientations " +
+        "in your app's iOS Info.plist / Android manifest.",
+    );
+  }
+  reportOrientationFailure(
+    new Error(`orientation lock unsupported by host build: ${target}`),
+  );
+}
+
+/**
+ * Dedupes the dev warning per target: a flow remounts the capture screen for the back
+ * side and interstitial, and the misconfiguration can't change mid-session.
+ */
+const warnedUnsupportedTargets = new Set<ScreenOrientation.OrientationLock>();
+
+/** Test seam: clears the once-per-target dev-warning dedupe. */
+export function resetUnsupportedLockWarningsForTesting(): void {
+  warnedUnsupportedTargets.clear();
 }
 
 /** Lock to `target`, routing a native failure through crash reporting. */
@@ -39,8 +97,12 @@ async function lockOrientation(
   try {
     await ScreenOrientation.lockAsync(target);
   } catch (error) {
-    UseSmileIDCrashReporting.captureException(
-      error instanceof Error ? error : new Error(String(error)),
-    );
+    reportOrientationFailure(error);
   }
 }
+
+function reportOrientationFailure(error: unknown): void {
+  UseSmileIDCrashReporting.captureException(
+    error instanceof Error ? error : new Error(String(error)),
+  );
+}

package/src/presentation/screen/use_smile_id_capture_screen.tsx

@@ -6,7 +6,13 @@ import {
   useState,
   type ReactNode,
 } from "react";
-import { StatusBar, StyleSheet, View } from "react-native";
+import {
+  Platform,
+  StatusBar,
+  StyleSheet,
+  View,
+  useWindowDimensions,
+} from "react-native";
 import {
   Camera,
   useCameraDevice,
@@ -22,25 +28,35 @@ import type {
   DocumentAnalyzer,
   FaceAnalyzer,
 } from "@smileid/usesmileid_platform_interface";
-import type { CaptureReadyEvent, ScanState } from "@smileid/usesmileid_bridge";
+import type {
+  CaptureReadyEvent,
+  UseSmileIDScanState,
+} from "@smileid/usesmileid_bridge";
 import {
   CaptureReadyEventKind,
   DocumentSide,
-  ScanStateType,
+  UseSmileIDScanStateType,
 } from "@smileid/usesmileid_bridge";
 import { CaptureType } from "../../core/models/ml_config";
 import type { DocumentCaptureMode } from "../../core/models/document_capture_mode";
+import type { DocumentType } from "../../core/models/document_type";
 import { resampleImportedDocument } from "../../camera/document_image_pipeline";
 import { defaultLightTheme, type UseSmileIDTheme } from "../theme/theme";
+import { UseSmileIDThemeProvider } from "../theme/theme_context";
 import {
   UseSmileIDCaptureContent,
   type UseSmileIDCaptureContentState,
 } from "../components/use_smile_id_capture_content";
+import {
+  DEFAULT_DOCUMENT_ASPECT,
+  documentGuideRect,
+} from "../components/use_smile_id_document_overlay";
 import { UseSmileIDCrashReporting } from "@smileid/usesmileid_bridge";
 import { ForceMaxBrightness } from "../utils/force_max_brightness";
 import { CameraDefaults } from "../../camera/camera_defaults";
 import type { SiKey } from "../../l10n/strings_en";
 import { DocumentImageOrigin } from "../../metadata/document_image_origin";
+import { DeviceOrientationCollector } from "../../metadata/device_orientation_collector";
 import { useSmileIDFrameStream } from "../../camera/use_smile_id_frame_stream";
 import { orientationToDegrees } from "../../camera/orientation_degrees";
 import {
@@ -55,6 +71,20 @@ import {
   triggerEssTurnHaptic,
 } from "./helpers/ess_turn_haptics";
 
+/** Capture telemetry surfaced alongside the captured artifacts at completion. */
+export interface CaptureTelemetry {
+  /** Elapsed time in ms from the first analyzed frame to completion. */
+  readonly durationMs: number;
+  /** Count of face/document-lost resets (rising edges of `unsatisfied`). */
+  readonly retries: number;
+  /** Identifier of the camera used for capture (`CameraDevice.id`); `undefined` until resolved. */
+  readonly cameraName?: string;
+  /** Accelerometer `"epochMs,x,y,z"` samples collected during capture. */
+  readonly devicePositions: readonly string[];
+  /** Span of movement magnitude during capture; `null` when no samples ran. */
+  readonly deviceMovementDetected: number | null;
+}
+
 export type UseSmileIDCaptureScreenProps = {
   readonly captureType: CaptureType;
 
@@ -73,12 +103,15 @@ export type UseSmileIDCaptureScreenProps = {
    * settled, with every `CaptureReadyEvent` of the session (one
    * `"selfie"` + N `"liveness"` for face, one `"document"` for document).
    */
-  readonly onCaptureComplete?: (events: readonly CaptureReadyEvent[]) => void;
+  readonly onCaptureComplete?: (
+    events: readonly CaptureReadyEvent[],
+    telemetry: CaptureTelemetry,
+  ) => void;
   /** Records how a document side was produced (auto/manual/gallery), fired just before delivery. */
   readonly onDocumentOrigin?: (origin: DocumentImageOrigin) => void;
 
   /** Fires when the state machine reaches `"timeout"`; the screen stops streaming. */
-  readonly onCaptureTimeout?: (state: ScanState) => void;
+  readonly onCaptureTimeout?: (state: UseSmileIDScanState) => void;
 
   readonly onBack?: () => void;
   readonly showAttribution?: boolean;
@@ -86,6 +119,9 @@ export type UseSmileIDCaptureScreenProps = {
   /** Keeps the oval rim neutral through CAPTURING/PROCESSING — ESS has no green oval treatment. */
   readonly enableEnhancedLiveness?: boolean;
 
+  /** Runs a selfie capture on the rear camera. Ignored for document capture. */
+  readonly allowAgentMode?: boolean;
+
   /**
    * Document aspect ratio (width / height) for the document capture
    * guide cutout. Ignored for selfie capture. Omitted ⇒ the overlay's
@@ -106,6 +142,8 @@ export type UseSmileIDCaptureScreenProps = {
    * `document_front.jpg` / `document_back.jpg`. Ignored for selfie capture.
    */
   readonly documentSide?: DocumentSide;
+  /** Document type — selects the in-frame capture shimmer skeleton. Ignored for selfie. */
+  readonly documentTypeKind?: DocumentType["kind"];
   /** Close/cancel the whole flow (document capture chrome — top-right X). */
   readonly onClose?: () => void;
 
@@ -130,9 +168,12 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
   const theme = props.theme ?? defaultLightTheme;
   const showAttribution = props.showAttribution ?? true;
   const enableEnhancedLiveness = props.enableEnhancedLiveness ?? false;
+  const allowAgentMode = props.allowAgentMode ?? false;
   // Literal union — useCameraDevice takes the lowercase string directly.
   const cameraFacing: "front" | "back" =
-    props.captureType === CaptureType.selfie ? "front" : "back";
+    props.captureType === CaptureType.selfie && !allowAgentMode
+      ? "front"
+      : "back";
 
   const { hasPermission, requestPermission } = useCameraPermission();
   const device = useCameraDevice(cameraFacing);
@@ -140,15 +181,24 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
   const cameraRef = useRef<Camera>(null);
   // Pin an explicit format: the "highest supported" heuristic can pick 4K,
   // stalling the frame-processor thread and stuttering the pipeline.
+  // Document capture uses 16:9 so the analysis FOV matches the visible 16:9
+  // preview — keeping the guide-rectangle crop aligned with the framed document
+  // (mirrors the native Android SDK's RATIO_16_9 + 1280×720 pin). Selfie keeps
+  // 4:3: the face geometry + smile heuristic are calibrated on 4:3, and 16:9
+  // skews normalized landmark ratios and shifts every threshold.
+  const isDocumentFormat = props.captureType === CaptureType.document;
   const format = useCameraFormat(device, [
-    // 4:3 first: geometry checks + smile heuristic are calibrated on 4:3;
-    // 16:9 skews normalized landmark ratios and shifts every threshold.
-    { videoAspectRatio: 4 / 3 },
+    { videoAspectRatio: isDocumentFormat ? 16 / 9 : 4 / 3 },
     {
-      videoResolution: {
-        width: CameraDefaults.analysisTargetResolution.width,
-        height: CameraDefaults.analysisTargetResolution.height,
-      },
+      videoResolution: isDocumentFormat
+        ? {
+            width: CameraDefaults.documentAnalysisResolution.width,
+            height: CameraDefaults.documentAnalysisResolution.height,
+          }
+        : {
+            width: CameraDefaults.analysisTargetResolution.width,
+            height: CameraDefaults.analysisTargetResolution.height,
+          },
     },
     { fps: CameraDefaults.analysisTargetFps },
   ]);
@@ -161,8 +211,8 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
   }, [hasPermission, requestPermission]);
 
   // Per-frame scan state drives the overlay + feedback bubble.
-  const [scanState, setScanState] = useState<ScanState>({
-    type: ScanStateType.Initial,
+  const [scanState, setScanState] = useState<UseSmileIDScanState>({
+    type: UseSmileIDScanStateType.Initial,
   });
   const [streaming, setStreaming] = useState<boolean>(false);
   // Bumped on every Start tap to reset the feedback debouncer.
@@ -172,6 +222,11 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
   const [hasAnalyzedFrame, setHasAnalyzedFrame] = useState<boolean>(false);
   // Fallback shutter, revealed after activateManualAfterMs. Resets per mount.
   const [manualShutterRevealed, setManualShutterRevealed] = useState(false);
+  // Set when a document scan times out, so the recovery controls stay on screen
+  // after the scan (and `streaming`) stops. `timedOutRef` keeps the terminal
+  // branch idempotent without latching the one-shot delivery gate.
+  const [captureTimedOut, setCaptureTimedOut] = useState(false);
+  const timedOutRef = useRef(false);
   // True while a manual/gallery delivery is in flight — disables the controls.
   const [deliveringDocument, setDeliveringDocument] = useState(false);
   // Transient gallery-import error; overrides the live chip, self-clears so the user can re-pick.
@@ -191,7 +246,34 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
   const completedRef = useRef<boolean>(false);
   // Raw (not committed) frame state for the session-boundary check, so
   // transitions the 1% bucketing skips committing are still seen.
-  const previousScanStateRef = useRef<ScanState | null>(null);
+  const previousScanStateRef = useRef<UseSmileIDScanState | null>(null);
+
+  // Capture telemetry: wall-clock start (first analyzed frame) and a
+  // rising-edge `unsatisfied` retry counter, surfaced via onCaptureComplete.
+  const captureStartedAtRef = useRef<number | null>(null);
+  const captureRetriesRef = useRef<number>(0);
+  const wasUnsatisfiedRef = useRef<boolean>(false);
+  // Accelerometer sampler for device_positions / device_movement_detected, run only
+  // while the live capture loop is streaming.
+  const deviceOrientationRef = useRef<DeviceOrientationCollector>(
+    new DeviceOrientationCollector(),
+  );
+
+  const captureTelemetry = useCallback(
+    (): CaptureTelemetry => ({
+      durationMs:
+        captureStartedAtRef.current === null
+          ? 0
+          : Date.now() - captureStartedAtRef.current,
+      retries: captureRetriesRef.current,
+      devicePositions: deviceOrientationRef.current.devicePositions,
+      deviceMovementDetected:
+        deviceOrientationRef.current.deviceMovementDetected,
+      // Omit (not set to undefined) when unresolved — exactOptionalPropertyTypes.
+      ...(device?.id !== undefined ? { cameraName: device.id } : {}),
+    }),
+    [device],
+  );
 
   const onStartCapture = props.onStartCapture;
   const handleStart = useCallback(() => {
@@ -213,6 +295,23 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
   const documentSide = props.documentSide ?? DocumentSide.Front;
   const isDocumentCapture = props.captureType === CaptureType.document;
 
+  // Reset capture telemetry per side so each document side reports its own
+  // duration / retries (the screen instance is reused across the front→back flip).
+  useEffect(() => {
+    captureStartedAtRef.current = null;
+    captureRetriesRef.current = 0;
+    wasUnsatisfiedRef.current = false;
+  }, [documentSide]);
+
+  // Sample the accelerometer only while the live capture loop streams. start()
+  // clears prior samples, so a retry / side switch begins fresh; cleanup stops it.
+  useEffect(() => {
+    if (streaming) {
+      deviceOrientationRef.current.start();
+    }
+    return () => deviceOrientationRef.current.stop();
+  }, [streaming]);
+
   // Reveal the fallback shutter after the delay once streaming begins.
   // Bound to `streaming`: any capture clears it, tearing this effect down
   // and clearing the timer, so it can't fire post-capture or leak.
@@ -249,13 +348,16 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
           documentSide,
         );
         onDocumentOrigin?.(DocumentImageOrigin.CameraManualCapture);
-        onCaptureComplete?.([
-          {
-            kind: CaptureReadyEventKind.Document,
-            captureIndex: 0,
-            url: processedUri,
-          },
-        ]);
+        onCaptureComplete?.(
+          [
+            {
+              kind: CaptureReadyEventKind.Document,
+              captureIndex: 0,
+              url: processedUri,
+            },
+          ],
+          captureTelemetry(),
+        );
       } catch (error) {
         UseSmileIDCrashReporting.captureException(
           error instanceof Error ? error : new Error(String(error)),
@@ -318,13 +420,16 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
           documentSide,
         );
         onDocumentOrigin?.(DocumentImageOrigin.Gallery);
-        onCaptureComplete?.([
-          {
-            kind: CaptureReadyEventKind.Document,
-            captureIndex: 0,
-            url: processedUri,
-          },
-        ]);
+        onCaptureComplete?.(
+          [
+            {
+              kind: CaptureReadyEventKind.Document,
+              captureIndex: 0,
+              url: processedUri,
+            },
+          ],
+          captureTelemetry(),
+        );
       } catch (error) {
         UseSmileIDCrashReporting.captureException(
           error instanceof Error ? error : new Error(String(error)),
@@ -379,7 +484,19 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
       // Unsatisfied = native session reset; drop accumulated events so it
       // can't leak stale liveness frames. `else` so a reset frame can't
       // re-add its own stale events on the same pass.
-      if (result.state.type === ScanStateType.Unsatisfied) {
+      // Capture telemetry: anchor the start clock on the first analyzed frame,
+      // and count rising edges of `unsatisfied` as retries.
+      if (captureStartedAtRef.current === null) {
+        captureStartedAtRef.current = Date.now();
+      }
+      const isUnsatisfied =
+        result.state.type === UseSmileIDScanStateType.Unsatisfied;
+      if (isUnsatisfied && !wasUnsatisfiedRef.current) {
+        captureRetriesRef.current += 1;
+      }
+      wasUnsatisfiedRef.current = isUnsatisfied;
+
+      if (result.state.type === UseSmileIDScanStateType.Unsatisfied) {
         capturedEventsRef.current = [];
       } else if (result.capturedEvents.length > 0) {
         capturedEventsRef.current = [
@@ -405,7 +522,7 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
 
       // Terminal states: finished → flush + complete; timeout → failure
       // without flushing (no captured artifacts to wait on).
-      if (result.state.type === ScanStateType.Finished) {
+      if (result.state.type === UseSmileIDScanStateType.Finished) {
         if (completedRef.current) return;
         completedRef.current = true;
         setStreaming(false);
@@ -420,12 +537,20 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
           .finally(() => {
             // No-op for selfie (callback unset).
             onDocumentOrigin?.(DocumentImageOrigin.CameraAutoCapture);
-            onCaptureComplete?.(capturedEventsRef.current);
+            onCaptureComplete?.(capturedEventsRef.current, captureTelemetry());
           });
-      } else if (result.state.type === ScanStateType.Timeout) {
-        if (completedRef.current) return;
-        completedRef.current = true;
+      } else if (result.state.type === UseSmileIDScanStateType.Timeout) {
+        if (completedRef.current || timedOutRef.current) return;
         setStreaming(false);
+        if (isDocumentCapture) {
+          // Document capture has no Start button, so a timeout must leave a way
+          // forward: reveal the manual shutter and keep the delivery gate open
+          // so the tap can still produce a capture.
+          timedOutRef.current = true;
+          setCaptureTimedOut(true);
+        } else {
+          completedRef.current = true;
+        }
         onCaptureTimeout?.(result.state);
       }
     },
@@ -447,7 +572,7 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
     sessionEpoch,
   );
   const isInstructionState =
-    scanState.type === ScanStateType.Initial && !streaming;
+    scanState.type === UseSmileIDScanStateType.Initial && !streaming;
   const canStart = !streaming && !completedRef.current;
 
   const previewReady = hasPermission && device != null;
@@ -487,33 +612,116 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
     });
   }, [onFrameResult]);
 
-  // Physical device tilt (0 = upright portrait) for the native
-  // session's upright validator and head-pose math; gravity-sourced,
-  // never derived from `frame.orientation` (fixed sensor mounting).
+  // Physical device tilt (0 = portrait) for the native upright validator /
+  // head-pose math; gravity-sourced, never from `frame.orientation`.
   const [deviceOrientationDegrees, setDeviceOrientationDegrees] = useState(0);
 
+  // Locked INTERFACE orientation (0/90/270) — the axis the preview and guide are
+  // drawn against, from VisionCamera's preview orientation, NOT device gravity
+  // (the document screen locks the interface while the phone is held flat, so
+  // gravity disagrees). iOS uprights the saved document to this axis.
+  const [previewOrientationDegrees, setPreviewOrientationDegrees] = useState(0);
+
+  // VisionCamera derives its iOS preview orientation from the interface
+  // orientation but only refreshes it on a PHYSICAL rotation — a programmatic
+  // lock (the document landscape lock) never fires that, so the preview stays
+  // portrait in the rotated UI. Remounting <Camera> when the interface flips
+  // forces a re-read. iOS only — Android's preview already tracks the lock.
+  const { width: windowWidth, height: windowHeight } = useWindowDimensions();
+  const cameraOrientationKey =
+    Platform.OS === "ios"
+      ? windowWidth > windowHeight
+        ? "landscape"
+        : "portrait"
+      : "camera";
+
+  // Camera viewport size, reported by the capture content on layout. Drives the
+  // document crop region so the saved capture matches the on-screen frame.
+  const [viewport, setViewport] = useState({ width: 0, height: 0 });
+  const handleViewportLayout = useCallback(
+    (size: { width: number; height: number }) => {
+      setViewport((previous) =>
+        previous.width === size.width && previous.height === size.height
+          ? previous
+          : size,
+      );
+    },
+    [],
+  );
+
+  // The document guide rectangle as a native crop region — viewport fractions +
+  // size + cover scale — derived from the SAME geometry the overlay draws
+  // (documentGuideRect), so the native side crops the saved document to exactly
+  // the framed rectangle. undefined for selfie or before the viewport is known.
+  const documentCropRegion = useMemo(() => {
+    if (!isDocumentCapture || viewport.width <= 0 || viewport.height <= 0) {
+      return undefined;
+    }
+    const aspect = props.knownIdAspectRatio ?? DEFAULT_DOCUMENT_ASPECT;
+    const rect = documentGuideRect(aspect, viewport.width, viewport.height);
+    return {
+      left: rect.left / viewport.width,
+      top: rect.top / viewport.height,
+      width: rect.width / viewport.width,
+      height: rect.height / viewport.height,
+      viewportWidthPx: Math.round(viewport.width),
+      viewportHeightPx: Math.round(viewport.height),
+    };
+  }, [isDocumentCapture, viewport, props.knownIdAspectRatio]);
+
   const frameProcessor = useFrameProcessor(
     (frame) => {
       "worklet";
       if (!plugin) return;
+      // Crop region passed as FLAT numeric args — frame-processor arguments
+      // don't reliably accept nested objects. cropWidth <= 0 signals "no region"
+      // (selfie, or before the viewport is measured), leaving it uncropped.
+      //
+      // The saved document uprights to the LOCKED INTERFACE axis (what the
+      // preview and guide are drawn against), never device gravity (the phone is
+      // held flat): iOS uprights to `viewportOrientation`, Android via its
+      // display-tracking `rotationDegrees`. `rotation` stays the RAW gravity
+      // tilt the native upright validator needs.
       const rawResult = plugin.call(frame, {
         rotation: deviceOrientationDegrees,
+        viewportOrientation: previewOrientationDegrees,
+        cropLeft: documentCropRegion ? documentCropRegion.left : 0,
+        cropTop: documentCropRegion ? documentCropRegion.top : 0,
+        cropWidth: documentCropRegion ? documentCropRegion.width : 0,
+        cropHeight: documentCropRegion ? documentCropRegion.height : 0,
+        cropViewportWidth: documentCropRegion
+          ? documentCropRegion.viewportWidthPx
+          : 0,
+        cropViewportHeight: documentCropRegion
+          ? documentCropRegion.viewportHeightPx
+          : 0,
       });
       onFrameResultRunOnJS(rawResult);
     },
-    [plugin, onFrameResultRunOnJS, deviceOrientationDegrees],
+    [
+      plugin,
+      onFrameResultRunOnJS,
+      deviceOrientationDegrees,
+      previewOrientationDegrees,
+      documentCropRegion,
+    ],
   );
 
   // Document controls — live capture only (after Start). Manual shutter
   // follows the capture mode + fallback timer; gallery follows
   // allowGalleryUpload. Renderer also hides both during CAPTURING/PROCESSING.
+  // A timeout offers the shutter in every capture mode — it is the recovery
+  // affordance, so it outranks `captureMode` and survives `streaming` going
+  // false with the scan.
   const manualShutterAvailable =
     isDocumentCapture &&
-    streaming &&
-    (captureMode?.kind === "manualCapture" ||
-      (captureMode?.kind === "autoCaptureWithManualFallback" &&
-        manualShutterRevealed));
-  const galleryAvailable = isDocumentCapture && streaming && allowGalleryUpload;
+    (captureTimedOut ||
+      (streaming &&
+        (captureMode?.kind === "manualCapture" ||
+          (captureMode?.kind === "autoCaptureWithManualFallback" &&
+            manualShutterRevealed))));
+  const galleryAvailable =
+    isDocumentCapture && (streaming || captureTimedOut) && allowGalleryUpload;
 
   // Deps are scalar fields (mapCaptureUiState returns a fresh object per
   // render). captureProgress intentionally stays a separate per-frame prop.
@@ -530,9 +738,13 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
       showCaptureButton: isInstructionState && !isDocumentCapture,
       showManualShutter: manualShutterAvailable,
       showGalleryUpload: galleryAvailable,
+      isBackSide: documentSide === DocumentSide.Back,
       ...(props.knownIdAspectRatio !== undefined
         ? { knownIdAspectRatio: props.knownIdAspectRatio }
         : {}),
+      ...(props.documentTypeKind !== undefined
+        ? { documentTypeKind: props.documentTypeKind }
+        : {}),
     }),
     [
       props.captureType,
@@ -546,7 +758,9 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
       isDocumentCapture,
       manualShutterAvailable,
       galleryAvailable,
+      documentSide,
       props.knownIdAspectRatio,
+      props.documentTypeKind,
     ],
   );
 
@@ -554,14 +768,14 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
   const cameraPreview = useMemo(
     () => (
       <>
-        {/* Selfie uses the front camera with the screen as fill light, so
-            force max brightness on selfie only; document uses the rear
-            camera, where screen brightness doesn't help. */}
-        <ForceMaxBrightness
-          enabled={props.captureType === CaptureType.selfie}
-        />
+        {/* Every capture screen runs at max brightness with the screen kept
+            awake, restored on unmount. Selfie uses the front camera with the
+            screen as fill light; document capture keeps the same guarantee so
+            the preview never dims or auto-locks mid-scan. */}
+        <ForceMaxBrightness />
         {previewReady ? (
           <Camera
+            key={cameraOrientationKey}
             ref={cameraRef}
             style={StyleSheet.absoluteFill}
             device={device}
@@ -576,6 +790,11 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
             onOutputOrientationChanged={(orientation) => {
               setDeviceOrientationDegrees(orientationToDegrees(orientation));
             }}
+            // The LOCKED interface orientation (follows the screen even under a
+            // programmatic lock) — the axis the saved document uprights to.
+            onPreviewOrientationChanged={(orientation) => {
+              setPreviewOrientationDegrees(orientationToDegrees(orientation));
+            }}
             // Attach the frame processor only while streaming (skip pre-Start
             // preview). Spread idiom because exactOptionalPropertyTypes rejects
             // passing `undefined` to an optional prop directly.
@@ -602,11 +821,17 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
       streaming,
       frameProcessor,
       theme.colors.offBlack,
+      cameraOrientationKey,
     ],
   );
 
   return (
-    <>
+    // The capture screen is always light, regardless of the system dark-mode
+    // setting (every other screen tracks the system). Providing the light theme
+    // here forces every descendant that reads it from context — not only the
+    // ones passing `forceLightMode` — to render light; partner colours still
+    // apply because `theme` carries the partner's resolved light tokens.
+    <UseSmileIDThemeProvider value={theme}>
       {/* Translucent status bar → full-bleed window so the oval's reference
           frame is the full screen (no-op on iOS). On-device-pending: residual
           inset also depends on the host SafeAreaProvider config. */}
@@ -620,6 +845,7 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
         onBack={props.onBack}
         showAttribution={showAttribution}
         startButton={props.startButton}
+        onViewportLayout={handleViewportLayout}
         {...(isDocumentCapture
           ? {
               onManualShutter: handleManualShutter,
@@ -630,6 +856,6 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
           : {})}
         theme={theme}
       />
-    </>
+    </UseSmileIDThemeProvider>
   );
 }