react-native-image-stitcher 0.12.0 → 0.14.0

package/dist/camera/Camera.d.ts

@@ -41,7 +41,22 @@
 import React from 'react';
 import { type StyleProp, type ViewStyle } from 'react-native';
 import type { DrawableFrameProcessor, ReadonlyFrameProcessor } from 'react-native-vision-camera';
+import { type CaptureHeaderProps } from './CaptureHeader';
+import { type CapturePreviewAction } from './CapturePreview';
+import { type CaptureThumbnailItem } from './CaptureThumbnailStrip';
+import { type DeviceOrientation } from './useDeviceOrientation';
 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';
@@ -139,6 +154,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>;
     /**
      * Which incremental stitcher engine to drive.  Default
@@ -211,6 +239,158 @@ export interface CameraProps {
      * 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 — 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.
      *
@@ -305,4 +485,50 @@ export interface CameraProps {
  * The public `<Camera>` component.
  */
 export declare function Camera(props: CameraProps): React.JSX.Element;
+/**
+ * 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';
+declare function homeIndicatorEdge(jsLandscape: boolean, deviceOrient: DeviceOrientation): HomeIndicatorEdge;
+/**
+ * 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.
+ */
+declare function isSideEdge(edge: HomeIndicatorEdge): boolean;
+/** @internal test-only — see `homeIndicatorEdge`. */
+export declare const _homeIndicatorEdgeForTests: typeof homeIndicatorEdge;
+/** @internal test-only — see `isSideEdge`. */
+export declare const _isSideEdgeForTests: typeof isSideEdge;
+export {};
 //# sourceMappingURL=Camera.d.ts.map

package/dist/camera/Camera.js

@@ -74,7 +74,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CameraError = void 0;
+exports._isSideEdgeForTests = exports._homeIndicatorEdgeForTests = exports.CameraError = void 0;
 exports.Camera = Camera;
 const react_1 = __importStar(require("react"));
 const react_native_1 = require("react-native");
@@ -83,6 +83,9 @@ const useARSession_1 = require("../ar/useARSession");
 const ARCameraView_1 = require("./ARCameraView");
 const CameraShutter_1 = require("./CameraShutter");
 const CameraView_1 = require("./CameraView");
+const CaptureHeader_1 = require("./CaptureHeader");
+const CapturePreview_1 = require("./CapturePreview");
+const CaptureThumbnailStrip_1 = require("./CaptureThumbnailStrip");
 const CaptureStatusOverlay_1 = require("./CaptureStatusOverlay");
 const CaptureDebugOverlay_1 = require("./CaptureDebugOverlay");
 const CaptureMemoryPill_1 = require("./CaptureMemoryPill");
@@ -96,6 +99,7 @@ const buildPanoramaInitialSettings_1 = require("./buildPanoramaInitialSettings")
 const lowMemDevice_1 = require("./lowMemDevice");
 const useCapture_1 = require("./useCapture");
 const useDeviceOrientation_1 = require("./useDeviceOrientation");
+const useContentRotation_1 = require("./useContentRotation");
 const useOrientationDrift_1 = require("./useOrientationDrift");
 const OrientationDriftModal_1 = require("./OrientationDriftModal");
 const incremental_1 = require("../stitching/incremental");
@@ -113,10 +117,10 @@ class CameraError extends Error {
     }
 }
 exports.CameraError = CameraError;
