react-native-image-stitcher 0.2.0 → 0.3.0

package/dist/camera/CaptureOrientationPill.js

@@ -0,0 +1,44 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CaptureOrientationPill — diagnostic pill showing the operator's
+ * current hold orientation as detected by the pose-derived hook.
+ *
+ * Useful for diagnosing rotation issues — if the pill says
+ * `landscape-left` but the band overlay is rendering as if it's
+ * `portrait`, there's a mismatch between the JS orientation hook
+ * and the engine's pose-derived isLandscape signal.
+ *
+ * Pinned top-left below the status bar.  Layer-2 hosts can mount
+ * this directly; Layer-1 `<Camera>` mounts it automatically when
+ * `settings.debug = true`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CaptureOrientationPill = CaptureOrientationPill;
+const react_1 = __importDefault(require("react"));
+const react_native_1 = require("react-native");
+function CaptureOrientationPill({ orientation, topInset = 0, }) {
+    return (react_1.default.createElement(react_native_1.View, { pointerEvents: "none", style: [styles.container, { top: topInset + 56 }], accessibilityRole: "alert" },
+        react_1.default.createElement(react_native_1.Text, { style: styles.text }, `orient: ${orientation}`)));
+}
+const styles = react_native_1.StyleSheet.create({
+    container: {
+        position: 'absolute',
+        left: 12,
+        paddingHorizontal: 10,
+        paddingVertical: 5,
+        borderRadius: 999,
+        backgroundColor: 'rgba(99, 102, 241, 0.92)',
+        zIndex: 100,
+    },
+    text: {
+        color: '#fff',
+        fontSize: 11,
+        fontWeight: '700',
+        fontFamily: 'Menlo',
+    },
+});
+//# sourceMappingURL=CaptureOrientationPill.js.map

package/dist/camera/CaptureStitchStatsToast.d.ts

@@ -0,0 +1,45 @@
+/**
+ * CaptureStitchStatsToast — auto-dismissing toast that shows the
+ * batch-stitcher's leaveBiggestComponent telemetry + the resolved
+ * cv::Stitcher mode after every successful finalize.
+ *
+ * Pattern: top-center capsule, dark translucent background, dismisses
+ * itself after `dismissAfterMs` (default 4500).  Replaces the
+ * Alert.alert blocking modal that used to interrupt the next
+ * capture.  See `useStitchStatsToast` hook for the matching
+ * imperative API.
+ *
+ * Layer-2 hosts can mount this directly + pass their own message;
+ * Layer-1 `<Camera>` mounts it under `settings.debug` and feeds
+ * the formatted message from the finalize result automatically.
+ */
+import React from 'react';
+import type { IncrementalFinalizeResult } from '../stitching/incremental';
+export interface CaptureStitchStatsToastProps {
+    /** Toast message to show.  Pass null to hide. */
+    message: string | null;
+    /** Top inset for safe-area placement.  Toast pinned `topInset + 12`. */
+    topInset?: number;
+}
+export declare function CaptureStitchStatsToast({ message, topInset, }: CaptureStitchStatsToastProps): React.JSX.Element | null;
+/**
+ * Imperative API for showing transient stitch-stats toasts.
+ *
+ * Returns `{ message, showFor, showResult }`:
+ *   - `message`     — current toast text (pass to CaptureStitchStatsToast)
+ *   - `showFor`     — show an arbitrary string, auto-dismiss
+ *   - `showResult`  — format an `IncrementalFinalizeResult` into the
+ *                     standard "Stitch: N/M frames • thresh X.XX •
+ *                     N attempt(s) • mode" line and show it.  Convenience
+ *                     for hosts that just want the canonical format.
+ *
+ * Auto-clears its setTimeout on unmount so callers don't have to
+ * worry about setState-on-unmounted warnings.
+ */
+export interface UseStitchStatsToastReturn {
+    message: string | null;
+    showFor: (msg: string, ms?: number) => void;
+    showResult: (result: IncrementalFinalizeResult, ms?: number) => void;
+}
+export declare function useStitchStatsToast(): UseStitchStatsToastReturn;
+//# sourceMappingURL=CaptureStitchStatsToast.d.ts.map

