@smileid/usesmileid 12.0.2 → 12.1.1

package/src/presentation/screen/use_smile_id_capture_screen.tsx

@@ -1,912 +0,0 @@
-import {
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-  type ReactNode,
-} from "react";
-import {
-  Platform,
-  StatusBar,
-  StyleSheet,
-  View,
-  useWindowDimensions,
-} from "react-native";
-import {
-  Camera,
-  useCameraDevice,
-  useCameraFormat,
-  useCameraPermission,
-  useFrameProcessor,
-  VisionCameraProxy,
-} from "react-native-vision-camera";
-import { Worklets } from "react-native-worklets-core";
-import * as ImagePicker from "expo-image-picker";
-import { FrameProcessorPluginNotRegisteredException } from "@smileid/usesmileid_bridge";
-import type {
-  DocumentAnalyzer,
-  FaceAnalyzer,
-} from "@smileid/usesmileid_platform_interface";
-import type {
-  CaptureReadyEvent,
-  UseSmileIDScanState,
-} from "@smileid/usesmileid_bridge";
-import {
-  CaptureReadyEventKind,
-  DocumentSide,
-  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 {
-  isSessionBoundary,
-  mapCaptureUiState,
-  preCaptureUiState,
-  type UseSmileIDCaptureUiState,
-} from "./helpers/capture_ui_state";
-import { useDebouncedFeedbackKey } from "./helpers/use_debounced_feedback_key";
-import {
-  essTurnHaptic,
-  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;
-
-  /**
-   * Per-frame analyzer driving the state machine. Lifecycle is the
-   * partner's responsibility (the orchestrated wrapper handles
-   * configure/close for DSL-built flows).
-   */
-  readonly analyzer: FaceAnalyzer | DocumentAnalyzer;
-
-  /** Fires on Start tap; frames begin streaming to the analyzer after. */
-  readonly onStartCapture?: () => void;
-
-  /**
-   * Fires when the state machine reaches `finished` and `flush()` has
-   * settled, with every `CaptureReadyEvent` of the session (one
-   * `"selfie"` + N `"liveness"` for face, one `"document"` for document).
-   */
-  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: UseSmileIDScanState) => void;
-
-  readonly onBack?: () => void;
-  readonly showAttribution?: boolean;
-
-  /** 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
-   * default ID-1 ratio.
-   */
-  readonly knownIdAspectRatio?: number;
-
-  /**
-   * Document capture mode. `manualCapture` surfaces the shutter immediately;
-   * `autoCaptureWithManualFallback` surfaces it after `activateManualAfterMs`;
-   * `autoCapture` never surfaces it. Ignored for selfie capture.
-   */
-  readonly captureMode?: DocumentCaptureMode;
-  /** Show the gallery-upload control (document capture). Ignored for selfie. */
-  readonly allowGalleryUpload?: boolean;
-  /**
-   * Active document side — names the imported (manual / gallery) artifact
-   * `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;
-
-  readonly startButton?: (props: {
-    onClick: () => void;
-    enabled: boolean;
-  }) => ReactNode;
-  readonly theme?: UseSmileIDTheme;
-};
-
-/**
- * Capture route — owns the camera session, frame streaming, analyzer
- * results, and effects; derives an immutable `UseSmileIDCaptureContentState`
- * per scan-state update and delegates rendering to the stateless
- * `UseSmileIDCaptureContent` (camera preview injected through its slot).
- *
- * Flow: Start → frame processor runs the native plugin per frame
- * (`useSmileIDFrameStream` validates results) → on `finished`, `flush()`
- * then `onCaptureComplete`; on `timeout`, `onCaptureTimeout`.
- */
-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 && !allowAgentMode
-      ? "front"
-      : "back";
-
-  const { hasPermission, requestPermission } = useCameraPermission();
-  const device = useCameraDevice(cameraFacing);
-  // Still-capture handle for the document manual shutter (`takePhoto()`).
-  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, [
-    { videoAspectRatio: isDocumentFormat ? 16 / 9 : 4 / 3 },
-    {
-      videoResolution: isDocumentFormat
-        ? {
-            width: CameraDefaults.documentAnalysisResolution.width,
-            height: CameraDefaults.documentAnalysisResolution.height,
-          }
-        : {
-            width: CameraDefaults.analysisTargetResolution.width,
-            height: CameraDefaults.analysisTargetResolution.height,
-          },
-    },
-    { fps: CameraDefaults.analysisTargetFps },
-  ]);
-  const requestedRef = useRef(false);
-  useEffect(() => {
-    if (!hasPermission && !requestedRef.current) {
-      requestedRef.current = true;
-      void requestPermission();
-    }
-  }, [hasPermission, requestPermission]);
-
-  // Per-frame scan state drives the overlay + feedback bubble.
-  const [scanState, setScanState] = useState<UseSmileIDScanState>({
-    type: UseSmileIDScanStateType.Initial,
-  });
-  const [streaming, setStreaming] = useState<boolean>(false);
-  // Bumped on every Start tap to reset the feedback debouncer.
-  const [sessionEpoch, setSessionEpoch] = useState<number>(0);
-  // Overlay stays IDLE (gray) until the first analyzed frame — eagerly
-  // forcing INSTRUCTION here causes a green flash.
-  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);
-  // Set when streaming produced no analyzed frame at all, which the analyzer's own timeout cannot report.
-  const [captureStalled, setCaptureStalled] = useState(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.
-  const [galleryErrorKey, setGalleryErrorKey] = useState<SiKey | null>(null);
-  useEffect(() => {
-    if (galleryErrorKey === null) return;
-    const timer = setTimeout(() => setGalleryErrorKey(null), 3000);
-    return () => clearTimeout(timer);
-  }, [galleryErrorKey]);
-
-  // Accumulate events across frames in a ref (not state) so an event
-  // arrival never triggers a re-render; the final onCaptureComplete
-  // payload then carries every event the session emitted.
-  const capturedEventsRef = useRef<CaptureReadyEvent[]>([]);
-  // Exactly-once latch: a frame can land while flush() is in flight, so
-  // this keeps flush()/onCaptureComplete from firing twice per session.
-  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<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(() => {
-    if (streaming || completedRef.current) return;
-    onStartCapture?.();
-    setSessionEpoch((epoch) => epoch + 1);
-    // A new session must not compare against the old session's last state.
-    previousScanStateRef.current = null;
-    // Clear the terminal latches so a retry after a timeout or a stall is a fresh session.
-    const wasTerminal = timedOutRef.current;
-    timedOutRef.current = false;
-    setCaptureTimedOut(false);
-    setCaptureStalled(false);
-    setScanState({ type: UseSmileIDScanStateType.Initial });
-    setHasAnalyzedFrame(false);
-    // Frames banked before the abandoned session must not pad this one.
-    capturedEventsRef.current = [];
-    if (wasTerminal) {
-      // A timed-out native session is terminal — stream only after it resets,
-      // or the first retry frame re-reports Timeout and re-latches the error.
-      void props.analyzer
-        .reset()
-        .catch((error) => UseSmileIDCrashReporting.captureException(error))
-        .finally(() => {
-          if (!completedRef.current) setStreaming(true);
-        });
-    } else {
-      setStreaming(true);
-    }
-  }, [streaming, onStartCapture, props.analyzer]);
-
-  const analyzer = props.analyzer;
-  const onCaptureComplete = props.onCaptureComplete;
-  const onDocumentOrigin = props.onDocumentOrigin;
-  const onCaptureTimeout = props.onCaptureTimeout;
-
-  const captureMode = props.captureMode;
-  const allowGalleryUpload = props.allowGalleryUpload ?? false;
-  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.
-  const fallbackDelayMs =
-    captureMode?.kind === "autoCaptureWithManualFallback"
-      ? captureMode.activateManualAfterMs
-      : null;
-  useEffect(() => {
-    if (!streaming || fallbackDelayMs === null) return;
-    const timer = setTimeout(() => {
-      setManualShutterRevealed(true);
-    }, fallbackDelayMs);
-    return () => clearTimeout(timer);
-  }, [streaming, fallbackDelayMs]);
-
-  // Manual shutter: capture a still and deliver via the SAME
-  // onCaptureComplete path as auto-capture. completedRef is claimed before
-  // the async work so a concurrent auto-capture is dropped — exactly one delivery.
-  const handleManualShutter = useCallback(() => {
-    if (completedRef.current) return;
-    const camera = cameraRef.current;
-    if (camera === null) return;
-    completedRef.current = true;
-    setStreaming(false);
-    setDeliveringDocument(true);
-    void (async () => {
-      try {
-        const photo = await camera.takePhoto();
-        const sourceUri = photo.path.startsWith("file://")
-          ? photo.path
-          : `file://${photo.path}`;
-        const processedUri = await resampleImportedDocument(
-          { uri: sourceUri, width: photo.width, height: photo.height },
-          documentSide,
-        );
-        onDocumentOrigin?.(DocumentImageOrigin.CameraManualCapture);
-        onCaptureComplete?.(
-          [
-            {
-              kind: CaptureReadyEventKind.Document,
-              captureIndex: 0,
-              url: processedUri,
-            },
-          ],
-          captureTelemetry(),
-        );
-      } catch (error) {
-        UseSmileIDCrashReporting.captureException(
-          error instanceof Error ? error : new Error(String(error)),
-        );
-        // Release the gate so the user can retry, and resume auto-capture.
-        completedRef.current = false;
-        setDeliveringDocument(false);
-        setStreaming(true);
-      }
-    })();
-  }, [onCaptureComplete, onDocumentOrigin, documentSide]);
-
-  // Gallery upload: pause auto-capture while the picker is open (so it can't
-  // settle behind the modal), import via the same resample + delivery path.
-  // Cancel / permission-denial resumes auto-capture.
-  const handleGalleryPick = useCallback(() => {
-    if (completedRef.current) return;
-    setStreaming(false);
-    setDeliveringDocument(true);
-    void (async () => {
-      try {
-        const permission =
-          await ImagePicker.requestMediaLibraryPermissionsAsync();
-        if (!permission.granted) {
-          setDeliveringDocument(false);
-          // Don't resume if a concurrent auto-capture already claimed delivery.
-          if (!completedRef.current) setStreaming(true);
-          return;
-        }
-        const result = await ImagePicker.launchImageLibraryAsync({
-          mediaTypes: ["images"],
-          allowsMultipleSelection: false,
-          quality: 1,
-        });
-        const asset = result.canceled ? undefined : result.assets[0];
-        if (asset === undefined) {
-          setDeliveringDocument(false);
-          // Don't resume if a concurrent auto-capture already claimed delivery.
-          if (!completedRef.current) setStreaming(true);
-          return;
-        }
-        // Reject too-small images before claiming the latch — upscaling them
-        // yields unreadable documents. Show a chip and resume auto-capture.
-        if (
-          asset.width !== undefined &&
-          asset.height !== undefined &&
-          Math.min(asset.width, asset.height) <
-            CameraDefaults.minGalleryDocumentDimensionPx
-        ) {
-          setGalleryErrorKey("si_document_gallery_image_too_small");
-          setDeliveringDocument(false);
-          // Don't resume if a concurrent auto-capture already claimed delivery.
-          if (!completedRef.current) setStreaming(true);
-          return;
-        }
-        if (completedRef.current) return; // auto-capture won the race
-        completedRef.current = true;
-        const processedUri = await resampleImportedDocument(
-          { uri: asset.uri, width: asset.width, height: asset.height },
-          documentSide,
-        );
-        onDocumentOrigin?.(DocumentImageOrigin.Gallery);
-        onCaptureComplete?.(
-          [
-            {
-              kind: CaptureReadyEventKind.Document,
-              captureIndex: 0,
-              url: processedUri,
-            },
-          ],
-          captureTelemetry(),
-        );
-      } catch (error) {
-        UseSmileIDCrashReporting.captureException(
-          error instanceof Error ? error : new Error(String(error)),
-        );
-        setGalleryErrorKey("si_document_gallery_image_failed");
-        completedRef.current = false;
-        setDeliveringDocument(false);
-        setStreaming(true);
-      }
-    })();
-  }, [onCaptureComplete, onDocumentOrigin, documentSide]);
-
-  // Auto-start document capture (document idle has no Start button; selfie
-  // keeps its). Fires once per mount, so each side / retake auto-starts.
-  const autoStartedRef = useRef(false);
-  // Latest-ref so a new `handleStart` identity (it depends on `streaming`)
-  // doesn't re-run this effect; auto-start fires once per mount.
-  const handleStartRef = useRef(handleStart);
-  handleStartRef.current = handleStart;
-  useEffect(() => {
-    if (!isDocumentCapture || autoStartedRef.current || completedRef.current) {
-      return;
-    }
-    autoStartedRef.current = true;
-    handleStartRef.current();
-  }, [isDocumentCapture]);
-
-  // useSmileIDFrameStream overloads on FaceAnalyzer vs DocumentAnalyzer;
-  // the cast routes through the FaceAnalyzer overload — sound because the
-  // DocumentAnalyzer shape produces an identical wire surface, and the
-  // runtime pairing is guaranteed by captureType.
-  const frameStream = useSmileIDFrameStream(
-    (streaming ? analyzer : null) as FaceAnalyzer | null,
-    (result) => {
-      // A session boundary resets the debouncer so suppressed guidance can re-surface.
-      const previousScanState = previousScanStateRef.current;
-      if (
-        previousScanState !== null &&
-        isSessionBoundary(previousScanState, result.state)
-      ) {
-        setSessionEpoch((epoch) => epoch + 1);
-      }
-      // Haptic on a completed head turn (light between, success on the
-      // final, never on reset). Driven off the raw per-frame transition
-      // so 1% bucketing can't drop it; fired imperatively (no re-render).
-      if (previousScanState !== null) {
-        const haptic = essTurnHaptic(previousScanState, result.state);
-        if (haptic !== null) triggerEssTurnHaptic(haptic);
-      }
-      previousScanStateRef.current = result.state;
-
-      // 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 === 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 = [
-          ...capturedEventsRef.current,
-          ...result.capturedEvents,
-        ];
-      }
-      // Camera-rate results are mostly identical — commit only
-      // render-relevant changes, progress bucketed to 1% for smooth fill.
-      setScanState((previous) =>
-        previous.type === result.state.type &&
-        previous.feedback === result.state.feedback &&
-        previous.reason === result.state.reason &&
-        previous.currentDirection === result.state.currentDirection &&
-        (previous.poseMatched ?? false) ===
-          (result.state.poseMatched ?? false) &&
-        Math.round((previous.captureProgress ?? 0) * 100) ===
-          Math.round((result.state.captureProgress ?? 0) * 100)
-          ? previous
-          : result.state,
-      );
-      setHasAnalyzedFrame(true);
-
-      // Terminal states: finished → flush + complete; timeout → failure
-      // without flushing (no captured artifacts to wait on).
-      if (result.state.type === UseSmileIDScanStateType.Finished) {
-        // `timedOutRef` too: stopping the stream is async, so a frame queued before the timeout can still land here.
-        if (completedRef.current || timedOutRef.current) return;
-        completedRef.current = true;
-        setStreaming(false);
-        // flush() waits for every emitted JPG to land on disk before we
-        // hand URLs to the partner, so onCaptureComplete never returns a
-        // partial-write path.
-        void analyzer
-          .flush()
-          .catch((error) => {
-            UseSmileIDCrashReporting.captureException(error);
-          })
-          .finally(() => {
-            // No-op for selfie (callback unset).
-            onDocumentOrigin?.(DocumentImageOrigin.CameraAutoCapture);
-            onCaptureComplete?.(capturedEventsRef.current, captureTelemetry());
-          });
-      } else if (result.state.type === UseSmileIDScanStateType.Timeout) {
-        if (completedRef.current || timedOutRef.current) return;
-        setStreaming(false);
-        // The terminal state rides on `timedOutRef`, not the one-shot delivery gate, so the shutter and Start button stay usable.
-        timedOutRef.current = true;
-        setCaptureTimedOut(true);
-        onCaptureTimeout?.(result.state);
-      }
-    },
-    {
-      onError: (error) => {
-        // Native analyzer errors (model load, decode). Reported, but not
-        // terminal — the next frame is still attempted.
-        UseSmileIDCrashReporting.captureException(error);
-      },
-    },
-  );
-
-  const uiState: UseSmileIDCaptureUiState = hasAnalyzedFrame
-    ? mapCaptureUiState(scanState, props.captureType, enableEnhancedLiveness)
-    : preCaptureUiState(props.captureType, enableEnhancedLiveness);
-  // Only the guidance copy is debounced; rim, fill, and direction stay real-time.
-  const settledFeedbackKey = useDebouncedFeedbackKey(
-    uiState.feedbackKey,
-    sessionEpoch,
-  );
-  const isInstructionState =
-    scanState.type === UseSmileIDScanStateType.Initial && !streaming;
-  // A selfie timeout leaves `scanState` on Timeout, so the instruction predicate alone would hide the only way to retry.
-  const showStartButton =
-    (isInstructionState || captureTimedOut) && !isDocumentCapture;
-  const canStart = !streaming && !completedRef.current;
-
-  const previewReady = hasPermission && device != null;
-
-  // Resolve the native frame processor plugin once per name.
-  const plugin = useMemo(
-    () =>
-      VisionCameraProxy.initFrameProcessorPlugin(
-        analyzer.frameProcessorPluginName,
-        {},
-      ) ?? null,
-    [analyzer.frameProcessorPluginName],
-  );
-
-  // Every terminal signal arrives inside a frame result, so a camera that delivers no frame at all would sit on the initial state forever.
-  // Latest-ref, not a dep: an inline `onCaptureTimeout` prop is a fresh identity every render, which would restart the wall clock.
-  const onCaptureTimeoutRef = useRef(onCaptureTimeout);
-  onCaptureTimeoutRef.current = onCaptureTimeout;
-  useEffect(() => {
-    if (!streaming || hasAnalyzedFrame) return;
-    const timer = setTimeout(() => {
-      if (completedRef.current || timedOutRef.current) return;
-      timedOutRef.current = true;
-      setCaptureStalled(true);
-      setCaptureTimedOut(true);
-      setStreaming(false);
-      onCaptureTimeoutRef.current?.({ type: UseSmileIDScanStateType.Timeout });
-    }, CameraDefaults.firstFrameTimeoutMs);
-    return () => clearTimeout(timer);
-  }, [streaming, hasAnalyzedFrame]);
-
-  // A frame disproves the stall; document capture has no Start button to clear it by hand.
-  useEffect(() => {
-    if (hasAnalyzedFrame) setCaptureStalled(false);
-  }, [hasAnalyzedFrame]);
-
-  // A missing plugin means no frame ever produces a result — report once
-  // on capture start rather than sitting silently on the initial state.
-  const pluginErrorReportedRef = useRef(false);
-  useEffect(() => {
-    if (!streaming || plugin !== null || pluginErrorReportedRef.current) {
-      return;
-    }
-    pluginErrorReportedRef.current = true;
-    UseSmileIDCrashReporting.captureException(
-      new FrameProcessorPluginNotRegisteredException({
-        pluginName: analyzer.frameProcessorPluginName,
-      }),
-    );
-  }, [streaming, plugin, analyzer.frameProcessorPluginName]);
-
-  // Posts results to JS without blocking the worklet. Backpressure is
-  // native: the plugin blocks the frame-processor thread per scan, so
-  // mid-scan frames are dropped before reaching JS.
-  const onFrameResult = frameStream.onFrameResult;
-  const onFrameResultRunOnJS = useMemo(() => {
-    return Worklets.createRunOnJS((rawResult: unknown) => {
-      onFrameResult(rawResult);
-    });
-  }, [onFrameResult]);
-
-  // 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,
-      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 &&
-    (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.
-  const contentState: UseSmileIDCaptureContentState = useMemo(
-    () => ({
-      captureType: props.captureType,
-      overlayState: uiState.overlayState,
-      enableEnhancedLiveness,
-      animationDirection: uiState.animationDirection,
-      poseMatched: uiState.poseMatched,
-      // A stalled camera, then a transient gallery-import error, preempt the live feedback chip.
-      feedbackKey: captureStalled
-        ? "si_capture_camera_unavailable"
-        : (galleryErrorKey ?? settledFeedbackKey),
-      // Documents auto-start (no Start button); selfie keeps its.
-      showCaptureButton: showStartButton,
-      showManualShutter: manualShutterAvailable,
-      showGalleryUpload: galleryAvailable,
-      isBackSide: documentSide === DocumentSide.Back,
-      ...(props.knownIdAspectRatio !== undefined
-        ? { knownIdAspectRatio: props.knownIdAspectRatio }
-        : {}),
-      ...(props.documentTypeKind !== undefined
-        ? { documentTypeKind: props.documentTypeKind }
-        : {}),
-    }),
-    [
-      props.captureType,
-      uiState.overlayState,
-      enableEnhancedLiveness,
-      uiState.animationDirection,
-      uiState.poseMatched,
-      settledFeedbackKey,
-      galleryErrorKey,
-      captureStalled,
-      showStartButton,
-      isDocumentCapture,
-      manualShutterAvailable,
-      galleryAvailable,
-      documentSide,
-      props.knownIdAspectRatio,
-      props.documentTypeKind,
-    ],
-  );
-
-  // Stable element so the camera tree survives unrelated state updates.
-  const cameraPreview = useMemo(
-    () => (
-      <>
-        {/* 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}
-            isActive={true}
-            {...(format ? { format } : {})}
-            // Photo output only for document capture (manual shutter's takePhoto()).
-            {...(props.captureType === CaptureType.document
-              ? { photo: true }
-              : {})}
-            // Gravity-based — keeps reporting tilt even when UI orientation is locked to portrait.
-            outputOrientation="device"
-            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.
-            {...(streaming ? { frameProcessor } : {})}
-            testID="si_capture_camera_preview"
-          />
-        ) : (
-          <View
-            style={[
-              StyleSheet.absoluteFill,
-              { backgroundColor: theme.colors.offBlack },
-            ]}
-            testID="si_capture_camera_placeholder"
-          />
-        )}
-      </>
-    ),
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- setDeviceOrientationDegrees is a state setter (stable)
-    [
-      props.captureType,
-      previewReady,
-      device,
-      format,
-      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.
-          `dark-content` because the capture overlay draws a near-opaque white
-          scrim behind the status bar, whatever the host app's own bar style. */}
-      <StatusBar
-        translucent
-        backgroundColor="transparent"
-        barStyle="dark-content"
-      />
-      <UseSmileIDCaptureContent
-        state={contentState}
-        captureProgress={uiState.captureProgress}
-        cameraPreview={cameraPreview}
-        onStartCapture={handleStart}
-        startCaptureEnabled={canStart}
-        onBack={props.onBack}
-        showAttribution={showAttribution}
-        startButton={props.startButton}
-        onViewportLayout={handleViewportLayout}
-        {...(isDocumentCapture
-          ? {
-              onManualShutter: handleManualShutter,
-              onGalleryUpload: handleGalleryPick,
-              documentControlsEnabled: !deliveringDocument,
-              ...(props.onClose ? { onClose: props.onClose } : {}),
-            }
-          : {})}
-        theme={theme}
-      />
-    </UseSmileIDThemeProvider>
-  );
-}