react-native-image-stitcher 0.12.0 → 0.14.0

package/src/camera/Camera.tsx

@@ -48,6 +48,7 @@ import React, {
 } from 'react';
 import {
   NativeModules,
+  Platform,
   Pressable,
   StyleSheet,
   Text,
@@ -67,6 +68,12 @@ 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';
@@ -84,6 +91,7 @@ import {
 import { isLowMemDevice } from './lowMemDevice';
 import { useCapture } from './useCapture';
 import { useDeviceOrientation, type DeviceOrientation } from './useDeviceOrientation';
+import { useContentRotation } from './useContentRotation';
 import { useOrientationDrift } from './useOrientationDrift';
 import { OrientationDriftModal } from './OrientationDriftModal';
 import {
@@ -107,6 +115,17 @@ import {
 // ─── Types ──────────────────────────────────────────────────────────
 
 export type CaptureSource = 'ar' | 'non-ar';
+/**
+ * v0.13.2 — which capture sources the host ALLOWS.  A constraint on top
+ * of `defaultCaptureSource` (which picks the initial source within this
+ * constraint):
+ *   'both'   — AR and non-AR both available; AR toggle is shown.
+ *   'ar'     — AR only; AR toggle hidden (nothing to switch to), and the
+ *              0.5× lens chooser is hidden (ARKit/ARCore don't expose the
+ *              ultra-wide).
+ *   'non-ar' — non-AR only; AR toggle hidden.
+ */
+export type CaptureSourcesMode = 'ar' | 'non-ar' | 'both';
 export type CameraLens = '1x' | '0.5x';
 export type StitchMode = 'auto' | 'panorama' | 'scans';
 export type Blender = 'multiband' | 'feather';
@@ -235,6 +254,19 @@ export interface CameraProps {
   enablePhotoMode?: boolean;
   enablePanoramaMode?: boolean;
   showSettingsButton?: boolean;
+  /**
+   * v0.13.2 — which capture sources the host allows (default `'both'`).
+   * Constrains both the runtime AR toggle and `defaultCaptureSource`:
+   *   - `'both'`  : AR + non-AR; the AR toggle is shown so the user can
+   *     switch at runtime.
+   *   - `'ar'`    : AR only.  AR toggle hidden (nothing to toggle); the
+   *     0.5× lens chooser is also hidden (ARKit/ARCore can't use the
+   *     ultra-wide), so the camera stays on the AR-capable 1× lens.
+   *   - `'non-ar'`: non-AR only.  AR toggle hidden.
+   * When set to a single source, that source wins regardless of
+   * `defaultCaptureSource`.
+   */
+  captureSources?: CaptureSourcesMode;
   style?: StyleProp<ViewStyle>;
 
   /**
@@ -317,6 +349,173 @@ export interface CameraProps {
    */
   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 — 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.
    *
@@ -422,12 +621,19 @@ interface LensChipProps {
   lens: CameraLens;
   onChange: (lens: CameraLens) => void;
   has0_5x: boolean;
+  /**
+   * v0.13.1 — counter-rotation applied to the label TEXT (not the pill
+   * container) so the "0.5×"/"1×" glyphs read upright when the device
+   * is held landscape under a portrait-locked host, while the pill
+   * itself stays fixed in the layout.  `{}` (no-op) in the upright cases.
+   */
+  contentRotation?: { transform?: ViewStyle['transform'] };
 }
-function LensChip({ lens, onChange, has0_5x }: LensChipProps): React.JSX.Element {
+function LensChip({ lens, onChange, has0_5x, contentRotation }: LensChipProps): React.JSX.Element {
   if (!has0_5x) {
     return (
       <View style={[lensChipStyles.container, lensChipStyles.singleLens]}>
-        <Text style={lensChipStyles.label}>1×</Text>
+        <Text style={[lensChipStyles.label, contentRotation]}>1×</Text>
       </View>
     );
   }
@@ -447,6 +653,7 @@ function LensChip({ lens, onChange, has0_5x }: LensChipProps): React.JSX.Element
           style={[
             lensChipStyles.label,
             lens === '0.5x' && lensChipStyles.labelActive,
+            contentRotation,
           ]}
         >
           0.5×
@@ -466,6 +673,7 @@ function LensChip({ lens, onChange, has0_5x }: LensChipProps): React.JSX.Element
           style={[
             lensChipStyles.label,
             lens === '1x' && lensChipStyles.labelActive,
+            contentRotation,
           ]}
         >
           1×
@@ -515,8 +723,15 @@ const lensChipStyles = StyleSheet.create({
 interface ARToggleProps {
   arEnabled: boolean;
   onToggle: () => void;
+  /**
+   * v0.13.1 — counter-rotation applied to the "AR" label TEXT (not the
+   * pill container) so the glyph reads upright when the device is held
+   * landscape under a portrait-locked host, while the pill stays fixed.
+   * `{}` no-op in the upright cases.
+   */
+  contentRotation?: { transform?: ViewStyle['transform'] };
 }
-function ARToggle({ arEnabled, onToggle }: ARToggleProps): React.JSX.Element {
+function ARToggle({ arEnabled, onToggle, contentRotation }: ARToggleProps): React.JSX.Element {
   return (
     <Pressable
       onPress={onToggle}
@@ -529,6 +744,7 @@ function ARToggle({ arEnabled, onToggle }: ARToggleProps): React.JSX.Element {
         style={[
           arToggleStyles.label,
           arEnabled && arToggleStyles.labelOn,
+          contentRotation,
         ]}
       >
         AR
@@ -670,6 +886,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
   const {
     defaultCaptureSource = 'ar',
     defaultLens = '1x',
+    captureSources = 'both',
     enablePhotoMode = true,
     enablePanoramaMode = true,
     showSettingsButton = false,
@@ -681,10 +898,33 @@ export function Camera(props: CameraProps): React.JSX.Element {
     onFramesDropped,
     onError,
     onCaptureAbandoned,
+    flash: controlledFlash,
+    onFlashChange,
+    showFlashButton = true,
+    headerTitle,
+    onHeaderBack,
+    headerBackLabel,
+    headerGuidance,
+    headerColors,
+    thumbnails,
+    thumbnailsMin,
+    thumbnailsMax,
+    onThumbnailPress,
+    capturePreview,
+    capturePreviewActions,
+    onCapturePreviewClose,
     frameProcessor: hostFrameProcessor,
     engine = 'batch-keyframe',
   } = props;
 
+  // v0.13.2 — capture-source constraint (default 'both').  Derives which
+  // sources are permitted; `captureSources` overrides any conflicting
+  // `defaultCaptureSource`.  Used to constrain the initial AR preference
+  // and to hide the AR toggle / lens chooser below.
+  const arAllowed = captureSources !== 'non-ar';
+  const nonArAllowed = captureSources !== 'ar';
+  const arOnly = captureSources === 'ar';
+
   const insets = useSafeAreaInsets();
   // v0.12.0 — JS-layout orientation independent of device-physical.
   // `useWindowDimensions().width > height` tells us if the OS
@@ -696,10 +936,21 @@ export function Camera(props: CameraProps): React.JSX.Element {
   const jsLandscape = jsWindow.width > jsWindow.height;
 
   // ── State ───────────────────────────────────────────────────────
+  // v0.13.2 — initial AR preference honours `defaultCaptureSource` but
+  // is clamped to the `captureSources` constraint: 'ar' forces on,
+  // 'non-ar' forces off, 'both' uses the default.
   const [arPreference, setArPreference] = useState(
-    defaultCaptureSource === 'ar',
+    !arAllowed ? false : !nonArAllowed ? true : defaultCaptureSource === 'ar',
   );
-  const [lens, setLens] = useState<CameraLens>(defaultLens);
+  // v0.13.2 — `arOnly` forces the 1× lens (the ultra-wide isn't usable
+  // in AR), and the lens chooser is hidden in that mode.
+  const [lens, setLens] = useState<CameraLens>(arOnly ? '1x' : 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),
@@ -739,6 +990,15 @@ export function Camera(props: CameraProps): React.JSX.Element {
   const isNonAR = !isAR;
   const deviceOrientation = useDeviceOrientation();
 
+  // v0.13.1 — counter-rotation for control CONTENT (AR toggle, lens
+  // pill, flash icon, thumbnails) so their labels read upright relative
+  // to gravity when the device is held landscape under a PORTRAIT-LOCKED
+  // host (the recommended config — the JS framebuffer stays portrait, so
+  // without this the labels render at 90°).  Returns `{}` (no-op) in the
+  // common upright cases, including non-locked hosts where the OS already
+  // rotated the framebuffer.  See `useContentRotation` truth table.
+  const contentRotation = useContentRotation();
+
   // ── Camera handoff gate ─────────────────────────────────────────
   //
   // The placeholder rendered while the underlying camera identity
@@ -770,6 +1030,35 @@ export function Camera(props: CameraProps): React.JSX.Element {
     || cameraTransitioning;
 
 
+  // ── v0.13.1 — Android portrait lock ─────────────────────────────
+  //
+  // Android lets a mounted view force its host Activity's orientation,
+  // so `<Camera>` guarantees a portrait capture surface regardless of
+  // the host app's manifest (even a landscape/unlocked host gets a
+  // portrait camera while `<Camera>` is mounted).  The lock lives on
+  // the Activity via the native `RNSARSession` module, so it covers
+  // BOTH the AR (ARCore) and non-AR (vision-camera) capture paths.
+  //
+  // iOS is intentionally NOT locked here: iOS supported orientations
+  // are a static Info.plist declaration the host owns, and we want iOS
+  // hosts to be able to support landscape/unlocked capture.  Hosts that
+  // want a portrait-only iOS app set UISupportedInterfaceOrientations
+  // themselves.
+  //
+  // Empty dep array — lock on mount, restore the host's PRIOR
+  // orientation on unmount (the native side captures it).
+  useEffect(() => {
+    if (Platform.OS !== 'android') return undefined;
+    const arModule = (NativeModules as Record<string, unknown>)
+      .RNSARSession as
+      | { lockPortrait?: () => void; unlockOrientation?: () => void }
+      | undefined;
+    arModule?.lockPortrait?.();
+    return () => {
+      arModule?.unlockOrientation?.();
+    };
+  }, []);
+
   // ── Notify parent of capture-source changes ─────────────────────
   const lastEmittedSourceRef = useRef<CaptureSource | null>(null);
   useEffect(() => {
@@ -779,21 +1068,23 @@ export function Camera(props: CameraProps): React.JSX.Element {
     }
   }, [effectiveCaptureSource, onCaptureSourceChange]);
 
-  // ── Lens chip availability ──────────────────────────────────────
-  // TODO follow-up: probe the device's available physical lenses via
-  // vision-camera's `useCameraDevices` and surface in
-  // `useCapture().availablePhysicalDevices`.  For now we assume the
-  // 0.5x ultra-wide exists on modern devices.  When it doesn't, the
-  // lens chip degenerates to a static 1× indicator (see LensChip).
-  const has0_5x = true;
-
   // ── Capture hooks ───────────────────────────────────────────────
+  // v0.13.2 — pass the active `lens` so useCapture uses capability-aware
+  // selection (multi-cam zoom-switch where available, standalone-ultra-
+  // wide swap otherwise).  Replaces the old per-lens
+  // `preferredPhysicalDevice` request that mis-selected on some phones.
   const capture = useCapture({
     cameraPosition: 'back',
     enableQualityChecks: false,
-    preferredPhysicalDevice:
-      lens === '0.5x' ? 'ultra-wide-angle-camera' : 'wide-angle-camera',
+    lens,
   });
+
+  // ── Lens chip availability ──────────────────────────────────────
+  // v0.13.2 — real device capability from `useCapture` (which uses
+  // `selectCaptureDevice`).  True only when the device actually exposes
+  // an ultra-wide reachable via a multi-cam zoom OR a standalone
+  // ultra-wide device; false on wide-only hardware (chip hides).
+  const has0_5x = capture.has0_5x;
   const incremental = useIncrementalStitcher();
   const visionCameraRef = useRef<VisionCamera | null>(null);
   const arViewRef = useRef<ARCameraViewHandle | null>(null);
@@ -1349,6 +1640,47 @@ 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 drive into vision-camera (non-AR).  AR
+  // mode forces 'off' (flash is hidden in AR; ARKit/ARCore own the
+  // device) so vision-camera — which isn't the active camera in AR —
+  // doesn't fight for it.
+  //
+  // v0.13.1 — the ACTIVE device's torch capability is the source of
+  // truth.  The ultra-wide (0.5×) lens has no flash/torch unit on most
+  // phones, so vision-camera throws `flash-not-available` if we pass
+  // flash="on" while it's selected.  `capture.device.hasTorch` (from
+  // vision-camera's device list) tells us definitively; we hide the
+  // flash control and force 'off' when the device can't flash.
+  // v0.13.2 — `capture.deviceHasTorch` reflects the MOUNTED device.  In
+  // multi-cam mode this is the multi-cam device (has a torch → flash
+  // works on both 1× and 0.5× via zoom).  In standalone-uw mode on 0.5×
+  // the mounted device is the torchless ultra-wide → flash hides.
+  const deviceHasTorch = capture.deviceHasTorch;
+  const flashRequested: 'on' | 'off' = controlledFlash ?? internalFlash;
+  const effectiveFlash: 'on' | 'off' =
+    isAR || !deviceHasTorch ? 'off' : flashRequested;
+  const toggleFlash = useCallback(() => {
+    const next: 'on' | 'off' = flashRequested === 'on' ? 'off' : 'on';
+    if (controlledFlash == null) setInternalFlash(next);
+    onFlashChange?.(next);
+  }, [flashRequested, controlledFlash, onFlashChange]);
+
+  // v0.13.1 — top-right control pills (flash + AR) stack vertically
+  // UNDER the settings affordance.  Anchor depends on what's above:
+  //   - headerTitle set  → pills clear the CaptureHeader bar
+  //     (title row ≈ topInset + ~36; guidance pill adds ~28 when present)
+  //   - standalone gear  → pills clear the 40px gear at topInset + 8
+  //   - neither          → pills start where the gear would be
+  const pillStackTop =
+    headerTitle != null
+      ? insets.top + (headerGuidance != null ? 72 : 40)
+      : showSettingsButton
+        ? insets.top + 8 + 44
+        : insets.top + 8;
+
   // ── JSX ─────────────────────────────────────────────────────────
 
   return (
@@ -1380,7 +1712,12 @@ 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}
+          // v0.13.2 — in multi-cam mode the lens is switched via zoom
+          // on a single mounted device (0.5× → ultra-wide end, 1× →
+          // wide baseline).  undefined in standalone/wide-only modes
+          // (lens = device identity, no zoom).
+          zoom={capture.deviceZoom}
           style={StyleSheet.absoluteFill}
           // F8 (FrameProcessor port) — host-supplied worklet runs on
           // the camera producer thread for every frame.  Only wired
@@ -1416,6 +1753,13 @@ export function Camera(props: CameraProps): React.JSX.Element {
         recordingStartedAt={recordingStartedAt ?? undefined}
       />
 
+      {/* v0.13.1 — the built-in pan-guidance overlays
+          (IncrementalPanGuide drift marker + PanoramaGuidance speed
+          pill) were removed from the public surface.  They remain in
+          the tree as internal-only components but <Camera> no longer
+          renders them and the `panGuide` / `panoramaGuidance` props
+          are gone.  Re-wire here if a host need resurfaces. */}
+
       {/*
         2026-05-22 (audit F9 + F3) — debug UI suite, all gated on
         settings.debug.  Mounts in <Camera> automatically; Layer-2
@@ -1459,12 +1803,34 @@ 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)}
+          />
+        )
       )}
 
       {/*
@@ -1500,18 +1866,52 @@ export function Camera(props: CameraProps): React.JSX.Element {
           />
         )}
 
+        {/* v0.13.0 — built-in capture-history thumbnail strip.  Lives
+            INSIDE the orientation-aware bottomArea container so it
+            rides along to the home-indicator edge in landscape rather
+            than sitting at a hard-coded `bottom: 160` mid-screen.
+            Hidden during recording so the PanoramaBandOverlay above
+            it has room without overlap.  Strip is intrinsically
+            horizontal; v0.13.1 will add orientation-aware rotation
+            for the thumbnails + tablet "user-bottom" placement. */}
+        {thumbnails != null && statusPhase !== 'recording' && (
+          <CaptureThumbnailStrip
+            items={thumbnails}
+            minPhotos={thumbnailsMin}
+            maxPhotos={thumbnailsMax}
+            onItemPress={onThumbnailPress}
+            // v0.13.1 — stack the idle strip vertically when the
+            // home-indicator anchor is on a side edge (non-locked host
+            // in landscape), matching PanoramaBandOverlay's `vertical`
+            // so the strip rides the home-indicator edge instead of
+            // running horizontally across the rotated screen.
+            vertical={isSideEdge(homeIndicatorEdge(jsLandscape, deviceOrientation))}
+            // v0.13.1 — counter-rotate the thumbnail images so the
+            // captured scene reads upright in portrait-locked landscape.
+            contentRotation={contentRotation}
+          />
+        )}
+
         {/* 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))}>
+        {/* v0.13.1 — flash + AR moved to the top-right pill stack (see
+            below).  Left/right slots stay as flex spacers so the shutter
+            + lens chip remain centred. */}
         <View style={styles.bottomBarLeft} />
         <View style={styles.bottomBarCenter}>
-          <LensChip
-            lens={lens}
-            onChange={handleLensChange}
-            has0_5x={has0_5x}
-          />
+          {/* v0.13.2 — lens chooser hidden in AR-only mode (ARKit/ARCore
+              can't use the ultra-wide, so there's nothing to choose). */}
+          {!arOnly && (
+            <LensChip
+              lens={lens}
+              onChange={handleLensChange}
+              has0_5x={has0_5x}
+              contentRotation={contentRotation}
+            />
+          )}
           <View style={styles.shutterWrap}>
             <CameraShutter
               onTap={handleTap}
@@ -1522,14 +1922,53 @@ export function Camera(props: CameraProps): React.JSX.Element {
             />
           </View>
         </View>
-        <View style={styles.bottomBarRight}>
-          {lens === '1x' && isARSupportedOnDevice && (
-            <ARToggle arEnabled={arPreference} onToggle={handleARToggle} />
-          )}
-        </View>
+        <View style={styles.bottomBarRight} />
         </View>
       </View>
 
+      {/* v0.13.1 — top-right control pill stack, anchored UNDER the
+          settings affordance.  Vertical column; pills match the AR
+          toggle's shape.  ORDER MATTERS: AR pill is FIRST (top) so it
+          stays anchored when the flash pill below it shows/hides
+          (flash is hidden in AR mode, and when the active device has no
+          torch — e.g. the ultra-wide 0.5× lens).  AR toggle shows only
+          when the lens is 1× (ARKit/ARCore don't expose the ultra-wide)
+          and the device supports AR. */}
+      <View
+        style={[styles.pillStack, { top: pillStackTop }]}
+        pointerEvents="box-none"
+      >
+        {/* v0.13.2 — AR toggle only when BOTH sources are allowed
+            (captureSources='both'); a single-source constraint has
+            nothing to toggle.  Still gated on 1× + device AR support. */}
+        {arAllowed && nonArAllowed && lens === '1x' && isARSupportedOnDevice && (
+          <ARToggle arEnabled={arPreference} onToggle={handleARToggle} contentRotation={contentRotation} />
+        )}
+        {showFlashButton && !isAR && deviceHasTorch && (
+          <Pressable
+            onPress={toggleFlash}
+            accessibilityRole="button"
+            accessibilityLabel={`Flash ${flashRequested === 'on' ? 'on' : 'off'}`}
+            accessibilityState={{ selected: flashRequested === 'on' }}
+            hitSlop={8}
+            style={[
+              pillStyles.pill,
+              flashRequested === 'on' && pillStyles.pillActive,
+            ]}
+          >
+            <Text
+              style={[
+                pillStyles.flashGlyph,
+                flashRequested === 'on' && pillStyles.glyphActive,
+                contentRotation,
+              ]}
+            >
+              ⚡
+            </Text>
+          </Pressable>
+        )}
+      </View>
+
       {/* Settings modal (rendered always, visible-gated). */}
       <PanoramaSettingsModal
         visible={settingsModalVisible}
@@ -1550,6 +1989,21 @@ export function Camera(props: CameraProps): React.JSX.Element {
         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>
   );
 }
@@ -1615,6 +2069,17 @@ function isSideEdge(edge: HomeIndicatorEdge): boolean {
   return edge === 'left' || edge === 'right';
 }
 
+// v0.13.1 — test-only exports of the pure orientation-decision
+// functions.  `homeIndicatorEdge` + `isSideEdge` together produce the
+// `vertical` flag that drives PanoramaBandOverlay and
+// CaptureThumbnailStrip layout, so they carry the orientation contract.
+// Unit-tested via these handles (the lib's jest config is pure-TS and
+// can't mount <Camera>; see jest.config.js).
+/** @internal test-only — see `homeIndicatorEdge`. */
+export const _homeIndicatorEdgeForTests = homeIndicatorEdge;
+/** @internal test-only — see `isSideEdge`. */
+export const _isSideEdgeForTests = isSideEdge;
+
 
 /**
  * v0.12.0 — bottom-controls outer container positioning.  Anchors
@@ -1731,6 +2196,8 @@ const styles = StyleSheet.create({
   },
   bottomBarLeft: {
     flex: 1,
+    alignItems: 'flex-start',
+    justifyContent: 'flex-end',
   },
   bottomBarCenter: {
     flex: 1,
@@ -1744,4 +2211,51 @@ const styles = StyleSheet.create({
   shutterWrap: {
     marginTop: 12,
   },
+  headerWrap: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+  },
+  // v0.13.1 — `thumbnailStripWrap` removed.  The strip now renders
+  // inside the orientation-aware bottomArea container (alongside
+  // PanoramaBandOverlay and the bottom bar) rather than as a
+  // position-absolute overlay at hard-coded `bottom: 160`.
+  //
+  // v0.13.1 — top-right control pill stack (flash + AR).  Absolute,
+  // pinned to the right edge under the settings affordance; `top` is
+  // set inline from `pillStackTop`.  Column so the pills stack
+  // vertically; gap keeps them from touching.
+  pillStack: {
+    position: 'absolute',
+    right: 14,
+    alignItems: 'flex-end',
+    gap: 10,
+  },
+});
+
+
+// v0.13.1 — shared pill style for the top-right control stack.  The
+// flash pill matches the AR toggle's shape (same padding / radius /
+// background) so the two read as a set.
+const pillStyles = StyleSheet.create({
+  pill: {
+    paddingHorizontal: 14,
+    paddingVertical: 8,
+    borderRadius: 16,
+    backgroundColor: 'rgba(0,0,0,0.45)',
+    minWidth: 56,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  pillActive: {
+    backgroundColor: '#ffd34d',
+  },
+  flashGlyph: {
+    color: '#ffffff',
+    fontSize: 18,
+  },
+  glyphActive: {
+    color: '#1a1a1a',
+  },
 });