package/dist/camera/CaptureStitchStatsToast.js

@@ -0,0 +1,133 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CaptureStitchStatsToast — auto-dismissing toast that shows the
+ * batch-stitcher's leaveBiggestComponent telemetry + the resolved
+ * cv::Stitcher mode after every successful finalize.
+ *
+ * Pattern: top-center capsule, dark translucent background, dismisses
+ * itself after `dismissAfterMs` (default 4500).  Replaces the
+ * Alert.alert blocking modal that used to interrupt the next
+ * capture.  See `useStitchStatsToast` hook for the matching
+ * imperative API.
+ *
+ * Layer-2 hosts can mount this directly + pass their own message;
+ * Layer-1 `<Camera>` mounts it under `settings.debug` and feeds
+ * the formatted message from the finalize result automatically.
+ */
+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.CaptureStitchStatsToast = CaptureStitchStatsToast;
+exports.useStitchStatsToast = useStitchStatsToast;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+function CaptureStitchStatsToast({ message, topInset = 0, }) {
+    if (message === null)
+        return null;
+    return (react_1.default.createElement(react_native_1.View, { pointerEvents: "none", style: [
+            styles.wrap,
+            { top: topInset + 12 },
+        ] },
+        react_1.default.createElement(react_native_1.View, { style: styles.capsule, accessibilityRole: "alert", accessibilityLiveRegion: "polite" },
+            react_1.default.createElement(react_native_1.Text, { style: styles.text, numberOfLines: 3 }, message))));
+}
+const styles = react_native_1.StyleSheet.create({
+    wrap: {
+        position: 'absolute',
+        left: 24,
+        right: 24,
+        alignItems: 'center',
+        zIndex: 110,
+    },
+    capsule: {
+        paddingHorizontal: 16,
+        paddingVertical: 10,
+        borderRadius: 16,
+        backgroundColor: 'rgba(15, 23, 42, 0.92)',
+        maxWidth: '100%',
+    },
+    text: {
+        color: '#ffffff',
+        fontSize: 13,
+        fontWeight: '600',
+        textAlign: 'center',
+    },
+});
+const DEFAULT_DISMISS_MS = 4500;
+function useStitchStatsToast() {
+    const [message, setMessage] = (0, react_1.useState)(null);
+    const timerRef = (0, react_1.useRef)(null);
+    const showFor = (0, react_1.useCallback)((msg, ms = DEFAULT_DISMISS_MS) => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        setMessage(msg);
+        timerRef.current = setTimeout(() => {
+            setMessage(null);
+            timerRef.current = null;
+        }, ms);
+    }, []);
+    const showResult = (0, react_1.useCallback)((result, ms = DEFAULT_DISMISS_MS) => {
+        // Format mirrors the RetaiLens debug toast that operators
+        // already recognise.  Includes the new (audit F2g) resolved
+        // stitchMode as a fourth segment when present.
+        const requested = result.framesRequested;
+        const included = result.framesIncluded;
+        const thresh = result.finalConfidenceThresh;
+        const mode = result.stitchModeResolved;
+        // The retry-attempt count is derived deterministically from
+        // the threshold used on the successful attempt (1.0→1, 0.5→2,
+        // 0.3→3) per cpp/stitcher.cpp's retry loop.
+        const attempts = typeof thresh === 'number'
+            ? thresh >= 0.99 ? 1
+                : thresh >= 0.49 ? 2
+                    : thresh >= 0.29 ? 3
+                        : null
+            : null;
+        const reqStr = typeof requested === 'number' ? requested : '?';
+        const incStr = typeof included === 'number' ? included : '?';
+        const threshStr = typeof thresh === 'number' && thresh >= 0
+            ? thresh.toFixed(2)
+            : 'n/a';
+        const attStr = attempts !== null ? `${attempts} attempt${attempts > 1 ? 's' : ''}` : '? attempts';
+        const modeStr = mode ? ` • ${mode}` : '';
+        showFor(`Stitch: ${incStr}/${reqStr} frames • thresh ${threshStr} • ${attStr}${modeStr}`, ms);
+    }, [showFor]);
+    (0, react_1.useEffect)(() => () => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+    }, []);
+    return { message, showFor, showResult };
+}
+//# sourceMappingURL=CaptureStitchStatsToast.js.map

