react-native-image-stitcher 0.13.0 → 0.14.0

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.0",
   "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",