react-native-image-stitcher 0.2.1 → 0.4.0

package/dist/camera/buildPanoramaInitialSettings.d.ts

@@ -0,0 +1,70 @@
+/**
+ * buildPanoramaInitialSettings — pure helper that materialises the
+ * initial `PanoramaSettings` snapshot from <Camera>'s `default*` props
+ * and a device-capability hint.
+ *
+ * Why a separate file?
+ * ────────────────────
+ *
+ * The settings tree lives in `PanoramaSettings.ts`; <Camera> consumes
+ * it and writes it into React state.  The translation FROM the prop
+ * surface (flat names like `defaultStitchMode`) INTO the hierarchical
+ * settings tree is the part that:
+ *
+ *   • is non-trivial enough to deserve direct unit-test coverage
+ *     (covers the prop→sub-tree path mapping, which is easy to drift),
+ *   • is pure TS — no React, no React Native — so the test runs in
+ *     jest's `node` environment without needing the `react-native`
+ *     preset (the rest of <Camera> is unmockable in pure TS).
+ *
+ * Living alongside `Camera.tsx` (vs. burying it as a private function
+ * inside) is the only way to get those two properties without taking
+ * on full React-Native jest setup just for this one helper.
+ *
+ * The exported `PanoramaPropOverrides` type is the prop-fragment
+ * <Camera> uses; `CameraProps` extends it.  Keeping it explicit here
+ * means future Camera prop additions don't accidentally widen the
+ * settings-translation surface — every consumer of the helper sees
+ * exactly the prop fields that drive the settings tree.
+ */
+import { type PanoramaSettings } from './PanoramaSettings';
+/**
+ * Subset of <Camera>'s props that map onto fields of the initial
+ * `PanoramaSettings` snapshot.  Anything outside this interface
+ * (e.g. `defaultLens`, `enablePhotoMode`, callbacks) is irrelevant
+ * to the settings shape and stays in `CameraProps` only.
+ *
+ * Forward-looking `default*ResolMP` props are documented here but
+ * intentionally not translated yet — the new `PanoramaSettings` tree
+ * has no home for them (the v0.3 audit found cv::Stitcher's resol
+ * knobs aren't reached by the current native bridges).
+ */
+export interface PanoramaPropOverrides {
+    defaultCaptureSource?: 'ar' | 'non-ar';
+    defaultStitchMode?: 'auto' | 'panorama' | 'scans';
+    defaultBlender?: 'multiband' | 'feather';
+    defaultSeamFinder?: 'graphcut' | 'skip';
+    defaultWarper?: 'plane' | 'cylindrical' | 'spherical';
+    defaultFlowNoveltyPercentile?: number;
+    defaultFlowEvalEveryNFrames?: number;
+    defaultFlowMaxTranslationCm?: number;
+    defaultKeyframeMaxCount?: number;
+    defaultKeyframeOverlapThreshold?: number;
+}
+/**
+ * Whether this device is low-memory enough to benefit from the
+ * feather+skip blender/seam fallback (vs. the heavier multiband+
+ * graphcut default).  <Camera> derives this from
+ * `NativeModules.BatchStitcher.physicalMemoryBytes` at module load
+ * (RN-only — see `getIsLowMemDevice` in Camera.tsx); tests pass
+ * `false` explicitly to keep the prop-translation path the unit of
+ * the unit test.
+ *
+ * Why a parameter and not a constant import?
+ *   The pre-v0.4 `DEFAULT_PANORAMA_SETTINGS` was a `let` mutated at
+ *   module load — side-effect-heavy, untestable.  v0.4 keeps the
+ *   defaults static + side-effect-free; the device adaptation lives
+ *   exactly where it needs to (Camera's mount-time `useState`).
+ */
+export declare function buildPanoramaInitialSettings(overrides: PanoramaPropOverrides, isLowMemDevice: boolean): PanoramaSettings;
+//# sourceMappingURL=buildPanoramaInitialSettings.d.ts.map

package/dist/camera/buildPanoramaInitialSettings.js

