@smileid/usesmileid 12.0.0-beta01 → 12.0.0

package/src/presentation/flow/validation/job_type_validator.ts

@@ -453,6 +453,30 @@ export class DocumentJobTypeValidator implements JobTypeValidator {
 
     this.appendParamsRule(input, issues);
 
+    // The South Africa Green Book carries no usable data on its back and is not
+    // supported by the Enhanced Document Verification ID-authority cross check.
+    // Reject it for that job type so the partner sees a build-time error instead
+    // of a server-side job failure.
+    if (
+      this.jobType === JobType.enhancedDocumentVerification &&
+      documentCaptures.some(
+        (s) =>
+          s.kind === "capture" &&
+          s.config.documentConfig?.documentType?.kind ===
+            "southAfricaGreenBook",
+      )
+    ) {
+      issues.push(
+        InvalidJobTypeScreenConfigException.forJob({
+          jobType: this.jobType,
+          reason:
+            "South Africa Green Book is not supported for Enhanced Document Verification",
+          suggestedFix:
+            "Use JobType.documentVerification for the Green Book, or choose a supported document type for Enhanced Document Verification",
+        }),
+      );
+    }
+
     if (input.userDetails === undefined) {
       issues.push(
         InvalidJobTypeScreenConfigException.forJob({

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__/use_smile_id_capture_screen.test.tsx

@@ -534,10 +534,12 @@ 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 }),
+    );
   });
 });
 

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

@@ -93,6 +93,7 @@ const FEEDBACK_COPY: Partial<
   si_ess_look_left: (loc) => loc.siEssLookLeft,
   si_ess_look_right: (loc) => loc.siEssLookRight,
   si_ess_look_up: (loc) => loc.siEssLookUp,
+  si_ess_look_at_camera: (loc) => loc.siEssLookAtCamera,
   si_document_initial_instruction: (loc) => loc.siDocumentInitialInstruction,
   si_document_ready: (loc) => loc.siDocumentReady,
   si_document_capturing: (loc) => loc.siDocumentCapturing,

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

@@ -2,7 +2,7 @@ import type { UseSmileIDLocalizations } from "../../../l10n/use_smile_id_localiz
 import type { DocumentType } from "../../../core/models/document_type";
 import type { InstructionGuideline } from "../../flow/model/instruction_guideline";
 import {
-  DOCUMENT_GUIDELINES,
+  documentGuidelines,
   documentHeroAnimation,
   ESS_HERO_ANIMATION,
   SELFIE_GUIDELINES,
@@ -33,6 +33,7 @@ export type ResolvedInstructions = {
   readonly showAttribution: boolean;
   readonly showHeroOval: boolean;
   readonly showHeroOvalProgress: boolean;
+  readonly showCardBackground: boolean;
 };
 
 /**
@@ -74,7 +75,7 @@ export function resolveInstructionsConfig(
   const isDocument = documentType !== undefined;
 
   const defaultGuidelines = isDocument
-    ? DOCUMENT_GUIDELINES
+    ? documentGuidelines(documentType)
     : SELFIE_GUIDELINES;
   const guidelines =
     config.guidelines && config.guidelines.length > 0
@@ -104,5 +105,9 @@ export function resolveInstructionsConfig(
     // selfie flows only (a document has no face to frame).
     showHeroOval: isDocument ? false : (config.showHeroOval ?? true),
     showHeroOvalProgress: isDocument ? false : !enhanced,
+    // Card hero is the document variant only — tied to the flow type, not to
+    // `!showHeroOval` (a selfie flow can disable the oval without becoming a
+    // document, and must not then render the document card).
+    showCardBackground: isDocument,
   };
 }

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

@@ -104,6 +104,9 @@ function resolveFeedbackOverlay(
         return UseSmileIDOverlayState.MOVE_UP;
       case "si_capture_move_lower":
         return UseSmileIDOverlayState.MOVE_DOWN;
+      // ESS re-center gate between head-turn directions
+      case "si_ess_look_at_camera":
+        return UseSmileIDOverlayState.FACE_NOT_CENTERED;
       default:
         return fallback;
     }

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,
@@ -30,17 +36,24 @@ import {
 } 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 +68,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,7 +100,10 @@ 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;
 
@@ -106,6 +136,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;
 
@@ -140,15 +172,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 },
   ]);
@@ -193,6 +234,33 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
   // transitions the 1% bucketing skips committing are still seen.
   const previousScanStateRef = useRef<ScanState | 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(() => {
     if (streaming || completedRef.current) return;
@@ -213,6 +281,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 +334,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 +406,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,6 +470,17 @@ 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.
+      // 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 === ScanStateType.Unsatisfied;
+      if (isUnsatisfied && !wasUnsatisfiedRef.current) {
+        captureRetriesRef.current += 1;
+      }
+      wasUnsatisfiedRef.current = isUnsatisfied;
+
       if (result.state.type === ScanStateType.Unsatisfied) {
         capturedEventsRef.current = [];
       } else if (result.capturedEvents.length > 0) {
@@ -420,7 +522,7 @@ 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;
@@ -487,21 +589,99 @@ 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
@@ -530,9 +710,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 +730,9 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
       isDocumentCapture,
       manualShutterAvailable,
       galleryAvailable,
+      documentSide,
       props.knownIdAspectRatio,
+      props.documentTypeKind,
     ],
   );
 
@@ -554,14 +740,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 +762,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 +793,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 +817,7 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
         onBack={props.onBack}
         showAttribution={showAttribution}
         startButton={props.startButton}
+        onViewportLayout={handleViewportLayout}
         {...(isDocumentCapture
           ? {
               onManualShutter: handleManualShutter,
@@ -630,6 +828,6 @@ export function UseSmileIDCaptureScreen(props: UseSmileIDCaptureScreenProps) {
           : {})}
         theme={theme}
       />
-    </>
+    </UseSmileIDThemeProvider>
   );
 }