react-native-image-stitcher 0.2.1 → 0.4.0

package/src/camera/__tests__/PanoramaSettingsBridge.test.ts

@@ -0,0 +1,375 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit tests for the JS→native settings bridge.
+ *
+ * Scope: every adapter (panoramaSettingsToNativeConfig,
+ * slitscanSettingsToNativeConfig, hybridSettingsToNativeConfig)
+ * round-trip from a hierarchical typed input to the flat wire dict
+ * the native side reads.  Asserts both:
+ *
+ *   1. Naming — JS key `registration.ncc1d.searchRadius` becomes
+ *      native key `nccSearchRadius1d` (and similar mappings).  Each
+ *      DEFAULT_* snapshot's expected wire dict is enumerated below;
+ *      drift in either direction (lib drops a key, or adds a phantom
+ *      one) is caught here.
+ *
+ *   2. Presence-as-enable — undefined optional sub-objects in the
+ *      typed shape (`registration.ncc1d`, `registration.ncc2d`,
+ *      `registration.ncc2d.emaSmoothing`, `registration.ncc2d.panAxisLock`,
+ *      `frameSelection.flow`, `advanced`) translate to explicit
+ *      `enable*: false` (or the absence of all the sub-object's
+ *      payload keys) on the wire.  Many of these have been silent
+ *      drift hazards historically — the old flat type required the
+ *      consumer to set BOTH `enable1dNcc: true` AND `nccSearchRadius1d:
+ *      <value>`; v0.4 makes them inseparable by collapsing into a
+ *      single optional sub-object, and this file is what guarantees
+ *      the wire side still gets both halves.
+ *
+ *   3. Engine-discriminated coverage — plane source variants
+ *      ('Disabled' / 'ARKitDetected' / 'Virtual') gate which optional
+ *      plane fields are emitted; the bridge filters those at the
+ *      adapter boundary so the modal's per-source rendering doesn't
+ *      get mislead by stale-but-present keys from a previous source
+ *      selection.
+ *
+ * These tests are pure-TS; no React Native module import.  Jest config
+ * (`jest.config.js`) routes test files in `__tests__/` through ts-jest
+ * with the `node` testEnvironment.
+ */
+
+import {
+  DEFAULT_FLOW_GATE_SETTINGS,
+  DEFAULT_HYBRID_SETTINGS,
+  DEFAULT_PANORAMA_SETTINGS,
+  DEFAULT_SLITSCAN_SETTINGS,
+  type HybridSettings,
+  type PanoramaSettings,
+  type SlitscanSettings,
+} from '../PanoramaSettings';
+import {
+  hybridSettingsToNativeConfig,
+  panoramaSettingsToNativeConfig,
+  slitscanSettingsToNativeConfig,
+} from '../PanoramaSettingsBridge';
+
+
+// ════════════════════════════════════════════════════════════════════
+// PANORAMA — batch-keyframe engine
+// ════════════════════════════════════════════════════════════════════
+
+describe('panoramaSettingsToNativeConfig', () => {
+  it('round-trips DEFAULT_PANORAMA_SETTINGS to the expected flat dict', () => {
+    const cfg = panoramaSettingsToNativeConfig(DEFAULT_PANORAMA_SETTINGS);
+
+    // Cross-cutting
+    expect(cfg.captureSource).toBe('ar');
+
+    // BatchStitcherSettings
+    expect(cfg.stitchMode).toBe('auto');
+    expect(cfg.warperType).toBe('plane');
+    expect(cfg.blenderType).toBe('multiband');
+    expect(cfg.seamFinderType).toBe('graphcut');
+    expect(cfg.enableMaxInscribedRectCrop).toBe(false);
+
+    // FrameSelectionSettings
+    expect(cfg.frameSelectionMode).toBe('flow-based');
+    expect(cfg.keyframeMaxCount).toBe(6);
+    expect(cfg.keyframeOverlapThreshold).toBe(0.2);
+
+    // FlowGateSettings (flow is defined in the default)
+    expect(cfg.flowNoveltyPercentile).toBe(0.85);
+    expect(cfg.flowEvalEveryNFrames).toBe(5);
+    expect(cfg.flowMaxTranslationCm).toBe(50);
+    expect(cfg.flowMaxCorners).toBe(150);
+    expect(cfg.flowQualityLevel).toBe(0.01);
+    expect(cfg.flowMinDistance).toBe(10);
+  });
+
+  it('falls back to DEFAULT_FLOW_GATE_SETTINGS when frameSelection.flow is undefined', () => {
+    // F10 Phase 2 review B1 — native compiled-in defaults disagree
+    // with the JS defaults for two flow knobs (maxTranslationCm and
+    // evalEveryNFrames).  The bridge must always emit every flow key
+    // so sparse-literal hosts get the JS defaults on the wire, not
+    // the native fallbacks.
+    const noFlow: PanoramaSettings = {
+      ...DEFAULT_PANORAMA_SETTINGS,
+      frameSelection: {
+        ...DEFAULT_PANORAMA_SETTINGS.frameSelection,
+        flow: undefined,
+      },
+    };
+    const cfg = panoramaSettingsToNativeConfig(noFlow);
+
+    expect(cfg.frameSelectionMode).toBe('flow-based');
+    expect(cfg.keyframeMaxCount).toBe(6);
+    expect(cfg.keyframeOverlapThreshold).toBe(0.2);
+
+    // Every flow.* native key present, matching DEFAULT_FLOW_GATE_SETTINGS.
+    expect(cfg.flowNoveltyPercentile).toBe(DEFAULT_FLOW_GATE_SETTINGS.noveltyPercentile);
+    expect(cfg.flowEvalEveryNFrames).toBe(DEFAULT_FLOW_GATE_SETTINGS.evalEveryNFrames);
+    expect(cfg.flowMaxTranslationCm).toBe(DEFAULT_FLOW_GATE_SETTINGS.maxTranslationCm);
+    expect(cfg.flowMaxCorners).toBe(DEFAULT_FLOW_GATE_SETTINGS.maxCorners);
+    expect(cfg.flowQualityLevel).toBe(DEFAULT_FLOW_GATE_SETTINGS.qualityLevel);
+    expect(cfg.flowMinDistance).toBe(DEFAULT_FLOW_GATE_SETTINGS.minDistance);
+  });
+
+  it('emits flow defaults to the wire when frameSelection.flow is undefined AND mode is flow-based', () => {
+    // F10 Phase 2 review N3 — the realistic user-facing case:
+    // host writes `mode: 'flow-based'` but omits the flow sub-tree.
+    // Pre-B1-fix, the gate would silently run with native fallbacks
+    // (flowMaxTranslationCm=0, flowEvalEveryNFrames=1) instead of
+    // the JS defaults (50 cm budget, 5× throttle).
+    const s: PanoramaSettings = {
+      ...DEFAULT_PANORAMA_SETTINGS,
+      frameSelection: {
+        mode: 'flow-based',
+        maxKeyframes: 6,
+        overlapThreshold: 0.20,
+        // flow omitted — legal per the optional `?` in the type
+      },
+    };
+    const cfg = panoramaSettingsToNativeConfig(s);
+
+    expect(cfg.flowMaxTranslationCm).toBe(50);
+    expect(cfg.flowEvalEveryNFrames).toBe(5);
+    expect(cfg.flowNoveltyPercentile).toBe(0.85);
+    expect(cfg.flowMaxCorners).toBe(150);
+    expect(cfg.flowQualityLevel).toBe(0.01);
+    expect(cfg.flowMinDistance).toBe(10);
+  });
+
+  it('locks down the full wire-key set for DEFAULT_PANORAMA_SETTINGS', () => {
+    // F10 Phase 2 review N4 — mirror the hybrid test below.  Lock
+    // down which keys leave the bridge so a future field accidentally
+    // riding along (e.g. `debug` being treated as a wire knob) fails
+    // this test immediately.
+    const cfg = panoramaSettingsToNativeConfig(DEFAULT_PANORAMA_SETTINGS);
+    expect(Object.keys(cfg).sort()).toEqual([
+      'blenderType',
+      'captureSource',
+      'enableMaxInscribedRectCrop',
+      'flowEvalEveryNFrames',
+      'flowMaxCorners',
+      'flowMaxTranslationCm',
+      'flowMinDistance',
+      'flowNoveltyPercentile',
+      'flowQualityLevel',
+      'frameSelectionMode',
+      'keyframeMaxCount',
+      'keyframeOverlapThreshold',
+      'seamFinderType',
+      'stitchMode',
+      'warperType',
+    ]);
+  });
+
+  it('honours captureSource and stitcher overrides', () => {
+    const overridden: PanoramaSettings = {
+      ...DEFAULT_PANORAMA_SETTINGS,
+      captureSource: 'non-ar',
+      debug: true,
+      stitcher: {
+        stitchMode: 'scans',
+        warperType: 'spherical',
+        blenderType: 'feather',
+        seamFinderType: 'skip',
+        enableMaxInscribedRectCrop: true,
+      },
+    };
+    const cfg = panoramaSettingsToNativeConfig(overridden);
+
+    expect(cfg.captureSource).toBe('non-ar');
+    expect(cfg.stitchMode).toBe('scans');
+    expect(cfg.warperType).toBe('spherical');
+    expect(cfg.blenderType).toBe('feather');
+    expect(cfg.seamFinderType).toBe('skip');
+    expect(cfg.enableMaxInscribedRectCrop).toBe(true);
+    // Note: `debug` is intentionally NOT on the wire — it's a
+    // JS-side UI gate, not a native config knob.  The bridge MUST
+    // omit it; if a future change starts emitting it, the modal's
+    // operator-facing semantics will silently drift.
+    expect(cfg).not.toHaveProperty('debug');
+  });
+});
+
+
+// ════════════════════════════════════════════════════════════════════
+// SLITSCAN — Layer 2 slit-scan engines
+// ════════════════════════════════════════════════════════════════════
+
+describe('slitscanSettingsToNativeConfig', () => {
+  it('round-trips DEFAULT_SLITSCAN_SETTINGS to the expected flat dict', () => {
+    const cfg = slitscanSettingsToNativeConfig(DEFAULT_SLITSCAN_SETTINGS);
+
+    expect(cfg.captureSource).toBe('ar');
+    expect(cfg.engineVariant).toBe('slitscan-rotate');
+
+    // Painting
+    expect(cfg.paintMode).toBe('FirstPaintedWins');
+    expect(cfg.sliverPosition).toBe('Bottom');
+    expect(cfg.firstFrameFullFrame).toBe(true);
+
+    // Registration (explicit booleans)
+    expect(cfg.enableTriangulation).toBe(false);
+    expect(cfg.enableTriAccumulator).toBe(false);
+    expect(cfg.enableRansacHomography).toBe(false);
+
+    // Plane
+    expect(cfg.planeSource).toBe('ARKitDetected');
+    expect(cfg.planeProjectionStyle).toBe('Rectified');
+    expect(cfg.arkitPlaneAlignmentThreshold).toBe(0.6);
+
+    // ncc1d / ncc2d both omitted in defaults
+    expect(cfg.enable1dNcc).toBe(false);
+    expect(cfg.enable2dNcc).toBe(false);
+    expect(cfg).not.toHaveProperty('nccSearchRadius1d');
+    expect(cfg).not.toHaveProperty('nccSearchMargin2d');
+    expect(cfg).not.toHaveProperty('nccConfidenceThreshold2d');
+    expect(cfg).not.toHaveProperty('ncc2dEmaAlpha');
+    expect(cfg).not.toHaveProperty('ncc2dCrossAxisLockPx');
+
+    // Plane: ARKitDetected — alignmentThreshold present, virtual depth absent
+    expect(cfg).not.toHaveProperty('virtualPlaneDepthMeters');
+
+    // Advanced: not set in defaults
+    expect(cfg).not.toHaveProperty('kPanAxisFractionRect');
+    expect(cfg).not.toHaveProperty('kMinAcceptDeltaPx');
+  });
+
+  it('expands `registration.ncc1d` presence-as-enable correctly', () => {
+    const withNcc1d: SlitscanSettings = {
+      ...DEFAULT_SLITSCAN_SETTINGS,
+      registration: {
+        ...DEFAULT_SLITSCAN_SETTINGS.registration,
+        ncc1d: { searchRadius: 25 },
+      },
+    };
+    const cfg = slitscanSettingsToNativeConfig(withNcc1d);
+    expect(cfg.enable1dNcc).toBe(true);
+    expect(cfg.nccSearchRadius1d).toBe(25);
+  });
+
+  it('expands `registration.ncc2d` presence-as-enable with nested optionals', () => {
+    const withNcc2dFull: SlitscanSettings = {
+      ...DEFAULT_SLITSCAN_SETTINGS,
+      registration: {
+        ...DEFAULT_SLITSCAN_SETTINGS.registration,
+        ncc2d: {
+          searchMargin: 14,
+          confidenceThreshold: 0.95,
+          emaSmoothing: { alpha: 0.5 },
+          panAxisLock: { crossAxisLockPx: 4 },
+        },
+      },
+    };
+    const cfg = slitscanSettingsToNativeConfig(withNcc2dFull);
+
+    expect(cfg.enable2dNcc).toBe(true);
+    expect(cfg.nccSearchMargin2d).toBe(14);
+    expect(cfg.nccConfidenceThreshold2d).toBe(0.95);
+    expect(cfg.enableNcc2dEmaSmoothing).toBe(true);
+    expect(cfg.ncc2dEmaAlpha).toBe(0.5);
+    expect(cfg.enableNcc2dPanAxisLock).toBe(true);
+    expect(cfg.ncc2dCrossAxisLockPx).toBe(4);
+  });
+
+  it('honours ncc2d nested-optional absence (ema + panAxisLock undefined)', () => {
+    const withNcc2dBare: SlitscanSettings = {
+      ...DEFAULT_SLITSCAN_SETTINGS,
+      registration: {
+        ...DEFAULT_SLITSCAN_SETTINGS.registration,
+        ncc2d: {
+          searchMargin: 12,
+          confidenceThreshold: 0.99,
+          // emaSmoothing + panAxisLock omitted → enable-flag false, no payload
+        },
+      },
+    };
+    const cfg = slitscanSettingsToNativeConfig(withNcc2dBare);
+
+    expect(cfg.enable2dNcc).toBe(true);
+    expect(cfg.enableNcc2dEmaSmoothing).toBe(false);
+    expect(cfg.enableNcc2dPanAxisLock).toBe(false);
+    // Critical: payload keys for the disabled sub-features must NOT
+    // ride along — Native engine would treat them as authoritative
+    // even with the enable flag off (defensive against a native bug).
+    expect(cfg).not.toHaveProperty('ncc2dEmaAlpha');
+    expect(cfg).not.toHaveProperty('ncc2dCrossAxisLockPx');
+  });
+
+  it.each([
+    ['Disabled', { virtualPlaneDepthMeters: false, arkitPlaneAlignmentThreshold: false, planeProjectionStyle: false }],
+    ['Virtual', { virtualPlaneDepthMeters: true, arkitPlaneAlignmentThreshold: false, planeProjectionStyle: true }],
+    ['ARKitDetected', { virtualPlaneDepthMeters: false, arkitPlaneAlignmentThreshold: true, planeProjectionStyle: true }],
+  ] as const)(
+    'emits plane optionals consistent with source=%s',
+    (source, expected) => {
+      const s: SlitscanSettings = {
+        ...DEFAULT_SLITSCAN_SETTINGS,
+        plane: {
+          source,
+          projectionStyle: 'Rectified',
+          virtualDepthMeters: 2.0,
+          alignmentThreshold: 0.7,
+        },
+      };
+      const cfg = slitscanSettingsToNativeConfig(s);
+      expect(cfg.planeSource).toBe(source);
+      expect('virtualPlaneDepthMeters' in cfg).toBe(expected.virtualPlaneDepthMeters);
+      expect('arkitPlaneAlignmentThreshold' in cfg).toBe(expected.arkitPlaneAlignmentThreshold);
+      expect('planeProjectionStyle' in cfg).toBe(expected.planeProjectionStyle);
+    },
+  );
+
+  it('emits `advanced` knobs only when explicitly set', () => {
+    const withAdvanced: SlitscanSettings = {
+      ...DEFAULT_SLITSCAN_SETTINGS,
+      advanced: { panAxisFractionRect: 0.6, minAcceptDeltaPx: 30 },
+    };
+    const cfg = slitscanSettingsToNativeConfig(withAdvanced);
+    expect(cfg.kPanAxisFractionRect).toBe(0.6);
+    expect(cfg.kMinAcceptDeltaPx).toBe(30);
+
+    const onlyOne: SlitscanSettings = {
+      ...DEFAULT_SLITSCAN_SETTINGS,
+      advanced: { panAxisFractionRect: 0.6 },
+      // minAcceptDeltaPx omitted within the sub-object
+    };
+    const cfgOne = slitscanSettingsToNativeConfig(onlyOne);
+    expect(cfgOne.kPanAxisFractionRect).toBe(0.6);
+    expect(cfgOne).not.toHaveProperty('kMinAcceptDeltaPx');
+  });
+});
+
+
+// ════════════════════════════════════════════════════════════════════
+// HYBRID — RetaiLens live engine
+// ════════════════════════════════════════════════════════════════════
+
+describe('hybridSettingsToNativeConfig', () => {
+  it('round-trips DEFAULT_HYBRID_SETTINGS to the expected flat dict', () => {
+    const cfg = hybridSettingsToNativeConfig(DEFAULT_HYBRID_SETTINGS);
+    expect(cfg.captureSource).toBe('ar');
+    expect(cfg.hybridProjection).toBe('Planar');
+  });
+
+  it('honours projection override', () => {
+    const cyl: HybridSettings = {
+      ...DEFAULT_HYBRID_SETTINGS,
+      projection: 'Cylindrical',
+    };
+    expect(hybridSettingsToNativeConfig(cyl).hybridProjection).toBe('Cylindrical');
+  });
+
+  it('emits only the documented hybrid surface (debug is JS-only)', () => {
+    // Hybrid presets internally clobber most fields; the bridge
+    // deliberately keeps the wire surface minimal.  This test guards
+    // against future drift where someone adds a hybrid setting to the
+    // bridge without first validating that the engine actually reads it.
+    const cfg = hybridSettingsToNativeConfig({
+      ...DEFAULT_HYBRID_SETTINGS,
+      debug: true, // JS-only, must NOT reach the wire
+    });
+    expect(Object.keys(cfg).sort()).toEqual(['captureSource', 'hybridProjection']);
+  });
+});

