react-native-image-stitcher 0.13.0 → 0.14.1

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

package/dist/camera/useContentRotation.d.ts

@@ -0,0 +1,99 @@
+/**
+ * useContentRotation — returns a CSS transform that rotates control
+ * content so labels stay upright relative to device gravity,
+ * regardless of whether the OS rotated the framebuffer.
+ *
+ * ## Why this exists
+ *
+ * v0.12 anchored `<Camera>`'s bottom controls to the home-indicator
+ * edge so they stay in thumb reach on phones in landscape on
+ * non-locked iOS hosts.  The anchoring works because the OS rotates
+ * the framebuffer to match the device, so a JS-bottom view in
+ * landscape is the device's actual landscape-bottom edge.
+ *
+ * On locked-portrait hosts (the most common production
+ * configuration) the OS does NOT rotate the framebuffer when the
+ * device tilts to landscape.  v0.12 still anchored controls to
+ * "JS-bottom" — which is now the device's side edge — so the
+ * shutter sits where the thumb expects, BUT the labels inside
+ * each control (`AR`, `1×`, `0.5×`, the lens chip pills, the gear)
+ * render at their JS-portrait baseline, so the user holding the
+ * device sideways reads them at 90°.
+ *
+ * This hook fixes that by applying a `transform: rotate(±90°)` to
+ * the control's *content* so it appears upright relative to actual
+ * gravity, while the control container itself stays in place.
+ *
+ * ## How the rotation is computed
+ *
+ * Two signals:
+ *   - **Framebuffer rotation** — what rotation has the OS already
+ *     applied to the JS layout?  Read from
+ *     `useWindowDimensions().width > height` — non-locked +
+ *     device-landscape is the only case where the OS rotates,
+ *     and that's exactly when `jsLandscape === true`.
+ *   - **Device-physical rotation** — what rotation does the device
+ *     have relative to gravity?  Read from `useDeviceOrientation()`
+ *     (accelerometer-derived).
+ *
+ * The content rotation we apply is the *difference* between
+ * device-physical and framebuffer rotation, so the net rotation
+ * (content × framebuffer) equals device-physical → labels are
+ * upright in the world.
+ *
+ * ## Truth table
+ *
+ * |  Host config        | Device          | jsLandscape | Net rot |
+ * |---                  |---              |---          |---      |
+ * |  Locked-portrait    | portrait        | false       |  0°     |
+ * |  Locked-portrait    | landscape-left  | false       |  90°    |
+ * |  Locked-portrait    | landscape-right | false       | -90°    |
+ * |  Locked-portrait    | upside-down     | false       | 180°    |
+ * |  Non-locked         | portrait        | false       |  0°     |
+ * |  Non-locked         | landscape-left  | true        |  0°     |
+ * |  Non-locked         | landscape-right | true        |  0°     |
+ *
+ * The 0° case is the common one (locked-portrait + device-portrait
+ * OR non-locked + framebuffer-already-rotated); we return an empty
+ * style object so React skips the layout work.
+ *
+ * ## Caveats
+ *
+ * - Rotation transforms preserve hit-testing in RN 0.84 (verified
+ *   on iOS + Android), but historical RN versions had bugs in this
+ *   area.  If support for older RN is added, retest pressables.
+ * - Containers whose sized layouts depend on un-rotated content
+ *   (e.g. a 100px-wide pill containing text that's now rotated 90°)
+ *   may overflow.  Fixed-size pills (the lens chip, AR toggle,
+ *   flash button) are fine; the header title's `flex: 1 + textAlign:
+ *   center` may need tuning when rotated — see `CaptureHeader`'s
+ *   own rotation handling.
+ */
+import { type ViewStyle } from 'react-native';
+import { type DeviceOrientation } from './useDeviceOrientation';
+export type ContentRotationDeg = 0 | 90 | -90 | 180;
+/**
+ * Return type for `useContentRotation`.  Typed structurally on just
+ * the `transform` property so it spreads cleanly into ViewStyle,
+ * TextStyle, AND ImageStyle — all three accept identical transform
+ * shapes in RN 0.84.  Returning the more specific `ViewStyle` would
+ * collide with ImageStyle's stricter `overflow` enum at <Image>
+ * call sites.
+ */
+export type ContentRotationStyle = {
+    transform?: ViewStyle['transform'];
+};
+/**
+ * Pure rotation computation.  Exported so tests can exercise the
+ * full truth table without booting a React render.
+ */
+export declare function contentRotationDeg(jsLandscape: boolean, deviceOrient: DeviceOrientation): ContentRotationDeg;
+/**
+ * Returns the rotation as a ready-to-spread style object.  Empty
+ * object in the common 0° case so React skips the layout work.
+ * Type `ContentRotationStyle` is structurally just `{ transform? }`
+ * so call sites can spread it into ViewStyle, TextStyle, or
+ * ImageStyle interchangeably.
+ */
+export declare function useContentRotation(): ContentRotationStyle;
+//# sourceMappingURL=useContentRotation.d.ts.map