@@ -0,0 +1,97 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * buildPanoramaInitialSettings — pure helper that materialises the
+ * initial `PanoramaSettings` snapshot from <Camera>'s `default*` props
+ * and a device-capability hint.
+ *
+ * Why a separate file?
+ * ────────────────────
+ *
+ * The settings tree lives in `PanoramaSettings.ts`; <Camera> consumes
+ * it and writes it into React state.  The translation FROM the prop
+ * surface (flat names like `defaultStitchMode`) INTO the hierarchical
+ * settings tree is the part that:
+ *
+ *   • is non-trivial enough to deserve direct unit-test coverage
+ *     (covers the prop→sub-tree path mapping, which is easy to drift),
+ *   • is pure TS — no React, no React Native — so the test runs in
+ *     jest's `node` environment without needing the `react-native`
+ *     preset (the rest of <Camera> is unmockable in pure TS).
+ *
+ * Living alongside `Camera.tsx` (vs. burying it as a private function
+ * inside) is the only way to get those two properties without taking
+ * on full React-Native jest setup just for this one helper.
+ *
+ * The exported `PanoramaPropOverrides` type is the prop-fragment
+ * <Camera> uses; `CameraProps` extends it.  Keeping it explicit here
+ * means future Camera prop additions don't accidentally widen the
+ * settings-translation surface — every consumer of the helper sees
+ * exactly the prop fields that drive the settings tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPanoramaInitialSettings = buildPanoramaInitialSettings;
+const PanoramaSettings_1 = require("./PanoramaSettings");
+/**
+ * Whether this device is low-memory enough to benefit from the
+ * feather+skip blender/seam fallback (vs. the heavier multiband+
+ * graphcut default).  <Camera> derives this from
+ * `NativeModules.BatchStitcher.physicalMemoryBytes` at module load
+ * (RN-only — see `getIsLowMemDevice` in Camera.tsx); tests pass
+ * `false` explicitly to keep the prop-translation path the unit of
+ * the unit test.
+ *
+ * Why a parameter and not a constant import?
+ *   The pre-v0.4 `DEFAULT_PANORAMA_SETTINGS` was a `let` mutated at
+ *   module load — side-effect-heavy, untestable.  v0.4 keeps the
+ *   defaults static + side-effect-free; the device adaptation lives
+ *   exactly where it needs to (Camera's mount-time `useState`).
+ */
+function buildPanoramaInitialSettings(overrides, isLowMemDevice) {
+    // Start from the static, side-effect-free defaults.
+    const base = PanoramaSettings_1.DEFAULT_PANORAMA_SETTINGS;
+    // Apply the low-memory device adaptation:
+    //   - feather blender (streams warped frames, no peak-memory spike)
+    //   - skip seam finder (no graphcut working set)
+    // Replaces the v0.3 module-load-time mutation; same semantics.
+    const stitcherDefaults = isLowMemDevice
+        ? {
+            ...base.stitcher,
+            blenderType: 'feather',
+            seamFinderType: 'skip',
+        }
+        : base.stitcher;
+    // Use the standalone DEFAULT_FLOW_GATE_SETTINGS constant rather
+    // than `base.frameSelection.flow!` — the non-null assertion would
+    // crash silently if a future refactor un-defines the default's
+    // flow sub-tree, but the constant lives at the same level as the
+    // type and is type-checked.  See F10 Phase 2 review (NIT-4).
+    const flowDefaults = PanoramaSettings_1.DEFAULT_FLOW_GATE_SETTINGS;
+    return {
+        captureSource: overrides.defaultCaptureSource ?? base.captureSource,
+        debug: base.debug,
+        stitcher: {
+            ...stitcherDefaults,
+            stitchMode: overrides.defaultStitchMode ?? stitcherDefaults.stitchMode,
+            warperType: overrides.defaultWarper ?? stitcherDefaults.warperType,
+            blenderType: overrides.defaultBlender ?? stitcherDefaults.blenderType,
+            seamFinderType: overrides.defaultSeamFinder ?? stitcherDefaults.seamFinderType,
+        },
+        frameSelection: {
+            ...base.frameSelection,
+            maxKeyframes: overrides.defaultKeyframeMaxCount ?? base.frameSelection.maxKeyframes,
+            overlapThreshold: overrides.defaultKeyframeOverlapThreshold
+                ?? base.frameSelection.overlapThreshold,
+            flow: {
+                ...flowDefaults,
+                noveltyPercentile: overrides.defaultFlowNoveltyPercentile
+                    ?? flowDefaults.noveltyPercentile,
+                evalEveryNFrames: overrides.defaultFlowEvalEveryNFrames
+                    ?? flowDefaults.evalEveryNFrames,
+                maxTranslationCm: overrides.defaultFlowMaxTranslationCm
+                    ?? flowDefaults.maxTranslationCm,
+            },
+        },
+    };
+}
+//# sourceMappingURL=buildPanoramaInitialSettings.js.map

package/dist/camera/lowMemDevice.d.ts

