react-native-image-stitcher 0.1.0

package/dist/camera/CameraShutter.d.ts

@@ -0,0 +1,80 @@
+/**
+ * CameraShutter — dual-mode shutter button for the SDK's panorama UX.
+ *
+ *     ┌──────────────────────────────────────────────────┐
+ *     │  TAP   → take a single photo (existing flow)      │
+ *     │  HOLD  → start recording video                    │
+ *     │  RELEASE → stop recording → return video file     │
+ *     └──────────────────────────────────────────────────┘
+ *
+ * The button is "pure" UI — it owns gesture detection + visual
+ * feedback (idle / pressing / recording / processing rings) but
+ * NOT the recording / stitching pipeline itself.  Host apps wire
+ * the resulting `onTap` / `onHoldComplete` callbacks to whatever
+ * `useCapture` / `useVideoCapture` instance they've configured.
+ *
+ * Why expose just the button (not the full surface)?
+ *   Different audit screens want different layouts (thumbnails,
+ *   quality badges, mode chips); pinning them all to one
+ *   "PanoramaCaptureSurface" would overfit one customer's UX.  The
+ *   button is the only piece every screen needs identical, so it
+ *   ships in the SDK.  The orchestration helpers ship as
+ *   `<PanoramaCaptureSurface>` next door — host apps that want full
+ *   plug-and-play use that; the rest stitch this button into their
+ *   own layout.
+ *
+ * Gesture detection
+ *   onPressIn fires immediately on touch down; we start a
+ *   ``HOLD_THRESHOLD_MS`` timer.  Two outcomes:
+ *
+ *     - onPressOut fires before the timer → it was a tap.
+ *     - timer fires before onPressOut → transition to recording
+ *       state, fire ``onHoldStart``.  When onPressOut eventually
+ *       fires we call ``onHoldComplete``.
+ *
+ *   We deliberately do NOT use react-native-gesture-handler — the
+ *   Pressable + setTimeout pattern stays in the SDK's existing dep
+ *   surface (RN core only).  Adds zero new peer deps for host apps.
+ */
+import React from 'react';
+import { type ViewStyle } from 'react-native';
+export interface CameraShutterProps {
+    /** Called when the user taps (press-and-release before the threshold). */
+    onTap: () => void;
+    /** Called when the press crosses the threshold and recording should start. */
+    onHoldStart: () => void;
+    /** Called on release while in the hold state — recording should stop. */
+    onHoldComplete: () => void;
+    /**
+     * Maximum hold duration in milliseconds.  When the timer fires
+     * we auto-fire `onHoldComplete` — same behaviour as the user
+     * releasing the button.  Default 8000 ms; keeps recording
+     * within the stitcher's adjacent-frame-overlap budget
+     * (16 frames × 2 fps = 8 s upper bound).  Pass 0 / undefined
+     * to disable the auto-stop.
+     *
+     * Pair with `<CaptureStatusOverlay countdownMs>` so the user
+     * sees how much hold time is left.
+     */
+    maxHoldMs?: number;
+    /**
+     * Optional state-driven visual override.  When the host has its own
+     * processing indicator (e.g. "Stitching... 70%") set this to true to
+     * paint the button in the disabled-while-processing visual.
+     */
+    isProcessing?: boolean;
+    /** Disable the whole button (e.g. while permissions are loading). */
+    disabled?: boolean;
+    /** Optional style applied to the outer touch target. */
+    style?: ViewStyle;
+}
+/**
+ * Imperative handle so a parent can force-release (e.g. on unmount
+ * during a long press).  Exposed via forwardRef.
+ */
+export interface CameraShutterHandle {
+    /** Cancel any in-flight hold without calling onHoldComplete. */
+    cancelHold: () => void;
+}
+export declare const CameraShutter: React.ForwardRefExoticComponent<CameraShutterProps & React.RefAttributes<CameraShutterHandle>>;
+//# sourceMappingURL=CameraShutter.d.ts.map

package/dist/camera/CameraShutter.js