package/dist/camera/useContentRotation.js

@@ -0,0 +1,124 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * useContentRotation — returns a CSS transform that rotates control
+ * content so labels stay upright relative to device gravity,
+ * regardless of whether the OS rotated the framebuffer.
+ *
+ * ## Why this exists
+ *
+ * v0.12 anchored `<Camera>`'s bottom controls to the home-indicator
+ * edge so they stay in thumb reach on phones in landscape on
+ * non-locked iOS hosts.  The anchoring works because the OS rotates
+ * the framebuffer to match the device, so a JS-bottom view in
+ * landscape is the device's actual landscape-bottom edge.
+ *
+ * On locked-portrait hosts (the most common production
+ * configuration) the OS does NOT rotate the framebuffer when the
+ * device tilts to landscape.  v0.12 still anchored controls to
+ * "JS-bottom" — which is now the device's side edge — so the
+ * shutter sits where the thumb expects, BUT the labels inside
+ * each control (`AR`, `1×`, `0.5×`, the lens chip pills, the gear)
+ * render at their JS-portrait baseline, so the user holding the
+ * device sideways reads them at 90°.
+ *
+ * This hook fixes that by applying a `transform: rotate(±90°)` to
+ * the control's *content* so it appears upright relative to actual
+ * gravity, while the control container itself stays in place.
+ *
+ * ## How the rotation is computed
+ *
+ * Two signals:
+ *   - **Framebuffer rotation** — what rotation has the OS already
+ *     applied to the JS layout?  Read from
+ *     `useWindowDimensions().width > height` — non-locked +
+ *     device-landscape is the only case where the OS rotates,
+ *     and that's exactly when `jsLandscape === true`.
+ *   - **Device-physical rotation** — what rotation does the device
+ *     have relative to gravity?  Read from `useDeviceOrientation()`
+ *     (accelerometer-derived).
+ *
+ * The content rotation we apply is the *difference* between
+ * device-physical and framebuffer rotation, so the net rotation
+ * (content × framebuffer) equals device-physical → labels are
+ * upright in the world.
+ *
+ * ## Truth table
+ *
+ * |  Host config        | Device          | jsLandscape | Net rot |
+ * |---                  |---              |---          |---      |
+ * |  Locked-portrait    | portrait        | false       |  0°     |
+ * |  Locked-portrait    | landscape-left  | false       |  90°    |
+ * |  Locked-portrait    | landscape-right | false       | -90°    |
+ * |  Locked-portrait    | upside-down     | false       | 180°    |
+ * |  Non-locked         | portrait        | false       |  0°     |
+ * |  Non-locked         | landscape-left  | true        |  0°     |
+ * |  Non-locked         | landscape-right | true        |  0°     |
+ *
+ * The 0° case is the common one (locked-portrait + device-portrait
+ * OR non-locked + framebuffer-already-rotated); we return an empty
+ * style object so React skips the layout work.
+ *
+ * ## Caveats
+ *
+ * - Rotation transforms preserve hit-testing in RN 0.84 (verified
+ *   on iOS + Android), but historical RN versions had bugs in this
+ *   area.  If support for older RN is added, retest pressables.
+ * - Containers whose sized layouts depend on un-rotated content
+ *   (e.g. a 100px-wide pill containing text that's now rotated 90°)
+ *   may overflow.  Fixed-size pills (the lens chip, AR toggle,
+ *   flash button) are fine; the header title's `flex: 1 + textAlign:
+ *   center` may need tuning when rotated — see `CaptureHeader`'s
+ *   own rotation handling.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contentRotationDeg = contentRotationDeg;
+exports.useContentRotation = useContentRotation;
+const react_native_1 = require("react-native");
+const useDeviceOrientation_1 = require("./useDeviceOrientation");
+/**
+ * Pure rotation computation.  Exported so tests can exercise the
+ * full truth table without booting a React render.
+ */
+function contentRotationDeg(jsLandscape, deviceOrient) {
+    // Framebuffer rotation relative to device-physical.  Only the
+    // non-locked + device-landscape cases see a rotated framebuffer.
+    // jsLandscape can briefly be true mid-rotation on devices that
+    // aren't a clean landscape orientation; the device-orientation
+    // check below catches those and falls through to 0.
+    const fbRot = !jsLandscape ? 0
+        : deviceOrient === 'landscape-left' ? 90
+            : deviceOrient === 'landscape-right' ? -90
+                : 0;
+    // Device-physical rotation relative to gravity.
+    const deviceRot = deviceOrient === 'portrait' ? 0
+        : deviceOrient === 'landscape-left' ? 90
+            : deviceOrient === 'landscape-right' ? -90
+                : 180;
+    // Net rotation we need to apply to content so that
+    // content + framebuffer = device-physical (upright in the world).
+    // Normalise to [-180, 180] so transform values stay canonical.
+    let net = deviceRot - fbRot;
+    if (net > 180)
+        net -= 360;
+    if (net < -180)
+        net += 360;
+    return net;
+}
+/**
+ * Returns the rotation as a ready-to-spread style object.  Empty
+ * object in the common 0° case so React skips the layout work.
+ * Type `ContentRotationStyle` is structurally just `{ transform? }`
+ * so call sites can spread it into ViewStyle, TextStyle, or
+ * ImageStyle interchangeably.
+ */
+function useContentRotation() {
+    const orient = (0, useDeviceOrientation_1.useDeviceOrientation)();
+    const { width, height } = (0, react_native_1.useWindowDimensions)();
+    const jsLandscape = width > height;
+    const deg = contentRotationDeg(jsLandscape, orient);
+    return deg === 0
+        ? {}
+        : { transform: [{ rotate: `${deg}deg` }] };
+}
+//# sourceMappingURL=useContentRotation.js.map

package/dist/index.d.ts

@@ -20,7 +20,7 @@
  * adds RetaiLens-specific features on top.
  */
 export { Camera, CameraError } from './camera/Camera';
-export type { CameraProps, CameraCaptureResult, CameraErrorCode, CaptureSource, CameraLens, StitchMode, Blender, SeamFinder, Warper, FramesDroppedInfo, } from './camera/Camera';
+export type { CameraProps, CameraCaptureResult, CameraErrorCode, CaptureSource, CaptureSourcesMode, CameraLens, StitchMode, Blender, SeamFinder, Warper, FramesDroppedInfo, } from './camera/Camera';
 export { useARSession, ARTrackingState } from './ar/useARSession';
 export type { UseARSessionReturn, FramePose, } from './ar/useARSession';
 export { useIMUTranslationGate } from './sensors/useIMUTranslationGate';
@@ -47,9 +47,7 @@ export { CaptureStitchStatsToast, useStitchStatsToast, } from './camera/CaptureS
 export type { CaptureStitchStatsToastProps, UseStitchStatsToastReturn, } from './camera/CaptureStitchStatsToast';
 export { CaptureThumbnailStrip } from './camera/CaptureThumbnailStrip';
 export type { CaptureThumbnailItem } from './camera/CaptureThumbnailStrip';
-export { IncrementalPanGuide } from './camera/IncrementalPanGuide';
 export { PanoramaBandOverlay } from './camera/PanoramaBandOverlay';
-export { PanoramaGuidance } from './camera/PanoramaGuidance';
 export { PanoramaSettingsModal } from './camera/PanoramaSettingsModal';
 export type { PanoramaSettingsModalProps } from './camera/PanoramaSettingsModal';
 export { DEFAULT_PANORAMA_SETTINGS, DEFAULT_FLOW_GATE_SETTINGS, DEFAULT_SLITSCAN_SETTINGS, DEFAULT_HYBRID_SETTINGS, } from './camera/PanoramaSettings';

package/dist/index.js

@@ -22,7 +22,7 @@
  * adds RetaiLens-specific features on top.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stitchVideo = exports.useStitcherWorklet = exports.useFrameProcessorDriver = exports.useFrameStream = exports.useThrottledFrameProcessor = exports.useFrameProcessor = exports.useKeyframeStream = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = exports.OrientationDriftModal = exports.useOrientationDrift = exports.useDeviceOrientation = exports.useVideoCapture = exports.useCapture = exports.ViewportCropOverlay = exports.hybridSettingsToNativeConfig = exports.slitscanSettingsToNativeConfig = exports.panoramaSettingsToNativeConfig = exports.DEFAULT_HYBRID_SETTINGS = exports.DEFAULT_SLITSCAN_SETTINGS = exports.DEFAULT_FLOW_GATE_SETTINGS = exports.DEFAULT_PANORAMA_SETTINGS = exports.PanoramaSettingsModal = exports.PanoramaGuidance = exports.PanoramaBandOverlay = exports.IncrementalPanGuide = exports.CaptureThumbnailStrip = exports.useStitchStatsToast = exports.CaptureStitchStatsToast = exports.CaptureOrientationPill = exports.CaptureKeyframePill = exports.CaptureMemoryPill = exports.CaptureDebugOverlay = exports.CaptureStatusOverlay = exports.CapturePreview = exports.CaptureControlsBar = exports.CaptureHeader = exports.CameraView = exports.ARCameraView = exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.CameraError = exports.Camera = void 0;
+exports.stitchVideo = exports.useStitcherWorklet = exports.useFrameProcessorDriver = exports.useFrameStream = exports.useThrottledFrameProcessor = exports.useFrameProcessor = exports.useKeyframeStream = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = exports.OrientationDriftModal = exports.useOrientationDrift = exports.useDeviceOrientation = exports.useVideoCapture = exports.useCapture = exports.ViewportCropOverlay = exports.hybridSettingsToNativeConfig = exports.slitscanSettingsToNativeConfig = exports.panoramaSettingsToNativeConfig = exports.DEFAULT_HYBRID_SETTINGS = exports.DEFAULT_SLITSCAN_SETTINGS = exports.DEFAULT_FLOW_GATE_SETTINGS = exports.DEFAULT_PANORAMA_SETTINGS = exports.PanoramaSettingsModal = exports.PanoramaBandOverlay = exports.CaptureThumbnailStrip = exports.useStitchStatsToast = exports.CaptureStitchStatsToast = exports.CaptureOrientationPill = exports.CaptureKeyframePill = exports.CaptureMemoryPill = exports.CaptureDebugOverlay = exports.CaptureStatusOverlay = exports.CapturePreview = exports.CaptureControlsBar = exports.CaptureHeader = exports.CameraView = exports.ARCameraView = exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.CameraError = exports.Camera = void 0;
 // ─────────────────────────────────────────────────────────────────────
 // Layer 1 — the high-level <Camera> component
 // ─────────────────────────────────────────────────────────────────────
@@ -85,12 +85,13 @@ Object.defineProperty(exports, "CaptureStitchStatsToast", { enumerable: true, ge
 Object.defineProperty(exports, "useStitchStatsToast", { enumerable: true, get: function () { return CaptureStitchStatsToast_1.useStitchStatsToast; } });
 var CaptureThumbnailStrip_1 = require("./camera/CaptureThumbnailStrip");
 Object.defineProperty(exports, "CaptureThumbnailStrip", { enumerable: true, get: function () { return CaptureThumbnailStrip_1.CaptureThumbnailStrip; } });
-var IncrementalPanGuide_1 = require("./camera/IncrementalPanGuide");
-Object.defineProperty(exports, "IncrementalPanGuide", { enumerable: true, get: function () { return IncrementalPanGuide_1.IncrementalPanGuide; } });
+// v0.13.1 — IncrementalPanGuide (drift marker) and PanoramaGuidance
+// (pan-speed pill) are no longer part of the public API.  They remain
+// in the tree as internal-only components but are not exported and not
+// rendered by <Camera> (the `panGuide` / `panoramaGuidance` props were
+// removed).  Re-introduce here if a host need resurfaces.
 var PanoramaBandOverlay_1 = require("./camera/PanoramaBandOverlay");
 Object.defineProperty(exports, "PanoramaBandOverlay", { enumerable: true, get: function () { return PanoramaBandOverlay_1.PanoramaBandOverlay; } });
-var PanoramaGuidance_1 = require("./camera/PanoramaGuidance");
-Object.defineProperty(exports, "PanoramaGuidance", { enumerable: true, get: function () { return PanoramaGuidance_1.PanoramaGuidance; } });
 // Settings modal — the modal is in `PanoramaSettingsModal.tsx`, but
 // the type tree + defaults + JS↔native bridge live in dedicated
 // files since v0.4 (F10).  The modal is now a thin presentational

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Pose-aware panorama capture + stitching for React Native. One <Camera> component, both tap-to-photo and hold-to-pan modes, both AR-backed and IMU-fallback capture paths.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",