package/dist/camera/PanoramaSettingsModal.d.ts

@@ -292,11 +292,12 @@ export interface PanoramaSettings {
      *     PlaneWarper.  Canvas size bounded by sum of frame areas.
      *     Slight quality drop on pure rotations but works for them too.
      *
-     * iOS NOTE: as of 2026-05-14 the iOS stitcher uses a hand-rolled
-     * PANORAMA-style pipeline (OpenCVStitcher.mm:600+) regardless of
-     * this setting.  Setting is passed through to iOS but ignored.
-     * Android honours it via image_stitcher_jni.cpp.  Bridging iOS is
-     * a follow-up.
+     * Both platforms honour this as of 2026-05-22 (audit F2).  Android
+     * routes through `image_stitcher_jni.cpp` → `cpp/stitcher.cpp`;
+     * iOS routes through `OpenCVStitcher.stitchFramePaths(stitchMode:)`
+     * → `cpp/stitcher.cpp`.  Both 'auto' resolutions use the same
+     * translation/rotation ratio heuristic
+     * (`resolveStitchModeAuto` on each side).
      */
     stitchMode: 'auto' | 'panorama' | 'scans';
 }

package/dist/index.d.ts

@@ -35,6 +35,16 @@ export { CapturePreview } from './camera/CapturePreview';
 export type { CapturePreviewAction } from './camera/CapturePreview';
 export { CaptureStatusOverlay } from './camera/CaptureStatusOverlay';
 export type { CaptureStatusPhase } from './camera/CaptureStatusOverlay';
+export { CaptureDebugOverlay } from './camera/CaptureDebugOverlay';
+export type { CaptureDebugOverlayProps } from './camera/CaptureDebugOverlay';
+export { CaptureMemoryPill } from './camera/CaptureMemoryPill';
+export type { CaptureMemoryPillProps } from './camera/CaptureMemoryPill';
+export { CaptureKeyframePill } from './camera/CaptureKeyframePill';
+export type { CaptureKeyframePillProps } from './camera/CaptureKeyframePill';
+export { CaptureOrientationPill } from './camera/CaptureOrientationPill';
+export type { CaptureOrientationPillProps } from './camera/CaptureOrientationPill';
+export { CaptureStitchStatsToast, useStitchStatsToast, } from './camera/CaptureStitchStatsToast';
+export type { CaptureStitchStatsToastProps, UseStitchStatsToastReturn, } from './camera/CaptureStitchStatsToast';
 export { CaptureThumbnailStrip } from './camera/CaptureThumbnailStrip';
 export type { CaptureThumbnailItem } from './camera/CaptureThumbnailStrip';
 export { IncrementalPanGuide } from './camera/IncrementalPanGuide';

package/dist/index.js

@@ -22,7 +22,7 @@
  * adds RetaiLens-specific features on top.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stitchVideo = exports.useIncrementalJSDriver = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = exports.useDeviceOrientation = exports.useVideoCapture = exports.useCapture = exports.ViewportCropOverlay = exports.DEFAULT_PANORAMA_SETTINGS = exports.PanoramaSettingsModal = exports.PanoramaGuidance = exports.PanoramaBandOverlay = exports.IncrementalPanGuide = exports.CaptureThumbnailStrip = exports.CaptureStatusOverlay = exports.CapturePreview = exports.CaptureControlsBar = exports.CaptureHeader = exports.CameraView = exports.ARCameraView = exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.CameraError = exports.Camera = void 0;
