react-native-image-stitcher 0.4.0 → 0.5.0

package/dist/camera/CameraView.d.ts

@@ -55,11 +55,23 @@ export interface CameraViewProps {
         x: number;
         y: number;
     }) => void;
+    /**
+     * Forwarded from vision-camera's `<Camera onError>` AFTER lifecycle
+     * errors are filtered.  The SDK's built-in filter swallows:
+     *
+     *   * `system/camera-is-restricted` — screen-lock / DoNotDisturb
+     *     temporarily revokes camera access; vision-camera re-acquires
+     *     on resume.  Logged to console.warn, NOT surfaced.
+     *   * `system/camera-has-been-disconnected` — another app grabbed
+     *     the camera.  Same auto-recovery.
+     *   * `device/camera-already-in-use` — same class as above.
+     *
+     * Real errors (permission denials, hardware failures, malformed
+     * format requests) are forwarded.  Hosts can therefore safely
+     * pipe this to a redbox / Crashlytics without getting paged on
+     * routine screen-lock events.
+     */
+    onError?: (error: unknown) => void;
 }
-/**
- * A forwardRef'd wrapper that exposes the underlying Camera ref
- * to callers (so ``cameraRef.current.takePhoto()`` keeps working),
- * while presenting a smaller API on the outside.
- */
 export declare const CameraView: React.ForwardRefExoticComponent<CameraViewProps & React.RefAttributes<Camera | null>>;
 //# sourceMappingURL=CameraView.d.ts.map

package/dist/camera/CameraView.js

@@ -62,7 +62,33 @@ const react_native_vision_camera_1 = require("react-native-vision-camera");
  * to callers (so ``cameraRef.current.takePhoto()`` keeps working),
  * while presenting a smaller API on the outside.
  */
-exports.CameraView = (0, react_1.forwardRef)(function CameraView({ device, flash = 'off', isActive = true, video = false, guidance, style, cameraProps, }, ref) {
+// Error codes vision-camera reports for transient lifecycle events.
+// Filtered out of the SDK's onError forward (see `handleVcError` in
+// the body): the camera self-recovers when the device comes back into
+// the foreground / regains permission / the other app releases the
+// device.  Surfacing these as host errors causes spurious crash
+// reports during routine phone-lock / app-switch operations.
+const VC_LIFECYCLE_ERROR_CODES = new Set([
+    'system/camera-is-restricted', // screen lock, DoNotDisturb, MDM policy
+    'system/camera-has-been-disconnected', // another app grabbed the camera
+    'device/camera-already-in-use', // same class as above
+]);
+exports.CameraView = (0, react_1.forwardRef)(function CameraView({ device, flash = 'off', isActive = true, video = false, guidance, style, cameraProps, onError, }, ref) {
+    // Error filter — see `VC_LIFECYCLE_ERROR_CODES` for the swallow
+    // list rationale.  `code` on vision-camera's `CameraRuntimeError`
+    // is typed as a string; treat any non-string defensively as a
+    // "forward it" so we don't accidentally swallow unknown errors.
+    const handleVcError = (err) => {
+        const code = err?.code;
+        if (typeof code === 'string' && VC_LIFECYCLE_ERROR_CODES.has(code)) {
+            // eslint-disable-next-line no-console
+            console.warn('[react-native-image-stitcher] vision-camera reported a '
+                + `transient lifecycle error (${code}); the camera will `
+                + 'auto-recover on resume.  Not forwarding to onError.');
+            return;
+        }
+        onError?.(err);
+    };
     // Internal ref so we can both attach to <Camera> and forward outward.
     const innerRef = (0, react_1.useRef)(null);
     (0, react_1.useImperativeHandle)(ref, () => innerRef.current);
@@ -81,7 +107,7 @@ exports.CameraView = (0, react_1.forwardRef)(function CameraView({ device, flash
             // `outputOrientation="device"` rotates the pixels to match
             // how the user is holding the phone, so the saved JPEG is
             // "what you see is what was taken".
-            outputOrientation: "device", torch: flash === 'on' ? 'on' : 'off', ...cameraProps }),
+            outputOrientation: "device", torch: flash === 'on' ? 'on' : 'off', onError: handleVcError, ...cameraProps }),
         guidance ? (react_1.default.createElement(react_native_1.View, { style: styles.guidance, pointerEvents: "none", accessible: true, accessibilityRole: "text" },
             react_1.default.createElement(react_native_1.Text, { style: styles.guidanceText, numberOfLines: 2 }, guidance))) : null));
 });