package/src/camera/__tests__/buildPanoramaInitialSettings.test.ts

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit tests for buildPanoramaInitialSettings — the prop→settings-tree
+ * translation that runs once at <Camera>'s mount.
+ *
+ * Coverage:
+ *
+ *   - Defaults (no prop overrides) reproduce DEFAULT_PANORAMA_SETTINGS
+ *     when `isLowMemDevice=false`.
+ *   - `isLowMemDevice=true` swaps blender + seamFinder defaults to the
+ *     feather+skip fallback; other fields unchanged.
+ *   - Every prop override routes to its hierarchical path: stitchMode →
+ *     stitcher.stitchMode, defaultFlowMaxTranslationCm →
+ *     frameSelection.flow.maxTranslationCm, etc.
+ *   - Partial overrides leave non-overridden fields at the default.
+ *
+ * Plus a "wire-format integration" check: the produced settings tree,
+ * fed through `panoramaSettingsToNativeConfig`, lands at the expected
+ * flat dict.  This is the seam where the prop translation, the
+ * hierarchical tree, and the bridge all meet — verifying it here means
+ * <Camera>'s `incremental.start({ config })` call is correctly wired
+ * end-to-end on the JS side (on-device run remains the integration
+ * check across the JS/native boundary itself).
+ */
+
+import {
+  DEFAULT_PANORAMA_SETTINGS,
+  type PanoramaSettings,
+} from '../PanoramaSettings';
+import { panoramaSettingsToNativeConfig } from '../PanoramaSettingsBridge';
+import { buildPanoramaInitialSettings } from '../buildPanoramaInitialSettings';
+
+
+describe('buildPanoramaInitialSettings', () => {
+  it('returns DEFAULT_PANORAMA_SETTINGS verbatim when no overrides and not low-mem', () => {
+    const s = buildPanoramaInitialSettings({}, false);
+    expect(s).toEqual(DEFAULT_PANORAMA_SETTINGS);
+  });
+
+  it('swaps blender + seamFinder for the low-mem fallback', () => {
+    const s = buildPanoramaInitialSettings({}, true);
+    expect(s.stitcher.blenderType).toBe('feather');
+    expect(s.stitcher.seamFinderType).toBe('skip');
+    // Everything else stays at the static default.
+    expect(s.stitcher.stitchMode).toBe(DEFAULT_PANORAMA_SETTINGS.stitcher.stitchMode);
+    expect(s.stitcher.warperType).toBe(DEFAULT_PANORAMA_SETTINGS.stitcher.warperType);
+    expect(s.frameSelection).toEqual(DEFAULT_PANORAMA_SETTINGS.frameSelection);
+    expect(s.captureSource).toBe(DEFAULT_PANORAMA_SETTINGS.captureSource);
+  });
+
+  it('routes every prop override to its hierarchical path', () => {
+    const s = buildPanoramaInitialSettings(
+      {
+        defaultCaptureSource: 'non-ar',
+        defaultStitchMode: 'scans',
+        defaultBlender: 'feather',
+        defaultSeamFinder: 'skip',
+        defaultWarper: 'cylindrical',
+        defaultFlowNoveltyPercentile: 0.70,
+        defaultFlowEvalEveryNFrames: 3,
+        defaultFlowMaxTranslationCm: 12,
+        defaultKeyframeMaxCount: 8,
+        defaultKeyframeOverlapThreshold: 0.30,
+      },
+      false,
+    );
+
+    expect(s.captureSource).toBe('non-ar');
+    expect(s.stitcher.stitchMode).toBe('scans');
+    expect(s.stitcher.blenderType).toBe('feather');
+    expect(s.stitcher.seamFinderType).toBe('skip');
+    expect(s.stitcher.warperType).toBe('cylindrical');
+    expect(s.frameSelection.flow?.noveltyPercentile).toBe(0.70);
+    expect(s.frameSelection.flow?.evalEveryNFrames).toBe(3);
+    expect(s.frameSelection.flow?.maxTranslationCm).toBe(12);
+    expect(s.frameSelection.maxKeyframes).toBe(8);
+    expect(s.frameSelection.overlapThreshold).toBe(0.30);
+  });
+
+  it('leaves non-overridden fields at the default (partial override)', () => {
+    const s = buildPanoramaInitialSettings(
+      { defaultStitchMode: 'panorama' },
+      false,
+    );
+
+    // The override took effect …
+    expect(s.stitcher.stitchMode).toBe('panorama');
+
+    // … and every other field stays at the corresponding default.
+    expect(s.stitcher.warperType).toBe(DEFAULT_PANORAMA_SETTINGS.stitcher.warperType);
+    expect(s.stitcher.blenderType).toBe(DEFAULT_PANORAMA_SETTINGS.stitcher.blenderType);
+    expect(s.stitcher.seamFinderType).toBe(DEFAULT_PANORAMA_SETTINGS.stitcher.seamFinderType);
+    expect(s.frameSelection).toEqual(DEFAULT_PANORAMA_SETTINGS.frameSelection);
+    expect(s.captureSource).toBe(DEFAULT_PANORAMA_SETTINGS.captureSource);
+  });
+
+  it('produces wire-format-clean output when piped through the bridge', () => {
+    // The end-to-end JS-side path: props → buildPanoramaInitialSettings →
+    // panoramaSettingsToNativeConfig.  Verifying it here catches drift
+    // at any of the three layers (prop name, type-tree shape, bridge
+    // adapter) with a single assertion.
+    const overrides = {
+      defaultCaptureSource: 'non-ar' as const,
+      defaultStitchMode: 'scans' as const,
+      defaultFlowMaxTranslationCm: 25,
+    };
+    const settings: PanoramaSettings =
+      buildPanoramaInitialSettings(overrides, false);
+    const wire = panoramaSettingsToNativeConfig(settings);
+
+    expect(wire.captureSource).toBe('non-ar');
+    expect(wire.stitchMode).toBe('scans');
+    expect(wire.flowMaxTranslationCm).toBe(25);
+    // Defaulted fields still on the wire with their default value.
+    expect(wire.warperType).toBe('plane');
+    expect(wire.frameSelectionMode).toBe('flow-based');
+    expect(wire.flowNoveltyPercentile).toBe(0.85);
+  });
+});