+exports.stitchVideo = exports.useIncrementalJSDriver = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = exports.useDeviceOrientation = exports.useVideoCapture = exports.useCapture = exports.ViewportCropOverlay = exports.DEFAULT_PANORAMA_SETTINGS = exports.PanoramaSettingsModal = exports.PanoramaGuidance = exports.PanoramaBandOverlay = exports.IncrementalPanGuide = exports.CaptureThumbnailStrip = exports.useStitchStatsToast = exports.CaptureStitchStatsToast = exports.CaptureOrientationPill = exports.CaptureKeyframePill = exports.CaptureMemoryPill = exports.CaptureDebugOverlay = exports.CaptureStatusOverlay = exports.CapturePreview = exports.CaptureControlsBar = exports.CaptureHeader = exports.CameraView = exports.ARCameraView = exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.CameraError = exports.Camera = void 0;
 // ─────────────────────────────────────────────────────────────────────
 // Layer 1 — the high-level <Camera> component
 // ─────────────────────────────────────────────────────────────────────
@@ -69,6 +69,20 @@ var CapturePreview_1 = require("./camera/CapturePreview");
 Object.defineProperty(exports, "CapturePreview", { enumerable: true, get: function () { return CapturePreview_1.CapturePreview; } });
 var CaptureStatusOverlay_1 = require("./camera/CaptureStatusOverlay");
 Object.defineProperty(exports, "CaptureStatusOverlay", { enumerable: true, get: function () { return CaptureStatusOverlay_1.CaptureStatusOverlay; } });
+var CaptureDebugOverlay_1 = require("./camera/CaptureDebugOverlay");
+Object.defineProperty(exports, "CaptureDebugOverlay", { enumerable: true, get: function () { return CaptureDebugOverlay_1.CaptureDebugOverlay; } });
+// 2026-05-22 (audit F9) — composable debug pills.  Layer-1 <Camera>
+// mounts all of them automatically when settings.debug is on;
+// Layer-2 hosts compose their own debug surface from these primitives.
+var CaptureMemoryPill_1 = require("./camera/CaptureMemoryPill");
+Object.defineProperty(exports, "CaptureMemoryPill", { enumerable: true, get: function () { return CaptureMemoryPill_1.CaptureMemoryPill; } });
+var CaptureKeyframePill_1 = require("./camera/CaptureKeyframePill");
+Object.defineProperty(exports, "CaptureKeyframePill", { enumerable: true, get: function () { return CaptureKeyframePill_1.CaptureKeyframePill; } });
+var CaptureOrientationPill_1 = require("./camera/CaptureOrientationPill");
+Object.defineProperty(exports, "CaptureOrientationPill", { enumerable: true, get: function () { return CaptureOrientationPill_1.CaptureOrientationPill; } });
+var CaptureStitchStatsToast_1 = require("./camera/CaptureStitchStatsToast");
+Object.defineProperty(exports, "CaptureStitchStatsToast", { enumerable: true, get: function () { return CaptureStitchStatsToast_1.CaptureStitchStatsToast; } });
+Object.defineProperty(exports, "useStitchStatsToast", { enumerable: true, get: function () { return CaptureStitchStatsToast_1.useStitchStatsToast; } });
 var CaptureThumbnailStrip_1 = require("./camera/CaptureThumbnailStrip");
 Object.defineProperty(exports, "CaptureThumbnailStrip", { enumerable: true, get: function () { return CaptureThumbnailStrip_1.CaptureThumbnailStrip; } });
 var IncrementalPanGuide_1 = require("./camera/IncrementalPanGuide");

package/dist/sensors/useIMUTranslationGate.d.ts