package/dist/index.d.ts

@@ -65,5 +65,8 @@ export { IncrementalOutcome, incrementalStitcherIsAvailable, subscribeIncrementa
 export type { IncrementalState } from './stitching/incremental';
 export { useIncrementalStitcher } from './stitching/useIncrementalStitcher';
 export { useIncrementalJSDriver } from './stitching/useIncrementalJSDriver';
+export type { UseIncrementalJSDriverOptions, IncrementalJSDriverHandle, } from './stitching/useIncrementalJSDriver';
+export { useFrameProcessorDriver } from './stitching/useFrameProcessorDriver';
+export type { UseFrameProcessorDriverOptions, FrameProcessorDriverHandle, } from './stitching/useFrameProcessorDriver';
 export { stitchVideo } from './stitching/stitchVideo';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -22,7 +22,7 @@
  * adds RetaiLens-specific features on top.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stitchVideo = exports.useIncrementalJSDriver = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = 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.useFrameProcessorDriver = exports.useIncrementalJSDriver = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = 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;
 // ─────────────────────────────────────────────────────────────────────
 // Layer 1 — the high-level <Camera> component
 // ─────────────────────────────────────────────────────────────────────
@@ -141,6 +141,11 @@ var useIncrementalStitcher_1 = require("./stitching/useIncrementalStitcher");
 Object.defineProperty(exports, "useIncrementalStitcher", { enumerable: true, get: function () { return useIncrementalStitcher_1.useIncrementalStitcher; } });
 var useIncrementalJSDriver_1 = require("./stitching/useIncrementalJSDriver");
 Object.defineProperty(exports, "useIncrementalJSDriver", { enumerable: true, get: function () { return useIncrementalJSDriver_1.useIncrementalJSDriver; } });
+// F8.3 — vision-camera Frame Processor variant of the non-AR
+// driver.  Preferred over `useIncrementalJSDriver` in v0.5+; the
+// JS driver stays exported as a deprecated fallback until v0.6.
+var useFrameProcessorDriver_1 = require("./stitching/useFrameProcessorDriver");
+Object.defineProperty(exports, "useFrameProcessorDriver", { enumerable: true, get: function () { return useFrameProcessorDriver_1.useFrameProcessorDriver; } });
 // ── Batch stitching ───────────────────────────────────────────────────
 // Feed a video file straight to OpenCV's cv::Stitcher, bypassing the
 // incremental pipeline.  Useful when you have content captured

package/dist/stitching/incremental.d.ts

@@ -194,11 +194,20 @@ export interface IncrementalStartOptions {
      *   - 'jsDriver' — engine skips AR-session registration; JS
      *     feeds frames via `processFrameAtPath`.  Use in iOS non-AR
      *     captures (vision-camera + gyro).  No AR session required.
-     *
-     * Android ignores this option — its engine always accepts
-     * JS-driven frames.
+     *     LEGACY; deprecated in v0.5, removed in v0.6.
+     *
+     *   - 'frameProcessor' (F8.3 iOS / F8.4 Android, v0.5+) — engine
+     *     flips on `frameProcessorIngestEnabled` so the vision-camera
+     *     Frame Processor plugin (`cv_flow_gate_process_frame`) can
+     *     feed pixel data directly into the engine's gate path.  iOS
+     *     passes the `CVPixelBuffer` straight to `consumeFrame`;
+     *     Android extracts the Y plane to a ByteArray and encodes
+     *     accepted frames to JPEG inline (the platform-specific
+     *     engine-input divergence is tracked as F8.6).  Use in non-AR
+     *     captures driven by `useFrameProcessorDriver`.  Pairs with
+     *     `Camera`'s default driver mode.
      */
-    frameSourceMode?: 'arSession' | 'jsDriver';
+    frameSourceMode?: 'arSession' | 'jsDriver' | 'frameProcessor';
     /** Compose-resolution width in pixels (default 720 for portrait, 960 for landscape). */
     composeWidth?: number;
     /** Compose-resolution height in pixels (default 960 for portrait, 720 for landscape). */

package/dist/stitching/useFrameProcessorDriver.d.ts

@@ -0,0 +1,148 @@
+/**
+ * useFrameProcessorDriver — vision-camera Frame Processor + gyro
+ * driver for the incremental panorama engine.  Replaces
+ * `useIncrementalJSDriver` in non-AR captures.
+ *
+ * Why this exists (vs the JS-driver predecessor)
+ *
+ *   The JS driver takes a JPEG snapshot every ~250 ms and feeds the
+ *   path to `IncrementalStitcher.processFrameAtPath`.  That path
+ *   has three costs:
+ *
+ *     1. JPEG encode (`takeSnapshot` ≈ 30–80 ms on iPhone 16 Pro)
+ *     2. Disk write of the JPEG
+ *     3. JPEG decode + cv::Mat alloc inside the engine
+ *
+ *   Per-frame round-trip ~80 ms means ~4 Hz max throughput, and
+ *   ~80 ms latency between "this is the moment to accept" and "this
+ *   frame is in the engine".  Both numbers caused operator-felt lag
+ *   on long shelf pans.
+ *
+ *   This hook uses vision-camera's Frame Processor instead.  The
+ *   worklet runs on the camera producer thread at the native frame
+ *   rate (30 fps on iOS).  Each frame goes through a JSI plugin
+ *   (`cv_flow_gate_process_frame`) directly into
+ *   `IncrementalStitcher.consumeFrame` — the SAME entry point AR
+ *   mode uses, with the engine's existing KeyframeGate making the
+ *   accept/reject decision.  Rejected frames cost ~3–8 ms; accepted
+ *   frames take the same deep-copy + workQueue path AR mode takes.
+ *
+ *   Net wins: no JPEG round-trip on rejected frames, no disk thrash
+ *   during recording, lower latency to accept, full 30 fps gate
+ *   evaluation budget.
+ *
+ * Pose synthesis
+ *
+ *   Non-AR mode has no ARKit pose.  We integrate the gyroscope on
+ *   the JS thread (`react-native-sensors`), accumulate yaw + pitch,
+ *   and publish them via Reanimated `useSharedValue` so the worklet
+ *   can read them WITHOUT a thread hop.  Translation is reported as
+ *   zero (no IMU translation; this is a known limitation we share
+ *   with the legacy driver — drift ~1–2°/min over a 30 s capture is
+ *   below the gate's overlap threshold and rarely matters).
+ *
+ *   Quaternion synthesis (q = q_yaw * q_pitch * q_roll, Tait-Bryan
+ *   YPR order to match the legacy driver's body-frame intent):
+ *     q_yaw   = (0, sin(yaw/2), 0, cos(yaw/2))
+ *     q_pitch = (sin(pitch/2), 0, 0, cos(pitch/2))
+ *     q_roll  = (0, 0, sin(roll/2), cos(roll/2))
+ *
+ *   Expanded (cy, sy = cos/sin(yaw/2); analogous for cp/sp, cr/sr):
+ *     qx = cy*sp*cr + sy*cp*sr
+ *     qy = sy*cp*cr - cy*sp*sr
+ *     qz = cy*cp*sr - sy*sp*cr
+ *     qw = cy*cp*cr + sy*sp*sr
+ *
+ *   When roll=0 this collapses to the 2-axis form
+ *   `(cy*sp, sy*cp, -sy*sp, cy*cp)` the legacy driver used, so
+ *   captures held perfectly level produce identical poses to the
+ *   pre-roll behaviour.
+ *
+ *   Intrinsics are synthesised from the actual frame dimensions
+ *   (`frame.width`, `frame.height`) plus the host-provided
+ *   horizontal/vertical FoV defaults.  The stitcher derives its FoV-
+ *   overlap window from these, so the assumed FoV matters for the
+ *   gate's overlap math but not for the panorama itself (the
+ *   stitcher feature-matches + RANSACs the final alignment).
+ *
+ * Throttling
+ *
+ *   `evalEveryNFrames` controls how often the worklet calls the
+ *   plugin.  Default 1 (every frame).  Set higher to amortise the
+ *   plugin call + consumeFrame's gate evaluation across multiple
+ *   producer-thread frames on lower-end devices.  Independent of —
+ *   and stacks on top of — the stitcher's own internal
+ *   `flowEvalEveryNFrames` (see `KeyframeGate.swift`); both
+ *   throttles can be active simultaneously and the effective cadence
+ *   is `evalEveryNFrames * flowEvalEveryNFrames`.
+ *
+ * Lifecycle
+ *
+ *   `start()` subscribes to the gyro and resets pose accumulators.
+ *   `stop()` unsubscribes and resets.  The returned `frameProcessor`
+ *   is meant to be passed to `<Camera frameProcessor={...} />` —
+ *   it's stable as long as the plugin reference and the FoV props
+ *   haven't changed.  Returns `null` when the plugin isn't loaded
+ *   yet; pass `null`-or-fallback to the Camera in that case.
+ *
+ * Pairing with `IncrementalStitcher.start({frameSourceMode})`
+ *
+ *   The plugin's per-frame call into `consumeFrameFromPlugin` is
+ *   gated by `IncrementalStitcher.frameProcessorIngestEnabled`,
+ *   which is TRUE only when the stitcher was started with
+ *   `frameSourceMode === 'frameProcessor'`.  Hosts MUST call
+ *   `incrementalStitcher.start({ frameSourceMode: 'frameProcessor',
+ *   ... })` to actually get frames into the engine — otherwise the
+ *   worklet runs to completion but the wrapper drops the call.
+ *   `Camera.tsx` does this wiring automatically when the host opts
+ *   into this driver.
+ */
+import type { ReadonlyFrameProcessor } from 'react-native-vision-camera';
+export interface UseFrameProcessorDriverOptions {
+    /**
+     * Gyro sample interval in ms (~30 Hz default).  Drives the JS-
+     * thread pose integration loop; not the producer-thread plugin
+     * call rate (the plugin runs at vision-camera's frame rate,
+     * usually 30 fps).
+     */
+    gyroIntervalMs?: number;
+    /**
+     * Approximate horizontal FoV of the device camera, used to
+     * synthesise `fx` from frame width.  Default 65° matches a typical
+     * mid-tier smartphone main camera.  Host apps that know the actual
+     * FoV (e.g. via `Camera.getCameraFormat`) should pass it here —
+     * the engine's overlap gate gets a slightly better estimate.
+     */
+    fovHorizDegrees?: number;
+    /**
+     * Approximate vertical FoV of the device camera, used to
+     * synthesise `fy` from frame height.  Default 50° matches a
+     * typical 4:3 phone camera in landscape; for 16:9 portrait you
+     * probably want ~75°.
+     */
+    fovVertDegrees?: number;
+    /**
+     * Evaluate the plugin every Nth producer-thread frame.  Default 1
+     * (every frame).  Higher values reduce the producer-thread cost
+     * linearly at the price of acceptance latency — N=3 with 30 fps
+     * source = up to 100 ms before a key moment is evaluated.
+     */
+    evalEveryNFrames?: number;
+}
+export interface FrameProcessorDriverHandle {
+    /** Subscribe to the gyro + reset pose accumulators.  Idempotent. */
+    start: () => void;
+    /** Unsubscribe + reset pose. */
+    stop: () => void;
+    /**
+     * Pass this to `<Camera frameProcessor={...} />`.  `null` until
+     * the JSI plugin is loaded (typically resolves within ~1 frame of
+     * mount); the consumer should fall back to undefined / a no-op
+     * processor in that window.
+     */
+    frameProcessor: ReadonlyFrameProcessor | null;
+    /** Whether `start()` has been called and `stop()` hasn't. */
+    isRunning: boolean;
+}
+export declare function useFrameProcessorDriver(options?: UseFrameProcessorDriverOptions): FrameProcessorDriverHandle;
+//# sourceMappingURL=useFrameProcessorDriver.d.ts.map

package/dist/stitching/useFrameProcessorDriver.js

@@ -0,0 +1,321 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * useFrameProcessorDriver — vision-camera Frame Processor + gyro
+ * driver for the incremental panorama engine.  Replaces
+ * `useIncrementalJSDriver` in non-AR captures.
+ *
+ * Why this exists (vs the JS-driver predecessor)
+ *
+ *   The JS driver takes a JPEG snapshot every ~250 ms and feeds the
+ *   path to `IncrementalStitcher.processFrameAtPath`.  That path
+ *   has three costs:
+ *
+ *     1. JPEG encode (`takeSnapshot` ≈ 30–80 ms on iPhone 16 Pro)
+ *     2. Disk write of the JPEG
+ *     3. JPEG decode + cv::Mat alloc inside the engine
+ *
+ *   Per-frame round-trip ~80 ms means ~4 Hz max throughput, and
+ *   ~80 ms latency between "this is the moment to accept" and "this
+ *   frame is in the engine".  Both numbers caused operator-felt lag
+ *   on long shelf pans.
+ *
+ *   This hook uses vision-camera's Frame Processor instead.  The
+ *   worklet runs on the camera producer thread at the native frame
+ *   rate (30 fps on iOS).  Each frame goes through a JSI plugin
+ *   (`cv_flow_gate_process_frame`) directly into
+ *   `IncrementalStitcher.consumeFrame` — the SAME entry point AR
+ *   mode uses, with the engine's existing KeyframeGate making the
+ *   accept/reject decision.  Rejected frames cost ~3–8 ms; accepted
+ *   frames take the same deep-copy + workQueue path AR mode takes.
+ *
+ *   Net wins: no JPEG round-trip on rejected frames, no disk thrash
+ *   during recording, lower latency to accept, full 30 fps gate
+ *   evaluation budget.
+ *
+ * Pose synthesis
+ *
+ *   Non-AR mode has no ARKit pose.  We integrate the gyroscope on
+ *   the JS thread (`react-native-sensors`), accumulate yaw + pitch,
+ *   and publish them via Reanimated `useSharedValue` so the worklet
+ *   can read them WITHOUT a thread hop.  Translation is reported as
+ *   zero (no IMU translation; this is a known limitation we share
+ *   with the legacy driver — drift ~1–2°/min over a 30 s capture is
+ *   below the gate's overlap threshold and rarely matters).
+ *
+ *   Quaternion synthesis (q = q_yaw * q_pitch * q_roll, Tait-Bryan
+ *   YPR order to match the legacy driver's body-frame intent):
+ *     q_yaw   = (0, sin(yaw/2), 0, cos(yaw/2))
+ *     q_pitch = (sin(pitch/2), 0, 0, cos(pitch/2))
+ *     q_roll  = (0, 0, sin(roll/2), cos(roll/2))
+ *
+ *   Expanded (cy, sy = cos/sin(yaw/2); analogous for cp/sp, cr/sr):
+ *     qx = cy*sp*cr + sy*cp*sr
+ *     qy = sy*cp*cr - cy*sp*sr
+ *     qz = cy*cp*sr - sy*sp*cr
+ *     qw = cy*cp*cr + sy*sp*sr
+ *
+ *   When roll=0 this collapses to the 2-axis form
+ *   `(cy*sp, sy*cp, -sy*sp, cy*cp)` the legacy driver used, so
+ *   captures held perfectly level produce identical poses to the
+ *   pre-roll behaviour.
+ *
+ *   Intrinsics are synthesised from the actual frame dimensions
+ *   (`frame.width`, `frame.height`) plus the host-provided
+ *   horizontal/vertical FoV defaults.  The stitcher derives its FoV-
+ *   overlap window from these, so the assumed FoV matters for the
+ *   gate's overlap math but not for the panorama itself (the
+ *   stitcher feature-matches + RANSACs the final alignment).
+ *
+ * Throttling
+ *
+ *   `evalEveryNFrames` controls how often the worklet calls the
+ *   plugin.  Default 1 (every frame).  Set higher to amortise the
+ *   plugin call + consumeFrame's gate evaluation across multiple
+ *   producer-thread frames on lower-end devices.  Independent of —
+ *   and stacks on top of — the stitcher's own internal
+ *   `flowEvalEveryNFrames` (see `KeyframeGate.swift`); both
+ *   throttles can be active simultaneously and the effective cadence
+ *   is `evalEveryNFrames * flowEvalEveryNFrames`.
+ *
+ * Lifecycle
+ *
+ *   `start()` subscribes to the gyro and resets pose accumulators.
+ *   `stop()` unsubscribes and resets.  The returned `frameProcessor`
+ *   is meant to be passed to `<Camera frameProcessor={...} />` —
+ *   it's stable as long as the plugin reference and the FoV props
+ *   haven't changed.  Returns `null` when the plugin isn't loaded
+ *   yet; pass `null`-or-fallback to the Camera in that case.
+ *
+ * Pairing with `IncrementalStitcher.start({frameSourceMode})`
+ *
+ *   The plugin's per-frame call into `consumeFrameFromPlugin` is
+ *   gated by `IncrementalStitcher.frameProcessorIngestEnabled`,
+ *   which is TRUE only when the stitcher was started with
+ *   `frameSourceMode === 'frameProcessor'`.  Hosts MUST call
+ *   `incrementalStitcher.start({ frameSourceMode: 'frameProcessor',
+ *   ... })` to actually get frames into the engine — otherwise the
+ *   worklet runs to completion but the wrapper drops the call.
+ *   `Camera.tsx` does this wiring automatically when the host opts
+ *   into this driver.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFrameProcessorDriver = useFrameProcessorDriver;
+const react_1 = require("react");
+const react_native_sensors_1 = require("react-native-sensors");
+// Reanimated's `useSharedValue` is the documented vision-camera
+// idiom, but it's a heavy peer dep.  `react-native-worklets-core`
+// (already a transitive dep via vision-camera v4 on RN 0.84) exposes
+// the same API surface (a `value` getter/setter readable from
+// worklets and the JS thread) and is sufficient for our use.
+const react_native_worklets_core_1 = require("react-native-worklets-core");
+const react_native_vision_camera_1 = require("react-native-vision-camera");
+function useFrameProcessorDriver(options = {}) {
+    const { gyroIntervalMs = 33, fovHorizDegrees = 65, fovVertDegrees = 50, evalEveryNFrames = 1, } = options;
+    // ── Plugin acquisition ──────────────────────────────────────────
+    //
+    // `initFrameProcessorPlugin` can return `undefined` if called
+    // before vision-camera's plugin registry has finished initialising
+    // (race observed in F8.1.a).  We retry on a fixed timer instead of
+    // firing on every render — the earlier render-driven pattern
+    // (adversarial-review H3) re-invoked `initFrameProcessorPlugin`
+    // 60+ times per second during recording, and the vision-camera
+    // contract for repeated lookups is undocumented.
+    //
+    // Pattern: mount-once useEffect, try synchronously, fall back to a
+    // 16-ms retry timer until success or unmount.
+    const [plugin, setPlugin] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        let cancelled = false;
+        let timerId = null;
+        const tryAcquire = () => {
+            if (cancelled)
+                return;
+            const p = react_native_vision_camera_1.VisionCameraProxy.initFrameProcessorPlugin('cv_flow_gate_process_frame', {});
+            if (p != null) {
+                setPlugin(p);
+                return;
+            }
+            // ~one display-frame retry — matches the F8.1.a observation
+            // that the registry becomes ready by the next render tick.
+            timerId = setTimeout(tryAcquire, 16);
+        };
+        tryAcquire();
+        return () => {
+            cancelled = true;
+            if (timerId != null)
+                clearTimeout(timerId);
+        };
+        // Empty deps on purpose — runs ONCE on mount.  Re-acquiring on
+        // re-render would race with worklet binding.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // ── Shared values (worklet ↔ JS thread) ─────────────────────────
+    //
+    // Reanimated guarantees coherent reads from the producer thread.
+    // We write yaw/pitch on the JS thread (gyro callbacks); the worklet
+    // reads them every frame.  No round-trip cost — these are mapped
+    // into the worklet's runtime by the Reanimated bridge.
+    //
+    // FoV-derived values (the "half-angle tangent reciprocal"
+    // f-numerators) are pre-computed on the JS thread + published via
+    // shared values so the worklet's dependency array shrinks to just
+    // `[plugin]`.  Earlier draft baked `fovHorizDegrees` /
+    // `fovVertDegrees` into the closure → worklet re-serialised on
+    // every host re-render that changed the prop refs (adversarial-
+    // review M1).
+    const sharedYaw = (0, react_native_worklets_core_1.useSharedValue)(0);
+    const sharedPitch = (0, react_native_worklets_core_1.useSharedValue)(0);
+    // F8.3-followup-roll — integrate gyroscope Z (out-of-screen for a
+    // portrait device) to track wrist-twist roll.  Field captures with
+    // casual hand-hold rarely stay perfectly level; without this the
+    // pose stream lies and the cv::Stitcher's intrinsic estimator may
+    // pick a worse projection mode.
+    const sharedRoll = (0, react_native_worklets_core_1.useSharedValue)(0);
+    const sharedFrameCounter = (0, react_native_worklets_core_1.useSharedValue)(0);
+    const sharedEvalEveryN = (0, react_native_worklets_core_1.useSharedValue)(Math.max(1, evalEveryNFrames));
+    const sharedFxNumerator = (0, react_native_worklets_core_1.useSharedValue)(1.0 / (2.0 * Math.tan((fovHorizDegrees * Math.PI / 180) / 2)));
+    const sharedFyNumerator = (0, react_native_worklets_core_1.useSharedValue)(1.0 / (2.0 * Math.tan((fovVertDegrees * Math.PI / 180) / 2)));
+    // Keep prop-derived shared values in sync.  Cheap re-renders;
+    // these don't trigger worklet rebuild.
+    (0, react_1.useEffect)(() => {
+        sharedEvalEveryN.value = Math.max(1, evalEveryNFrames);
+    }, [evalEveryNFrames, sharedEvalEveryN]);
+    (0, react_1.useEffect)(() => {
+        sharedFxNumerator.value =
+            1.0 / (2.0 * Math.tan((fovHorizDegrees * Math.PI / 180) / 2));
+    }, [fovHorizDegrees, sharedFxNumerator]);
+    (0, react_1.useEffect)(() => {
+        sharedFyNumerator.value =
+            1.0 / (2.0 * Math.tan((fovVertDegrees * Math.PI / 180) / 2));
+    }, [fovVertDegrees, sharedFyNumerator]);
+    // ── Lifecycle state (JS thread only) ────────────────────────────
+    const gyroSubRef = (0, react_1.useRef)(null);
+    const lastGyroAtRef = (0, react_1.useRef)(null);
+    const isRunningRef = (0, react_1.useRef)(false);
+    const stop = (0, react_1.useCallback)(() => {
+        if (gyroSubRef.current) {
+            gyroSubRef.current.unsubscribe();
+            gyroSubRef.current = null;
+        }
+        isRunningRef.current = false;
+        sharedYaw.value = 0;
+        sharedPitch.value = 0;
+        sharedRoll.value = 0;
+        sharedFrameCounter.value = 0;
+        lastGyroAtRef.current = null;
+    }, [sharedYaw, sharedPitch, sharedRoll, sharedFrameCounter]);
+    const start = (0, react_1.useCallback)(() => {
+        if (isRunningRef.current)
+            return;
+        sharedYaw.value = 0;
+        sharedPitch.value = 0;
+        sharedRoll.value = 0;
+        sharedFrameCounter.value = 0;
+        lastGyroAtRef.current = null;
+        isRunningRef.current = true;
+        // Gyro integration.  Each sample carries angular velocity in
+        // rad/s; multiply by dt to accumulate displacement.  Axes for a
+        // device held portrait:
+        //   y = horizontal pan (yaw, about world-Y)
+        //   x = vertical tilt (pitch, about world-X)
+        //   z = wrist-twist roll (about world-Z, normal to the screen)
+        // Signs match the legacy `useIncrementalJSDriver` for x/y; z
+        // follows the same right-hand-rule convention.  If field
+        // captures show inverted roll, flip the sign on `z * dt` below.
+        (0, react_native_sensors_1.setUpdateIntervalForType)(react_native_sensors_1.SensorTypes.gyroscope, gyroIntervalMs);
+        gyroSubRef.current = react_native_sensors_1.gyroscope.subscribe({
+            next: ({ x, y, z }) => {
+                const now = Date.now();
+                if (lastGyroAtRef.current === null) {
+                    lastGyroAtRef.current = now;
+                    return;
+                }
+                const dt = (now - lastGyroAtRef.current) / 1000.0;
+                lastGyroAtRef.current = now;
+                sharedYaw.value += y * dt;
+                sharedPitch.value += x * dt;
+                sharedRoll.value += z * dt;
+            },
+            error: (err) => {
+                // eslint-disable-next-line no-console
+                console.warn('[useFrameProcessorDriver] gyro error', err);
+            },
+        });
+    }, [gyroIntervalMs, sharedYaw, sharedPitch, sharedRoll, sharedFrameCounter]);
+    // ── Worklet ─────────────────────────────────────────────────────
+    //
+    // Memoised: rebuilt only when the plugin acquires (null → defined)
+    // or when the FoV props change (cheap math but they're in the
+    // closure so they must be in the deps).  Shared values are NOT in
+    // the deps — Reanimated wires their .value reads through the
+    // worklet's frozen runtime independently of React's render cycle.
+    const frameProcessor = (0, react_native_vision_camera_1.useFrameProcessor)((frame) => {
+        'worklet';
+        if (plugin == null)
+            return;
+        // Throttle: only every Nth frame.  Counter increments first so
+        // frame #0 is "due" (N>=1 always divides 0).  Cheaper than
+        // calling the plugin on rejected frames; saves the ~1 µs
+        // marshalling cost per skip.
+        sharedFrameCounter.value += 1;
+        const N = sharedEvalEveryN.value;
+        if (N > 1 && (sharedFrameCounter.value % N) !== 0)
+            return;
+        // Synthesise quaternion from accumulated yaw + pitch + roll.
+        // YPR Tait-Bryan order: q = q_yaw * q_pitch * q_roll.  When
+        // roll=0 this reduces to the legacy 2-axis form (cy*sp, sy*cp,
+        // -sy*sp, cy*cp), so captures held level produce identical
+        // poses to the pre-F8.3-followup-roll behaviour.  See the
+        // expanded math in the file header doc-comment.
+        const halfYaw = sharedYaw.value / 2;
+        const halfPitch = sharedPitch.value / 2;
+        const halfRoll = sharedRoll.value / 2;
+        const cy_ = Math.cos(halfYaw);
+        const sy_ = Math.sin(halfYaw);
+        const cp = Math.cos(halfPitch);
+        const sp = Math.sin(halfPitch);
+        const cr = Math.cos(halfRoll);
+        const sr = Math.sin(halfRoll);
+        const qx = cy_ * sp * cr + sy_ * cp * sr;
+        const qy = sy_ * cp * cr - cy_ * sp * sr;
+        const qz = cy_ * cp * sr - sy_ * sp * cr;
+        const qw = cy_ * cp * cr + sy_ * sp * sr;
+        // Intrinsics from FoV + actual frame dims.
+        //   fx = w * (1 / (2 * tan(fovH/2)))   (the parenthesised half
+        // is the precomputed `sharedFxNumerator` — see M1 fix).
+        const w = frame.width;
+        const h = frame.height;
+        const fx = w * sharedFxNumerator.value;
+        const fy = h * sharedFyNumerator.value;
+        plugin.call(frame, {
+            tx: 0, ty: 0, tz: 0,
+            qx, qy, qz, qw,
+            fx, fy,
+            cx: w / 2, cy: h / 2,
+            imageWidth: w, imageHeight: h,
+            timestampMs: 0,
+            // 2 == RNSARTrackingState.tracking — we always claim "good
+            // tracking" because there's no ARKit signal to differentiate
+            // (matches legacy useIncrementalJSDriver semantics).
+            trackingStateRaw: 2,
+        });
+        // Deps array intentionally minimal: only `plugin` actually
+        // requires worklet rebuild.  All FoV / pose / counter / cadence
+        // values flow through stable shared-value refs that Reanimated
+        // wires through the producer-thread runtime independently of
+        // React's render cycle.  (Adversarial-review M1.)
+    }, [plugin]);
+    // ── Return handle ───────────────────────────────────────────────
+    //
+    // Returns a getter for `isRunning` so callers always see the live
+    // state (the hook itself doesn't re-render on start/stop — that's
+    // intentional, avoids stale-Camera-prop churn).
+    return (0, react_1.useMemo)(() => ({
+        start,
+        stop,
+        frameProcessor: plugin != null ? frameProcessor : null,
+        get isRunning() { return isRunningRef.current; },
+    }), [start, stop, plugin, frameProcessor]);
+}
+//# sourceMappingURL=useFrameProcessorDriver.js.map

package/dist/stitching/useIncrementalJSDriver.js

@@ -44,6 +44,11 @@ exports.useIncrementalJSDriver = useIncrementalJSDriver;
 const react_1 = require("react");
 const react_native_1 = require("react-native");
 const react_native_sensors_1 = require("react-native-sensors");
+// One-shot deprecation flag — module-scoped so multiple host
+// instances of the hook all share the same gate and we only emit
+// the warning the first time anyone calls .start() in this
+// process.
+let deprecationWarningEmitted = false;
 function getNativeIncremental() {
     const m = react_native_1.NativeModules['IncrementalStitcher'];
     if (!m || typeof m !== 'object')
@@ -88,6 +93,22 @@ function useIncrementalJSDriver(options = {}) {
         // non-AR mode.
         if (isRunningRef.current)
             return;
+        // F8.5 — one-shot deprecation warning.  v0.5.0 introduced
+        // `useFrameProcessorDriver` (vision-camera producer-thread
+        // path, native frame rate, no JPEG round-trip).  The legacy
+        // takeSnapshot path stays available for one minor cycle to
+        // give hosts time to migrate, then is removed in v0.6.
+        if (!deprecationWarningEmitted) {
+            deprecationWarningEmitted = true;
+            // eslint-disable-next-line no-console
+            console.warn('[react-native-image-stitcher] `useIncrementalJSDriver` '
+                + 'is DEPRECATED as of v0.5.0 and will be REMOVED in '
+                + 'v0.6.0.  Migrate to `useFrameProcessorDriver` (or '
+                + 'simply let `<Camera>` use its default driver — no host '
+                + 'code change needed).  Opt-out via the `legacyDriver` '
+                + 'prop on `<Camera>` if you need to stay on the legacy '
+                + 'path temporarily.');
+        }
         const native = getNativeIncremental();
         if (!native)
             return;