@@ -0,0 +1,24 @@
+/** 2 GB in bytes — the cutoff below which `<Camera>` falls back
+ *  to the feather+skip blender/seam combo for safer peak memory. */
+export declare const LOW_MEM_THRESHOLD_BYTES: number;
+/**
+ * Pure classifier.  Returns `true` when `bytes` is a positive
+ * number strictly below the threshold.  Zero / NaN / undefined-shaped
+ * inputs return `false` — the safe choice when the native bridge
+ * hasn't surfaced the value (assume the device has enough memory
+ * for the higher-quality combo; the operator can still flip
+ * blender / seamFinder in the modal).
+ */
+export declare function isBelowMemThreshold(bytes: number): boolean;
+/**
+ * Read the device's physical memory from the native bridge.
+ * Returns 0 when the bridge isn't loaded or the constant is missing
+ * — caller should treat 0 as "unknown".
+ */
+export declare function getPhysicalMemoryBytes(): number;
+/**
+ * Composed `getPhysicalMemoryBytes()` + `isBelowMemThreshold()`.
+ * Convenience for the common consumer pattern.
+ */
+export declare function isLowMemDevice(): boolean;
+//# sourceMappingURL=lowMemDevice.d.ts.map

package/dist/camera/lowMemDevice.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOW_MEM_THRESHOLD_BYTES = void 0;
+exports.isBelowMemThreshold = isBelowMemThreshold;
+exports.getPhysicalMemoryBytes = getPhysicalMemoryBytes;
+exports.isLowMemDevice = isLowMemDevice;
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * lowMemDevice — shared helpers around the iOS BatchStitcher
+ * `physicalMemoryBytes` constant.
+ *
+ * Two consumers (Camera.tsx's `useState` initialiser + the modal's
+ * device-mem debug line) had near-identical implementations of the
+ * same "read physical memory from NativeModules, classify as
+ * low-mem" logic.  The F10 Phase 2 review (N2) flagged this as a
+ * drift hazard — exactly the kind of subtle duplication that audit
+ * fix F1 chased on the native side.
+ *
+ * Layered for testability:
+ *
+ *   - `isBelowMemThreshold(bytes)` is pure (in: number, out:
+ *     boolean) — unit-testable.
+ *   - `getPhysicalMemoryBytes()` reads the RN bridge module — must
+ *     run on a real device.
+ *   - `isLowMemDevice()` composes the two for the common case.
+ *
+ * The 2 GB threshold corresponds to iPhone X / 8 Plus / iPhone 6s
+ * era devices; below that, multiband blend + graphcut seam-finder
+ * peak memory risks the jetsam threshold mid-stitch.  Static value
+ * (no runtime config); revisit if the SDK ever targets a wider
+ * device range.
+ */
+const react_native_1 = require("react-native");
+/** 2 GB in bytes — the cutoff below which `<Camera>` falls back
+ *  to the feather+skip blender/seam combo for safer peak memory. */
+exports.LOW_MEM_THRESHOLD_BYTES = 2 * 1024 * 1024 * 1024;
+/**
+ * Pure classifier.  Returns `true` when `bytes` is a positive
+ * number strictly below the threshold.  Zero / NaN / undefined-shaped
+ * inputs return `false` — the safe choice when the native bridge
+ * hasn't surfaced the value (assume the device has enough memory
+ * for the higher-quality combo; the operator can still flip
+ * blender / seamFinder in the modal).
+ */
+function isBelowMemThreshold(bytes) {
+    return Number.isFinite(bytes)
+        && bytes > 0
+        && bytes < exports.LOW_MEM_THRESHOLD_BYTES;
+}
+/**
+ * Read the device's physical memory from the native bridge.
+ * Returns 0 when the bridge isn't loaded or the constant is missing
+ * — caller should treat 0 as "unknown".
+ */
+function getPhysicalMemoryBytes() {
+    const m = react_native_1.NativeModules.BatchStitcher;
+    const bytes = m && typeof m === 'object'
+        ? m.physicalMemoryBytes
+        : undefined;
+    return typeof bytes === 'number' ? bytes : 0;
+}
+/**
+ * Composed `getPhysicalMemoryBytes()` + `isBelowMemThreshold()`.
+ * Convenience for the common consumer pattern.
+ */
+function isLowMemDevice() {
+    return isBelowMemThreshold(getPhysicalMemoryBytes());
+}
+//# sourceMappingURL=lowMemDevice.js.map

package/dist/index.d.ts

@@ -35,13 +35,27 @@ 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';
 export { PanoramaBandOverlay } from './camera/PanoramaBandOverlay';
 export { PanoramaGuidance } from './camera/PanoramaGuidance';