-function LensChip({ lens, onChange, has0_5x }) {
+function LensChip({ lens, onChange, has0_5x, contentRotation }) {
     if (!has0_5x) {
         return (react_1.default.createElement(react_native_1.View, { style: [lensChipStyles.container, lensChipStyles.singleLens] },
-            react_1.default.createElement(react_native_1.Text, { style: lensChipStyles.label }, "1\u00D7")));
+            react_1.default.createElement(react_native_1.Text, { style: [lensChipStyles.label, contentRotation] }, "1\u00D7")));
     }
     return (react_1.default.createElement(react_native_1.View, { style: lensChipStyles.container },
         react_1.default.createElement(react_native_1.Pressable, { onPress: () => onChange('0.5x'), accessibilityRole: "button", accessibilityLabel: "0.5x ultra-wide lens", accessibilityState: { selected: lens === '0.5x' }, style: [
@@ -126,6 +130,7 @@ function LensChip({ lens, onChange, has0_5x }) {
             react_1.default.createElement(react_native_1.Text, { style: [
                     lensChipStyles.label,
                     lens === '0.5x' && lensChipStyles.labelActive,
+                    contentRotation,
                 ] }, "0.5\u00D7")),
         react_1.default.createElement(react_native_1.Pressable, { onPress: () => onChange('1x'), accessibilityRole: "button", accessibilityLabel: "1x wide-angle lens", accessibilityState: { selected: lens === '1x' }, style: [
                 lensChipStyles.pill,
@@ -134,6 +139,7 @@ function LensChip({ lens, onChange, has0_5x }) {
             react_1.default.createElement(react_native_1.Text, { style: [
                     lensChipStyles.label,
                     lens === '1x' && lensChipStyles.labelActive,
+                    contentRotation,
                 ] }, "1\u00D7"))));
 }
 const lensChipStyles = react_native_1.StyleSheet.create({
@@ -166,11 +172,12 @@ const lensChipStyles = react_native_1.StyleSheet.create({
         color: '#1a1a1a',
     },
 });
-function ARToggle({ arEnabled, onToggle }) {
+function ARToggle({ arEnabled, onToggle, contentRotation }) {
     return (react_1.default.createElement(react_native_1.Pressable, { onPress: onToggle, accessibilityRole: "switch", accessibilityLabel: `AR mode ${arEnabled ? 'on' : 'off'}`, accessibilityState: { checked: arEnabled }, style: [arToggleStyles.container, arEnabled && arToggleStyles.containerOn] },
         react_1.default.createElement(react_native_1.Text, { style: [
                 arToggleStyles.label,
                 arEnabled && arToggleStyles.labelOn,
+                contentRotation,
             ] }, "AR")));
 }
 const arToggleStyles = react_native_1.StyleSheet.create({
@@ -272,7 +279,14 @@ function extractPanoramaOverrides(props) {
  * The public `<Camera>` component.
  */
 function Camera(props) {
-    const { defaultCaptureSource = 'ar', defaultLens = '1x', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, onLensChange, onFramesDropped, onError, onCaptureAbandoned, frameProcessor: hostFrameProcessor, engine = 'batch-keyframe', } = props;
+    const { defaultCaptureSource = 'ar', defaultLens = '1x', captureSources = 'both', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, onLensChange, 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 = (0, react_native_safe_area_context_1.useSafeAreaInsets)();
     // v0.12.0 — JS-layout orientation independent of device-physical.
     // `useWindowDimensions().width > height` tells us if the OS
@@ -283,8 +297,19 @@ function Camera(props) {
     const jsWindow = (0, react_native_1.useWindowDimensions)();
     const jsLandscape = jsWindow.width > jsWindow.height;
     // ── State ───────────────────────────────────────────────────────
-    const [arPreference, setArPreference] = (0, react_1.useState)(defaultCaptureSource === 'ar');
-    const [lens, setLens] = (0, react_1.useState)(defaultLens);
+    // 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] = (0, react_1.useState)(!arAllowed ? false : !nonArAllowed ? true : defaultCaptureSource === 'ar');
+    // 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] = (0, react_1.useState)(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] = (0, react_1.useState)('off');
     const [settings, setSettings] = (0, react_1.useState)(() => (0, buildPanoramaInitialSettings_1.buildPanoramaInitialSettings)(extractPanoramaOverrides(props), (0, lowMemDevice_1.isLowMemDevice)()));
     const [settingsModalVisible, setSettingsModalVisible] = (0, react_1.useState)(false);
     const [statusPhase, setStatusPhase] = (0, react_1.useState)('idle');
@@ -308,6 +333,14 @@ function Camera(props) {
     const isAR = effectiveCaptureSource === 'ar';
     const isNonAR = !isAR;
     const deviceOrientation = (0, useDeviceOrientation_1.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 = (0, useContentRotation_1.useContentRotation)();
     // ── Camera handoff gate ─────────────────────────────────────────
     //
     // The placeholder rendered while the underlying camera identity
@@ -336,6 +369,33 @@ function Camera(props) {
     const inFlightTransition = settledIsARRef.current !== isAR
         || settledLensRef.current !== lens
         || 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).
+    (0, react_1.useEffect)(() => {
+        if (react_native_1.Platform.OS !== 'android')
+            return undefined;
+        const arModule = react_native_1.NativeModules
+            .RNSARSession;
+        arModule?.lockPortrait?.();
+        return () => {
+            arModule?.unlockOrientation?.();
+        };
+    }, []);
     // ── Notify parent of capture-source changes ─────────────────────
     const lastEmittedSourceRef = (0, react_1.useRef)(null);
     (0, react_1.useEffect)(() => {
@@ -344,19 +404,22 @@ function Camera(props) {
             onCaptureSourceChange?.(effectiveCaptureSource);
         }
     }, [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 = (0, useCapture_1.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 = (0, useIncrementalStitcher_1.useIncrementalStitcher)();
     const visionCameraRef = (0, react_1.useRef)(null);
     const arViewRef = (0, react_1.useRef)(null);
@@ -867,6 +930,44 @@ function Camera(props) {
     const handleARToggle = (0, react_1.useCallback)(() => {
         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 = controlledFlash ?? internalFlash;
+    const effectiveFlash = isAR || !deviceHasTorch ? 'off' : flashRequested;
+    const toggleFlash = (0, react_1.useCallback)(() => {
+        const next = 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 (react_1.default.createElement(react_native_1.View, { style: [styles.container, style] },
         inFlightTransition ? (react_1.default.createElement(react_native_1.View, { style: [react_native_1.StyleSheet.absoluteFill, styles.transitionPlaceholder] },
@@ -878,7 +979,12 @@ function Camera(props) {
             // the very first buffered preview frame.  Android takeSnapshot
             // works either way.  Pattern matches AuditCaptureScreen.tsx
             // which has run on `video` (true) for months without issue.
-            video: true, flash: "off", style: react_native_1.StyleSheet.absoluteFill, 
+            video: true, 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: react_native_1.StyleSheet.absoluteFill, 
             // F8 (FrameProcessor port) — host-supplied worklet runs on
             // the camera producer thread for every frame.  Only wired
             // in non-AR mode; AR mode uses ARCameraView which doesn't
@@ -905,18 +1011,43 @@ function Camera(props) {
             react_1.default.createElement(CaptureMemoryPill_1.CaptureMemoryPill, { topInset: insets.top }),
             react_1.default.createElement(CaptureDebugOverlay_1.CaptureDebugOverlay, { incrementalState: incrementalState, imuTranslationMetres: isNonAR ? imuGate.getTranslationMetres() : null, captureSource: effectiveCaptureSource, frameSelectionMode: settings.frameSelection.mode, stitchMode: settings.stitcher.stitchMode }))),
         react_1.default.createElement(CaptureStitchStatsToast_1.CaptureStitchStatsToast, { message: stitchToast.message, topInset: insets.top }),
-        showSettingsButton && (react_1.default.createElement(SettingsButton, { topInset: insets.top, onPress: () => setSettingsModalVisible(true) })),
+        headerTitle != null ? (react_1.default.createElement(react_native_1.View, { style: styles.headerWrap, pointerEvents: "box-none" },
+            react_1.default.createElement(CaptureHeader_1.CaptureHeader, { title: headerTitle, onBack: onHeaderBack, backLabel: headerBackLabel, guidance: headerGuidance, colors: headerColors, topInset: insets.top, onSettingsPress: showSettingsButton
+                    ? () => setSettingsModalVisible(true)
+                    : undefined }))) : (showSettingsButton && (react_1.default.createElement(SettingsButton, { topInset: insets.top, onPress: () => setSettingsModalVisible(true) }))),
         react_1.default.createElement(react_native_1.View, { pointerEvents: "box-none", style: bottomAreaStyleForEdge(homeIndicatorEdge(jsLandscape, deviceOrientation), insets.bottom + 12, insets.top + 12) },
             statusPhase === 'recording' && (react_1.default.createElement(PanoramaBandOverlay_1.PanoramaBandOverlay, { state: incrementalState, frameUris: batchKeyframeThumbnails, captureOrientation: deviceOrientation, vertical: isSideEdge(homeIndicatorEdge(jsLandscape, deviceOrientation)) })),
+            thumbnails != null && statusPhase !== 'recording' && (react_1.default.createElement(CaptureThumbnailStrip_1.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 })),
             react_1.default.createElement(react_native_1.View, { style: bottomBarStyleForEdge(homeIndicatorEdge(jsLandscape, deviceOrientation)) },
                 react_1.default.createElement(react_native_1.View, { style: styles.bottomBarLeft }),
                 react_1.default.createElement(react_native_1.View, { style: styles.bottomBarCenter },
-                    react_1.default.createElement(LensChip, { lens: lens, onChange: handleLensChange, has0_5x: has0_5x }),
+                    !arOnly && (react_1.default.createElement(LensChip, { lens: lens, onChange: handleLensChange, has0_5x: has0_5x, contentRotation: contentRotation })),
                     react_1.default.createElement(react_native_1.View, { style: styles.shutterWrap },
                         react_1.default.createElement(CameraShutter_1.CameraShutter, { onTap: handleTap, onHoldStart: enablePanoramaMode ? handleHoldStart : noop, onHoldComplete: enablePanoramaMode ? handleHoldEnd : noop, isProcessing: statusPhase === 'stitching', disabled: statusPhase === 'stitching' }))),
-                react_1.default.createElement(react_native_1.View, { style: styles.bottomBarRight }, lens === '1x' && isARSupportedOnDevice && (react_1.default.createElement(ARToggle, { arEnabled: arPreference, onToggle: handleARToggle }))))),
+                react_1.default.createElement(react_native_1.View, { style: styles.bottomBarRight }))),
+        react_1.default.createElement(react_native_1.View, { style: [styles.pillStack, { top: pillStackTop }], pointerEvents: "box-none" },
+            arAllowed && nonArAllowed && lens === '1x' && isARSupportedOnDevice && (react_1.default.createElement(ARToggle, { arEnabled: arPreference, onToggle: handleARToggle, contentRotation: contentRotation })),
+            showFlashButton && !isAR && deviceHasTorch && (react_1.default.createElement(react_native_1.Pressable, { onPress: toggleFlash, accessibilityRole: "button", accessibilityLabel: `Flash ${flashRequested === 'on' ? 'on' : 'off'}`, accessibilityState: { selected: flashRequested === 'on' }, hitSlop: 8, style: [
+                    pillStyles.pill,
+                    flashRequested === 'on' && pillStyles.pillActive,
+                ] },
+                react_1.default.createElement(react_native_1.Text, { style: [
+                        pillStyles.flashGlyph,
+                        flashRequested === 'on' && pillStyles.glyphActive,
+                        contentRotation,
+                    ] }, "\u26A1")))),
         react_1.default.createElement(PanoramaSettingsModal_1.PanoramaSettingsModal, { visible: settingsModalVisible, settings: settings, onChange: setSettings, onClose: () => setSettingsModalVisible(false) }),
-        react_1.default.createElement(OrientationDriftModal_1.OrientationDriftModal, { visible: drift.drifted && !driftModalDismissed, captureOrientation: drift.captureOrientation, currentOrientation: drift.currentOrientation, onAcknowledge: () => setDriftModalDismissed(true) })));
+        react_1.default.createElement(OrientationDriftModal_1.OrientationDriftModal, { visible: drift.drifted && !driftModalDismissed, captureOrientation: drift.captureOrientation, currentOrientation: drift.currentOrientation, onAcknowledge: () => setDriftModalDismissed(true) }),
+        react_1.default.createElement(CapturePreview_1.CapturePreview, { visible: capturePreview != null, imageUri: capturePreview?.imageUri ?? '', imageWidth: capturePreview?.imageWidth, imageHeight: capturePreview?.imageHeight, title: capturePreview?.title, actions: capturePreviewActions, onClose: onCapturePreviewClose ?? noop })));
 }
 function noop() {
     /* no-op handler used when panorama mode is disabled */
@@ -938,6 +1069,16 @@ function homeIndicatorEdge(jsLandscape, deviceOrient) {
 function isSideEdge(edge) {
     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`. */
+exports._homeIndicatorEdgeForTests = homeIndicatorEdge;
+/** @internal test-only — see `isSideEdge`. */
+exports._isSideEdgeForTests = isSideEdge;
 /**
  * v0.12.0 — bottom-controls outer container positioning.  Anchors
  * to the home-indicator JS edge with the appropriate flex direction
@@ -1045,6 +1186,8 @@ const styles = react_native_1.StyleSheet.create({
     },
     bottomBarLeft: {
         flex: 1,
+        alignItems: 'flex-start',
+        justifyContent: 'flex-end',
     },
     bottomBarCenter: {
         flex: 1,
@@ -1058,5 +1201,50 @@ const styles = react_native_1.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 = react_native_1.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',
+    },
 });
 //# sourceMappingURL=Camera.js.map

package/dist/camera/CameraView.d.ts

@@ -25,6 +25,12 @@ export interface CameraViewProps {
     device: CameraDevice | null | undefined;
     /** Flash / torch state from ``useCapture().flash``. */
     flash?: 'off' | 'on';
+    /**
+     * v0.13.2 — zoom factor for the mounted device.  Used in multi-cam
+     * mode to switch lenses (0.5× ultra-wide ↔ 1× wide) on a single
+     * device.  `undefined` leaves vision-camera at its default zoom.
+     */
+    zoom?: number;
     /** Whether the preview is actively rendering.  Defaults to true. */
     isActive?: boolean;
     /**

package/dist/camera/CameraView.js

@@ -73,7 +73,7 @@ const VC_LIFECYCLE_ERROR_CODES = new Set([
     'system/camera-has-been-disconnected', // another app grabbed the camera
     'device/camera-already-in-use', // same class as above
 ]);
-exports.CameraView = (0, react_1.forwardRef)(function CameraView({ device, flash = 'off', isActive = true, video = false, guidance, style, cameraProps, onError, }, ref) {
+exports.CameraView = (0, react_1.forwardRef)(function CameraView({ device, flash = 'off', zoom, isActive = true, video = false, guidance, style, cameraProps, onError, }, ref) {
     // Error filter — see `VC_LIFECYCLE_ERROR_CODES` for the swallow
     // list rationale.  `code` on vision-camera's `CameraRuntimeError`
     // is typed as a string; treat any non-string defensively as a
@@ -97,7 +97,7 @@ exports.CameraView = (0, react_1.forwardRef)(function CameraView({ device, flash
             react_1.default.createElement(react_native_1.Text, { style: styles.placeholderText }, "Initialising camera\u2026")));
     }
     return (react_1.default.createElement(react_native_1.View, { style: [styles.root, style] },
-        react_1.default.createElement(react_native_vision_camera_1.Camera, { ref: innerRef, style: react_native_1.StyleSheet.absoluteFill, device: device, isActive: isActive, photo: true, video: video, 
+        react_1.default.createElement(react_native_vision_camera_1.Camera, { ref: innerRef, style: react_native_1.StyleSheet.absoluteFill, device: device, isActive: isActive, photo: true, video: video, ...(zoom != null ? { zoom } : {}), 
             // Bake the device orientation into the captured pixels.
             // Without this, vision-camera writes the file in the camera
             // sensor's native landscape and relies on EXIF metadata to