react-native-image-stitcher 0.14.2 → 0.15.1

package/src/camera/PanoramaSettingsBridge.ts

@@ -44,8 +44,6 @@
 import {
   DEFAULT_FLOW_GATE_SETTINGS,
   type PanoramaSettings,
-  type SlitscanSettings,
-  type HybridSettings,
 } from './PanoramaSettings';
 
 
@@ -86,6 +84,9 @@ export function panoramaSettingsToNativeConfig(
     frameSelectionMode: s.frameSelection.mode,
     keyframeMaxCount: s.frameSelection.maxKeyframes,
     keyframeOverlapThreshold: s.frameSelection.overlapThreshold,
+    // Time-budget force-accept (both strategies).  Native reads
+    // configOverrides["maxKeyframeIntervalMs"] → setMaxKeyframeIntervalMs.
+    maxKeyframeIntervalMs: s.frameSelection.maxKeyframeIntervalMs,
   };
 
   // Flow strategy knobs — always serialised, regardless of
@@ -124,115 +125,3 @@ export function panoramaSettingsToNativeConfig(
 
   return cfg;
 }
-
-
-/**
- * Convert a v0.4 SlitscanSettings tree into the flat dict the
- * slit-scan / firstwins native engines read.  Handles the
- * "presence-as-enable" boolean expansion: a non-undefined
- * `registration.ncc1d` means `enable1dNcc: true` on the wire,
- * with the sub-object's `searchRadius` carried alongside.
- *
- * Verified against:
- *   - iOS  `IncrementalStitcher.swift:1006-1100` (applyConfigOverrides)
- *   - iOS  `OpenCVSlitScanStitcher.mm` (all numbered references in
- *          the audit ground-truth matrix)
- */
-export function slitscanSettingsToNativeConfig(
-  s: SlitscanSettings,
-): NativeConfigDict {
-  const cfg: NativeConfigDict = {
-    captureSource: s.captureSource,
-    // The native side reads `engine: 'slitscan-…'` at start time
-    // from a separate top-level field, NOT from configOverrides.
-    // We still serialise the variant here for hosts that want to
-    // round-trip a single settings object through both surfaces.
-    engineVariant: s.variant,
-
-    // ── Painting ─────────────────────────────────────────────────
-    paintMode: s.painting.paintMode,
-    sliverPosition: s.painting.sliverPosition,
-    firstFrameFullFrame: s.painting.firstFrameFullFrame,
-
-    // ── Registration (explicit booleans) ─────────────────────────
-    enableTriangulation: s.registration.enableTriangulation,
-    enableTriAccumulator: s.registration.enableTriAccumulator,
-    enableRansacHomography: s.registration.enableRansacHomography,
-
-    // ── Plane projection ─────────────────────────────────────────
-    planeSource: s.plane.source,
-  };
-
-  // ── 1D NCC: presence-as-enable ─────────────────────────────────
-  if (s.registration.ncc1d) {
-    cfg.enable1dNcc = true;
-    cfg.nccSearchRadius1d = s.registration.ncc1d.searchRadius;
-  } else {
-    cfg.enable1dNcc = false;
-  }
-
-  // ── 2D NCC: presence-as-enable + nested optionals ──────────────
-  if (s.registration.ncc2d) {
-    const n2 = s.registration.ncc2d;
-    cfg.enable2dNcc = true;
-    cfg.nccSearchMargin2d = n2.searchMargin;
-    cfg.nccConfidenceThreshold2d = n2.confidenceThreshold;
-    if (n2.emaSmoothing) {
-      cfg.enableNcc2dEmaSmoothing = true;
-      cfg.ncc2dEmaAlpha = n2.emaSmoothing.alpha;
-    } else {
-      cfg.enableNcc2dEmaSmoothing = false;
-    }
-    if (n2.panAxisLock) {
-      cfg.enableNcc2dPanAxisLock = true;
-      cfg.ncc2dCrossAxisLockPx = n2.panAxisLock.crossAxisLockPx;
-    } else {
-      cfg.enableNcc2dPanAxisLock = false;
-    }
-  } else {
-    cfg.enable2dNcc = false;
-  }
-
-  // ── Plane optionals ────────────────────────────────────────────
-  // Only emit when `source` actually consumes the field.  Native
-  // tolerates unsolicited keys but the modal also walks the dict
-  // to decide which sliders to render — extra keys would mislead.
-  if (s.plane.source !== 'Disabled' && s.plane.projectionStyle !== undefined) {
-    cfg.planeProjectionStyle = s.plane.projectionStyle;
-  }
-  if (s.plane.source === 'Virtual' && s.plane.virtualDepthMeters !== undefined) {
-    cfg.virtualPlaneDepthMeters = s.plane.virtualDepthMeters;
-  }
-  if (s.plane.source === 'ARKitDetected' && s.plane.alignmentThreshold !== undefined) {
-    cfg.arkitPlaneAlignmentThreshold = s.plane.alignmentThreshold;
-  }
-
-  // ── Advanced motion knobs (only emit if explicitly set) ────────
-  if (s.advanced?.panAxisFractionRect !== undefined) {
-    cfg.kPanAxisFractionRect = s.advanced.panAxisFractionRect;
-  }
-  if (s.advanced?.minAcceptDeltaPx !== undefined) {
-    cfg.kMinAcceptDeltaPx = s.advanced.minAcceptDeltaPx;
-  }
-
-  return cfg;
-}
-
-
-/**
- * Convert a v0.4 HybridSettings tree into the flat dict the hybrid
- * engine reads.  Minimal surface — hybrid presets internally clobber
- * almost everything; see HybridSettings JSDoc for context.
- *
- * Verified against:
- *   - iOS  `OpenCVIncrementalStitcher.mm:139-180` (preset paths)
- *   - iOS  `IncrementalStitcher.swift:1034-1040` (hybridProjection override)
- */
-export function hybridSettingsToNativeConfig(
-  s: HybridSettings,
-): NativeConfigDict {
-  return {
-    captureSource: s.captureSource,
-    hybridProjection: s.projection,
-  };
-}

