react-native-image-stitcher 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -16,6 +16,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] — 2026-05-29
+
+### Added — Layer-2 components absorbed into `<Camera>` (opt-out)
+
+The flagship `<Camera>` now ships built-in defaults for every UX
+chrome piece previously exposed only as a Layer-2 component.  Hosts
+adopting `<Camera>` directly get a complete capture surface — flash
+button, pan-speed pill, drift-marker guide, header chrome,
+capture-history strip, and post-stitch preview — without having to
+import and wire each piece by hand.
+
+All built-ins use the opt-out pattern: enabled by default, disabled
+by setting the corresponding boolean to `false` or by omitting the
+corresponding payload prop.  Hosts that want their own chrome can
+opt out per piece and layer custom UI on top of `<Camera>` (the
+Layer-2 components remain exported and are unchanged).
+
+#### Flash control
+
+- `flash?: 'on' | 'off'` — controlled torch state.  Omit to let
+  `<Camera>` own it internally.
+- `onFlashChange?` — fires on tap (controlled and uncontrolled both).
+- `showFlashButton?: boolean` (default `true`) — built-in flash button
+  in the bottom-left slot.  AR mode auto-disables (ARKit / ARCore own
+  the device's torch; surfaces "Flash unavailable in AR mode" a11y
+  label and greyed styling).
+
+#### Pan guidance
+
+- `panGuide?: boolean` (default `true`) — built-in
+  `IncrementalPanGuide` ("keep the arrow on the line" drift marker).
+- `panoramaGuidance?: boolean` (default `true`) — built-in
+  `PanoramaGuidance` pan-speed pill.
+- Both are gyroscope-driven and only subscribe to the sensor while
+  recording — no idle cost.
+
+#### Header
+
+- `headerTitle?: string` — when set, renders a built-in
+  `CaptureHeader` at the top of the screen.  The existing settings
+  gear is absorbed into the header's right side (no duplicate gear).
+- `onHeaderBack?`, `headerBackLabel?`, `headerGuidance?`,
+  `headerColors?` — pass-through to `CaptureHeader`.
+
+#### Capture history + preview
+
+- `thumbnails?: CaptureThumbnailItem[]` — when supplied (even `[]`),
+  renders the built-in `CaptureThumbnailStrip` above the bottom
+  controls.  Hidden during recording so it doesn't overlap the
+  panorama band overlay.
+- `thumbnailsMin?`, `thumbnailsMax?` — count-line hints.
+- `onThumbnailPress?` — replaces the strip's built-in
+  tap-to-preview modal with a host handler.
+- `capturePreview?` — when set, renders a built-in `CapturePreview`
+  modal showing the supplied image.  Use for post-stitch
+  confirmation; the host clears the prop on dismiss via
+  `onCapturePreviewClose`.
+- `capturePreviewActions?` — pass-through action buttons for the
+  preview modal.
+
+### Migration
+
+- Hosts that were importing Layer-2 components (`CaptureHeader`,
+  `CaptureControlsBar`, `IncrementalPanGuide`, `PanoramaGuidance`,
+  `CaptureThumbnailStrip`, `CapturePreview`) directly can now drop
+  those imports and use the corresponding `<Camera>` props.
+- The Layer-2 components remain exported and unchanged in v0.13 for
+  backward compatibility.  Deprecation of those exports is targeted
+  for v0.14.
+- No behaviour change for hosts that already use `<Camera>` and
+  don't supply any of the new props — every new built-in defaults
+  to the previous (omitted) UX, except the flash button which
+  appears in the now-occupied bottom-left slot.  Hosts that previously
+  rendered chrome in that slot above `<Camera>` can pass
+  `showFlashButton={false}`.
+
 ## [0.12.0] — 2026-05-28
 
 ### Added — Orientation-aware `<Camera>` (R2-lite)

package/dist/camera/Camera.d.ts

@@ -41,6 +41,9 @@
 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';
 export type CaptureSource = 'ar' | 'non-ar';
 export type CameraLens = '1x' | '0.5x';
 export type StitchMode = 'auto' | 'panorama' | 'scans';
@@ -211,6 +214,174 @@ 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 — 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.
      *

package/dist/camera/Camera.js

@@ -83,13 +83,18 @@ 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");
 const CaptureKeyframePill_1 = require("./CaptureKeyframePill");
 const CaptureOrientationPill_1 = require("./CaptureOrientationPill");
 const CaptureStitchStatsToast_1 = require("./CaptureStitchStatsToast");
+const IncrementalPanGuide_1 = require("./IncrementalPanGuide");
 const PanoramaBandOverlay_1 = require("./PanoramaBandOverlay");
