react-native-image-stitcher 0.3.0 → 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

@@ -50,8 +50,12 @@ 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.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;
+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
 // ─────────────────────────────────────────────────────────────────────
@@ -91,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Pose-aware panorama capture + stitching for React Native. One <Camera> component, both tap-to-photo and hold-to-pan modes, both AR-backed and IMU-fallback capture paths.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,8 +25,9 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
+    "test": "jest",
     "clean": "rm -rf dist",
     "postinstall": "node scripts/postinstall-fetch-binaries.js"
   },
@@ -52,13 +53,16 @@
   },
   "homepage": "https://github.com/bhargavkanda/react-native-image-stitcher#readme",
   "devDependencies": {
+    "@types/jest": "^29.5.0",
     "@types/react": "^19.0.0",
+    "jest": "^29.7.0",
     "react": "^19.0.0",
     "react-native": "^0.84.0",
     "react-native-safe-area-context": "^4.0.0",
     "react-native-sensors": "^7.0.0",
     "react-native-vision-camera": "^4.0.0",
     "rxjs": "^7.0.0",
+    "ts-jest": "^29.1.0",
     "typescript": "^5.5.0"
   },
   "peerDependencies": {

package/src/camera/Camera.tsx

@@ -69,11 +69,14 @@ import { CaptureKeyframePill } from './CaptureKeyframePill';
 import { CaptureOrientationPill } from './CaptureOrientationPill';
 import { CaptureStitchStatsToast, useStitchStatsToast } from './CaptureStitchStatsToast';
 import { PanoramaBandOverlay } from './PanoramaBandOverlay';
+import { type PanoramaSettings } from './PanoramaSettings';
+import { panoramaSettingsToNativeConfig } from './PanoramaSettingsBridge';
+import { PanoramaSettingsModal } from './PanoramaSettingsModal';
 import {
-  DEFAULT_PANORAMA_SETTINGS,
-  PanoramaSettingsModal,
-  type PanoramaSettings,
-} from './PanoramaSettingsModal';
+  buildPanoramaInitialSettings,
+  type PanoramaPropOverrides,
+} from './buildPanoramaInitialSettings';
+import { isLowMemDevice } from './lowMemDevice';
 import { useCapture } from './useCapture';
 import { useDeviceOrientation } from './useDeviceOrientation';
 import {
@@ -471,40 +474,31 @@ function deriveEffectiveCaptureSource(
 
 
 /**
- * Apply per-prop defaults to build the initial settings snapshot.
- * The settings live in component state from there; the prop values
- * never re-flow.
+ * Pluck the props that influence the initial PanoramaSettings tree.
+ * Kept inline (vs. a wide structural type) so future Camera prop
+ * additions don't accidentally widen the settings-translation
+ * surface — the pure builder in `./buildPanoramaInitialSettings.ts`
+ * has the canonical interface; this just forwards the relevant
+ * fields.
  *
- * Note: the `default*ResolMP` props don't have a home on PanoramaSettings
- * yet — they're accepted on the prop interface for forward compatibility
- * but ignored here.  Wiring is a follow-up once PanoramaSettings is
- * extended.
+ * The `default*ResolMP` props on `CameraProps` are documented as
+ * forward-looking no-ops; the new PanoramaSettings tree has no home
+ * for them yet (the v0.3 audit found cv::Stitcher's resol knobs
+ * aren't reached by either platform's bridge).  They're accepted on
+ * the prop interface for API stability and ignored here.
  */
-function buildInitialSettings(props: CameraProps): PanoramaSettings {
+function extractPanoramaOverrides(props: CameraProps): PanoramaPropOverrides {
   return {
-    ...DEFAULT_PANORAMA_SETTINGS,
-    stitchMode: props.defaultStitchMode ?? DEFAULT_PANORAMA_SETTINGS.stitchMode,
-    blenderType:
-      props.defaultBlender ?? DEFAULT_PANORAMA_SETTINGS.blenderType,
-    seamFinderType:
-      props.defaultSeamFinder ?? DEFAULT_PANORAMA_SETTINGS.seamFinderType,
-    warperType:
-      props.defaultWarper ?? DEFAULT_PANORAMA_SETTINGS.warperType,
-    flowNoveltyPercentile:
-      props.defaultFlowNoveltyPercentile ??
-      DEFAULT_PANORAMA_SETTINGS.flowNoveltyPercentile,
-    flowEvalEveryNFrames:
-      props.defaultFlowEvalEveryNFrames ??
-      DEFAULT_PANORAMA_SETTINGS.flowEvalEveryNFrames,
-    flowMaxTranslationCm:
-      props.defaultFlowMaxTranslationCm ??
-      DEFAULT_PANORAMA_SETTINGS.flowMaxTranslationCm,
-    keyframeMaxCount:
-      props.defaultKeyframeMaxCount ??
-      DEFAULT_PANORAMA_SETTINGS.keyframeMaxCount,
-    keyframeOverlapThreshold:
-      props.defaultKeyframeOverlapThreshold ??
-      DEFAULT_PANORAMA_SETTINGS.keyframeOverlapThreshold,
+    defaultCaptureSource: props.defaultCaptureSource,
+    defaultStitchMode: props.defaultStitchMode,
+    defaultBlender: props.defaultBlender,
+    defaultSeamFinder: props.defaultSeamFinder,
+    defaultWarper: props.defaultWarper,
+    defaultFlowNoveltyPercentile: props.defaultFlowNoveltyPercentile,
+    defaultFlowEvalEveryNFrames: props.defaultFlowEvalEveryNFrames,
+    defaultFlowMaxTranslationCm: props.defaultFlowMaxTranslationCm,
+    defaultKeyframeMaxCount: props.defaultKeyframeMaxCount,
+    defaultKeyframeOverlapThreshold: props.defaultKeyframeOverlapThreshold,
   };
 }
 
@@ -546,7 +540,10 @@ export function Camera(props: CameraProps): React.JSX.Element {
   );
   const [lens, setLens] = useState<CameraLens>(defaultLens);
   const [settings, setSettings] = useState<PanoramaSettings>(() =>
-    buildInitialSettings(props),
+    buildPanoramaInitialSettings(
+      extractPanoramaOverrides(props),
+      isLowMemDevice(),
+    ),
   );
   const [settingsModalVisible, setSettingsModalVisible] = useState(false);
   const [statusPhase, setStatusPhase] = useState<CaptureStatusPhase>('idle');
@@ -694,12 +691,18 @@ export function Camera(props: CameraProps): React.JSX.Element {
   // |residual|` — which undercounted any time a non-IMU accept
   // (flow novelty, force-last) reset the integrator before the
   // budget threshold was reached.
+  // The translation budget lives at `frameSelection.flow.maxTranslationCm`
+  // in the new hierarchical settings shape.  When `flow` is undefined
+  // (the consumer opted out of the flow strategy entirely), the gate
+  // stays disabled — same observable behaviour as v0.3's `0` default.
+  const flowMaxTranslationCm =
+    settings.frameSelection.flow?.maxTranslationCm ?? 0;
   const imuGate = useIMUTranslationGate({
     enabled:
       isNonAR
       && statusPhase === 'recording'
-      && settings.flowMaxTranslationCm > 0,
-    budgetMeters: Math.max(0.001, settings.flowMaxTranslationCm / 100.0),
+      && flowMaxTranslationCm > 0,
+    budgetMeters: Math.max(0.001, flowMaxTranslationCm / 100.0),
     onBudgetExceeded: () => {
       const mod = getIncrementalNativeModule();
       mod?.markNextFrameAsLastKeyframe?.().catch(() => undefined);
@@ -890,6 +893,25 @@ export function Camera(props: CameraProps): React.JSX.Element {
         deviceOrientation === 'portrait' ? 90
           : deviceOrientation === 'portrait-upside-down' ? 270
             : 0;
+      // v0.4 — the inline-flat config dict that v0.3 maintained here
+      // moved into `panoramaSettingsToNativeConfig` (see
+      // PanoramaSettingsBridge.ts).  That adapter is the single source
+      // of truth for the JS→native wire format; both this call site
+      // AND the modal's reset-to-defaults preview agree on the same
+      // mapping.  Audit fixes F1 / F4 / F6 from v0.3 are now properties
+      // of the bridge (verified by the unit tests in
+      // src/camera/__tests__/PanoramaSettingsBridge.test.ts).
+      //
+      // 2026-05-23 — override `captureSource` with the runtime-derived
+      // `effectiveCaptureSource` (from `arPreference + lens +
+      // AR-device-support`).  Pre-this change the camera-screen AR
+      // toggle wrote ONLY to local `arPreference` state while the
+      // bridge read `settings.captureSource` — so native could think
+      // the capture was AR while the operator had toggled it off (or
+      // vice-versa).  Single source of truth now: whatever camera the
+      // operator can see is what native is told it is.  The settings
+      // modal's `captureSource` control has been removed for the same
+      // reason — see PanoramaSettingsModal.tsx for the rationale.
       await incremental.start({
         snapshotJpegQuality: 75,
         snapshotEveryNAccepts: 1,
@@ -901,37 +923,10 @@ export function Camera(props: CameraProps): React.JSX.Element {
         canvasWidth: 5000,
         canvasHeight: 5000,
         engine: 'batch-keyframe',
-        config: {
-          // ── cv::Stitcher (batch finalize) ─────────────────────────
-          stitchMode: settings.stitchMode,
-          warperType: settings.warperType,
-          blenderType: settings.blenderType,
-          seamFinderType: settings.seamFinderType,
-          enableMaxInscribedRectCrop: settings.enableMaxInscribedRectCrop,
-          // ── KeyframeGate (per-frame selection) ────────────────────
-          // F6 audit fix: pass settings.frameSelectionMode through
-          // instead of hardcoding 'flow-based' (which silently made the
-          // time-based / pose-based modal options no-ops).
-          frameSelectionMode: settings.frameSelectionMode,
-          keyframeMaxCount: settings.keyframeMaxCount,
-          keyframeOverlapThreshold: settings.keyframeOverlapThreshold,
-          // ── Flow-strategy tunables ────────────────────────────────
-          // F4 audit fix: previously omitted, which made the modal
-          // sliders for these three a complete no-op (only iOS native
-          // even read them, and only when JS sent them).
-          flowNoveltyPercentile: settings.flowNoveltyPercentile,
-          flowEvalEveryNFrames: settings.flowEvalEveryNFrames,
-          flowMaxTranslationCm: settings.flowMaxTranslationCm,
-          flowMaxCorners: settings.flowMaxCorners,
-          flowQualityLevel: settings.flowQualityLevel,
-          flowMinDistance: settings.flowMinDistance,
-          // ── Engine-routing flags consumed by native ───────────────
-          // F1 audit fix: Android keyframe gate's disableAngularFallback
-          // opt-out reads this to decide whether to skip the angular
-          // fallback (gyro pose is too noisy for the FoV-overlap calc
-          // in non-AR mode, causing degenerate cv::Stitcher params).
-          captureSource: settings.captureSource,
-        },
+        config: panoramaSettingsToNativeConfig({
+          ...settings,
+          captureSource: effectiveCaptureSource,
+        }),
       });
       imuGate.resetAnchor();
       // Start pumping vision-camera snapshots into the engine for
@@ -959,6 +954,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
     isNonAR,
     deviceOrientation,
     settings,
+    effectiveCaptureSource,
     imuGate,
     jsDriver,
     onError,
@@ -1048,6 +1044,18 @@ export function Camera(props: CameraProps): React.JSX.Element {
     onError,
     recordingStartedAt,
     jsDriver,
+    // F10 Phase 2 review N1 — these four were missing pre-fix.  The
+    // callback reads `settings.debug` (to gate the stitchToast),
+    // `isNonAR` (to decide whether to read IMU totalAbs translation),
+    // `imuGate` (the read itself), and `stitchToast` (the toast hook
+    // object).  If any of those identities change between the user
+    // pressing-and-holding the shutter and the release, the stale-
+    // closure read could disagree with the actual current state.
+    // Pre-existing v0.3 bug; v0.4 was the natural time to address it.
+    settings,
+    isNonAR,
+    imuGate,
+    stitchToast,
   ]);
 
   // ── Lens / AR-toggle handlers ───────────────────────────────────
@@ -1132,8 +1140,8 @@ export function Camera(props: CameraProps): React.JSX.Element {
               isNonAR ? imuGate.getTranslationMetres() : null
             }
             captureSource={effectiveCaptureSource}
-            frameSelectionMode={settings.frameSelectionMode}
-            stitchMode={settings.stitchMode}
+            frameSelectionMode={settings.frameSelection.mode}
+            stitchMode={settings.stitcher.stitchMode}
           />
         </>
       )}