react-native-image-stitcher 0.13.0 → 0.14.0

package/dist/camera/PanoramaBandOverlay.d.ts

@@ -115,5 +115,81 @@ export interface PanoramaBandOverlayProps {
      */
     captureOrientation?: BandCaptureOrientation;
 }
+/**
+ * Resolve band layout from capture orientation.  2026-05-18 (Issue #3)
+ * — uses the 4-way `BandCaptureOrientation` instead of the 2-way
+ * `state.isLandscape` so we can pick the right flex direction +
+ * arrow glyph in EACH landscape rotation.
+ *
+ * The two landscape rotations require different JS-coordinate setups
+ * because the phone tilts the JS coordinate system relative to the
+ * user differently:
+ *
+ *   LANDSCAPE-LEFT  (Apple: home indicator on user's RIGHT; phone
+ *                    rotated 90° CCW from portrait).
+ *     JS-left  = user-top
+ *     JS-right = user-bottom
+ *     Band at JS-bottom edge appears on user's RIGHT edge.
+ *     For "oldest at user-top, newest at user-bottom":
+ *       flexDirection = 'row' (array[0] at JS-left = user-top).
+ *     For arrow appearing as user-DOWN-arrow:
+ *       glyph `←` (rotated 90° CCW = points user-down).
+ *
+ *   LANDSCAPE-RIGHT (Apple: home indicator on user's LEFT; phone
+ *                    rotated 90° CW from portrait).
+ *     JS-left  = user-bottom
+ *     JS-right = user-top
+ *     Band at JS-TOP edge appears on user's RIGHT edge (so we move
+ *     the band to JS-top here, not JS-bottom).
+ *     For "oldest at user-top, newest at user-bottom":
+ *       flexDirection = 'row-reverse' (array[0] at JS-right = user-top).
+ *     For arrow appearing as user-DOWN-arrow:
+ *       glyph `→` (rotated 90° CW = points user-down).
+ *
+ *   PORTRAIT (and portrait-upside-down — collapsed because the band's
+ *             bottom-anchored position remains sensible either way):
+ *     Band at JS-bottom = user-bottom.  Row left-to-right.  Arrow `→`
+ *     reads as user-right-arrow (pointing along the horizontal pan
+ *     direction).
+ */
+/**
+ * v0.13.1 — pure rotation-decision helpers, extracted for unit testing
+ * (the lib's jest config is pure-TS, no component mounting; see
+ * jest.config.js).  These encode the orientation contract the band
+ * relies on, so a regression in the angles/branches is caught in CI
+ * rather than only on-device.
+ *
+ * `bandThumbRotation` — the CSS rotate transform that aligns a thumb's
+ * pixels with the band box.  Returns the transform array RN expects, or
+ * `undefined` for "no rotation".  Two regimes:
+ *   - vertical=false (portrait-locked UI): the box is device-aligned, so
+ *     a landscape device needs a 90° counter-rotation (CW for
+ *     landscape-left, CCW for landscape-right).
+ *   - vertical=true (non-locked, OS-rotated framebuffer): the screen
+ *     rotation already did half the work, so the compensation is the
+ *     OPPOSITE sign.
+ * Exported as `_bandThumbRotationForTests`.
+ */
+declare function bandThumbRotation(orientation: BandCaptureOrientation, vertical: boolean): Array<{
+    rotate: string;
+}> | undefined;
+/**
+ * v0.13.1 — the rotation actually applied to the per-keyframe (multi-
+ * thumb) TILES.  This is the EXIF double-rotation fix: the saved
+ * `keyframe-N.jpg` is sensor-native landscape + EXIF Orientation 6, which
+ * RN's <Image> already auto-rotates upright.  So in the portrait-locked
+ * (vertical=false) path NO further transform is applied — adding one
+ * double-rotates (the original v0.12 bug).  Only the non-locked
+ * (vertical=true) path needs the compensation.  Returns `undefined` for
+ * "no transform".  Exported as `_tileRotationForTests`.
+ */
+declare function tileRotation(orientation: BandCaptureOrientation, vertical: boolean): Array<{
+    rotate: string;
+}> | undefined;
+/** @internal test-only export — see `bandThumbRotation`. */
+export declare const _bandThumbRotationForTests: typeof bandThumbRotation;
+/** @internal test-only export — see `tileRotation`. */
+export declare const _tileRotationForTests: typeof tileRotation;
 export declare function PanoramaBandOverlay({ state, frameUris, captureOrientation, vertical, }: PanoramaBandOverlayProps): React.JSX.Element | null;
