react-native-image-stitcher 0.1.0

package/dist/camera/ViewportCropOverlay.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ViewportCropOverlay — V12.12.
+ *
+ * Translucent dim bars on the camera preview's PAN-AXIS edges
+ * showing where the panorama engine's source-crop is.  Earlier
+ * versions (V12.11 Step B) put the bars on JS-top/bottom because
+ * the engine clipped the long sensor axis (perpendicular to pan
+ * in landscape, along pan in portrait) — that produced visible
+ * bars on the user-LEFT/RIGHT in landscape, which is the WRONG
+ * place: those edges aren't what the engine clips.
+ *
+ * V12.12: engine now clips ALONG the pan axis.  In sensor-native
+ * coords:
+ *   • landscape capture (vertical pan): clip = sensor Y (rows).
+ *     User perceives this as TOP and BOTTOM of their landscape view.
+ *   • portrait capture (horizontal pan): clip = sensor X (cols).
+ *     User perceives this as LEFT and RIGHT of their portrait view.
+ *
+ * In JS coords (the host app is portrait-locked):
+ *   • portrait device: user-left/right == JS-left/right.  Bars on
+ *                       JS-left/right.
+ *   • landscape device: user-top/bottom == JS-left/right (because
+ *                       the user's vertical maps to JS-horizontal
+ *                       under portrait-lock).  Bars on JS-left/right.
+ *
+ * So in BOTH device orientations the bars sit at JS-left and JS-right.
+ * **No orientation detection needed in this component.**  The
+ * engine has already arranged for the clip to manifest at the same
+ * JS edges regardless of physical device orientation.
+ *
+ * Bar width = `(1 - panFraction) / 2` of the JS-horizontal extent.
+ * For the default `kPanAxisFractionRect = 0.70` engine constant,
+ * each bar is 15 % wide — visibly substantial, matching what the
+ * engine clips out per frame.
+ */
+import React from 'react';
+export interface ViewportCropOverlayProps {
+    /**
+     * Fraction of the PAN axis the engine keeps per frame, in (0, 1].
+     * E.g. 0.70 for the V12.12 rectilinear engine's
+     * `kPanAxisFractionRect`.  Values ≥ 1 hide the overlay (no clip).
+     */
+    panFraction: number;
+}
+export declare function ViewportCropOverlay({ panFraction, }: ViewportCropOverlayProps): React.JSX.Element | null;
+//# sourceMappingURL=ViewportCropOverlay.d.ts.map

package/dist/camera/ViewportCropOverlay.js