@@ -0,0 +1,237 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CameraShutter — dual-mode shutter button for the SDK's panorama UX.
+ *
+ *     ┌──────────────────────────────────────────────────┐
+ *     │  TAP   → take a single photo (existing flow)      │
+ *     │  HOLD  → start recording video                    │
+ *     │  RELEASE → stop recording → return video file     │
+ *     └──────────────────────────────────────────────────┘
+ *
+ * The button is "pure" UI — it owns gesture detection + visual
+ * feedback (idle / pressing / recording / processing rings) but
+ * NOT the recording / stitching pipeline itself.  Host apps wire
+ * the resulting `onTap` / `onHoldComplete` callbacks to whatever
+ * `useCapture` / `useVideoCapture` instance they've configured.
+ *
+ * Why expose just the button (not the full surface)?
+ *   Different audit screens want different layouts (thumbnails,
+ *   quality badges, mode chips); pinning them all to one
+ *   "PanoramaCaptureSurface" would overfit one customer's UX.  The
+ *   button is the only piece every screen needs identical, so it
+ *   ships in the SDK.  The orchestration helpers ship as
+ *   `<PanoramaCaptureSurface>` next door — host apps that want full
+ *   plug-and-play use that; the rest stitch this button into their
+ *   own layout.
+ *
+ * Gesture detection
+ *   onPressIn fires immediately on touch down; we start a
+ *   ``HOLD_THRESHOLD_MS`` timer.  Two outcomes:
+ *
+ *     - onPressOut fires before the timer → it was a tap.
+ *     - timer fires before onPressOut → transition to recording
+ *       state, fire ``onHoldStart``.  When onPressOut eventually
+ *       fires we call ``onHoldComplete``.
+ *
+ *   We deliberately do NOT use react-native-gesture-handler — the
+ *   Pressable + setTimeout pattern stays in the SDK's existing dep
+ *   surface (RN core only).  Adds zero new peer deps for host apps.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CameraShutter = void 0;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+/// Time the user must hold before tap → hold mode flip.  250 ms is
+/// the iOS native "long press" default; matches user muscle memory
+/// for distinguishing "snap" from "stay".
+const HOLD_THRESHOLD_MS = 250;
+exports.CameraShutter = (0, react_1.forwardRef)(function CameraShutter({ onTap, onHoldStart, onHoldComplete, maxHoldMs, isProcessing = false, disabled = false, style, }, ref) {
+    // Phase machine.  We use a state value for re-render-driven
+    // visuals AND a ref so onPressOut can read the up-to-date phase
+    // without waiting on React's render cycle (otherwise the
+    // tap-vs-hold decision can race the timer).
+    const [phase, setPhase] = (0, react_1.useState)('idle');
+    const phaseRef = (0, react_1.useRef)('idle');
+    const holdTimerRef = (0, react_1.useRef)(null);
+    // Separate timer for the auto-stop (max hold).  Distinct from
+    // the tap-vs-hold detection timer so each can fire independently.
+    const maxHoldTimerRef = (0, react_1.useRef)(null);
+    const setPhaseBoth = (0, react_1.useCallback)((next) => {
+        phaseRef.current = next;
+        setPhase(next);
+    }, []);
+    const clearHoldTimer = (0, react_1.useCallback)(() => {
+        if (holdTimerRef.current !== null) {
+            clearTimeout(holdTimerRef.current);
+            holdTimerRef.current = null;
+        }
+    }, []);
+    const clearMaxHoldTimer = (0, react_1.useCallback)(() => {
+        if (maxHoldTimerRef.current !== null) {
+            clearTimeout(maxHoldTimerRef.current);
+            maxHoldTimerRef.current = null;
+        }
+    }, []);
+    const cancelHold = (0, react_1.useCallback)(() => {
+        clearHoldTimer();
+        clearMaxHoldTimer();
+        setPhaseBoth('idle');
+    }, [clearHoldTimer, clearMaxHoldTimer, setPhaseBoth]);
+    (0, react_1.useImperativeHandle)(ref, () => ({ cancelHold }), [cancelHold]);
+    // Belt-and-suspenders: clean both timers on unmount so a
+    // fast navigation away from the camera doesn't leave one
+    // firing into a stale closure.
+    (0, react_1.useEffect)(() => () => {
+        clearHoldTimer();
+        clearMaxHoldTimer();
+    }, [clearHoldTimer, clearMaxHoldTimer]);
+    const handlePressIn = (0, react_1.useCallback)(() => {
+        if (disabled || isProcessing)
+            return;
+        setPhaseBoth('pressing');
+        holdTimerRef.current = setTimeout(() => {
+            // Threshold elapsed → enter hold mode + notify.
+            if (phaseRef.current === 'pressing') {
+                setPhaseBoth('holding');
+                onHoldStart();
+                // Schedule the auto-stop if maxHoldMs is set.  Same
+                // outcome as the user releasing the button manually —
+                // fires onHoldComplete + drops back to idle.
+                if (maxHoldMs && maxHoldMs > 0) {
+                    maxHoldTimerRef.current = setTimeout(() => {
+                        // Auto-stop unconditionally after maxHoldMs.  Earlier
+                        // versions gated this on `phase === 'holding'`, which
+                        // skipped the fire when iOS' gesture recogniser had
+                        // already flipped the phase to 'idle' due to finger
+                        // drift from camera motion — leaving the engine running
+                        // for hundreds of frames after the user thought they
+                        // released.  An extra onHoldComplete call when nothing
+                        // is recording is a safe no-op (`!incremental.isRunning`
+                        // early-returns).
+                        if (phaseRef.current === 'holding')
+                            setPhaseBoth('idle');
+                        onHoldComplete();
+                    }, maxHoldMs);
+                }
+            }
+        }, HOLD_THRESHOLD_MS);
+    }, [disabled, isProcessing, onHoldStart, onHoldComplete, maxHoldMs, setPhaseBoth]);
+    const handlePressOut = (0, react_1.useCallback)(() => {
+        // CRITICAL: release ALWAYS stops the recording, regardless of
+        // disabled/isProcessing state.  The previous version returned
+        // early when `isProcessing === true`, silently swallowing the
+        // release.  When that happened mid-recording, `onHoldComplete`
+        // never fired, the engine kept ingesting AR frames forever
+        // (hundreds of frames stacked up before the user even noticed),
+        // and the final stitch ran on data the user never intended.
+        //
+        // The release event is the user's primary signal that they
+        // want this capture to end.  No internal state is allowed to
+        // block it.  `onHoldComplete` itself is idempotent (it
+        // early-returns when there's nothing running), so an extra
+        // call when the engine is already finishing is a safe no-op.
+        const wasHolding = phaseRef.current === 'holding';
+        clearHoldTimer();
+        clearMaxHoldTimer();
+        setPhaseBoth('idle');
+        if (wasHolding) {
+            onHoldComplete();
+        }
+        else if (!disabled && !isProcessing) {
+            // It was a tap (released before the threshold).  Suppress
+            // the tap when the camera is busy — taps trigger photos and
+            // we don't want to fire-and-forget into a busy pipeline.
+            onTap();
+        }
+    }, [disabled, isProcessing, onTap, onHoldComplete, clearHoldTimer, clearMaxHoldTimer, setPhaseBoth]);
+    // Visuals.  Three layered circles so the inner colour can swap
+    // without animating the outer ring (smoother on lower-end phones).
+    const innerStyle = isProcessing
+        ? styles.innerProcessing
+        : phase === 'holding'
+            ? styles.innerRecording
+            : phase === 'pressing'
+                ? styles.innerPressing
+                : styles.innerIdle;
+    return (react_1.default.createElement(react_native_1.Pressable, { accessibilityRole: "button", accessibilityLabel: phase === 'holding'
+            ? 'Recording — release to stitch panorama'
+            : 'Tap for photo, hold for panorama', accessibilityState: { disabled: disabled || isProcessing }, disabled: disabled || isProcessing, onPressIn: handlePressIn, onPressOut: handlePressOut, style: [styles.outer, disabled && styles.disabled, style] },
+        react_1.default.createElement(react_native_1.View, { style: styles.ring }),
+        react_1.default.createElement(react_native_1.View, { style: [styles.inner, innerStyle] })));
+});
+const styles = react_native_1.StyleSheet.create({
+    outer: {
+        width: 76,
+        height: 76,
+        alignItems: 'center',
+        justifyContent: 'center',
+    },
+    disabled: {
+        opacity: 0.4,
+    },
+    ring: {
+        position: 'absolute',
+        width: 76,
+        height: 76,
+        borderRadius: 38,
+        borderWidth: 4,
+        borderColor: '#ffffff',
+    },
+    inner: {
+        width: 60,
+        height: 60,
+        borderRadius: 30,
+    },
+    innerIdle: {
+        backgroundColor: '#ffffff',
+    },
+    innerPressing: {
+        // Subtle shrink-effect via colour shift; opacity dims confirm
+        // touch landed without committing to a mode yet.
+        backgroundColor: 'rgba(255,255,255,0.7)',
+    },
+    innerRecording: {
+        // Apple-native panorama / shutter recording uses red.
+        backgroundColor: '#FF3B30',
+    },
+    innerProcessing: {
+        // Greyed mid-tone with reduced contrast — clearly "busy, can't
+        // press me" without being alarming.
+        backgroundColor: '#9aa0a6',
+    },
+});
+//# sourceMappingURL=CameraShutter.js.map

