react-native-image-stitcher 0.11.1 → 0.13.0

package/src/camera/Camera.tsx

@@ -52,6 +52,7 @@ import {
   StyleSheet,
   Text,
   View,
+  useWindowDimensions,
   type StyleProp,
   type ViewStyle,
 } from 'react-native';
@@ -66,13 +67,21 @@ import { useARSession } from '../ar/useARSession';
 import { ARCameraView, type ARCameraViewHandle } from './ARCameraView';
 import { CameraShutter } from './CameraShutter';
 import { CameraView } from './CameraView';
+import { CaptureHeader, type CaptureHeaderProps } from './CaptureHeader';
+import { CapturePreview, type CapturePreviewAction } from './CapturePreview';
+import {
+  CaptureThumbnailStrip,
+  type CaptureThumbnailItem,
+} from './CaptureThumbnailStrip';
 import { CaptureStatusOverlay, type CaptureStatusPhase } from './CaptureStatusOverlay';
 import { CaptureDebugOverlay } from './CaptureDebugOverlay';
 import { CaptureMemoryPill } from './CaptureMemoryPill';
 import { CaptureKeyframePill } from './CaptureKeyframePill';
 import { CaptureOrientationPill } from './CaptureOrientationPill';
 import { CaptureStitchStatsToast, useStitchStatsToast } from './CaptureStitchStatsToast';
+import { IncrementalPanGuide } from './IncrementalPanGuide';
 import { PanoramaBandOverlay } from './PanoramaBandOverlay';
+import { PanoramaGuidance } from './PanoramaGuidance';
 import { type PanoramaSettings } from './PanoramaSettings';
 import { panoramaSettingsToNativeConfig } from './PanoramaSettingsBridge';
 import { PanoramaSettingsModal } from './PanoramaSettingsModal';
@@ -82,7 +91,9 @@ import {
 } from './buildPanoramaInitialSettings';
 import { isLowMemDevice } from './lowMemDevice';
 import { useCapture } from './useCapture';