@@ -0,0 +1,67 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * ViewportCropOverlay — V12.12.
+ *
+ * Translucent dim bars on the camera preview's PAN-AXIS edges
+ * showing where the panorama engine's source-crop is.  Earlier
+ * versions (V12.11 Step B) put the bars on JS-top/bottom because
+ * the engine clipped the long sensor axis (perpendicular to pan
+ * in landscape, along pan in portrait) — that produced visible
+ * bars on the user-LEFT/RIGHT in landscape, which is the WRONG
+ * place: those edges aren't what the engine clips.
+ *
+ * V12.12: engine now clips ALONG the pan axis.  In sensor-native
+ * coords:
+ *   • landscape capture (vertical pan): clip = sensor Y (rows).
+ *     User perceives this as TOP and BOTTOM of their landscape view.
+ *   • portrait capture (horizontal pan): clip = sensor X (cols).
+ *     User perceives this as LEFT and RIGHT of their portrait view.
+ *
+ * In JS coords (the host app is portrait-locked):
+ *   • portrait device: user-left/right == JS-left/right.  Bars on
+ *                       JS-left/right.
+ *   • landscape device: user-top/bottom == JS-left/right (because
+ *                       the user's vertical maps to JS-horizontal
+ *                       under portrait-lock).  Bars on JS-left/right.
+ *
+ * So in BOTH device orientations the bars sit at JS-left and JS-right.
+ * **No orientation detection needed in this component.**  The
+ * engine has already arranged for the clip to manifest at the same
+ * JS edges regardless of physical device orientation.
+ *
+ * Bar width = `(1 - panFraction) / 2` of the JS-horizontal extent.
+ * For the default `kPanAxisFractionRect = 0.70` engine constant,
+ * each bar is 15 % wide — visibly substantial, matching what the
+ * engine clips out per frame.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViewportCropOverlay = ViewportCropOverlay;
+const react_1 = __importDefault(require("react"));
+const react_native_1 = require("react-native");
+function ViewportCropOverlay({ panFraction, }) {
+    if (panFraction >= 1)
+        return null;
+    // (1 - panFraction) / 2 of the JS-horizontal extent on each side.
+    const barPercent = `${((1 - panFraction) / 2) * 100}%`;
+    return (react_1.default.createElement(react_native_1.View, { pointerEvents: "none", style: styles.root },
+        react_1.default.createElement(react_native_1.View, { style: [styles.bar, { left: 0, top: 0, bottom: 0, width: barPercent }] }),
+        react_1.default.createElement(react_native_1.View, { style: [styles.bar, { right: 0, top: 0, bottom: 0, width: barPercent }] })));
+}
+const styles = react_native_1.StyleSheet.create({
+    root: {
+        ...react_native_1.StyleSheet.absoluteFillObject,
+    },
+    // Dim bars: translucent black overlay so the underlying camera
+    // preview is still visible (the user gets spatial context for
+    // what's about to leave the frame), but darkened enough to read
+    // as "this is OUTSIDE the capture region."
+    bar: {
+        position: 'absolute',
+        backgroundColor: 'rgba(0, 0, 0, 0.55)',
+    },
+});
+//# sourceMappingURL=ViewportCropOverlay.js.map

package/dist/camera/useCapture.d.ts