package/dist/camera/CameraView.d.ts

@@ -0,0 +1,65 @@
+/**
+ * CameraView — the SDK's drop-in replacement for the raw
+ * vision-camera ``<Camera />``.
+ *
+ * Why wrap it?
+ *   1. **Default props** — always ``isActive={true}``, ``photo={true}``,
+ *      and honouring the hook's flash state.  Every call-site in the
+ *      mobile app repeated the same tuple; the SDK canonicalises it.
+ *   2. **Branded guidance overlay** — optional ``guidance`` prop renders
+ *      a themed banner over the preview without the host app having to
+ *      know about positioning / contrast.
+ *   3. **Forward ref** — so ``useCapture``'s ref attaches cleanly.
+ *
+ * The component is intentionally thin — anything more elaborate goes
+ * into a separate screen (e.g. AuditCaptureSurface that combines this
+ * view with thumbnails and a shutter button).  Keeping CameraView at
+ * the vision-camera layer means host apps that want a highly-custom
+ * UI can still use it as their building block.
+ */
+import React from 'react';
+import { type ViewStyle } from 'react-native';
+import { Camera, type CameraDevice, type CameraProps } from 'react-native-vision-camera';
+export interface CameraViewProps {
+    /** Output of ``useCapture().device``.  If null, a placeholder is shown. */
+    device: CameraDevice | null | undefined;
+    /** Flash / torch state from ``useCapture().flash``. */
+    flash?: 'off' | 'on';
+    /** Whether the preview is actively rendering.  Defaults to true. */
+    isActive?: boolean;
+    /**
+     * Enable video recording on the underlying camera.  Required for
+     * `useVideoCapture().startRecording()` — vision-camera throws
+     * `capture/video-not-enabled` if you call startRecording without
+     * this flag set.  Defaults to `false` so apps that only take photos
+     * don't pay the video-pipeline allocation cost.
+     *
+     * Photo capture remains enabled regardless of this flag, so a
+     * single `<CameraView video />` can do both tap (photo) and
+     * hold (video → stitch) flows.
+     */
+    video?: boolean;
+    /** Optional themed guidance banner.  Renders over the preview at the top. */
+    guidance?: string;
+    /** Extra style layer applied on top of the default full-screen layout. */
+    style?: ViewStyle;
+    /** Pass-through to vision-camera for anything custom. */
+    cameraProps?: Partial<CameraProps>;
+    /**
+     * Called when the user taps the preview.  Host apps may use this to
+     * drive focus-on-tap, AE/AF lock, etc.  Not wired into vision-camera's
+     * focus API by this component on purpose — host apps have different
+     * preferences (focus-on-tap vs. tap-to-lock).
+     */
+    onPreviewTap?: (event: {
+        x: number;
+        y: number;
+    }) => void;
+}
+/**
+ * A forwardRef'd wrapper that exposes the underlying Camera ref
+ * to callers (so ``cameraRef.current.takePhoto()`` keeps working),
+ * while presenting a smaller API on the outside.
+ */
+export declare const CameraView: React.ForwardRefExoticComponent<CameraViewProps & React.RefAttributes<Camera | null>>;
+//# sourceMappingURL=CameraView.d.ts.map

