react-native-image-stitcher 0.14.2 → 0.15.0

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;
+}

package/src/camera/selectCaptureDevice.ts

@@ -47,7 +47,11 @@ export interface DeviceLike {
 export type CaptureDeviceMode =
   /** One multi-cam device spans wide + ultra-wide; switch lenses via zoom. */
   | 'multicam'
-  /** Separate standalone wide + ultra-wide devices; switch by remounting. */
+  /**
+   * Ultra-wide reached by remounting a dedicated ultra-wide device on 0.5x
+   * (the 1x primary may be a multi-cam *or* a standalone wide).  Used when
+   * no multi-cam device can reach the ultra-wide by zoom.
+   */
   | 'standalone-uw'
   /** No ultra-wide anywhere; wide-angle only (no 0.5× chip). */
   | 'wide-only';
@@ -71,6 +75,16 @@ export interface CaptureDeviceSelection<D extends DeviceLike = DeviceLike> {
 const hasLens = (d: DeviceLike, lens: LensType) =>
   d.physicalDevices.includes(lens);
 
+/**
+ * Max `minZoom` a multi-cam device may report and still count as able to
+ * reach the ultra-wide *by zoom*.  Real ultra-wides sit at ~0.5-0.65x, so a
+ * logical device whose zoom range genuinely extends to the ultra-wide reports
+ * `minZoom <= ~0.65`.  A device that only *lists* the ultra-wide (a separate
+ * physical camera on Android/Camera2, not a zoom target) reports
+ * `minZoom = 1.0`.  0.7 cleanly separates the two.
+ */
+const UW_ZOOM_REACH_MAX = 0.7;
+
 /**
  * Choose the back-camera device(s) for capture.
  *
@@ -107,7 +121,13 @@ export function selectCaptureDevice<D extends DeviceLike>(
     (d) =>
       d.isMultiCam &&
       hasLens(d, 'wide-angle-camera') &&
-      hasLens(d, 'ultra-wide-angle-camera'),
+      hasLens(d, 'ultra-wide-angle-camera') &&
+      // Must reach the ultra-wide by zoom.  On iOS the virtual device's zoom
+      // range spans it (minZoom ~0.5); on Android a logical device often
+      // *lists* the ultra-wide while its zoom range starts at 1.0 (separate
+      // physical camera, not a zoom target).  If it can't zoom there, it
+      // does NOT qualify -- we fall through to the device-swap path below.
+      d.minZoom <= UW_ZOOM_REACH_MAX,
   );
   if (multicamCandidates.length > 0) {
     const device = multicamCandidates.reduce((best, d) => {
@@ -135,9 +155,14 @@ export function selectCaptureDevice<D extends DeviceLike>(
   //
   // Prefer a torch-bearing wide-angle device as the `1×`/primary mount.
   const wideDevices = back.filter((d) => hasLens(d, 'wide-angle-camera'));
+  // A *true* standalone ultra-wide (its own id, NOT a multi-cam grouping).
+  // We deliberately do NOT fall back to a multi-cam device: mounting a
+  // logical multi-cam yields its WIDE member, not the ultra-wide, so a
+  // "swap" to it would silently show the wrong FOV.  If the only ultra-wide
+  // lives inside a non-zoomable multi-cam device, it is undeliverable and we
+  // hide the chooser (wide-only) below.
   const ultraWide =
     back.find((d) => !d.isMultiCam && hasLens(d, 'ultra-wide-angle-camera')) ??
-    back.find((d) => hasLens(d, 'ultra-wide-angle-camera')) ??
     null;
 
   if (wideDevices.length > 0 && ultraWide != null) {

package/src/camera/useCapture.ts

@@ -25,7 +25,7 @@
  * still use the SDK's quality + stitching modules.
  */
 
-import { useCallback, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import {
   Camera,
   useCameraDevice,
@@ -309,6 +309,49 @@ export function useCapture(options: UseCaptureOptions = {}): UseCaptureReturn {
     activeZoom = undefined;
   }
 
+  // v0.15 diagnostic (dev-only) — for the "0.5× pill shows but tapping
+  // doesn't switch the camera" report on Android (Samsung).  Logs the
+  // resolved capture mode + the mounted device's zoom range so logcat
+  // reveals whether `minZoom` actually reaches the ultra-wide.  On
+  // Camera2 the logical multi-camera's zoom range usually starts at 1.0
+  // (the ultra-wide is a separate physical id, not a zoom target), so a
+  // zoom-based 0.5× switch is a silent no-op.
+  useEffect(() => {
+    if (!__DEV__) return;
+    const summarise = (d: DeviceLike | null) =>
+      d
+        ? {
+            id: d.id,
+            physical: d.physicalDevices,
+            isMultiCam: d.isMultiCam,
+            minZoom: d.minZoom,
+            neutralZoom: d.neutralZoom,
+            maxZoom: d.maxZoom,
+            hasTorch: d.hasTorch,
+          }
+        : null;
+    const back = (allDevices as unknown as DeviceLike[]).filter(
+      (d) => d.position === 'back',
+    );
+    // eslint-disable-next-line no-console
+    console.log(
+      '[rnimagestitcher] lens-select ' +
+        JSON.stringify({
+          lens: lens ?? null,
+          mode: selection.mode,
+          has0_5x: selection.has0_5x,
+          activeZoom: activeZoom ?? null,
+          selected: summarise(selection.device),
+          ultraWide: summarise(selection.ultraWideDevice),
+          // Full back-camera enumeration — reveals whether a multicam
+          // device merely *lists* the ultra-wide while its zoom range
+          // can't reach it (minZoom ~1.0), and whether a STANDALONE
+          // ultra-wide device exists for the standalone-uw fallback.
+          allBack: back.map(summarise),
+        }),
+    );
+  }, [allDevices, selection, lens, activeZoom]);
+
   // Enumerate ALL physical lens types available on the chosen
   // position so the host can decide whether to render a switcher.
   // Vision-camera's `useCameraDevices()` returns CameraDevice[]; each