@@ -0,0 +1,111 @@
+/**
+ * useCapture — React hook that encapsulates the camera capture state
+ * machine so host apps get a drop-in replacement for the ad-hoc
+ * vision-camera wiring they used to have inline on each screen.
+ *
+ * Responsibilities:
+ *   - Holds the Camera ref for ``takePhoto``.
+ *   - Tracks the device permission state and exposes a request helper.
+ *   - Manages torch / flash state + a toggle helper.
+ *   - Wraps takePhoto with a single-flight guard so a double-tap on
+ *     the shutter button doesn't spawn two captures in parallel.
+ *   - Runs an optional JS-side quality check on the captured image
+ *     before resolving; the host app sees the QualityReport on the
+ *     returned CaptureResult.
+ *
+ * Non-goals:
+ *   - This hook does NOT persist captures.  Host apps hand the
+ *     returned CaptureResult to their own storage layer (WatermelonDB
+ *     insert, Redux dispatch, whatever).
+ *   - Video recording lives in useVideoCapture (TODO).
+ *
+ * The public API is designed to be minimal and replaceable: host apps
+ * that prefer the raw vision-camera API can opt out of this hook and
+ * still use the SDK's quality + stitching modules.
+ */
+import { Camera, useCameraDevice, type PhysicalCameraDeviceType, type TakePhotoOptions } from 'react-native-vision-camera';
+import type { CaptureResult, QualityThresholds } from '../types';
+/**
+ * Hook input.  Everything optional; sensible defaults are applied
+ * so simple call-sites can write ``useCapture()`` and get a usable
+ * back-camera pipeline with ``flash=off`` and no quality checking.
+ */
+export interface UseCaptureOptions {
+    /** 'back' | 'front' — defaults to 'back' (shelf photos). */
+    cameraPosition?: 'back' | 'front';
+    /** Quality check toggle + thresholds. */
+    enableQualityChecks?: boolean;
+    qualityThresholds?: QualityThresholds;
+    /**
+     * Extra TakePhotoOptions to pass through to vision-camera.
+     * The SDK merges these with its defaults; host-supplied values win.
+     */
+    takePhotoOptions?: TakePhotoOptions;
+    /**
+     * 2026-05-14 — preferred physical-lens type for the chosen
+     * `cameraPosition`.  Maps to vision-camera's `physicalDevices`
+     * filter on `useCameraDevice`.
+     *
+     *   undefined (default) — use vision-camera's selection algorithm,
+     *                         which picks the device that combines
+     *                         the most lenses (typically the "main"
+     *                         multi-lens virtual camera).  Existing
+     *                         behaviour; backwards-compatible.
+     *   'wide-angle-camera' — 1× physical lens (the standard rear
+     *                         camera most users think of as "the
+     *                         camera").
+     *   'ultra-wide-angle-camera' — 0.5× ultra-wide lens (only on
+     *                         devices with one; Samsung A35 has one;
+     *                         iPhone 11 Pro and later have one).
+     *   'telephoto-camera'  — 2× / 3× telephoto if the device has
+     *                         one.  Rare on field-rep deployments;
+     *                         exposed for symmetry.
+     *
+     * When the preferred type isn't available on the device, the
+     * hook falls back to vision-camera's default selection (i.e.,
+     * behaves as if `preferredPhysicalDevice` was undefined).  The
+     * returned `availablePhysicalDevices` exposes what the device
+     * actually offers so the host can render an appropriate switcher.
+     */
+    preferredPhysicalDevice?: PhysicalCameraDeviceType;
+}
+/**
+ * Hook output.  Intentionally flat so destructuring a subset is
+ * cheap and the API doesn't force callers to drill into nested
+ * objects for common concerns.
+ */
+export interface UseCaptureReturn {
+    /** Pass to <CameraView ref={ref} /> (or the raw Camera directly). */
+    cameraRef: React.RefObject<Camera | null>;
+    /** The currently selected device — null while vision-camera hasn't picked one. */
+    device: ReturnType<typeof useCameraDevice>;
+    /** True once the user has granted camera permission. */
+    hasPermission: boolean;
+    /** Trigger the system permission sheet.  Resolves to the new state. */
+    requestPermission: () => Promise<boolean>;
+    /** Current flash mode — controlled from host code. */
+    flash: 'off' | 'on';
+    toggleFlash: () => void;
+    /** True while takePhoto is in flight.  Use to disable the shutter button. */
+    isCapturing: boolean;
+    /**
+     * Take a photo.  Single-flight: parallel calls return the in-flight
+     * promise.  Returns a CaptureResult (with an optional QualityReport
+     * when ``enableQualityChecks`` is on).
+     */
+    takePhoto: () => Promise<CaptureResult>;
+    /**
+     * 2026-05-14 — physical lens types available on the chosen
+     * `cameraPosition`.  Computed once at the first vision-camera
+     * device-list emission; useful for the host to decide whether to
+     * render a 0.5×/1× camera switcher chip (only show if both
+     * `wide-angle-camera` AND `ultra-wide-angle-camera` are present).
+     *
+     * Empty array on platforms that haven't enumerated devices yet
+     * (very brief — vision-camera resolves the device list at module
+     * load).  Always populated by the time the camera is mountable.
+     */
+    availablePhysicalDevices: PhysicalCameraDeviceType[];
+}
+export declare function useCapture(options?: UseCaptureOptions): UseCaptureReturn;
+//# sourceMappingURL=useCapture.d.ts.map

package/dist/camera/useCapture.js