@@ -37,6 +37,32 @@ export interface UseIMUTranslationGateReturn {
      * benefits from continuous history across anchors.
      */
     resetAnchor: () => void;
+    /**
+     * 2026-05-22 (audit follow-up) — read the latest integrated
+     * translation magnitude in METRES.  Useful for debug overlays
+     * that want to surface "how much translation has the operator
+     * accumulated since the last keyframe accept" so they can sanity-
+     * check whether the budget is going to fire.  Cheap: returns the
+     * ref value, no React state subscription (the integrator runs at
+     * 50 Hz and we don't want to force a re-render every sample).
+     * Callers that want a live UI value should poll on an interval
+     * or use a frame-driven re-render trigger.
+     */
+    getTranslationMetres: () => number;
+    /**
+     * 2026-05-22 (audit F2f) — cumulative |segment displacement|
+     * across the entire capture, in METRES.  Includes:
+     *   (a) magnitudes banked at every prior anchor reset (whether
+     *       triggered by IMU budget auto-rearm or by host-side
+     *       resetAnchor on a non-IMU frame accept), PLUS
+     *   (b) the magnitude of the current (unfinished) segment.
+     *
+     * This is the right input for the stitchMode auto-resolver in
+     * non-AR mode — it captures total operator travel regardless of
+     * which gate accepted intermediate frames.  Resets to 0 only on
+     * subscription start (new capture).
+     */
+    getTotalAbsMetres: () => number;
 }
 export declare function useIMUTranslationGate({ enabled, budgetMeters, sampleIntervalMs, onBudgetExceeded, }: UseIMUTranslationGateOptions): UseIMUTranslationGateReturn;
 //# sourceMappingURL=useIMUTranslationGate.d.ts.map

package/dist/sensors/useIMUTranslationGate.js