-export { PanoramaSettingsModal, DEFAULT_PANORAMA_SETTINGS, } from './camera/PanoramaSettingsModal';
-export type { PanoramaSettings } from './camera/PanoramaSettingsModal';
+export { PanoramaSettingsModal } from './camera/PanoramaSettingsModal';
+export type { PanoramaSettingsModalProps } from './camera/PanoramaSettingsModal';
+export { DEFAULT_PANORAMA_SETTINGS, DEFAULT_FLOW_GATE_SETTINGS, DEFAULT_SLITSCAN_SETTINGS, DEFAULT_HYBRID_SETTINGS, } from './camera/PanoramaSettings';
+export type { CaptureBaseSettings, PanoramaSettings, BatchStitcherSettings, FrameSelectionSettings, FlowGateSettings, SlitscanSettings, SlitscanPaintingSettings, SlitscanRegistrationSettings, SlitscanAdvancedSettings, Ncc1dSettings, Ncc2dSettings, PlaneProjectionSettings, HybridSettings, } from './camera/PanoramaSettings';
+export { panoramaSettingsToNativeConfig, slitscanSettingsToNativeConfig, hybridSettingsToNativeConfig, } from './camera/PanoramaSettingsBridge';
+export type { NativeConfigDict } from './camera/PanoramaSettingsBridge';
 export { ViewportCropOverlay } from './camera/ViewportCropOverlay';
 export { useCapture } from './camera/useCapture';
 export type { TakePhotoCallOptions } from './camera/useCapture';

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.hybridSettingsToNativeConfig = exports.slitscanSettingsToNativeConfig = exports.panoramaSettingsToNativeConfig = exports.DEFAULT_HYBRID_SETTINGS = exports.DEFAULT_SLITSCAN_SETTINGS = exports.DEFAULT_FLOW_GATE_SETTINGS = 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");
@@ -77,9 +91,30 @@ var PanoramaBandOverlay_1 = require("./camera/PanoramaBandOverlay");
 Object.defineProperty(exports, "PanoramaBandOverlay", { enumerable: true, get: function () { return PanoramaBandOverlay_1.PanoramaBandOverlay; } });
 var PanoramaGuidance_1 = require("./camera/PanoramaGuidance");
 Object.defineProperty(exports, "PanoramaGuidance", { enumerable: true, get: function () { return PanoramaGuidance_1.PanoramaGuidance; } });
+// Settings modal — the modal is in `PanoramaSettingsModal.tsx`, but
+// the type tree + defaults + JS↔native bridge live in dedicated
+// files since v0.4 (F10).  The modal is now a thin presentational
+// component over the typed structure.
 var PanoramaSettingsModal_1 = require("./camera/PanoramaSettingsModal");
 Object.defineProperty(exports, "PanoramaSettingsModal", { enumerable: true, get: function () { return PanoramaSettingsModal_1.PanoramaSettingsModal; } });
-Object.defineProperty(exports, "DEFAULT_PANORAMA_SETTINGS", { enumerable: true, get: function () { return PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS; } });
+// Settings types — the v0.4 engine-discriminated structures.  Three
+// disjoint top-level types (one per stitching engine), each composed
+// of named sub-trees the corresponding native engine actually reads.
+// See `./camera/PanoramaSettings.ts` for the rationale and the
+// field-by-field native-consumer references.
+var PanoramaSettings_1 = require("./camera/PanoramaSettings");
+Object.defineProperty(exports, "DEFAULT_PANORAMA_SETTINGS", { enumerable: true, get: function () { return PanoramaSettings_1.DEFAULT_PANORAMA_SETTINGS; } });
+Object.defineProperty(exports, "DEFAULT_FLOW_GATE_SETTINGS", { enumerable: true, get: function () { return PanoramaSettings_1.DEFAULT_FLOW_GATE_SETTINGS; } });
+Object.defineProperty(exports, "DEFAULT_SLITSCAN_SETTINGS", { enumerable: true, get: function () { return PanoramaSettings_1.DEFAULT_SLITSCAN_SETTINGS; } });
+Object.defineProperty(exports, "DEFAULT_HYBRID_SETTINGS", { enumerable: true, get: function () { return PanoramaSettings_1.DEFAULT_HYBRID_SETTINGS; } });
+// Settings → native config adapters.  Layer 2 hosts building their
+// own capture flow on top of `incremental.start()` should always
+// pass the result of the matching adapter as `config`; the bridge is
+// the single source of truth for the JS↔native wire format.
+var PanoramaSettingsBridge_1 = require("./camera/PanoramaSettingsBridge");
+Object.defineProperty(exports, "panoramaSettingsToNativeConfig", { enumerable: true, get: function () { return PanoramaSettingsBridge_1.panoramaSettingsToNativeConfig; } });
+Object.defineProperty(exports, "slitscanSettingsToNativeConfig", { enumerable: true, get: function () { return PanoramaSettingsBridge_1.slitscanSettingsToNativeConfig; } });
+Object.defineProperty(exports, "hybridSettingsToNativeConfig", { enumerable: true, get: function () { return PanoramaSettingsBridge_1.hybridSettingsToNativeConfig; } });
 var ViewportCropOverlay_1 = require("./camera/ViewportCropOverlay");
 Object.defineProperty(exports, "ViewportCropOverlay", { enumerable: true, get: function () { return ViewportCropOverlay_1.ViewportCropOverlay; } });
 // ── Capture hooks ─────────────────────────────────────────────────────

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