@@ -0,0 +1,160 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * useCapture — React hook that encapsulates the camera capture state
+ * machine so host apps get a drop-in replacement for the ad-hoc
+ * vision-camera wiring they used to have inline on each screen.
+ *
+ * Responsibilities:
+ *   - Holds the Camera ref for ``takePhoto``.
+ *   - Tracks the device permission state and exposes a request helper.
+ *   - Manages torch / flash state + a toggle helper.
+ *   - Wraps takePhoto with a single-flight guard so a double-tap on
+ *     the shutter button doesn't spawn two captures in parallel.
+ *   - Runs an optional JS-side quality check on the captured image
+ *     before resolving; the host app sees the QualityReport on the
+ *     returned CaptureResult.
+ *
+ * Non-goals:
+ *   - This hook does NOT persist captures.  Host apps hand the
+ *     returned CaptureResult to their own storage layer (WatermelonDB
+ *     insert, Redux dispatch, whatever).
+ *   - Video recording lives in useVideoCapture (TODO).
+ *
+ * The public API is designed to be minimal and replaceable: host apps
+ * that prefer the raw vision-camera API can opt out of this hook and
+ * still use the SDK's quality + stitching modules.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCapture = useCapture;
+const react_1 = require("react");
+const react_native_vision_camera_1 = require("react-native-vision-camera");
+const runQualityCheck_1 = require("../quality/runQualityCheck");
+const normaliseOrientation_1 = require("../quality/normaliseOrientation");
+function makeCaptureResult(photo, qualityReport) {
+    const capturedAt = new Date().toISOString();
+    return {
+        // The device UUID the host wants to identify this capture with is
+        // app-specific.  We synthesise a deterministic ish value so the
+        // host gets a placeholder; most hosts will swap it out for a uuid
+        // library (react-native-uuid or similar) before persisting.
+        deviceUuid: `${capturedAt}-${photo.path.split('/').pop() ?? 'photo'}`,
+        compressedUri: `file://${photo.path}`,
+        // vision-camera reports width/height post-orientation-correction,
+        // matching what `<Image>` renders.  Forwarding them lets the
+        // SDK's thumbnail strip / preview modal lay out at the correct
+        // aspect ratio instead of forcing square crops.
+        width: photo.width,
+        height: photo.height,
+        isStitched: false,
+        capturedAt,
+        qualityReport,
+        deviceMetadata: {
+            platform: 'ios',
+            osVersion: '',
+            deviceModel: '',
+            cameraId: '',
+            flashEnabled: false,
+        },
+    };
+}
+function useCapture(options = {}) {
+    const { cameraPosition = 'back', enableQualityChecks = false, qualityThresholds, takePhotoOptions, preferredPhysicalDevice, } = options;
+    const cameraRef = (0, react_1.useRef)(null);
+    // 2026-05-14 — physical-lens-aware device picker.
+    //
+    // When `preferredPhysicalDevice` is supplied, ask vision-camera
+    // for a device that exposes that specific physical lens (e.g.,
+    // 'ultra-wide-angle-camera').  Falls back to the position-default
+    // when the device doesn't have that lens.  When undefined, behaves
+    // identically to the pre-2026-05-14 useCameraDevice(position) call.
+    const deviceWithPreferred = (0, react_native_vision_camera_1.useCameraDevice)(cameraPosition, {
+        physicalDevices: preferredPhysicalDevice ? [preferredPhysicalDevice] : undefined,
+    });
+    const deviceFallback = (0, react_native_vision_camera_1.useCameraDevice)(cameraPosition);
+    const device = deviceWithPreferred ?? deviceFallback;
+    // Enumerate ALL physical lens types available on the chosen
+    // position so the host can decide whether to render a switcher.
+    // Vision-camera's `useCameraDevices()` returns CameraDevice[]; each
+    // has `physicalDevices: PhysicalCameraDeviceType[]`.  We dedupe the
+    // union across all devices at `position` so the host sees the full
+    // set the platform exposes (some phones expose ultra-wide only via
+    // a separate logical camera, not the main one).
+    const allDevices = (0, react_native_vision_camera_1.useCameraDevices)();
+    const availablePhysicalDevices = (0, react_1.useMemo)(() => {
+        const seen = new Set();
+        for (const d of allDevices) {
+            if (d.position !== cameraPosition)
+                continue;
+            for (const pd of d.physicalDevices ?? []) {
+                seen.add(pd);
+            }
+        }
+        return Array.from(seen);
+    }, [allDevices, cameraPosition]);
+    const { hasPermission, requestPermission } = (0, react_native_vision_camera_1.useCameraPermission)();
+    const [flash, setFlash] = (0, react_1.useState)('off');
+    const [isCapturing, setIsCapturing] = (0, react_1.useState)(false);
+    // Holds the in-flight takePhoto promise so we don't kick off a second
+    // call while the first is still settling.  Cleared in the finally.
+    const inFlightRef = (0, react_1.useRef)(null);
+    const toggleFlash = (0, react_1.useCallback)(() => {
+        setFlash((prev) => (prev === 'off' ? 'on' : 'off'));
+    }, []);
+    const takePhoto = (0, react_1.useCallback)(async () => {
+        if (inFlightRef.current) {
+            return inFlightRef.current;
+        }
+        if (!cameraRef.current) {
+            throw new Error('useCapture.takePhoto: cameraRef is not yet attached. '
+                + 'Render <CameraView ref={cameraRef} /> or the raw Camera with this ref first.');
+        }
+        const promise = (async () => {
+            setIsCapturing(true);
+            try {
+                const photo = await cameraRef.current.takePhoto({
+                    flash,
+                    ...takePhotoOptions,
+                });
+                // Bake EXIF rotation into pixels so the file on disk matches
+                // what the operator just saw on the preview, regardless of
+                // how downstream consumers handle EXIF.  Returns the
+                // post-rotation dimensions; we override the photo's
+                // width/height before constructing the CaptureResult so
+                // the SDK contract reports "what's actually saved".
+                const normalised = await (0, normaliseOrientation_1.normaliseOrientation)(photo.path, {
+                    width: photo.width,
+                    height: photo.height,
+                });
+                const orientedPhoto = {
+                    ...photo,
+                    width: normalised.width || photo.width,
+                    height: normalised.height || photo.height,
+                };
+                let report;
+                if (enableQualityChecks && qualityThresholds) {
+                    report = await (0, runQualityCheck_1.runQualityCheck)(orientedPhoto.path, qualityThresholds);
+                }
+                return makeCaptureResult(orientedPhoto, report);
+            }
+            finally {
+                setIsCapturing(false);
+                inFlightRef.current = null;
+            }
+        })();
+        inFlightRef.current = promise;
+        return promise;
+    }, [flash, enableQualityChecks, qualityThresholds, takePhotoOptions]);
+    return {
+        cameraRef,
+        device,
+        hasPermission,
+        requestPermission,
+        flash,
+        toggleFlash,
+        isCapturing,
+        takePhoto,
+        availablePhysicalDevices,
+    };
+}
+//# sourceMappingURL=useCapture.js.map