-import { useDeviceOrientation } from './useDeviceOrientation';
+import { useDeviceOrientation, type DeviceOrientation } from './useDeviceOrientation';
+import { useOrientationDrift } from './useOrientationDrift';
+import { OrientationDriftModal } from './OrientationDriftModal';
 import {
   getIncrementalNativeModule,
   incrementalStitcherIsAvailable,
@@ -293,6 +304,212 @@ export interface CameraProps {
   onFramesDropped?: (info: FramesDroppedInfo) => void;
   onError?: (err: CameraError) => void;
 
+  /**
+   * v0.12.0 — fires when the SDK auto-abandons an in-progress
+   * capture without producing output.  `reason` is a string union
+   * so future reasons (network loss, low memory, etc.) can be added
+   * without breaking the callback signature.
+   *
+   * Currently the only reason in v0.12 is `'orientation-drift'`:
+   * the user rotated the device between Mode A (landscape + vertical
+   * pan) and Mode B (portrait + horizontal pan) mid-capture.  The
+   * engine docstring at `incremental.ts:373-403` is explicit that
+   * cross-mode capture is "best-effort, not supported," so the SDK
+   * decisively cancels the capture (`incremental.cancel()`) and
+   * surfaces `OrientationDriftModal` to explain what happened.
+   *
+   * Hosts use this callback to clean up their own state (e.g., reset
+   * a wizard step, log telemetry, surface their own retry UX in
+   * addition to the SDK's built-in modal).  No `onCapture` will fire
+   * for an abandoned capture.
+   */
+  onCaptureAbandoned?: (reason: 'orientation-drift') => void;
+
+  /**
+   * v0.13.0 — flash (torch) state.  Controlled-or-uncontrolled.
+   *
+   *   - **Uncontrolled** (omit `flash`): `<Camera>` owns the flash
+   *     state internally.  Tapping the built-in flash button toggles
+   *     it on/off.  `onFlashChange` (if supplied) fires for telemetry.
+   *   - **Controlled** (supply `flash`): the parent owns the state.
+   *     The built-in button still renders and fires `onFlashChange`
+   *     on press, but it's a no-op unless the parent updates `flash`
+   *     in response.
+   *
+   * Both shapes coexist with the v0.13 "flash button is on by default"
+   * built-in (see the bottom-left bar slot in the JSX).  Hosts that
+   * want their own flash chrome can opt out via `showFlashButton={false}`
+   * and drive the underlying torch by controlling `flash` directly.
+   *
+   * ## AR-mode behaviour
+   *
+   * In AR mode (`defaultCaptureSource="ar"` or runtime-toggled),
+   * ARKit / ARCore own the `AVCaptureDevice` and don't expose the
+   * torch through vision-camera's pipeline.  The built-in flash
+   * button renders as visibly disabled (a11y label "Flash unavailable
+   * in AR mode") and `flash` is forced to `'off'` regardless of
+   * controlled/uncontrolled state.  Hosts that need flash should
+   * toggle to non-AR before enabling.
+   */
+  flash?: 'on' | 'off';
+
+  /**
+   * v0.13.0 — fires when the user taps the built-in flash button.
+   * In uncontrolled mode, the internal state has already flipped
+   * (single render delay).  In controlled mode, the parent must
+   * update the `flash` prop in response or the visual toggle is
+   * a no-op.  Useful in either mode for telemetry.
+   */
+  onFlashChange?: (next: 'on' | 'off') => void;
+
+  /**
+   * v0.13.0 — show the built-in flash button in the bottom-left
+   * slot.  Defaults to `true`.  Hosts that render their own flash
+   * chrome (and drive the underlying torch via the controlled
+   * `flash` prop) can opt out by setting this to `false`.
+   */
+  showFlashButton?: boolean;
+
+  /**
+   * v0.13.0 — show the built-in IncrementalPanGuide ("keep the
+   * arrow on the line" drift marker) while recording.  Defaults
+   * to `true`.  The guide is gyroscope-driven and only active
+   * during the recording phase (no idle sensor cost).  Hosts that
+   * want their own pan-guide chrome can opt out via `false`.
+   */
+  panGuide?: boolean;
+
+  /**
+   * v0.13.0 — show the built-in PanoramaGuidance pan-speed pill
+   * ("Pan slowly" / "Slow down" / "Too fast") while recording.
+   * Defaults to `true`.  Gyroscope-driven, only active during
+   * recording.  Hosts that want their own speed chrome can opt
+   * out via `false`.
+   */
+  panoramaGuidance?: boolean;
+
+  /**
+   * v0.13.0 — built-in CaptureHeader title.  When set, `<Camera>`
+   * renders a top-of-screen header showing this title (centred)
+   * with an optional back affordance + guidance subtitle + the
+   * existing settings gear absorbed into the header's right side.
+   *
+   * When `headerTitle` is undefined the header is not rendered
+   * (matches pre-v0.13 behaviour: top of preview is bare except
+   * for the standalone settings gear gated on `showSettingsButton`).
+   *
+   * Combine with `onHeaderBack`, `headerBackLabel`, `headerGuidance`,
+   * and `headerColors` to customise the rest of the header.  Hosts
+   * that need richer header chrome can omit `headerTitle` and
+   * compose their own `<CaptureHeader>` above `<Camera>`.
+   */
+  headerTitle?: string;
+
+  /**
+   * v0.13.0 — header back-button callback.  When supplied (and
+   * `headerTitle` is set), the header renders a back affordance
+   * on the left.  Omitted ⇒ no back button (the title stays
+   * centred).
+   */
+  onHeaderBack?: () => void;
+
+  /**
+   * v0.13.0 — header back-button label.  Defaults to "‹ Back".
+   * No effect unless `headerTitle` and `onHeaderBack` are both set.
+   */
+  headerBackLabel?: string;
+
+  /**
+   * v0.13.0 — optional second-line subtitle shown below the
+   * header title.  E.g. "Photograph the promotional cola end cap."
+   * Renders nothing when undefined.  No effect unless `headerTitle`
+   * is set.
+   */
+  headerGuidance?: string;
+
+  /**
+   * v0.13.0 — colour overrides for the built-in header.  Defaults
+   * are white-on-black to stay legible over the camera preview.
+   * No effect unless `headerTitle` is set.
+   */
+  headerColors?: CaptureHeaderProps['colors'];
+
+  /**
+   * v0.13.0 — when provided (even as `[]`), `<Camera>` renders a
+   * built-in `CaptureThumbnailStrip` above the bottom controls
+   * showing the host's capture history.  Each item is a plain
+   * `{ id, uri, width?, height? }` object; the strip handles
+   * aspect-ratio rendering, tap-to-preview, and the count line.
+   *
+   * Omit (`undefined`) to skip the strip entirely.  Hosts using
+   * the strip independently (e.g. on a non-camera screen) can keep
+   * importing `CaptureThumbnailStrip` directly from the library —
+   * the prop here is the convenience wiring for in-`<Camera>` use.
+   *
+   * Captures emitted by `<Camera>`'s `onCapture` are NOT added to
+   * this array automatically — the host owns the canonical list
+   * (typically persisted to its own DB) and updates the prop in
+   * response.  This matches the SDK's "Camera owns runtime state,
+   * host persists" pattern.
+   */
+  thumbnails?: CaptureThumbnailItem[];
+
+  /**
+   * v0.13.0 — minimum-photos hint for the count line.  Renders
+   * "n / minPhotos min" with the success colour when reached,
+   * warning colour otherwise.
+   */
+  thumbnailsMin?: number;
+
+  /**
+   * v0.13.0 — maximum-photos hint for the count line.  Renders
+   * "· maxPhotos max" suffix.  No enforcement — the host decides
+   * what to do at the cap.
+   */
+  thumbnailsMax?: number;
+
+  /**
+   * v0.13.0 — tap handler for thumbnails.  When set, replaces the
+   * strip's built-in tap-to-preview modal; the host shows its own
+   * preview UI (e.g. with delete / recapture buttons gated on
+   * sync state).  Omit to use the built-in preview.
+   */
+  onThumbnailPress?: (item: CaptureThumbnailItem) => void;
+
+  /**
+   * v0.13.0 — when set, `<Camera>` renders a built-in `CapturePreview`
+   * modal as `visible`.  Use this for post-stitch confirmation:
+   * after `onCapture` emits, the host stores the result and sets
+   * `capturePreview` to the new image, with `capturePreviewActions`
+   * = `[Discard, Save]` (or similar).  Setting `undefined` hides
+   * the modal.
+   *
+   * Hosts using the modal for thumbnail tap-to-preview can leave
+   * this undefined and let the built-in strip's preview handle
+   * that case.
+   */
+  capturePreview?: {
+    imageUri: string;
+    imageWidth?: number;
+    imageHeight?: number;
+    title?: string;
+  };
+
+  /**
+   * v0.13.0 — action buttons rendered along the bottom of the
+   * `CapturePreview` modal.  Empty array (or undefined) renders
+   * no buttons, only the close affordance.
+   */
+  capturePreviewActions?: CapturePreviewAction[];
+
+  /**
+   * v0.13.0 — fires when the user dismisses the `capturePreview`
+   * modal (tap close, backdrop tap, hardware back on Android).
+   * The host is expected to clear the `capturePreview` prop in
+   * response.
+   */
+  onCapturePreviewClose?: () => void;
+
   /**
    * Optional host-supplied vision-camera frame processor.
    *
@@ -656,17 +873,49 @@ export function Camera(props: CameraProps): React.JSX.Element {
     onLensChange,
     onFramesDropped,
     onError,
+    onCaptureAbandoned,
+    flash: controlledFlash,
+    onFlashChange,
+    showFlashButton = true,
+    panGuide = true,
+    panoramaGuidance = true,
+    headerTitle,
+    onHeaderBack,
+    headerBackLabel,
+    headerGuidance,
+    headerColors,
+    thumbnails,
+    thumbnailsMin,
+    thumbnailsMax,
+    onThumbnailPress,
+    capturePreview,
+    capturePreviewActions,
+    onCapturePreviewClose,
     frameProcessor: hostFrameProcessor,
     engine = 'batch-keyframe',
   } = props;
 
   const insets = useSafeAreaInsets();
+  // v0.12.0 — JS-layout orientation independent of device-physical.
+  // `useWindowDimensions().width > height` tells us if the OS
+  // rotated the framebuffer (only happens for non-locked hosts in
+  // device-landscape).  Combined with `useDeviceOrientation()` to
+  // pick the JS edge corresponding to the home-indicator side of
+  // the device — see `homeIndicatorEdge` below.
+  const jsWindow = useWindowDimensions();
+  const jsLandscape = jsWindow.width > jsWindow.height;
 
   // ── State ───────────────────────────────────────────────────────
   const [arPreference, setArPreference] = useState(
     defaultCaptureSource === 'ar',
   );
   const [lens, setLens] = useState<CameraLens>(defaultLens);
+  // v0.13.0 — flash state.  Controlled by `controlledFlash` when the
+  // host supplies the `flash` prop; otherwise owned internally and
+  // toggled by the built-in flash button.  `effectiveFlash` below
+  // also forces 'off' in AR mode (ARKit / ARCore own the device's
+  // torch and don't surface it through vision-camera's pipeline).
+  const [internalFlash, setInternalFlash] = useState<'on' | 'off'>('off');
   const [settings, setSettings] = useState<PanoramaSettings>(() =>
     buildPanoramaInitialSettings(
       extractPanoramaOverrides(props),
@@ -857,6 +1106,64 @@ export function Camera(props: CameraProps): React.JSX.Element {
   // eslint-disable-next-line react-hooks/exhaustive-deps
   useEffect(() => () => { fpDriver.stop(); }, []);
 
+  // ── v0.12.0 — Orientation drift detection + auto-abandon ────────
+  //
+  // The incremental engine supports both portrait (Mode B, horizontal
+  // pan) and landscape (Mode A, vertical pan) capture as first-class,
+  // but the docstring at `incremental.ts:373-403` is explicit that
+  // mixing them mid-capture is "best-effort, not supported" — the
+  // output rotation becomes ambiguous and the stitched panorama is
+  // malformed.  v0.12 protects against this by snapshotting the
+  // orientation at `start()` and auto-cancelling the capture the
+  // instant the user rotates to a different orientation mid-flight.
+  //
+  // The modal is informational only — by the time it renders, the
+  // capture is already stopped.  No Continue/Resume affordance per
+  // the engine spec.
+  const drift = useOrientationDrift(statusPhase === 'recording');
+  const [driftModalDismissed, setDriftModalDismissed] = useState(false);
+  // Reset the dismissed flag when a new capture starts (or any non-
+  // recording state) so the next drift event surfaces a fresh modal.
+  useEffect(() => {
+    if (statusPhase !== 'recording') setDriftModalDismissed(false);
+  }, [statusPhase]);
+
+  useEffect(() => {
+    if (!drift.drifted || statusPhase !== 'recording') return;
+    // Auto-abandon the in-flight capture.  Order matches handleHoldEnd's
+    // "stitch" path but skips finalize:
+    //   1. Stop pumping frames so no new keyframes arrive mid-cancel.
+    //   2. Tell the native engine to drop accumulated state
+    //      (`incremental.cancel()`).
+    //   3. Reset statusPhase back to idle.
+    //   4. Notify the host via `onCaptureAbandoned`.
+    //
+    // Wrapped in an IIFE because useEffect callbacks can't be async
+    // directly.  Errors from `incremental.cancel()` are caught + sent
+    // through `onError` — abandonment must succeed even if the engine
+    // is in a weird state.
+    void (async () => {
+      fpDriver.stop();
+      try {
+        await incremental.cancel();
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        onError?.(new CameraError(
+          'PANORAMA_FINALIZE_FAILED',
+          `cancel after orientation drift failed: ${message}`,
+          err,
+        ));
+      } finally {
+        setStatusPhase('idle');
+        setRecordingStartedAt(null);
+        onCaptureAbandoned?.('orientation-drift');
+      }
+    })();
+    // Deps: re-run whenever drift latches OR recording state changes.
+    // Other deps are stable refs / setters.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [drift.drifted, statusPhase]);
+
   // v0.8.0 Phase 5 / v0.11.0 — frameProcessor prop semantics:
   //
   //   - Host supplied? → use host's processor.  The host's worklet
@@ -991,7 +1298,14 @@ export function Camera(props: CameraProps): React.JSX.Element {
         // ARCameraView writes to its own tmp location; relocate to
         // photoOutputPath via the native FileBridge so both branches
         // return paths under the same dir.
-        const photo = await arViewRef.current.takePhoto({ quality: 90 });
+        // v0.12.0 — pass deviceOrientation so the AR takePhoto's
+        // native CIImage rotation matches the user's view.  Pre-
+        // v0.12 the native side hardcoded portrait, so landscape
+        // photos came out sideways.
+        const photo = await arViewRef.current.takePhoto({
+          quality: 90,
+          orientation: deviceOrientation,
+        });
         try {
           await moveFile(photo.path, photoOutputPath);
         } catch (moveErr) {
@@ -1251,6 +1565,22 @@ export function Camera(props: CameraProps): React.JSX.Element {
     setArPreference((prev) => !prev);
   }, []);
 
+  // ── v0.13.0 — Flash control ─────────────────────────────────────
+  //
+  // `flashRequested` is what the host / built-in button asks for.
+  // `effectiveFlash` is what we actually drive into vision-camera —
+  // AR mode forces 'off' because ARKit / ARCore own AVCaptureDevice
+  // and the torch isn't exposed.  This way the button's visual state
+  // (a11y, styling) tracks `flashRequested` while the underlying
+  // camera always sees the correct value.
+  const flashRequested: 'on' | 'off' = controlledFlash ?? internalFlash;
+  const effectiveFlash: 'on' | 'off' = isAR ? 'off' : flashRequested;
+  const toggleFlash = useCallback(() => {
+    const next: 'on' | 'off' = flashRequested === 'on' ? 'off' : 'on';
+    if (controlledFlash == null) setInternalFlash(next);
+    onFlashChange?.(next);
+  }, [flashRequested, controlledFlash, onFlashChange]);
+
   // ── JSX ─────────────────────────────────────────────────────────
 
   return (
@@ -1282,7 +1612,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
           // works either way.  Pattern matches AuditCaptureScreen.tsx
           // which has run on `video` (true) for months without issue.
           video
-          flash="off"
+          flash={effectiveFlash}
           style={StyleSheet.absoluteFill}
           // F8 (FrameProcessor port) — host-supplied worklet runs on
           // the camera producer thread for every frame.  Only wired
@@ -1318,6 +1648,20 @@ export function Camera(props: CameraProps): React.JSX.Element {
         recordingStartedAt={recordingStartedAt ?? undefined}
       />
 
+      {/* v0.13.0 — built-in pan guidance overlays.  Both sit on top
+          of the camera preview but under the controls.  Each is
+          gyroscope-driven and only subscribes while `active` is
+          true — flipping `active` false on capture-end tears the
+          subscription down so the sensor isn't running idle.  Hosts
+          can opt out per overlay via the `panGuide` / `panoramaGuidance`
+          boolean props (both default true). */}
+      {panGuide && (
+        <IncrementalPanGuide active={statusPhase === 'recording'} />
+      )}
+      {panoramaGuidance && (
+        <PanoramaGuidance active={statusPhase === 'recording'} />
+      )}
+
       {/*
         2026-05-22 (audit F9 + F3) — debug UI suite, all gated on
         settings.debug.  Mounts in <Camera> automatically; Layer-2
@@ -1361,39 +1705,111 @@ export function Camera(props: CameraProps): React.JSX.Element {
         topInset={insets.top}
       />
 
-      {/* Settings gear (top-right), gated on showSettingsButton. */}
-      {showSettingsButton && (
-        <SettingsButton
-          topInset={insets.top}
-          onPress={() => setSettingsModalVisible(true)}
-        />
+      {/* v0.13.0 — built-in CaptureHeader, gated on `headerTitle`.
+          When the header is mounted, it absorbs the settings gear
+          on its right side (avoids stacking with the standalone
+          gear).  Hosts that DON'T set `headerTitle` get the legacy
+          standalone gear, still gated on `showSettingsButton`. */}
+      {headerTitle != null ? (
+        <View style={styles.headerWrap} pointerEvents="box-none">
+          <CaptureHeader
+            title={headerTitle}
+            onBack={onHeaderBack}
+            backLabel={headerBackLabel}
+            guidance={headerGuidance}
+            colors={headerColors}
+            topInset={insets.top}
+            onSettingsPress={
+              showSettingsButton
+                ? () => setSettingsModalVisible(true)
+                : undefined
+            }
+          />
+        </View>
+      ) : (
+        showSettingsButton && (
+          <SettingsButton
+            topInset={insets.top}
+            onPress={() => setSettingsModalVisible(true)}
+          />
+        )
+      )}
+
+      {/* v0.13.0 — built-in capture-history thumbnail strip.  Renders
+          when the host supplies a `thumbnails` array (even empty),
+          hidden during recording so it doesn't overlap the band
+          overlay.  Sits above the bottom controls in JS-bottom
+          coordinates; landscape/non-locked layouts get the strip in
+          the same place (no orientation-aware repositioning for now —
+          the strip is intrinsically horizontal). */}
+      {thumbnails != null && statusPhase !== 'recording' && (
+        <View style={styles.thumbnailStripWrap} pointerEvents="box-none">
+          <CaptureThumbnailStrip
+            items={thumbnails}
+            minPhotos={thumbnailsMin}
+            maxPhotos={thumbnailsMax}
+            onItemPress={onThumbnailPress}
+          />
+        </View>
       )}
 
       {/*
-        Bottom area: stacks the live-frame band ABOVE the shutter row
-        so the band is tethered to the shutter on the viewport side
-        (the operator's eye is drawn from the camera preview, down
-        the band, into the shutter — a single continuous reading
-        path).  With the SDK's orientation lock holding the UI in
-        portrait, this stack works the same regardless of how the
-        device is physically held.
+        v0.12.0 — Orientation-aware bottom controls anchored to the
+        physical home-indicator edge.  The shutter follows the home-
+        indicator regardless of host portrait-lock state:
+          - locked + any device              → JS-bottom (locked
+            framebuffer maps device-bottom to JS-bottom always)
+          - non-locked + device-portrait     → JS-bottom
+          - non-locked + device-landscape-L  → JS-right
+          - non-locked + device-landscape-R  → JS-left
+        Computed in `homeIndicatorEdge` which combines `jsLandscape`
+        (from window dims) with `deviceOrientation` (sensor).
       */}
       <View
         pointerEvents="box-none"
-        style={[styles.bottomArea, { paddingBottom: insets.bottom + 12 }]}
+        style={bottomAreaStyleForEdge(
+          homeIndicatorEdge(jsLandscape, deviceOrientation),
+          insets.bottom + 12,
+          insets.top + 12,
+        )}
       >
-        {/* Live-frame band — only visible while recording. */}
+        {/* Live-frame band — only visible while recording.  `vertical`
+            is true when the home-indicator anchor is on a side edge
+            (left or right), in which case the band is a vertical
+            column.  Otherwise it's a horizontal strip. */}
         {statusPhase === 'recording' && (
           <PanoramaBandOverlay
             state={incrementalState}
             frameUris={batchKeyframeThumbnails}
             captureOrientation={deviceOrientation}
+            vertical={isSideEdge(homeIndicatorEdge(jsLandscape, deviceOrientation))}
           />
         )}
 
-        {/* Shutter row: lens chip (left), shutter (centre), AR toggle (right). */}
-        <View style={styles.bottomBar}>
-        <View style={styles.bottomBarLeft} />
+        {/* Shutter row.  Horizontal row when home-indicator is on
+            top/bottom (lens left / shutter center / AR right);
+            vertical column when on left/right (slots stack along
+            the narrow strip).  Touch targets stay axis-aligned. */}
+        <View style={bottomBarStyleForEdge(homeIndicatorEdge(jsLandscape, deviceOrientation))}>
+        <View style={styles.bottomBarLeft}>
+          {showFlashButton && (
+            <Pressable
+              onPress={isAR ? undefined : toggleFlash}
+              accessibilityRole="button"
+              accessibilityLabel={isAR ? 'Flash unavailable in AR mode' : `Flash ${flashRequested === 'on' ? 'on' : 'off'}`}
+              accessibilityState={{ selected: flashRequested === 'on', disabled: isAR }}
+              disabled={isAR}
+              hitSlop={8}
+              style={[
+                styles.flashButton,
+                flashRequested === 'on' && !isAR && styles.flashButtonActive,
+                isAR && styles.flashButtonDisabled,
+              ]}
+            >
+              <Text style={styles.flashIcon}>⚡</Text>
+            </Pressable>
+          )}
+        </View>
         <View style={styles.bottomBarCenter}>
           <LensChip
             lens={lens}
@@ -1425,6 +1841,34 @@ export function Camera(props: CameraProps): React.JSX.Element {
         onChange={setSettings}
         onClose={() => setSettingsModalVisible(false)}
       />
+
+      {/* v0.12.0 — Orientation drift modal.  Shows AFTER the SDK has
+          auto-abandoned the capture (the useEffect above stops the
+          engine + transitions to idle + fires onCaptureAbandoned).
+          Modal exists purely to explain WHY the capture was
+          cancelled.  Single OK button (no Continue) per the engine
+          spec on cross-mode capture being best-effort, not supported. */}
+      <OrientationDriftModal
+        visible={drift.drifted && !driftModalDismissed}
+        captureOrientation={drift.captureOrientation}
+        currentOrientation={drift.currentOrientation}
+        onAcknowledge={() => setDriftModalDismissed(true)}
+      />
+
+      {/* v0.13.0 — built-in post-stitch / tap-to-preview modal.
+          Visible when the host supplies `capturePreview`.  When
+          undefined the modal stays hidden (visible=false) so it
+          doesn't intercept touches.  Host is expected to clear
+          `capturePreview` via `onCapturePreviewClose` on dismiss. */}
+      <CapturePreview
+        visible={capturePreview != null}
+        imageUri={capturePreview?.imageUri ?? ''}
+        imageWidth={capturePreview?.imageWidth}
+        imageHeight={capturePreview?.imageHeight}
+        title={capturePreview?.title}
+        actions={capturePreviewActions}
+        onClose={onCapturePreviewClose ?? noop}
+      />
     </View>
   );
 }
@@ -1435,6 +1879,148 @@ function noop(): void {
 }
 
 
+/**
+ * v0.12.0 — JS edge corresponding to the physical home-indicator
+ * side of the device.  This is where the shutter + controls anchor
+ * to so they're always within thumb reach of the user's grip
+ * (matching iOS Camera's behaviour).
+ *
+ * Combines two signals:
+ *   - `jsLandscape`: whether the OS rotated the framebuffer.  True
+ *     only for non-locked hosts in device-landscape.
+ *   - `deviceOrient`: physical device orientation from the sensor.
+ *
+ * Truth table:
+ *   | jsLandscape | deviceOrient        | edge   |
+ *   |---           |---                  |---     |
+ *   | false        | any                 | bottom | (portrait JS coords —
+ *   |              |                     |        |  device-bottom = JS-bottom
+ *   |              |                     |        |  in both locked and
+ *   |              |                     |        |  non-locked-portrait)
+ *   | true         | landscape-left      | right  | (screen rotated, home
+ *   |              |                     |        |  indicator on user-right)
+ *   | true         | landscape-right     | left   | (mirror)
+ *
+ * Caveats:
+ *   - Non-locked + upside-down doesn't surface JS-top here because
+ *     upside-down doesn't change window dimensions; we can't
+ *     distinguish locked-portrait-with-device-flipped from
+ *     non-locked-portrait-with-screen-flipped-180°.  Defaults to
+ *     JS-bottom which matches the more common locked case.  Add
+ *     handling here when a host needs upside-down support.
+ *   - jsLandscape=true with non-landscape device shouldn't happen
+ *     in steady state — only during a transition mid-rotation.
+ *     Falls through to 'right' as a defensive default.
+ */
+type HomeIndicatorEdge = 'bottom' | 'top' | 'left' | 'right';
+
+function homeIndicatorEdge(
+  jsLandscape: boolean,
+  deviceOrient: DeviceOrientation,
+): HomeIndicatorEdge {
+  if (!jsLandscape) return 'bottom';
+  if (deviceOrient === 'landscape-left') return 'right';
+  if (deviceOrient === 'landscape-right') return 'left';
+  return 'right';
+}
+
+
+/**
+ * v0.12.0 — true when the anchor edge is on a side (left/right), so
+ * the band + shutter row need to be vertical strips.  Top/bottom
+ * anchors yield horizontal strips.
+ */
+function isSideEdge(edge: HomeIndicatorEdge): boolean {
+  return edge === 'left' || edge === 'right';
+}
+
+
+/**
+ * v0.12.0 — bottom-controls outer container positioning.  Anchors
+ * to the home-indicator JS edge with the appropriate flex direction
+ * so the band sits on the viewport side of the shutter (toward the
+ * camera preview centre).
+ */
+function bottomAreaStyleForEdge(
+  edge: HomeIndicatorEdge,
+  bottomInsetPx: number,
+  topInsetPx: number,
+): ViewStyle {
+  switch (edge) {
+    case 'bottom':
+      // Band above shutter row, both at JS-bottom.  JSX order
+      // [band, shutter] + flexDirection 'column' = band at top of
+      // stack (closer to screen centre), shutter at JS-bottom.
+      return {
+        position: 'absolute',
+        left: 0,
+        right: 0,
+        bottom: 0,
+        flexDirection: 'column',
+        alignItems: 'stretch',
+        paddingBottom: bottomInsetPx,
+      };
+    case 'top':
+      // Mirror of bottom.  column-reverse so JSX [band, shutter]
+      // renders [shutter, band] in JS, shutter at JS-top, band
+      // below it (toward screen centre).
+      return {
+        position: 'absolute',
+        left: 0,
+        right: 0,
+        top: 0,
+        flexDirection: 'column-reverse',
+        alignItems: 'stretch',
+        paddingTop: topInsetPx,
+      };
+    case 'right':
+      // Band to the left of shutter column, both at JS-right.
+      // flexDirection 'row' + JSX [band, shutter] = band at JS-left
+      // of container (screen centre side), shutter at JS-right.
+      return {
+        position: 'absolute',
+        top: 0,
+        bottom: 0,
+        right: 0,
+        flexDirection: 'row',
+        alignItems: 'stretch',
+        paddingRight: 12,
+      };
+    case 'left':
+      // Mirror of right.  row-reverse so JSX [band, shutter] gives
+      // band at JS-right (screen centre side), shutter at JS-left.
+      return {
+        position: 'absolute',
+        top: 0,
+        bottom: 0,
+        left: 0,
+        flexDirection: 'row-reverse',
+        alignItems: 'stretch',
+        paddingLeft: 12,
+      };
+  }
+}
+
+
+/**
+ * v0.12.0 — inner shutter-row flex direction.  Horizontal row for
+ * top/bottom anchors; vertical column for left/right anchors so
+ * the three slots (lens / shutter / AR) stack along the narrow
+ * side strip.  Buttons don't rotate — touch targets and text
+ * orient correctly via either (a) un-rotated framebuffer under
+ * portrait-lock or (b) OS-rotated framebuffer under non-locked.
+ */
+function bottomBarStyleForEdge(edge: HomeIndicatorEdge): ViewStyle {
+  const vertical = isSideEdge(edge);
+  return {
+    flexDirection: vertical ? 'column' : 'row',
+    paddingHorizontal: vertical ? 0 : 18,
+    paddingVertical: vertical ? 18 : 0,
+    alignItems: 'center',
+  };
+}
+
+
 const styles = StyleSheet.create({
   container: {
     flex: 1,
@@ -1464,6 +2050,8 @@ const styles = StyleSheet.create({
   },
   bottomBarLeft: {
     flex: 1,
+    alignItems: 'flex-start',
+    justifyContent: 'flex-end',
   },
   bottomBarCenter: {
     flex: 1,
@@ -1477,4 +2065,34 @@ const styles = StyleSheet.create({
   shutterWrap: {
     marginTop: 12,
   },
+  headerWrap: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+  },
+  thumbnailStripWrap: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    bottom: 160,
+  },
+  flashButton: {
+    width: 44,
+    height: 44,
+    borderRadius: 22,
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: 'rgba(0,0,0,0.45)',
+  },
+  flashButtonActive: {
+    backgroundColor: '#ffd34d',
+  },
+  flashButtonDisabled: {
+    opacity: 0.35,
+  },
+  flashIcon: {
+    fontSize: 20,
+    color: '#ffffff',
+  },
 });