package/dist/camera/CameraView.js

@@ -0,0 +1,117 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CameraView — the SDK's drop-in replacement for the raw
+ * vision-camera ``<Camera />``.
+ *
+ * Why wrap it?
+ *   1. **Default props** — always ``isActive={true}``, ``photo={true}``,
+ *      and honouring the hook's flash state.  Every call-site in the
+ *      mobile app repeated the same tuple; the SDK canonicalises it.
+ *   2. **Branded guidance overlay** — optional ``guidance`` prop renders
+ *      a themed banner over the preview without the host app having to
+ *      know about positioning / contrast.
+ *   3. **Forward ref** — so ``useCapture``'s ref attaches cleanly.
+ *
+ * The component is intentionally thin — anything more elaborate goes
+ * into a separate screen (e.g. AuditCaptureSurface that combines this
+ * view with thumbnails and a shutter button).  Keeping CameraView at
+ * the vision-camera layer means host apps that want a highly-custom
+ * UI can still use it as their building block.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CameraView = void 0;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const react_native_vision_camera_1 = require("react-native-vision-camera");
+/**
+ * A forwardRef'd wrapper that exposes the underlying Camera ref
+ * to callers (so ``cameraRef.current.takePhoto()`` keeps working),
+ * while presenting a smaller API on the outside.
+ */
+exports.CameraView = (0, react_1.forwardRef)(function CameraView({ device, flash = 'off', isActive = true, video = false, guidance, style, cameraProps, }, ref) {
+    // Internal ref so we can both attach to <Camera> and forward outward.
+    const innerRef = (0, react_1.useRef)(null);
+    (0, react_1.useImperativeHandle)(ref, () => innerRef.current);
+    if (!device) {
+        return (react_1.default.createElement(react_native_1.View, { style: [styles.placeholder, style], accessibilityLabel: "Camera initialising" },
+            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, 
+            // 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
+            // tell viewers "rotate me" — but RN's <Image> on iOS often
+            // ignores EXIF, leading to thumbnails / previews appearing
+            // sideways even though the user shot in portrait.  Setting
+            // `outputOrientation="device"` rotates the pixels to match
+            // how the user is holding the phone, so the saved JPEG is
+            // "what you see is what was taken".
+            outputOrientation: "device", torch: flash === 'on' ? 'on' : 'off', ...cameraProps }),
+        guidance ? (react_1.default.createElement(react_native_1.View, { style: styles.guidance, pointerEvents: "none", accessible: true, accessibilityRole: "text" },
+            react_1.default.createElement(react_native_1.Text, { style: styles.guidanceText, numberOfLines: 2 }, guidance))) : null));
+});
+const styles = react_native_1.StyleSheet.create({
+    root: {
+        flex: 1,
+        overflow: 'hidden',
+    },
+    placeholder: {
+        flex: 1,
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: '#000',
+    },
+    placeholderText: {
+        color: '#ffffff',
+        fontSize: 14,
+    },
+    guidance: {
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0,
+        paddingHorizontal: 16,
+        paddingVertical: 10,
+        backgroundColor: 'rgba(0, 0, 0, 0.55)',
+    },
+    guidanceText: {
+        color: '#ffffff',
+        fontSize: 13,
+    },
+});
+//# sourceMappingURL=CameraView.js.map