@@ -85,12 +85,27 @@ function useIMUTranslationGate({ enabled, budgetMeters = DEFAULT_BUDGET_METERS,
     // All running-integrator state lives in a single ref so the
     // subscription callback can update it without forcing a re-render
     // every frame (50 Hz worth of re-renders would tank performance).
+    //
+    // 2026-05-22 (audit F2f) — `totalAbsMetres` is a separate, never-
+    // reset-within-capture accumulator of the |segment displacement|
+    // that's banked each time the current segment ends (either by
+    // auto-rearm on budget fire, or by host-side `resetAnchor` on a
+    // non-IMU frame accept).  This decouples the display-side
+    // segment integrator (`posX`, resets on every accept) from the
+    // measurement-side cumulative translation (`totalAbsMetres`,
+    // resets only on subscription start).  Pre-F2f the cumulative
+    // translation was reconstructed as `fires × budget + |residual|`
+    // — that undercounted whenever a non-IMU accept reset the
+    // integrator before the budget threshold was reached.
     const stateRef = (0, react_1.useRef)({
         posX: 0,
         velX: 0,
         /// NaN sentinel for "uninitialised"; first sample seeds it.
         gravityX: NaN,
         fired: false,
+        /// Cumulative |segment displacement| banked across all anchor
+        /// resets in this capture.  Reset only on subscription start.
+        totalAbsMetres: 0,
     });
     // Latest onBudgetExceeded callback in a ref so callers can pass
     // an inline closure that captures fresh state without us re-
@@ -99,6 +114,13 @@ function useIMUTranslationGate({ enabled, budgetMeters = DEFAULT_BUDGET_METERS,
     onExceededRef.current = onBudgetExceeded;
     const resetAnchor = (0, react_1.useCallback)(() => {
         const s = stateRef.current;
+        // 2026-05-22 (audit F2f) — bank current segment magnitude into
+        // the cumulative accumulator BEFORE zeroing.  This preserves
+        // total translation across non-IMU-driven anchor resets (e.g.
+        // when a flow-novelty accept arrives at 5 cm — short of the
+        // IMU budget — we want the 5 cm to count toward the
+        // auto-resolver's total, not be lost).
+        s.totalAbsMetres += Math.abs(s.posX);
         s.posX = 0;
         s.velX = 0;
         s.fired = false;
@@ -107,6 +129,40 @@ function useIMUTranslationGate({ enabled, budgetMeters = DEFAULT_BUDGET_METERS,
     (0, react_1.useEffect)(() => {
         if (!enabled)
             return;
+        // 2026-05-22 (audit follow-up) — reset ALL integrator state when
+        // the subscription is (re)established, not just on the host's
+        // resetAnchor() call.  Two reasons:
+        //
+        // 1. Race with statusPhase update: handleHoldStart sets
+        //    `statusPhase='recording'` synchronously, which flips
+        //    `enabled` and re-runs this effect immediately.  Samples
+        //    start arriving before the awaited `incremental.start()`
+        //    returns + the host gets a chance to call `resetAnchor()`.
+        //    During that window `posX` accumulates drift, and the
+        //    operator sees a non-zero starting `imuΔ` in the debug
+        //    overlay.
+        //
+        // 2. Stale gravity bias: `gravityX` was intentionally preserved
+        //    across `resetAnchor` calls to keep IIR history.  But
+        //    between captures the phone might be at a different
+        //    orientation; the stale gravity estimate biases `linX` for
+        //    the ~200ms IIR convergence window, and that bias compounds
+        //    into `posX` each capture.  Forcing NaN here makes the
+        //    first sample re-seed gravity cleanly — costs us one
+        //    sample of accuracy but eliminates the cross-capture drift.
+        //
+        // The host's `resetAnchor()` remains as the in-capture reset
+        // (called after each force-accept fire, etc).
+        {
+            const s = stateRef.current;
+            s.posX = 0;
+            s.velX = 0;
+            s.fired = false;
+            s.gravityX = NaN;
+            // 2026-05-22 (audit F2f) — new subscription = new capture =
+            // zero the cumulative accumulator too.
+            s.totalAbsMetres = 0;
+        }
         (0, react_native_sensors_1.setUpdateIntervalForType)(react_native_sensors_1.SensorTypes.accelerometer, sampleIntervalMs);
         const scale = react_native_1.Platform.OS === 'ios' ? G_TO_MPS2 : 1;
         const dt = sampleIntervalMs / 1000.0;
@@ -128,12 +184,38 @@ function useIMUTranslationGate({ enabled, budgetMeters = DEFAULT_BUDGET_METERS,
             s.velX = (s.velX + linX * dt) * (1 - VELOCITY_DAMPING_PER_SAMPLE);
             s.posX += s.velX * dt;
             if (!s.fired && Math.abs(s.posX) > budgetMeters) {
+                // Fire the callback (host-side force-accept hook).
                 s.fired = true;
                 onExceededRef.current();
+                // 2026-05-22 (audit follow-up) — auto-rearm the integrator
+                // so the gate fires EVERY `budgetMeters` of translation, not
+                // just once per capture.  Pre-audit behaviour was "fire once,
+                // wait for host to call resetAnchor()" — but Camera.tsx only
+                // calls resetAnchor at the start of a capture, so the gate
+                // latched after the first force-accept and never re-fired,
+                // even though the operator kept translating further (user
+                // observation: 8cm fires once, then 16cm/24cm/… don't
+                // re-trigger).
+                //
+                // 2026-05-22 (audit F2f) — bank the segment magnitude into
+                // the cumulative accumulator BEFORE zeroing (matches the
+                // resetAnchor path for symmetry — both paths represent
+                // anchor transitions, just driven by different triggers).
+                s.totalAbsMetres += Math.abs(s.posX);
+                s.posX = 0;
+                s.velX = 0;
+                s.fired = false;
             }
         });
         return () => sub.unsubscribe();
     }, [enabled, budgetMeters, sampleIntervalMs]);
-    return { resetAnchor };
+    const getTranslationMetres = (0, react_1.useCallback)(() => {
+        return stateRef.current.posX;
+    }, []);
+    const getTotalAbsMetres = (0, react_1.useCallback)(() => {
+        const s = stateRef.current;
+        return s.totalAbsMetres + Math.abs(s.posX);
+    }, []);
+    return { resetAnchor, getTranslationMetres, getTotalAbsMetres };
 }
 //# sourceMappingURL=useIMUTranslationGate.js.map

package/dist/stitching/incremental.d.ts

@@ -620,6 +620,21 @@ export interface IncrementalFinalizeResult {
     framesIncluded?: number;
     framesDropped?: number;
     finalConfidenceThresh?: number;
+    /**
+     * 2026-05-22 (audit F2g) — which cv::Stitcher pipeline the batch
+     * finalize actually ran, after the engine's `auto` resolution
+     * heuristic (or the operator's explicit choice).  Values: `'panorama'`
+     * (rotation-only, ORB + BundleAdjusterRay + SphericalWarper) or
+     * `'scans'` (translational, affine + BundleAdjusterAffine +
+     * PlaneWarper).  Undefined on non-batch engines (hybrid/slit-scan)
+     * which don't go through cv::Stitcher at finalize.
+     *
+     * Host code can surface this on the output preview (e.g. a small
+     * pill labelled "scans" / "panorama") and in the debug toast to
+     * help operators understand what choice the auto-resolver made
+     * on the just-completed capture.
+     */
+    stitchModeResolved?: 'panorama' | 'scans';
 }
 /**
  * 2026-05-16 — input to `refinePanorama`.  Mirrors the subset of
@@ -770,6 +785,16 @@ interface NativeIncrementalModule {
          * legacy start-time behaviour.
          */
         captureOrientation?: string;
+        /**
+         * 2026-05-22 (audit F2b) — JS-measured cumulative IMU translation
+         * magnitude in METRES.  Used by the auto-resolver in non-AR mode
+         * where the engine has no pose-driven translation source.  In AR
+         * mode native uses pose-derived translation and ignores this
+         * signal.  Defaults to 0 (back-compat) — auto-resolver always
+         * picks `panorama` when both pose-derived and IMU translation
+         * are zero, matching legacy behaviour.
+         */
+        imuTranslationMetres?: number;
     }): Promise<IncrementalFinalizeResult>;
     cancel(): Promise<{
         ok: true;

package/dist/stitching/useIncrementalStitcher.d.ts

@@ -50,7 +50,18 @@ export interface UseIncrementalStitcherReturn {
      * captured in landscape) bake correctly.  Omit to keep the legacy
      * behaviour (start-time orientation).
      */
-    finalize: (outputPath?: string, quality?: number, captureOrientation?: string) => Promise<IncrementalFinalizeResult>;
+    finalize: (outputPath?: string, quality?: number, captureOrientation?: string, 
+    /**
+     * 2026-05-22 (audit F2b) — measured cumulative translation
+     * magnitude in METRES from the JS-side IMU translation gate.
+     * Used by the auto-resolver in non-AR mode where the engine has
+     * no pose-driven translation source — without this signal the
+     * auto-resolver always picks `panorama` even for shelf scans.
+     * Omit (or pass 0) when no IMU translation data is available
+     * (e.g. in AR mode the native side has its own pose-driven
+     * translation magnitude and prefers that).
+     */
+    imuTranslationMetres?: number) => Promise<IncrementalFinalizeResult>;
     /** Abort the capture without producing output. */
     cancel: () => Promise<void>;
 }

package/dist/stitching/useIncrementalStitcher.js

@@ -110,7 +110,7 @@ function useIncrementalStitcher() {
         setState(null);
         lastHintRef.current = null;
     }, [native]);
-    const finalize = (0, react_1.useCallback)(async (outputPath, quality = 90, captureOrientation) => {
+    const finalize = (0, react_1.useCallback)(async (outputPath, quality = 90, captureOrientation, imuTranslationMetres) => {
         if (!native) {
             throw new Error('useIncrementalStitcher: native module unavailable');
         }
@@ -122,6 +122,12 @@ function useIncrementalStitcher() {
             // instead of the start-time snapshot.  Undefined = keep
             // legacy start-time behaviour.
             captureOrientation,
+            // 2026-05-22 (audit F2b) — fold JS-side IMU translation into
+            // the native auto-resolver.  In non-AR mode this is the only
+            // translation signal the resolver has (the JS-driver path
+            // doesn't carry tx/ty/tz, so pose-derived translation is 0).
+            // Native side treats it as a magnitude (always ≥ 0).
+            imuTranslationMetres: Math.max(0, imuTranslationMetres ?? 0),
         });
         setIsRunning(false);
         // Clear React state on finalize so the next start doesn't