+export {};
 //# sourceMappingURL=PanoramaBandOverlay.d.ts.map

package/dist/camera/PanoramaBandOverlay.js

@@ -92,6 +92,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports._tileRotationForTests = exports._bandThumbRotationForTests = void 0;
 exports.PanoramaBandOverlay = PanoramaBandOverlay;
 const react_1 = __importStar(require("react"));
 const react_native_1 = require("react-native");
@@ -141,6 +142,55 @@ const MULTI_THUMB_HARD_CAP = 32; // safety net; host typically caps at 24
  *     reads as user-right-arrow (pointing along the horizontal pan
  *     direction).
  */
+/**
+ * v0.13.1 — pure rotation-decision helpers, extracted for unit testing
+ * (the lib's jest config is pure-TS, no component mounting; see
+ * jest.config.js).  These encode the orientation contract the band
+ * relies on, so a regression in the angles/branches is caught in CI
+ * rather than only on-device.
+ *
+ * `bandThumbRotation` — the CSS rotate transform that aligns a thumb's
+ * pixels with the band box.  Returns the transform array RN expects, or
+ * `undefined` for "no rotation".  Two regimes:
+ *   - vertical=false (portrait-locked UI): the box is device-aligned, so
+ *     a landscape device needs a 90° counter-rotation (CW for
+ *     landscape-left, CCW for landscape-right).
+ *   - vertical=true (non-locked, OS-rotated framebuffer): the screen
+ *     rotation already did half the work, so the compensation is the
+ *     OPPOSITE sign.
+ * Exported as `_bandThumbRotationForTests`.
+ */
+function bandThumbRotation(orientation, vertical) {
+    if (vertical) {
+        if (orientation === 'landscape-left')
+            return [{ rotate: '-90deg' }];
+        if (orientation === 'landscape-right')
+            return [{ rotate: '90deg' }];
+        return undefined;
+    }
+    if (orientation === 'landscape-left')
+        return [{ rotate: '90deg' }];
+    if (orientation === 'landscape-right')
+        return [{ rotate: '-90deg' }];
+    return undefined;
+}
+/**
+ * v0.13.1 — the rotation actually applied to the per-keyframe (multi-
+ * thumb) TILES.  This is the EXIF double-rotation fix: the saved
+ * `keyframe-N.jpg` is sensor-native landscape + EXIF Orientation 6, which
+ * RN's <Image> already auto-rotates upright.  So in the portrait-locked
+ * (vertical=false) path NO further transform is applied — adding one
+ * double-rotates (the original v0.12 bug).  Only the non-locked
+ * (vertical=true) path needs the compensation.  Returns `undefined` for
+ * "no transform".  Exported as `_tileRotationForTests`.
+ */
+function tileRotation(orientation, vertical) {
+    return vertical ? bandThumbRotation(orientation, vertical) : undefined;
+}
+/** @internal test-only export — see `bandThumbRotation`. */
+exports._bandThumbRotationForTests = bandThumbRotation;
+/** @internal test-only export — see `tileRotation`. */
+exports._tileRotationForTests = tileRotation;
 function layoutFor(orientation, vertical) {
     const commonInner = {
         alignItems: 'center',
@@ -326,42 +376,49 @@ function PanoramaBandOverlay({ state, frameUris, captureOrientation, vertical =
     // transform, so they appeared sideways in portrait-locked
     // landscape captures (the case the example app's batch-keyframe
     // engine hits).
-    const thumbRotationTransform = (0, react_1.useMemo)(() => {
-        // Empirical observation (on-device test 2026-05-28): captured
-        // per-keyframe JPEGs ARE saved in sensor-native landscape (not
-        // user-perspective), despite the cumulative panorama getting
-        // device-orientation rotation via finalize().  So:
-        //
-        //   jsPortrait box + landscape device: box is device-aligned;
-        //     image's "up" is at file-right (sensor convention).  Rotate
-        //     90° CW (landscape-left) / 90° CCW (landscape-right) to
-        //     align image up with box up.
-        //   jsLandscape box + landscape device: box is user-aligned via
-        //     OS screen rotation; image's "up" still at file-right.  To
-        //     align image up with box up, rotate the OPPOSITE direction
-        //     from the jsPortrait case — the screen-rotation already
-        //     handles half the work; we just need to compensate for the
-        //     remaining mismatch.
-        if (vertical) {
-            if (resolvedOrientation === 'landscape-left')
-                return [{ rotate: '-90deg' }];
-            if (resolvedOrientation === 'landscape-right')
-                return [{ rotate: '90deg' }];
-            return undefined;
-        }
-        if (resolvedOrientation === 'landscape-left')
-            return [{ rotate: '90deg' }];
-        if (resolvedOrientation === 'landscape-right')
-            return [{ rotate: '-90deg' }];
-        return undefined;
-    }, [resolvedOrientation, vertical]);
+    // Rotation for the single cumulative thumb (panorama-*.jpg, a JFIF
+    // with NO EXIF tag → RN does not auto-rotate it, so the transform is
+    // always needed).  See `bandThumbRotation` for the angle contract.
+    const thumbRotationTransform = (0, react_1.useMemo)(() => bandThumbRotation(resolvedOrientation, vertical), [resolvedOrientation, vertical]);
     const singleImageStyle = (0, react_1.useMemo)(() => thumbRotationTransform
         ? [react_native_1.StyleSheet.absoluteFill, { transform: thumbRotationTransform }]
         : react_native_1.StyleSheet.absoluteFill, [thumbRotationTransform]);
-    // Same rotation applied to the per-keyframe (multi-thumb) tiles.
-    const multiThumbStyle = (0, react_1.useMemo)(() => thumbRotationTransform
-        ? [styles.multiThumb, { transform: thumbRotationTransform }]
-        : styles.multiThumb, [thumbRotationTransform]);
+    // v0.13.1 — per-keyframe tile rotation is conditional on `vertical`.
+    //
+    // The keyframe JPEGs (`keyframe-N.jpg`) are saved as sensor-native
+    // landscape PIXELS *plus* an EXIF Orientation tag (= 6, "rotate 90°
+    // CW for display") — verified on-device: Android SM-A356U1 640×480
+    // + EXIF6, iOS iPhone16Pro 1920×1080 + EXIF6.  RN's <Image> (Fresco
+    // on Android, ImageIO on iOS) HONORS EXIF and auto-rotates each tile
+    // to gravity-upright on its own.  Whether a *further* JS transform is
+    // needed depends on the band box's coordinate frame:
+    //
+    //   vertical=false (portrait-locked UI): box is in portrait JS coords,
+    //     which align with the EXIF-upright tile → NO transform.  Applying
+    //     one here double-rotates (the original v0.12 bug — tiles appeared
+    //     90° off in portrait-locked landscape captures).  Verified fixed
+    //     on Android portrait-lock.
+    //   vertical=true (non-locked host, device-landscape): box is in
+    //     landscape JS coords, rotated 90° from the EXIF-upright tile →
+    //     the counter-rotation is STILL required (verified on iOS: with no
+    //     transform the tiles sit 90° off).
+    //
+    // So reuse `thumbRotationTransform` (which already encodes the correct
+    // per-orientation angle) ONLY in the vertical=true branch.
+    //
+    // The single cumulative thumb above always needs the transform: its
+    // source (`panorama-*.jpg`) is a JFIF with NO EXIF tag (verified:
+    // header ff d8 ff e0), so RN never auto-rotates it.
+    //
+    // Stitcher is unaffected — it reads `keyframe-N.jpg` with EXIF IGNORED
+    // (IMREAD_IGNORE_ORIENTATION) so it still gets the sensor-native
+    // pixels its pose intrinsics expect.  Display-only.
+    const multiThumbStyle = (0, react_1.useMemo)(() => {
+        const tileTransform = tileRotation(resolvedOrientation, vertical);
+        return tileTransform
+            ? [styles.multiThumb, { transform: tileTransform }]
+            : styles.multiThumb;
+    }, [resolvedOrientation, vertical]);
     return (react_1.default.createElement(react_native_1.View, { pointerEvents: "none", style: [styles.bandBase, layout.band] }, hasMultiThumb ? (
     // Multi-thumb path: one image per accepted keyframe, scrolling
     // horizontally (in JS-coords) within the band.  Content

package/dist/camera/PanoramaConfirmModal.js

@@ -44,7 +44,17 @@ function PanoramaConfirmModal({ visible, panoramaUri, width, height, onSave, onR
     // correctly inside a flexible container without us having to
     // measure the modal's available area on every layout change.
     const aspectRatio = width > 0 && height > 0 ? width / height : 16 / 9;
-    return (react_1.default.createElement(react_native_1.Modal, { visible: visible, animationType: "fade", transparent: true, statusBarTranslucent: true, onRequestClose: onDiscard },
+    return (react_1.default.createElement(react_native_1.Modal, { visible: visible, animationType: "fade", transparent: true, statusBarTranslucent: true, 
+        // v0.13.1 — RN's iOS <Modal> defaults to portrait-only.  Declare
+        // all four so the confirm modal stays aligned with the interface
+        // under a non-locked host.  Mirrors OrientationDriftModal +
+        // PanoramaSettingsModal (v0.12) and CapturePreview (v0.13.1).
+        supportedOrientations: [
+            'portrait',
+            'portrait-upside-down',
+            'landscape-left',
+            'landscape-right',
+        ], onRequestClose: onDiscard },
         react_1.default.createElement(react_native_1.View, { style: styles.backdrop },
             react_1.default.createElement(react_native_1.Text, { style: styles.title, accessibilityRole: "header" }, title),
             react_1.default.createElement(react_native_1.View, { style: styles.imageWrapper },

package/dist/camera/selectCaptureDevice.d.ts

@@ -0,0 +1,93 @@
+/**
+ * selectCaptureDevice — capability-aware back-camera selection.
+ *
+ * Replaces the single-physical-device request that caused two
+ * user-visible bugs (see docs/plans/2026-06-01-v0.13.2-multilens-
+ * device-selection.md):
+ *
+ *   1. 0.5× silently showed the wide-angle FOV on phones where the
+ *      ultra-wide is only exposed inside a multi-cam logical device —
+ *      vision-camera's single-lens filter mis-scored and fell back to
+ *      a plain wide-angle device.
+ *   2. flash threw `flash-not-available` on 0.5× because the standalone
+ *      ultra-wide device has no torch unit.
+ *
+ * Both stem from mounting ONE standalone physical device per lens.  The
+ * fix: prefer a MULTI-CAM device that carries the ultra-wide (so a
+ * single mounted device spans both FOVs via zoom AND carries the torch
+ * through its wide-angle member).  Fall back to standalone devices for
+ * phones — common on Android — where the ultra-wide has no multi-cam
+ * grouping, so we don't regress those.
+ *
+ * Pure + synchronous: takes a plain device list (the structural subset
+ * of vision-camera's `CameraDevice` we need) and returns the choice.
+ * No React, no vision-camera hooks — unit-tested directly.
+ */
+export type LensType = 'ultra-wide-angle-camera' | 'wide-angle-camera' | 'telephoto-camera';
+/**
+ * The structural subset of vision-camera's `CameraDevice` this selector
+ * reads.  Declared locally (not imported) so tests can build synthetic
+ * devices without the full vision-camera type, and so the SDK doesn't
+ * couple its selection logic to vision-camera's evolving shape.
+ */
+export interface DeviceLike {
+    id: string;
+    position: 'front' | 'back' | 'external';
+    physicalDevices: LensType[];
+    isMultiCam: boolean;
+    hasTorch: boolean;
+    minZoom: number;
+    neutralZoom: number;
+    maxZoom: number;
+}
+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. */
+ | 'standalone-uw'
+/** No ultra-wide anywhere; wide-angle only (no 0.5× chip). */
+ | 'wide-only';
+export interface CaptureDeviceSelection<D extends DeviceLike = DeviceLike> {
+    /** The device to mount for the `1×` lens (and for `multicam`, all lenses). */
+    device: D | null;
+    /**
+     * The device to mount when the user picks `0.5×` in `standalone-uw`
+     * mode (a separate physical ultra-wide).  Null in `multicam` (same
+     * device, zoom instead) and `wide-only` (no ultra-wide).
+     */
+    ultraWideDevice: D | null;
+    mode: CaptureDeviceMode;
+    /** Whether a 0.5× chooser should be offered at all. */
+    has0_5x: boolean;
+    /** Whether the `1×`/primary mounted device can flash (drives flash UI). */
+    hasTorch: boolean;
+}
+/**
+ * Choose the back-camera device(s) for capture.
+ *
+ * Priority:
+ *   1. multicam — a multi-cam device containing BOTH wide + ultra-wide
+ *      (best: one device, zoom-switch, torch via the wide member).
+ *   2. standalone-uw — a standalone wide AND a standalone ultra-wide
+ *      exist as separate devices (device-swap on lens change; flash
+ *      hidden on the torchless ultra-wide).
+ *   3. wide-only — no ultra-wide reachable; wide-angle only.
+ *
+ * @param devices  All enumerated camera devices (any position).
+ */
+export declare function selectCaptureDevice<D extends DeviceLike>(devices: readonly D[]): CaptureDeviceSelection<D>;
+/**
+ * Map a UI lens label to a vision-camera `zoom` value for the
+ * `multicam` mode (where lens switching is zoom, not device swap).
+ *
+ * - `1×`   → the device's `neutralZoom` (wide-angle baseline; vision-
+ *   camera docs: "where the camera is in wide-angle mode and hasn't
+ *   switched to ultra-wide or telephoto yet").
+ * - `0.5×` → `minZoom` (the ultra-wide end of the zoom range).
+ *
+ * Returns `neutralZoom` for any non-0.5× label as a safe default.
+ * Only meaningful in `multicam` mode; the standalone path swaps devices
+ * and ignores this.
+ */
+export declare function zoomForLens(device: Pick<DeviceLike, 'minZoom' | 'neutralZoom'>, lens: '1x' | '0.5x'): number;
+//# sourceMappingURL=selectCaptureDevice.d.ts.map

package/dist/camera/selectCaptureDevice.js

@@ -0,0 +1,131 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * selectCaptureDevice — capability-aware back-camera selection.
+ *
+ * Replaces the single-physical-device request that caused two
+ * user-visible bugs (see docs/plans/2026-06-01-v0.13.2-multilens-
+ * device-selection.md):
+ *
+ *   1. 0.5× silently showed the wide-angle FOV on phones where the
+ *      ultra-wide is only exposed inside a multi-cam logical device —
+ *      vision-camera's single-lens filter mis-scored and fell back to
+ *      a plain wide-angle device.
+ *   2. flash threw `flash-not-available` on 0.5× because the standalone
+ *      ultra-wide device has no torch unit.
+ *
+ * Both stem from mounting ONE standalone physical device per lens.  The
+ * fix: prefer a MULTI-CAM device that carries the ultra-wide (so a
+ * single mounted device spans both FOVs via zoom AND carries the torch
+ * through its wide-angle member).  Fall back to standalone devices for
+ * phones — common on Android — where the ultra-wide has no multi-cam
+ * grouping, so we don't regress those.
+ *
+ * Pure + synchronous: takes a plain device list (the structural subset
+ * of vision-camera's `CameraDevice` we need) and returns the choice.
+ * No React, no vision-camera hooks — unit-tested directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectCaptureDevice = selectCaptureDevice;
+exports.zoomForLens = zoomForLens;
+const hasLens = (d, lens) => d.physicalDevices.includes(lens);
+/**
+ * Choose the back-camera device(s) for capture.
+ *
+ * Priority:
+ *   1. multicam — a multi-cam device containing BOTH wide + ultra-wide
+ *      (best: one device, zoom-switch, torch via the wide member).
+ *   2. standalone-uw — a standalone wide AND a standalone ultra-wide
+ *      exist as separate devices (device-swap on lens change; flash
+ *      hidden on the torchless ultra-wide).
+ *   3. wide-only — no ultra-wide reachable; wide-angle only.
+ *
+ * @param devices  All enumerated camera devices (any position).
+ */
+function selectCaptureDevice(devices) {
+    const back = devices.filter((d) => d.position === 'back');
+    if (back.length === 0) {
+        return {
+            device: null,
+            ultraWideDevice: null,
+            mode: 'wide-only',
+            has0_5x: false,
+            hasTorch: false,
+        };
+    }
+    // ── 1. Prefer a multi-cam device that carries BOTH wide + ultra-wide.
+    // Among candidates, prefer the one that ALSO has a torch (so flash
+    // works on every lens), then the one spanning the widest zoom range
+    // (more lenses → more reach), as a stable tiebreak.
+    const multicamCandidates = back.filter((d) => d.isMultiCam &&
+        hasLens(d, 'wide-angle-camera') &&
+        hasLens(d, 'ultra-wide-angle-camera'));
+    if (multicamCandidates.length > 0) {
+        const device = multicamCandidates.reduce((best, d) => {
+            // torch-bearing wins; then wider zoom span; then more lenses.
+            if (d.hasTorch !== best.hasTorch)
+                return d.hasTorch ? d : best;
+            const span = d.maxZoom - d.minZoom;
+            const bestSpan = best.maxZoom - best.minZoom;
+            if (span !== bestSpan)
+                return span > bestSpan ? d : best;
+            return d.physicalDevices.length > best.physicalDevices.length ? d : best;
+        });
+        return {
+            device,
+            ultraWideDevice: null,
+            mode: 'multicam',
+            has0_5x: true,
+            hasTorch: device.hasTorch,
+        };
+    }
+    // ── 2. Standalone ultra-wide + standalone wide as separate devices.
+    // CRITICAL: this fallback is what keeps phones (esp. Android) where
+    // the ultra-wide has NO multi-cam grouping working — without it,
+    // restricting to multicam would REINTRODUCE the "0.5× shows wide" bug
+    // for that device population.
+    //
+    // Prefer a torch-bearing wide-angle device as the `1×`/primary mount.
+    const wideDevices = back.filter((d) => hasLens(d, 'wide-angle-camera'));
+    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) {
+        // Prefer the simplest wide device (fewest extra lenses) with a torch
+        // as the 1× mount, so 1× flash works.  Falls back to any wide device.
+        const primary = wideDevices.find((d) => d.hasTorch) ?? wideDevices[0];
+        return {
+            device: primary,
+            ultraWideDevice: ultraWide,
+            mode: 'standalone-uw',
+            has0_5x: true,
+            hasTorch: primary.hasTorch,
+        };
+    }
+    // ── 3. Wide-angle only (no ultra-wide reachable on this device).
+    const wideOnly = wideDevices.find((d) => d.hasTorch) ?? wideDevices[0] ?? back[0];
+    return {
+        device: wideOnly,
+        ultraWideDevice: null,
+        mode: 'wide-only',
+        has0_5x: false,
+        hasTorch: wideOnly.hasTorch,
+    };
+}
+/**
+ * Map a UI lens label to a vision-camera `zoom` value for the
+ * `multicam` mode (where lens switching is zoom, not device swap).
+ *
+ * - `1×`   → the device's `neutralZoom` (wide-angle baseline; vision-
+ *   camera docs: "where the camera is in wide-angle mode and hasn't
+ *   switched to ultra-wide or telephoto yet").
+ * - `0.5×` → `minZoom` (the ultra-wide end of the zoom range).
+ *
+ * Returns `neutralZoom` for any non-0.5× label as a safe default.
+ * Only meaningful in `multicam` mode; the standalone path swaps devices
+ * and ignores this.
+ */
+function zoomForLens(device, lens) {
+    return lens === '0.5x' ? device.minZoom : device.neutralZoom;
+}
+//# sourceMappingURL=selectCaptureDevice.js.map

package/dist/camera/useCapture.d.ts

@@ -24,6 +24,7 @@
  * still use the SDK's quality + stitching modules.
  */
 import { Camera, useCameraDevice, type PhysicalCameraDeviceType, type TakePhotoOptions } from 'react-native-vision-camera';
+import { type CaptureDeviceMode } from './selectCaptureDevice';
 import type { CaptureResult, QualityThresholds } from '../types';
 /**
  * Hook input.  Everything optional; sensible defaults are applied
@@ -66,8 +67,22 @@ export interface UseCaptureOptions {
      * behaves as if `preferredPhysicalDevice` was undefined).  The
      * returned `availablePhysicalDevices` exposes what the device
      * actually offers so the host can render an appropriate switcher.
+     *
+     * v0.13.2 — superseded by `lens` for `<Camera>`'s own use (see
+     * `selectCaptureDevice`).  Still honoured for direct Layer-2 hosts.
      */
     preferredPhysicalDevice?: PhysicalCameraDeviceType;
+    /**
+     * v0.13.2 — the active UI lens (`1×` / `0.5×`).  When supplied, the
+     * hook uses capability-aware selection (`selectCaptureDevice`): it
+     * prefers a multi-cam device spanning both FOVs (lens switched via
+     * `zoom`, torch available on every lens), and falls back to a
+     * standalone ultra-wide device-swap only where no such multi-cam
+     * device exists.  Fixes the "0.5× shows wide-angle on some phones"
+     * and "flash unavailable on 0.5×" bugs.  When omitted, the legacy
+     * `preferredPhysicalDevice` path is used (backwards-compatible).
+     */
+    lens?: '1x' | '0.5x';
 }
 /**
  * Per-call options for `takePhoto`.  Separate from `UseCaptureOptions`
@@ -136,6 +151,31 @@ export interface UseCaptureReturn {
      * load).  Always populated by the time the camera is mountable.
      */
     availablePhysicalDevices: PhysicalCameraDeviceType[];
+    /**
+     * v0.13.2 — how lenses are switched for the mounted device:
+     *   'multicam'      — one device spans both FOVs; switch via `deviceZoom`.
+     *   'standalone-uw' — separate ultra-wide device; switch by remounting.
+     *   'wide-only'     — no ultra-wide; no 0.5× chooser.
+     */
+    captureMode: CaptureDeviceMode;
+    /**
+     * v0.13.2 — whether the device can offer a 0.5× ultra-wide lens AT ALL
+     * (real capability, replacing the old hardcoded assumption).  Drives
+     * whether `<Camera>` renders the lens chooser.
+     */
+    has0_5x: boolean;
+    /**
+     * v0.13.2 — whether the currently-MOUNTED device has a torch.  Drives
+     * the flash control's availability (the standalone ultra-wide has none).
+     */
+    deviceHasTorch: boolean;
+    /**
+     * v0.13.2 — the `zoom` value to apply for the active lens in
+     * `multicam` mode (0.5× → ultra-wide end, 1× → wide baseline).
+     * `undefined` in standalone/wide-only modes (lens = device identity,
+     * no zoom needed).  Pass to `<CameraView zoom>`.
+     */
+    deviceZoom: number | undefined;
 }
 export declare function useCapture(options?: UseCaptureOptions): UseCaptureReturn;
 //# sourceMappingURL=useCapture.d.ts.map

package/dist/camera/useCapture.js

@@ -29,6 +29,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.useCapture = useCapture;
 const react_1 = require("react");
 const react_native_vision_camera_1 = require("react-native-vision-camera");
+const selectCaptureDevice_1 = require("./selectCaptureDevice");
 const runQualityCheck_1 = require("../quality/runQualityCheck");
 const normaliseOrientation_1 = require("../quality/normaliseOrientation");
 const paths_1 = require("../utils/paths");
@@ -61,28 +62,61 @@ function makeCaptureResult(photo, qualityReport) {
     };
 }
 function useCapture(options = {}) {
-    const { cameraPosition = 'back', enableQualityChecks = false, qualityThresholds, takePhotoOptions, preferredPhysicalDevice, } = options;
+    const { cameraPosition = 'back', enableQualityChecks = false, qualityThresholds, takePhotoOptions, preferredPhysicalDevice, lens, } = options;
     const cameraRef = (0, react_1.useRef)(null);
-    // 2026-05-14 — physical-lens-aware device picker.
+    const allDevices = (0, react_native_vision_camera_1.useCameraDevices)();
+    // v0.13.2 — capability-aware selection (`lens` supplied) vs legacy
+    // per-lens physical-device swap (`preferredPhysicalDevice`).
     //
-    // When `preferredPhysicalDevice` is supplied, ask vision-camera
-    // for a device that exposes that specific physical lens (e.g.,
-    // 'ultra-wide-angle-camera').  Falls back to the position-default
-    // when the device doesn't have that lens.  When undefined, behaves
-    // identically to the pre-2026-05-14 useCameraDevice(position) call.
-    const deviceWithPreferred = (0, react_native_vision_camera_1.useCameraDevice)(cameraPosition, {
+    // Capability-aware: `selectCaptureDevice` prefers a multi-cam device
+    // that spans wide + ultra-wide (so 0.5× is reached via `zoom` and the
+    // torch works on every lens), falling back to a standalone ultra-wide
+    // device-swap only where the platform has no such multi-cam grouping.
+    // This fixes (a) 0.5× silently showing the wide-angle FOV on phones
+    // where the ultra-wide is only inside a multi-cam device, and (b)
+    // flash being unavailable on the torchless standalone ultra-wide.
+    const selection = (0, react_1.useMemo)(() => (0, selectCaptureDevice_1.selectCaptureDevice)(allDevices), [allDevices]);
+    // Legacy path (no `lens`): preserve the pre-v0.13.2 per-physical-lens
+    // request so direct Layer-2 hosts that pass `preferredPhysicalDevice`
+    // are unaffected.
+    const legacyDevice = (0, react_native_vision_camera_1.useCameraDevice)(cameraPosition, {
         physicalDevices: preferredPhysicalDevice ? [preferredPhysicalDevice] : undefined,
     });
-    const deviceFallback = (0, react_native_vision_camera_1.useCameraDevice)(cameraPosition);
-    const device = deviceWithPreferred ?? deviceFallback;
+    const legacyFallback = (0, react_native_vision_camera_1.useCameraDevice)(cameraPosition);
+    // The mounted device:
+    //   - lens supplied + multicam     → the single multi-cam device
+    //     (lens switched via `zoom`, computed below).
+    //   - lens supplied + standalone-uw→ swap to the ultra-wide device on
+    //     0.5×, else the wide primary (matches the legacy swap, but with
+    //     correct device identity from `selectCaptureDevice`).
+    //   - lens supplied + wide-only    → the wide device (0.5× hidden).
+    //   - no lens                      → legacy behaviour.
+    let device;
+    let activeZoom;
+    if (lens != null) {
+        if (selection.mode === 'standalone-uw' && lens === '0.5x') {
+            device = selection.ultraWideDevice ?? selection.device ?? legacyFallback;
+        }
+        else {
+            device = selection.device ?? legacyFallback;
+        }
+        activeZoom =
+            selection.mode === 'multicam' && selection.device
+                ? (0, selectCaptureDevice_1.zoomForLens)(selection.device, lens)
+                : undefined;
+    }
+    else {
+        device = legacyDevice ?? legacyFallback;
+        activeZoom = undefined;
+    }
     // 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
     // has `physicalDevices: PhysicalCameraDeviceType[]`.  We dedupe the
     // union across all devices at `position` so the host sees the full
     // set the platform exposes (some phones expose ultra-wide only via
-    // a separate logical camera, not the main one).
-    const allDevices = (0, react_native_vision_camera_1.useCameraDevices)();
+    // a separate logical camera, not the main one).  `allDevices` is
+    // computed once above (shared with `selectCaptureDevice`).
     const availablePhysicalDevices = (0, react_1.useMemo)(() => {
         const seen = new Set();
         for (const d of allDevices) {
@@ -176,6 +210,10 @@ function useCapture(options = {}) {
         isCapturing,
         takePhoto,
         availablePhysicalDevices,
+        captureMode: selection.mode,
+        has0_5x: selection.has0_5x,
+        deviceHasTorch: device?.hasTorch ?? false,
+        deviceZoom: activeZoom,
     };
 }
 //# sourceMappingURL=useCapture.js.map