+const PanoramaGuidance_1 = require("./PanoramaGuidance");
 const PanoramaSettingsBridge_1 = require("./PanoramaSettingsBridge");
 const PanoramaSettingsModal_1 = require("./PanoramaSettingsModal");
 const buildPanoramaInitialSettings_1 = require("./buildPanoramaInitialSettings");
@@ -272,7 +277,7 @@ 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', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, 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 = (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
@@ -285,6 +290,12 @@ function Camera(props) {
     // ── State ───────────────────────────────────────────────────────
     const [arPreference, setArPreference] = (0, react_1.useState)(defaultCaptureSource === 'ar');
     const [lens, setLens] = (0, react_1.useState)(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');
@@ -867,6 +878,22 @@ 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 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 = controlledFlash ?? internalFlash;
+    const effectiveFlash = isAR ? 'off' : flashRequested;
+    const toggleFlash = (0, react_1.useCallback)(() => {
+        const next = flashRequested === 'on' ? 'off' : 'on';
+        if (controlledFlash == null)
+            setInternalFlash(next);
+        onFlashChange?.(next);
+    }, [flashRequested, controlledFlash, onFlashChange]);
     // ── 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 +905,7 @@ 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, 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
@@ -899,24 +926,37 @@ function Camera(props) {
                 onError?.(new CameraError('VISION_CAMERA_RUNTIME', `${codeStr}: ${msg}`, err));
             } })),
         react_1.default.createElement(CaptureStatusOverlay_1.CaptureStatusOverlay, { phase: statusPhase, topInset: insets.top, recordingStartedAt: recordingStartedAt ?? undefined }),
+        panGuide && (react_1.default.createElement(IncrementalPanGuide_1.IncrementalPanGuide, { active: statusPhase === 'recording' })),
+        panoramaGuidance && (react_1.default.createElement(PanoramaGuidance_1.PanoramaGuidance, { active: statusPhase === 'recording' })),
         settings.debug && (react_1.default.createElement(react_1.default.Fragment, null,
             react_1.default.createElement(CaptureOrientationPill_1.CaptureOrientationPill, { orientation: deviceOrientation, topInset: insets.top }),
             react_1.default.createElement(CaptureKeyframePill_1.CaptureKeyframePill, { state: incrementalState, topInset: insets.top }),
             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) }))),
+        thumbnails != null && statusPhase !== 'recording' && (react_1.default.createElement(react_native_1.View, { style: styles.thumbnailStripWrap, pointerEvents: "box-none" },
+            react_1.default.createElement(CaptureThumbnailStrip_1.CaptureThumbnailStrip, { items: thumbnails, minPhotos: thumbnailsMin, maxPhotos: thumbnailsMax, onItemPress: onThumbnailPress }))),
         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)) })),
             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.bottomBarLeft }, showFlashButton && (react_1.default.createElement(react_native_1.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,
+                    ] },
+                    react_1.default.createElement(react_native_1.Text, { style: styles.flashIcon }, "\u26A1")))),
                 react_1.default.createElement(react_native_1.View, { style: styles.bottomBarCenter },
                     react_1.default.createElement(LensChip, { lens: lens, onChange: handleLensChange, has0_5x: has0_5x }),
                     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(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 */
@@ -1045,6 +1085,8 @@ const styles = react_native_1.StyleSheet.create({
     },
     bottomBarLeft: {
         flex: 1,
+        alignItems: 'flex-start',
+        justifyContent: 'flex-end',
     },
     bottomBarCenter: {
         flex: 1,
@@ -1058,5 +1100,35 @@ const styles = react_native_1.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',
+    },
 });
 //# sourceMappingURL=Camera.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Pose-aware panorama capture + stitching for React Native. One <Camera> component, both tap-to-photo and hold-to-pan modes, both AR-backed and IMU-fallback capture paths.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/camera/Camera.tsx

@@ -67,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';
@@ -317,6 +325,191 @@ 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 — 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.
    *
@@ -681,6 +874,23 @@ export function Camera(props: CameraProps): React.JSX.Element {
     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;
@@ -700,6 +910,12 @@ export function Camera(props: CameraProps): React.JSX.Element {
     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),
@@ -1349,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 (
@@ -1380,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
@@ -1416,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
@@ -1459,12 +1705,52 @@ 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>
       )}
 
       {/*
@@ -1505,7 +1791,25 @@ export function Camera(props: CameraProps): React.JSX.Element {
             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} />
+        <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}
@@ -1550,6 +1854,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>
   );
 }
@@ -1731,6 +2050,8 @@ const styles = StyleSheet.create({
   },
   bottomBarLeft: {
     flex: 1,
+    alignItems: 'flex-start',
+    justifyContent: 'flex-end',
   },
   bottomBarCenter: {
     flex: 1,
@@ -1744,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',
+  },
 });