package/dist/camera/useDeviceOrientation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * useDeviceOrientation — physical device orientation hook.
+ *
+ * The host app is portrait-locked at the iOS app level (so the
+ * camera preview, header, controls, and thumbnails stay in their
+ * portrait positions even when the user holds the phone sideways
+ * for a vertical pan).  But text overlays — the REC banner, the
+ * pan-speed pill, the live frame strip — need to follow the
+ * physical device orientation so they stay readable in the user's
+ * hands.  RN's `useWindowDimensions` can't help with this when
+ * the app is orientation-locked: window dimensions don't change
+ * when only the device rotates.
+ *
+ * 2026-05-18 (Issue #3) — rewritten on top of `expo-sensors`
+ * `DeviceMotion` (CoreMotion-fused on iOS, SensorManager on
+ * Android).  The previous implementation used
+ * `react-native-sensors` raw accelerometer with an Android-only
+ * sign convention (`y > 0` ⇒ portrait), which silently failed on
+ * iOS — Apple's CoreMotion convention is `y < 0` ⇒ portrait
+ * because device-Y points from the phone's bottom to the top,
+ * and gravity in that frame is `-Y`.  Users on iOS saw the hook
+ * stuck at its initial value ('portrait') regardless of physical
+ * rotation, which cascaded into wrong panorama bake-rotation and
+ * a broken landscape band layout.
+ *
+ * Sign conventions used here (per platform docs):
+ *
+ *   iOS (CMDeviceMotion.accelerationIncludingGravity, reported in
+ *   m/s² in the device reference frame):
+ *     portrait              → y ≈ -9.8
+ *     portrait-upside-down  → y ≈ +9.8
+ *     landscape-left  (home indicator on user's RIGHT) → x ≈ +9.8
+ *     landscape-right (home indicator on user's LEFT)  → x ≈ -9.8
+ *
+ *   Android (Sensor.TYPE_ACCELEROMETER, reaction-force convention):
+ *     portrait              → y ≈ +9.8   ← opposite sign vs iOS
+ *     portrait-upside-down  → y ≈ -9.8
+ *     landscape-left        → x ≈ -9.8
+ *     landscape-right       → x ≈ +9.8
+ *
+ *   We flip the Android x/y to match the iOS convention before
+ *   classification so the rest of the logic stays platform-
+ *   independent.  The classification then unambiguously maps to
+ *   the user-visible `DeviceOrientation` enum.
+ */
+export type DeviceOrientation = 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right';
+export declare function useDeviceOrientation(): DeviceOrientation;
+//# sourceMappingURL=useDeviceOrientation.d.ts.map

package/dist/camera/useDeviceOrientation.js

@@ -0,0 +1,131 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * useDeviceOrientation — physical device orientation hook.
+ *
+ * The host app is portrait-locked at the iOS app level (so the
+ * camera preview, header, controls, and thumbnails stay in their
+ * portrait positions even when the user holds the phone sideways
+ * for a vertical pan).  But text overlays — the REC banner, the
+ * pan-speed pill, the live frame strip — need to follow the
+ * physical device orientation so they stay readable in the user's
+ * hands.  RN's `useWindowDimensions` can't help with this when
+ * the app is orientation-locked: window dimensions don't change
+ * when only the device rotates.
+ *
+ * 2026-05-18 (Issue #3) — rewritten on top of `expo-sensors`
+ * `DeviceMotion` (CoreMotion-fused on iOS, SensorManager on
+ * Android).  The previous implementation used
+ * `react-native-sensors` raw accelerometer with an Android-only
+ * sign convention (`y > 0` ⇒ portrait), which silently failed on
+ * iOS — Apple's CoreMotion convention is `y < 0` ⇒ portrait
+ * because device-Y points from the phone's bottom to the top,
+ * and gravity in that frame is `-Y`.  Users on iOS saw the hook
+ * stuck at its initial value ('portrait') regardless of physical
+ * rotation, which cascaded into wrong panorama bake-rotation and
+ * a broken landscape band layout.
+ *
+ * Sign conventions used here (per platform docs):
+ *
+ *   iOS (CMDeviceMotion.accelerationIncludingGravity, reported in
+ *   m/s² in the device reference frame):
+ *     portrait              → y ≈ -9.8
+ *     portrait-upside-down  → y ≈ +9.8
+ *     landscape-left  (home indicator on user's RIGHT) → x ≈ +9.8
+ *     landscape-right (home indicator on user's LEFT)  → x ≈ -9.8
+ *
+ *   Android (Sensor.TYPE_ACCELEROMETER, reaction-force convention):
+ *     portrait              → y ≈ +9.8   ← opposite sign vs iOS
+ *     portrait-upside-down  → y ≈ -9.8
+ *     landscape-left        → x ≈ -9.8
+ *     landscape-right       → x ≈ +9.8
+ *
+ *   We flip the Android x/y to match the iOS convention before
+ *   classification so the rest of the logic stays platform-
+ *   independent.  The classification then unambiguously maps to
+ *   the user-visible `DeviceOrientation` enum.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useDeviceOrientation = useDeviceOrientation;
+const react_1 = require("react");
+const expo_sensors_1 = require("expo-sensors");
+/// Threshold (m/s²) above which gravity dominance is considered
+/// conclusive.  5 m/s² out of ~9.8 means the phone is at least ~30°
+/// tilted toward that axis — comfortable for stable orientation
+/// classification without flipping on minor wobbles.
+const DOMINANT_AXIS_THRESHOLD = 5.0;
+/// Sample at ~10 Hz — plenty for orientation detection (phones
+/// don't physically flip faster than this).
+const SAMPLE_INTERVAL_MS = 100;
+function classify(x, y) {
+    // 2026-05-18 (Issue #3 round 2) — re-derived sign convention.
+    //
+    // Through expo-sensors, BOTH platforms normalize to the iOS
+    // CoreMotion gravity-vector convention: stationary phone reports
+    // the gravity vector itself in the device frame.  Device axes:
+    // +X points from phone-left to phone-right; +Y from phone-bottom
+    // to phone-top; +Z out of the screen toward the viewer.
+    //
+    // Per-orientation gravity-vector signs in the device frame:
+    //
+    //   portrait (upright)      → y ≈ -9.8
+    //     Phone-Y points up in world; gravity is along device -Y.
+    //
+    //   portrait-upside-down    → y ≈ +9.8
+    //     Phone-Y points down in world; gravity is along device +Y.
+    //
+    //   landscape-left  (Apple: home indicator on user's RIGHT;
+    //                    phone rotated 90° CCW from portrait):
+    //     phone-X axis points from user-bottom to user-top in this
+    //     orientation, so gravity (world-down) is along device -X.
+    //     → x ≈ -9.8
+    //
+    //   landscape-right (Apple: home indicator on user's LEFT;
+    //                    phone rotated 90° CW from portrait):
+    //     phone-X axis points from user-top to user-bottom, so
+    //     gravity is along device +X.
+    //     → x ≈ +9.8
+    //
+    // The earlier implementation had an Android-specific axis flip
+    // baked in.  Removed — expo-sensors normalizes Android signs to
+    // match iOS, and the platform branch was producing wrong values
+    // (Android portrait → reported as portrait-upside-down; iOS
+    // landscape-left → reported as landscape-right).
+    if (Math.abs(y) > Math.abs(x)) {
+        if (y < -DOMINANT_AXIS_THRESHOLD)
+            return 'portrait';
+        if (y > DOMINANT_AXIS_THRESHOLD)
+            return 'portrait-upside-down';
+    }
+    else {
+        if (x < -DOMINANT_AXIS_THRESHOLD)
+            return 'landscape-left';
+        if (x > DOMINANT_AXIS_THRESHOLD)
+            return 'landscape-right';
+    }
+    // Phone face-up or face-down (z dominates): keep the previous
+    // orientation rather than flicker.
+    return null;
+}
+function useDeviceOrientation() {
+    const [orientation, setOrientation] = (0, react_1.useState)('portrait');
+    (0, react_1.useEffect)(() => {
+        expo_sensors_1.DeviceMotion.setUpdateInterval(SAMPLE_INTERVAL_MS);
+        let last = 'portrait';
+        const sub = expo_sensors_1.DeviceMotion.addListener((m) => {
+            const g = m.accelerationIncludingGravity;
+            // First emissions can be null on cold start while CoreMotion
+            // warms up; skip until data arrives.
+            if (!g)
+                return;
+            const next = classify(g.x, g.y);
+            if (next && next !== last) {
+                last = next;
+                setOrientation(next);
+            }
+        });
+        return () => sub.remove();
+    }, []);
+    return orientation;
+}
+//# sourceMappingURL=useDeviceOrientation.js.map

package/dist/camera/useVideoCapture.d.ts

@@ -0,0 +1,79 @@
+/**
+ * useVideoCapture — video recording + frame extraction API.
+ *
+ * Sibling of ``useCapture`` for the "sweep a shelf with a video" flow
+ * that feeds the stitcher.  The hook's state machine is:
+ *
+ *     idle → recording → stopping → idle  (success)
+ *     idle → recording → idle             (recording errored)
+ *     idle → recording → stopping → idle  (user cancelled)
+ *
+ * API shape — `startRecording` returns a `Promise<VideoFile>` that:
+ *   - resolves with the recorded file when the user releases the
+ *     shutter and `stopRecording()` is called (vision-camera fires
+ *     `onRecordingFinished`),
+ *   - rejects if vision-camera fires `onRecordingError` at any point
+ *     (e.g. `<Camera>` was rendered without `video={true}`, disk
+ *     full mid-recording, permission revoked).
+ *
+ * Why a single future instead of separate finished/error callbacks?
+ *   Lets host code use the natural async/await pattern.  Earlier we
+ *   used a callback + a parked resolver in the host screen; that
+ *   masked start-time errors (the resolver hung forever) and produced
+ *   confusing cascade errors when `stopRecording` ran against a
+ *   non-recording camera.
+ *
+ * Frame extraction lives behind the `extractFrames` method but is
+ * deferred to the higher-level `stitchVideo()` SDK API now — host
+ * apps shouldn't have to manage their own tmp dir.  This shim is
+ * kept for parity / future use; it currently throws.
+ */
+import { Camera, type VideoFile } from 'react-native-vision-camera';
+export type VideoCaptureState = 'idle' | 'recording' | 'stopping' | 'extracting';
+export interface UseVideoCaptureReturn {
+    state: VideoCaptureState;
+    /**
+     * Begin recording on the given camera ref.  Returns a Promise that
+     * resolves with the resulting `VideoFile` once `stopRecording()`
+     * has been called and vision-camera writes the file to disk, or
+     * rejects on any recording error.
+     *
+     * Callers who only need fire-and-forget can ignore the returned
+     * promise; the hook still tracks state internally.
+     */
+    startRecording: (cameraRef: React.RefObject<Camera | null>) => Promise<VideoFile>;
+    /**
+     * Tell vision-camera to stop the active recording.  If no recording
+     * is in progress (e.g. it errored at start) this is a safe no-op.
+     * The recorded file flows back through the promise returned by
+     * `startRecording`, NOT through this method's return.
+     */
+    stopRecording: (cameraRef: React.RefObject<Camera | null>) => Promise<void>;
+    /**
+     * Cancel the active recording without delivering the file.  The
+     * promise from `startRecording` will reject with a cancellation
+     * error so awaiters unblock instead of receiving a stale file.
+     */
+    cancelRecording: (cameraRef: React.RefObject<Camera | null>) => Promise<void>;
+    /**
+     * Decode an mp4 into N evenly-spaced still frames, written to
+     * ``outputDir``.  Throws NOT_IMPLEMENTED — call `stitchVideo` from
+     * the SDK index instead, which combines extract + stitch in one
+     * native bridge call so the JS thread never has to round-trip
+     * frame paths.
+     */
+    extractFrames: (opts: ExtractFramesOptions) => Promise<ExtractFramesResult>;
+}
+export interface ExtractFramesOptions {
+    videoPath: string;
+    outputDir: string;
+    frameCount: number;
+    /** JPEG quality [0-100]. Defaults to 85. */
+    quality?: number;
+}
+export interface ExtractFramesResult {
+    framePaths: string[];
+    durationMs: number;
+}
+export declare function useVideoCapture(): UseVideoCaptureReturn;
+//# sourceMappingURL=useVideoCapture.d.ts.map