package/src/camera/PanoramaSettingsModal.tsx

@@ -264,6 +264,19 @@ export function PanoramaSettingsModal({
                 })}
                 caption="Required NEW-content fraction.  20% (default): generous, ~5–6 keyframes for a 90° pan.  Native clamps to [10%, 80%]."
               />
+              <SectionHeader title="Keyframe interval (time-budget force-accept)" />
+              <SegmentedControl
+                options={['off', '1s', '2s', '3s', '5s']}
+                value={
+                  settings.frameSelection.maxKeyframeIntervalMs === 0
+                    ? 'off'
+                    : `${settings.frameSelection.maxKeyframeIntervalMs / 1000}s`
+                }
+                onChange={(v) => updateFrameSelection({
+                  maxKeyframeIntervalMs: v === 'off' ? 0 : parseInt(v, 10) * 1000,
+                })}
+                caption="Force-accept a keyframe at least this often even if novelty is low, so slow / static pans don't leave gaps.  Counts toward the keyframe cap.  off = disabled.  2s (default).  Applies to AR + non-AR."
+              />
 
               {showFlowTunables && (
                 <View style={styles.nested}>
@@ -373,7 +386,7 @@ export function PanoramaSettingsModal({
                 onChange={(v) => updateStitcher({
                   enableMaxInscribedRectCrop: v === 'on',
                 })}
-                caption="off (default): crop to cv::boundingRect of non-black pixels — preserves all stitched content; may leave black corners.  on: run MaxInscribedRectFromMask + column-projection second-pass for a clean rectangle (can shrink output if mask is lopsided)."
+                caption="off (default): crop to cv::boundingRect of non-black pixels — preserves all stitched content; may leave black corners.  on: run MaxInscribedRectFromMask + column-projection second-pass for a clean rectangle (can shrink output a lot if mask is lopsided / ultra-wide)."
               />
             </Accordion>
 

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

@@ -39,17 +39,11 @@
 
 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';
 
 
@@ -75,6 +69,7 @@ describe('panoramaSettingsToNativeConfig', () => {
     expect(cfg.frameSelectionMode).toBe('flow-based');
     expect(cfg.keyframeMaxCount).toBe(6);
     expect(cfg.keyframeOverlapThreshold).toBe(0.2);
+    expect(cfg.maxKeyframeIntervalMs).toBe(2000);
 
     // FlowGateSettings (flow is defined in the default)
     expect(cfg.flowNoveltyPercentile).toBe(0.85);
@@ -125,6 +120,7 @@ describe('panoramaSettingsToNativeConfig', () => {
         mode: 'flow-based',
         maxKeyframes: 6,
         overlapThreshold: 0.20,
+        maxKeyframeIntervalMs: 2000,
         // flow omitted — legal per the optional `?` in the type
       },
     };
@@ -157,6 +153,7 @@ describe('panoramaSettingsToNativeConfig', () => {
       'frameSelectionMode',
       'keyframeMaxCount',
       'keyframeOverlapThreshold',
+      'maxKeyframeIntervalMs',
       'seamFinderType',
       'stitchMode',
       'warperType',
@@ -191,185 +188,3 @@ describe('panoramaSettingsToNativeConfig', () => {
     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

@@ -61,6 +61,7 @@ describe('buildPanoramaInitialSettings', () => {
         defaultFlowMaxTranslationCm: 12,
         defaultKeyframeMaxCount: 8,
         defaultKeyframeOverlapThreshold: 0.30,
+        maxInscribedRectCrop: true,
       },
       false,
     );
@@ -75,6 +76,46 @@ describe('buildPanoramaInitialSettings', () => {
     expect(s.frameSelection.flow?.maxTranslationCm).toBe(12);
     expect(s.frameSelection.maxKeyframes).toBe(8);
     expect(s.frameSelection.overlapThreshold).toBe(0.30);
+    expect(s.stitcher.enableMaxInscribedRectCrop).toBe(true);
+  });
+
+  it('maps maxInscribedRectCrop → stitcher.enableMaxInscribedRectCrop', () => {
+    expect(
+      buildPanoramaInitialSettings({ maxInscribedRectCrop: true }, false)
+        .stitcher.enableMaxInscribedRectCrop,
+    ).toBe(true);
+    expect(
+      buildPanoramaInitialSettings({ maxInscribedRectCrop: false }, false)
+        .stitcher.enableMaxInscribedRectCrop,
+    ).toBe(false);
+    // Omitted ⇒ default (false — inscribed-rect crop is opt-in), and the
+    // low-mem fallback must not flip it.
+    expect(
+      buildPanoramaInitialSettings({}, false)
+        .stitcher.enableMaxInscribedRectCrop,
+    ).toBe(false);
+    expect(
+      buildPanoramaInitialSettings({}, true)
+        .stitcher.enableMaxInscribedRectCrop,
+    ).toBe(false);
+  });
+
+  it('maps defaultMaxKeyframeIntervalMs → frameSelection.maxKeyframeIntervalMs', () => {
+    expect(
+      buildPanoramaInitialSettings({ defaultMaxKeyframeIntervalMs: 3500 }, false)
+        .frameSelection.maxKeyframeIntervalMs,
+    ).toBe(3500);
+    // 0 explicitly disables the time-budget force-accept — it is NOT
+    // nullish, so `??` does not replace it with the default.
+    expect(
+      buildPanoramaInitialSettings({ defaultMaxKeyframeIntervalMs: 0 }, false)
+        .frameSelection.maxKeyframeIntervalMs,
+    ).toBe(0);
+    // Omitted ⇒ the 2000 ms default.
+    expect(
+      buildPanoramaInitialSettings({}, false)
+        .frameSelection.maxKeyframeIntervalMs,
+    ).toBe(2000);
   });
 
   it('leaves non-overridden fields at the default (partial override)', () => {

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

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit tests for the recoverable-stitch-failure guidance map.
+ *
+ * Guarantees: (1) every recoverable code yields non-empty, plain-language
+ * copy with no raw cv::Stitcher diagnostic leaking through; (2) the
+ * cause-specific guidance actually names its corrective action; (3) every
+ * non-recoverable code returns null so the host falls back to its generic
+ * error UI.
+ */
+import { userFacingStitchError } from '../cameraErrorMessages';
+import type { CameraErrorCode } from '../Camera';
+
+describe('userFacingStitchError', () => {
+  const RECOVERABLE: CameraErrorCode[] = [
+    'STITCH_NEED_MORE_IMGS',
+    'STITCH_HOMOGRAPHY_FAIL',
+    'STITCH_CAMERA_PARAMS_FAIL',
+    'STITCH_OOM',
+  ];
+
+  it.each(RECOVERABLE)(
+    'returns non-empty, jargon-free title+message for %s',
+    (code) => {
+      const r = userFacingStitchError(code);
+      expect(r).not.toBeNull();
+      expect(r!.title.length).toBeGreaterThan(0);
+      expect(r!.message.length).toBeGreaterThan(0);
+      // No raw stitcher diagnostics should ever reach the user.
+      expect(r!.message).not.toMatch(/warpRoi|cv::|OpenCV|ERR_|StsOutOfRange|estimator/i);
+      expect(r!.title).not.toMatch(/cv::|OpenCV|ERR_/i);
+      // The title is the corrective ASK (e.g. "Please pan more slowly"),
+      // not a generic failure headline.
+      expect(r!.title).not.toMatch(/couldn't|can't|error|failed|too large/i);
+    },
+  );
+
+  it('camera-params guidance names the 0.5x sensitivity and the 1x fix', () => {
+    const r = userFacingStitchError('STITCH_CAMERA_PARAMS_FAIL');
+    expect(r).not.toBeNull();
+    // The actual root cause (translation) + the actionable lens advice.
+    expect(r!.message).toMatch(/0\.5x|ultra-wide/i);
+    expect(r!.message).toMatch(/\b1x\b/i);
+    expect(r!.message).toMatch(/pivot|turning|one spot|moved|shifted/i);
+  });
+
+  it('need-more-images guidance is about overlap', () => {
+    expect(userFacingStitchError('STITCH_NEED_MORE_IMGS')!.message).toMatch(
+      /overlap/i,
+    );
+  });
+
+  it('oom guidance suggests a shorter sweep', () => {
+    expect(userFacingStitchError('STITCH_OOM')!.message).toMatch(
+      /shorter|narrower|memory/i,
+    );
+  });
+
+  const NON_RECOVERABLE: CameraErrorCode[] = [
+    'CAMERA_PERMISSION_DENIED',
+    'CAMERA_DEVICE_UNAVAILABLE',
+    'PHOTO_CAPTURE_FAILED',
+    'PANORAMA_START_FAILED',
+    'PANORAMA_FINALIZE_FAILED',
+    'OUTPUT_WRITE_FAILED',
+    'VISION_CAMERA_RUNTIME',
+    'UNKNOWN',
+  ];
+
+  it.each(NON_RECOVERABLE)(
+    'returns null for non-recoverable code %s',
+    (code) => {
+      expect(userFacingStitchError(code)).toBeNull();
+    },
+  );
+});

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

@@ -157,6 +157,39 @@ describe('selectCaptureDevice', () => {
     expect(sel.device).toBe(wideTorch);
     expect(sel.hasTorch).toBe(true);
   });
+
+  it('S24: multicam LISTS ultra-wide but zoom cannot reach it (minZoom~1) + standalone uw swaps', () => {
+    // Samsung/Camera2: the logical device lists the ultra-wide but its zoom
+    // range starts at 1.0, so zoom cannot reach it.  A separate ultra-wide id
+    // exists -> keep the multicam for 1x (torch) and swap to the standalone
+    // ultra-wide on 0.5x.
+    const multicamNoReach = dualWide({ minZoom: 1, hasTorch: true });
+    const uw = standaloneUltraWide();
+    const sel = selectCaptureDevice([multicamNoReach, uw]);
+    expect(sel.mode).toBe('standalone-uw');
+    expect(sel.device).toBe(multicamNoReach); // 1x primary keeps the torch
+    expect(sel.ultraWideDevice).toBe(uw); // 0.5x swaps to the real ultra-wide
+    expect(sel.has0_5x).toBe(true);
+    expect(sel.hasTorch).toBe(true);
+  });
+
+  it('multicam lists ultra-wide, zoom cannot reach (minZoom~1), NO standalone uw -> hide', () => {
+    // The ultra-wide exists ONLY inside a non-zoomable logical device with no
+    // separate id to swap to -> undeliverable -> hide the chooser.
+    const multicamNoReach = dualWide({ minZoom: 1 });
+    const sel = selectCaptureDevice([multicamNoReach]);
+    expect(sel.mode).toBe('wide-only');
+    expect(sel.has0_5x).toBe(false);
+    expect(sel.ultraWideDevice).toBeNull();
+  });
+
+  it('minZoom threshold: <=0.7 zoom-switches, >0.7 falls through to swap', () => {
+    const atThreshold = dualWide({ minZoom: 0.7 });
+    expect(selectCaptureDevice([atThreshold]).mode).toBe('multicam');
+    const aboveThreshold = dualWide({ minZoom: 0.71 });
+    const uw = standaloneUltraWide();
+    expect(selectCaptureDevice([aboveThreshold, uw]).mode).toBe('standalone-uw');
+  });
 });
 
 describe('zoomForLens (multicam lens→zoom mapping)', () => {

package/src/camera/buildPanoramaInitialSettings.ts

@@ -58,6 +58,17 @@ export interface PanoramaPropOverrides {
   defaultFlowMaxTranslationCm?: number;
   defaultKeyframeMaxCount?: number;
   defaultKeyframeOverlapThreshold?: number;
+  /**
+   * Initial value for `frameSelection.maxKeyframeIntervalMs` — the
+   * time-budget force-accept (ms).  `0` disables it.  Default 2000.
+   */
+  defaultMaxKeyframeIntervalMs?: number;
+  /**
+   * v0.15 — initial value for `stitcher.enableMaxInscribedRectCrop`.
+   * Maps from the standalone `maxInscribedRectCrop` <Camera> prop.
+   * Omitted ⇒ the stitcher default (false = bounding-rect crop).
+   */
+  maxInscribedRectCrop?: boolean;
 }
 
 
@@ -113,6 +124,9 @@ export function buildPanoramaInitialSettings(
       blenderType: overrides.defaultBlender ?? stitcherDefaults.blenderType,
       seamFinderType:
         overrides.defaultSeamFinder ?? stitcherDefaults.seamFinderType,
+      enableMaxInscribedRectCrop:
+        overrides.maxInscribedRectCrop
+        ?? stitcherDefaults.enableMaxInscribedRectCrop,
     },
 
     frameSelection: {
@@ -122,6 +136,9 @@ export function buildPanoramaInitialSettings(
       overlapThreshold:
         overrides.defaultKeyframeOverlapThreshold
         ?? base.frameSelection.overlapThreshold,
+      maxKeyframeIntervalMs:
+        overrides.defaultMaxKeyframeIntervalMs
+        ?? base.frameSelection.maxKeyframeIntervalMs,
       flow: {
         ...flowDefaults,
         noveltyPercentile:

package/src/camera/cameraErrorMessages.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Friendly, action-guiding copy for the *recoverable* stitch-failure
+ * `CameraErrorCode`s — the ones a user can fix by simply re-capturing.
+ * Hosts map these onto an Alert/toast instead of surfacing the raw
+ * cv::Stitcher diagnostic (e.g. "warpRoi too large (8171x12336) —
+ * estimator produced degenerate camera params").
+ *
+ * Returns `null` for every non-recoverable / non-stitch code (permission
+ * denied, device unavailable, generic finalize failure, unknown, ...):
+ * those have no single corrective action to suggest, so the host should
+ * fall back to its generic error display.
+ *
+ * Lives in the SDK (not per-host) so every consumer shows the same
+ * vetted guidance for the same failure — and so the mapping is
+ * unit-testable in isolation.
+ */
+import type { CameraErrorCode } from './Camera';
+
+export interface UserFacingStitchError {
+  /** Short, friendly alert title. */
+  title: string;
+  /** One-paragraph, plain-language corrective guidance. */
+  message: string;
+}
+
+/**
+ * The four recoverable stitch outcomes, each with copy tuned to its
+ * actual root cause.  `Partial<Record<...>>` keeps the keys
+ * compile-checked against the `CameraErrorCode` union — a renamed or
+ * dropped code breaks the build here rather than silently going
+ * unhandled.
+ */
+const RECOVERABLE_STITCH_GUIDANCE: Partial<
+  Record<CameraErrorCode, UserFacingStitchError>
+> = {
+  // cv::Stitcher ERR_NEED_MORE_IMGS / the manual pipeline's "0 valid
+  // pairwise matches" — the frames simply don't overlap enough to chain.
+  STITCH_NEED_MORE_IMGS: {
+    title: 'Please pan more slowly',
+    message:
+      "There wasn't enough overlap between the frames to stitch them "
+      + 'together — each frame needs to overlap the one before it.',
+  },
+  // Bundle adjuster produced degenerate camera params (the warp canvas
+  // blew past the size guard) — almost always real camera *translation*
+  // breaking PANORAMA mode's pure-rotation assumption, amplified hugely
+  // on the ultra-wide lens.
+  STITCH_CAMERA_PARAMS_FAIL: {
+    title: 'Please pan more slowly',
+    message:
+      'The view moved too much between frames to line them up — usually '
+      + 'because the phone moved through space rather than just turning. '
+      + 'The ultra-wide (0.5x) lens is especially sensitive to this, so '
+      + 'try 1x for wide scenes.',
+  },
+  // Pairwise homography estimation failed — frames couldn't be aligned.
+  STITCH_HOMOGRAPHY_FAIL: {
+    title: 'Please pan more slowly',
+    message:
+      "The frames couldn't be aligned — keep the phone level and steady so "
+      + 'each frame overlaps the one before it.',
+  },
+  // Ran out of memory finishing the stitch — usually an over-long sweep.
+  STITCH_OOM: {
+    title: 'Try a shorter sweep',
+    message:
+      'This panorama needs more memory than the device can spare to finish '
+      + '— a shorter, narrower sweep (or 1x for wide scenes) will fit.',
+  },
+};
+
+/**
+ * Maps a `CameraErrorCode` to friendly, action-guiding alert copy.
+ *
+ * @returns the title+message for a recoverable stitch failure, or `null`
+ *   if `code` has no single user-recoverable action (the host should
+ *   then show its generic error UI).
+ */
+export function userFacingStitchError(
+  code: CameraErrorCode,
+): UserFacingStitchError | null {
+  return RECOVERABLE_STITCH_GUIDANCE[code] ?? null;
+}