package/dist/camera/CaptureControlsBar.d.ts

@@ -0,0 +1,87 @@
+/**
+ * CaptureControlsBar — bottom-of-screen controls for any capture
+ * surface.
+ *
+ *   ┌──────────────────────────────────────────────────────────┐
+ *   │  [⚡ flash]      [● shutter]      [ host slot ]            │
+ *   └──────────────────────────────────────────────────────────┘
+ *
+ * The SDK owns the flash button and the shutter button (which is
+ * `<CameraShutter>` under the hood, so tap-vs-hold gesture handling
+ * comes "for free" in any host that uses this).  The right-side
+ * action is a render-prop — host apps put a "Submit", "Done",
+ * "Save", "Next" button there as fits their flow.
+ *
+ * Why a slot for the right-side action?
+ *   The flash and shutter buttons are universally camera-shaped;
+ *   every host wants them with the same gesture, the same colors,
+ *   the same accessibility labels.  But the third action varies
+ *   wildly — submitting an audit, saving a single photo, advancing
+ *   a wizard step.  Slotting keeps the SDK from prescribing host
+ *   semantics.
+ */
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+export interface CaptureControlsBarProps {
+    /** Current flash mode — drives the flash icon's colour. */
+    flashMode: 'off' | 'on';
+    /** Called when the flash button is pressed. */
+    onToggleFlash: () => void;
+    /**
+     * 2026-05-16 — disable the flash button.  Pass `true` when the
+     * active camera surface doesn't honour torch state — currently the
+     * AR camera (ARKit / ARCore own AVCaptureDevice and don't expose
+     * torch control through the JS bridge; toggling would silently
+     * no-op).  Renders the button at reduced opacity + ignores presses.
+     */
+    flashDisabled?: boolean;
+    /** Tap → take photo. */
+    onShutterTap: () => void;
+    /** Hold crosses threshold → start video recording. */
+    onShutterHoldStart: () => void;
+    /** Release after hold → stop recording, stitch. */
+    onShutterHoldComplete: () => void;
+    /**
+     * Disable the shutter (e.g. at-max-photos for the audit, no
+     * camera permission, etc).  Flash and the right-side action
+     * remain interactive.
+     */
+    shutterDisabled?: boolean;
+    /**
+     * Show the shutter's "processing" visual.  Use this while a
+     * stitch is in progress so the operator can't kick off a second
+     * recording mid-stitch.
+     */
+    shutterProcessing?: boolean;
+    /**
+     * Forwards to <CameraShutter maxHoldMs>.  Auto-fires
+     * onShutterHoldComplete when the timer elapses, simulating the
+     * user releasing.  Pair with <CaptureStatusOverlay countdownMs>
+     * so the user sees how long they have left.
+     */
+    shutterMaxHoldMs?: number;
+    /**
+     * Render-prop slot for the host's right-side action.  Typically a
+     * Pressable wrapping a "Submit" / "Done" button, but anything is
+     * fair game.  Receives no arguments — wire your callbacks in the
+     * usual way.
+     *
+     * Pass `null` to render an empty spacer instead (keeps the shutter
+     * centred when there's no action to show).
+     */
+    rightAction?: React.ReactNode;
+    /** Override the default colours. */
+    colors?: {
+        background?: string;
+        iconButton?: string;
+        iconActive?: string;
+        icon?: string;
+        iconAccessible?: string;
+    };
+    /** Bottom inset for safe-area on devices with a home indicator. */
+    bottomInset?: number;
+    /** Outer style passthrough. */
+    style?: StyleProp<ViewStyle>;
+}
+export declare function CaptureControlsBar({ flashMode, onToggleFlash, flashDisabled, onShutterTap, onShutterHoldStart, onShutterHoldComplete, shutterDisabled, shutterProcessing, shutterMaxHoldMs, rightAction, colors, bottomInset, style, }: CaptureControlsBarProps): React.JSX.Element;
+//# sourceMappingURL=CaptureControlsBar.d.ts.map