package/src/camera/__tests__/lowMemDevice.test.ts

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit tests for the pure `isBelowMemThreshold` classifier.
+ *
+ * The other two exports (`getPhysicalMemoryBytes` and `isLowMemDevice`)
+ * read the React Native bridge and can only be exercised on a real
+ * device.  This file covers the threshold logic exhaustively so the
+ * classification rule is unit-tested without needing the RN runtime.
+ */
+
+import {
+  LOW_MEM_THRESHOLD_BYTES,
+  isBelowMemThreshold,
+} from '../lowMemDevice';
+
+
+describe('isBelowMemThreshold', () => {
+  it('returns true for positive byte counts below the threshold', () => {
+    expect(isBelowMemThreshold(1)).toBe(true);
+    expect(isBelowMemThreshold(1024)).toBe(true);
+    expect(isBelowMemThreshold(LOW_MEM_THRESHOLD_BYTES - 1)).toBe(true);
+  });
+
+  it('returns false at exactly the threshold (strict < comparison)', () => {
+    expect(isBelowMemThreshold(LOW_MEM_THRESHOLD_BYTES)).toBe(false);
+  });
+
+  it('returns false for byte counts above the threshold', () => {
+    expect(isBelowMemThreshold(LOW_MEM_THRESHOLD_BYTES + 1)).toBe(false);
+    expect(isBelowMemThreshold(4 * 1024 * 1024 * 1024)).toBe(false);
+    expect(isBelowMemThreshold(Number.MAX_SAFE_INTEGER)).toBe(false);
+  });
+
+  it('returns false for zero (unknown — safe default to high-quality combo)', () => {
+    expect(isBelowMemThreshold(0)).toBe(false);
+  });
+
+  it('returns false for negative values (defensive)', () => {
+    expect(isBelowMemThreshold(-1)).toBe(false);
+    expect(isBelowMemThreshold(-LOW_MEM_THRESHOLD_BYTES)).toBe(false);
+  });
+
+  it('returns false for non-finite values (NaN / Infinity)', () => {
+    expect(isBelowMemThreshold(Number.NaN)).toBe(false);
+    expect(isBelowMemThreshold(Number.POSITIVE_INFINITY)).toBe(false);
+    expect(isBelowMemThreshold(Number.NEGATIVE_INFINITY)).toBe(false);
+  });
+
+  it('threshold is exactly 2 GB', () => {
+    expect(LOW_MEM_THRESHOLD_BYTES).toBe(2 * 1024 * 1024 * 1024);
+  });
+});

package/src/camera/buildPanoramaInitialSettings.ts

@@ -0,0 +1,139 @@
+// 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.
+ */
+
+import {
+  DEFAULT_FLOW_GATE_SETTINGS,
+  DEFAULT_PANORAMA_SETTINGS,
+  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 function buildPanoramaInitialSettings(
+  overrides: PanoramaPropOverrides,
+  isLowMemDevice: boolean,
+): PanoramaSettings {
+  // Start from the static, side-effect-free defaults.
+  const base = 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' as const,
+      seamFinderType: 'skip' as const,
+    }
+    : 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 = 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,
+      },
+    },
+  };
+}