package/dist/camera/CaptureControlsBar.js

@@ -0,0 +1,82 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CaptureControlsBar — bottom-of-screen controls for any capture
+ * surface.
+ *
+ *   ┌──────────────────────────────────────────────────────────┐
+ *   │  [⚡ flash]      [● shutter]      [ host slot ]            │
+ *   └──────────────────────────────────────────────────────────┘
+ *
+ * The SDK owns the flash button and the shutter button (which is
+ * `<CameraShutter>` under the hood, so tap-vs-hold gesture handling
+ * comes "for free" in any host that uses this).  The right-side
+ * action is a render-prop — host apps put a "Submit", "Done",
+ * "Save", "Next" button there as fits their flow.
+ *
+ * Why a slot for the right-side action?
+ *   The flash and shutter buttons are universally camera-shaped;
+ *   every host wants them with the same gesture, the same colors,
+ *   the same accessibility labels.  But the third action varies
+ *   wildly — submitting an audit, saving a single photo, advancing
+ *   a wizard step.  Slotting keeps the SDK from prescribing host
+ *   semantics.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CaptureControlsBar = CaptureControlsBar;
+const react_1 = __importDefault(require("react"));
+const react_native_1 = require("react-native");
+const CameraShutter_1 = require("./CameraShutter");
+function CaptureControlsBar({ flashMode, onToggleFlash, flashDisabled = false, onShutterTap, onShutterHoldStart, onShutterHoldComplete, shutterDisabled = false, shutterProcessing = false, shutterMaxHoldMs, rightAction = null, colors, bottomInset = 0, style, }) {
+    const bg = colors?.background ?? '#000000';
+    const iconButtonBg = colors?.iconButton ?? 'rgba(255,255,255,0.12)';
+    const iconActiveBg = colors?.iconActive ?? '#FF9F0A';
+    const iconColor = colors?.icon ?? '#ffffff';
+    return (react_1.default.createElement(react_native_1.View, { style: [
+            styles.bar,
+            { backgroundColor: bg, paddingBottom: bottomInset + 16 },
+            style,
+        ] },
+        react_1.default.createElement(react_native_1.Pressable, { onPress: flashDisabled ? undefined : onToggleFlash, accessibilityRole: "button", accessibilityLabel: flashDisabled
+                ? 'Flash unavailable in AR mode'
+                : `Flash ${flashMode === 'on' ? 'on' : 'off'}`, accessibilityState: {
+                selected: flashMode === 'on',
+                disabled: flashDisabled,
+            }, disabled: flashDisabled, style: [
+                styles.iconButton,
+                { backgroundColor: flashMode === 'on' ? iconActiveBg : iconButtonBg },
+                flashDisabled ? { opacity: 0.35 } : null,
+            ], hitSlop: 8 },
+            react_1.default.createElement(react_native_1.Text, { style: [styles.icon, { color: iconColor }] }, "\u26A1")),
+        react_1.default.createElement(CameraShutter_1.CameraShutter, { onTap: onShutterTap, onHoldStart: onShutterHoldStart, onHoldComplete: onShutterHoldComplete, maxHoldMs: shutterMaxHoldMs, disabled: shutterDisabled, isProcessing: shutterProcessing }),
+        react_1.default.createElement(react_native_1.View, { style: styles.rightSlot }, rightAction)));
+}
+const styles = react_native_1.StyleSheet.create({
+    bar: {
+        flexDirection: 'row',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        paddingHorizontal: 24,
+        paddingTop: 16,
+    },
+    iconButton: {
+        width: 48,
+        height: 48,
+        borderRadius: 24,
+        alignItems: 'center',
+        justifyContent: 'center',
+    },
+    icon: {
+        fontSize: 22,
+    },
+    rightSlot: {
+        width: 48,
+        height: 48,
+        alignItems: 'center',
+        justifyContent: 'center',
+    },
+});
+//# sourceMappingURL=CaptureControlsBar.js.map