react-native-image-stitcher 0.4.1 → 0.5.1

package/dist/camera/Camera.d.ts

@@ -40,6 +40,7 @@
  */
 import React from 'react';
 import { type StyleProp, type ViewStyle } from 'react-native';
+import type { DrawableFrameProcessor, ReadonlyFrameProcessor } from 'react-native-vision-camera';
 export type CaptureSource = 'ar' | 'non-ar';
 export type CameraLens = '1x' | '0.5x';
 export type StitchMode = 'auto' | 'panorama' | 'scans';
@@ -88,7 +89,16 @@ export type CameraCaptureResult = {
  * Errors surfaced via `onError`.  Classified codes so consumers can
  * branch on the kind of failure (toast vs retry vs report).
  */
-export type CameraErrorCode = 'CAMERA_PERMISSION_DENIED' | 'CAMERA_DEVICE_UNAVAILABLE' | 'PHOTO_CAPTURE_FAILED' | 'PANORAMA_START_FAILED' | 'PANORAMA_FINALIZE_FAILED' | 'STITCH_NEED_MORE_IMGS' | 'STITCH_HOMOGRAPHY_FAIL' | 'STITCH_CAMERA_PARAMS_FAIL' | 'STITCH_OOM' | 'OUTPUT_WRITE_FAILED' | 'UNKNOWN';
+export type CameraErrorCode = 'CAMERA_PERMISSION_DENIED' | 'CAMERA_DEVICE_UNAVAILABLE' | 'PHOTO_CAPTURE_FAILED' | 'PANORAMA_START_FAILED' | 'PANORAMA_FINALIZE_FAILED' | 'STITCH_NEED_MORE_IMGS' | 'STITCH_HOMOGRAPHY_FAIL' | 'STITCH_CAMERA_PARAMS_FAIL' | 'STITCH_OOM' | 'OUTPUT_WRITE_FAILED'
+/**
+ * Vision-camera surfaced a runtime error that isn't a known
+ * transient lifecycle event (those are swallowed inside the SDK's
+ * `<CameraView>`).  Examples that DO reach the host as this code:
+ * `format/invalid-format`, `capture/recording-canceled`,
+ * `device/microphone-permission-denied`, ...  The full error
+ * object is on `.cause` for inspection.
+ */
+ | 'VISION_CAMERA_RUNTIME' | 'UNKNOWN';
 export declare class CameraError extends Error {
     readonly code: CameraErrorCode;
     readonly cause?: unknown;
@@ -130,6 +140,24 @@ export interface CameraProps {
     enablePanoramaMode?: boolean;
     showSettingsButton?: boolean;
     style?: StyleProp<ViewStyle>;
+    /**
+     * Which incremental stitcher engine to drive.  Default
+     * `'batch-keyframe'` — collects accepted JPEGs and runs
+     * `cv::Stitcher` once at finalize time.  This is the v0.4+
+     * production default and what the v0.5 Frame Processor migration
+     * exercises.
+     *
+     * Switch to a live engine (`'firstwins-rectilinear'` or
+     * `'hybrid'`) for low-latency in-flight stitching.  Live engines
+     * exercise the F8.6 pixel-buffer ingest path (skipping the JPEG
+     * encode/decode round-trip; ~30–50 ms saved per accept) when the
+     * Frame Processor driver is active.
+     *
+     * See `docs/f8-frame-processor-plan.md` and the v0.5.0
+     * CHANGELOG for the trade-offs between batch-keyframe and live
+     * engines.
+     */
+    engine?: 'batch-keyframe' | 'hybrid' | 'slitscan-rotate' | 'slitscan-both' | 'firstwins' | 'firstwins-zoomed' | 'firstwins-rectilinear' | 'slitscan';
     /**
      * Optional destination directory for captures.  When set, the lib
      * lands tap-photos at `${outputDir}/photo-${ts}.jpg` and panoramas
@@ -163,6 +191,45 @@ export interface CameraProps {
     onLensChange?: (lens: CameraLens) => void;
     onFramesDropped?: (info: FramesDroppedInfo) => void;
     onError?: (err: CameraError) => void;
+    /**
+     * Optional vision-camera frame processor.  Only attached to the
+     * non-AR preview (AR mode uses ARCameraView, which doesn't expose
+     * a worklet seam).  Build the worklet on the host side with
+     * `useFrameProcessor` from `react-native-vision-camera`.
+     *
+     * Introduced for F8 (FrameProcessor port) — see
+     * `docs/f8-frame-processor-plan.md`.
+     *
+     * As of v0.5 (F8.3) this prop is **deprecated for the standard
+     * non-AR capture flow**: the SDK now installs its own frame
+     * processor via `useFrameProcessorDriver` that pipes pixel
+     * buffers into the incremental stitcher with synthesised pose.
+     * Setting this prop in the default mode will be IGNORED with a
+     * one-time console.warn — supplying your own worklet would race
+     * with the SDK's pixel-buffer feed.
+     *
+     * Three coexistence rules:
+     *   * Default (modern non-AR): SDK owns the worklet, this prop
+     *     is ignored.
+     *   * `legacyDriver={true}`: SDK uses the old `useIncrementalJSDriver`
+     *     (takeSnapshot path).  Honoured for diagnostics or as an
+     *     escape hatch.
+     *   * AR mode: vision-camera Camera isn't mounted, this prop is
+     *     irrelevant.
+     */
+    frameProcessor?: ReadonlyFrameProcessor | DrawableFrameProcessor;
+    /**
+     * Opt back into the legacy `useIncrementalJSDriver` for non-AR
+     * captures (the v0.4 path: `takeSnapshot` → JPEG → cache file →
+     * `IncrementalStitcher.processFrameAtPath`).
+     *
+     * Default `false` (use the new `useFrameProcessorDriver`, which
+     * runs the gate on the camera producer thread at native frame
+     * rate via a vision-camera Frame Processor plugin).  The legacy
+     * path will be removed in v0.6 — set this only if you hit a
+     * specific issue with the new driver and need to ship a fix.
+     */
+    legacyDriver?: boolean;
 }
 /**
  * The public `<Camera>` component.

package/dist/camera/Camera.js

@@ -98,6 +98,7 @@ const useCapture_1 = require("./useCapture");
 const useDeviceOrientation_1 = require("./useDeviceOrientation");
 const incremental_1 = require("../stitching/incremental");
 const useIncrementalJSDriver_1 = require("../stitching/useIncrementalJSDriver");
+const useFrameProcessorDriver_1 = require("../stitching/useFrameProcessorDriver");
 const useIncrementalStitcher_1 = require("../stitching/useIncrementalStitcher");
 const useIMUTranslationGate_1 = require("../sensors/useIMUTranslationGate");
 const paths_1 = require("../utils/paths");
@@ -270,7 +271,7 @@ function extractPanoramaOverrides(props) {
  * The public `<Camera>` component.
  */
 function Camera(props) {
-    const { defaultCaptureSource = 'ar', defaultLens = '1x', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, onLensChange, onFramesDropped, onError, } = props;
+    const { defaultCaptureSource = 'ar', defaultLens = '1x', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, onLensChange, onFramesDropped, onError, frameProcessor: hostFrameProcessor, legacyDriver = false, engine = 'batch-keyframe', } = props;
     const insets = (0, react_native_safe_area_context_1.useSafeAreaInsets)();
     // ── State ───────────────────────────────────────────────────────
     const [arPreference, setArPreference] = (0, react_1.useState)(defaultCaptureSource === 'ar');
@@ -434,10 +435,40 @@ function Camera(props) {
     // imperative pattern (start on hold-start, stop on hold-end) avoids
     // the re-render churn entirely.
     const jsDriver = (0, useIncrementalJSDriver_1.useIncrementalJSDriver)();
-    // Safety: ensure the driver is stopped if the component unmounts
+    // F8.3 — vision-camera Frame Processor variant.  Always
+    // instantiated so we don't have conditional hook calls; only one
+    // of the two drivers actually .start()s per capture.  Stop() on
+    // an idle driver is a no-op.
+    const fpDriver = (0, useFrameProcessorDriver_1.useFrameProcessorDriver)();
+    // Safety: ensure both drivers are stopped if the component unmounts
     // mid-recording.  Empty deps so this only fires on unmount.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    (0, react_1.useEffect)(() => () => { jsDriver.stop(); }, []);
+    (0, react_1.useEffect)(() => () => { jsDriver.stop(); fpDriver.stop(); }, []);
+    // F8.3 — one-shot deprecation warning when the host supplies their
+    // own `frameProcessor` while running in the default (Frame
+    // Processor driver) mode.  Two worklets racing on the same
+    // producer thread would corrupt the engine's workQueue ordering;
+    // the SDK's own worklet wins and the host's is ignored.  Hosts
+    // that *need* a custom worklet must opt into `legacyDriver={true}`
+    // (which switches off the SDK's worklet entirely).
+    const hostFrameProcessorIgnoredWarnedRef = (0, react_1.useRef)(false);
+    if (hostFrameProcessor != null
+        && !legacyDriver
+        && !hostFrameProcessorIgnoredWarnedRef.current) {
+        hostFrameProcessorIgnoredWarnedRef.current = true;
+        // eslint-disable-next-line no-console
+        console.warn('[react-native-image-stitcher] The `frameProcessor` prop on '
+            + '<Camera> is ignored when the default driver is active '
+            + '(legacyDriver=false).  Either remove the prop or set '
+            + 'legacyDriver={true} to opt into the legacy path.');
+    }
+    // The Frame Processor worklet actually bound to vision-camera's
+    // Camera.  Resolution order:
+    //   1. Legacy mode: honor the host's prop (or null).
+    //   2. Modern mode: SDK driver's worklet, regardless of host's prop.
+    const effectiveFrameProcessor = legacyDriver
+        ? (hostFrameProcessor ?? null)
+        : fpDriver.frameProcessor;
     // ── Subscribe to engine state for live keyframe thumbs ──────────
     (0, react_1.useEffect)(() => {
         const sub = (0, incremental_1.subscribeIncrementalState)((state) => {
@@ -493,6 +524,17 @@ function Camera(props) {
         const accepted = incrementalState?.acceptedCount ?? 0;
         if (accepted > lastAcceptedCountRef.current) {
             lastAcceptedCountRef.current = accepted;
+            // F8.3 review-of-review (M3 revert): originally gated this to
+            // `legacyDriver` because the Frame Processor driver doesn't
+            // consult `imuGate` for its own pose synthesis.  That ignored a
+            // load-bearing side effect: `imuGate.resetAnchor()` bounds the
+            // IIR-integrator drift window per-accept, and
+            // `imuGate.getTotalAbsMetres()` is read at finalize time
+            // (Camera.tsx:1097) as `imuTranslationMetres` into the native
+            // stitchMode auto-resolver (PANORAMA vs SCANS).  Without the
+            // per-accept reset, long FP-driver captures let IIR drift
+            // compound → inflated metres → biased toward SCANS.  Keep the
+            // reset firing for ALL non-AR modes.
             if (isNonAR) {
                 imuGate.resetAnchor();
             }
@@ -609,26 +651,44 @@ function Camera(props) {
                 snapshotEveryNAccepts: 1,
                 frameRotationDegrees: orientationRotation,
                 captureOrientation: deviceOrientation,
-                frameSourceMode: isNonAR ? 'jsDriver' : 'arSession',
+                // F8.3 — non-AR captures pick between the new Frame Processor
+                // driver (default) and the legacy JS-snapshot driver (opt-in
+                // via `legacyDriver={true}`).  AR captures always use the
+                // ARSession-driven path.
+                frameSourceMode: isNonAR
+                    ? (legacyDriver ? 'jsDriver' : 'frameProcessor')
+                    : 'arSession',
                 composeWidth: 1920,
                 composeHeight: 1080,
                 canvasWidth: 5000,
                 canvasHeight: 5000,
-                engine: 'batch-keyframe',
+                engine,
                 config: (0, PanoramaSettingsBridge_1.panoramaSettingsToNativeConfig)({
                     ...settings,
                     captureSource: effectiveCaptureSource,
                 }),
             });
+            // F8.3 review-of-review (M3 revert): `imuGate.resetAnchor()`
+            // is load-bearing for the stitchMode auto-resolver (see the
+            // matching comment on the per-accept reset useEffect above).
+            // Keep firing it on every capture start, not just legacy mode.
             imuGate.resetAnchor();
-            // Start pumping vision-camera snapshots into the engine for
-            // non-AR captures.  AR mode feeds frames natively from the
-            // ARSession, so the JS driver stays idle in that path.  This
-            // mirrors AuditCaptureScreen.handleHoldStart's `androidDriver.start`
-            // imperative call — see the comment near `useIncrementalJSDriver`
-            // for why this is NOT done via useEffect.
+            // Start the non-AR frame source.  AR mode feeds natively from
+            // ARSession so both drivers stay idle in that path.
+            //   * Default: Frame Processor driver — worklet runs on the
+            //     producer thread, plugin calls `consumeFrameFromPlugin`
+            //     directly.  No camera ref needed (vision-camera owns it).
+            //   * Legacy: JS driver — `takeSnapshot` + `processFrameAtPath`
+            //     via the cameraRef.
+            // Imperative-pattern rationale: see the useIncrementalJSDriver
+            // comment above re. why this isn't a useEffect.
             if (isNonAR) {
-                jsDriver.start(visionCameraRef);
+                if (legacyDriver) {
+                    jsDriver.start(visionCameraRef);
+                }
+                else {
+                    fpDriver.start();
+                }
             }
         }
         catch (err) {
@@ -644,16 +704,22 @@ function Camera(props) {
         effectiveCaptureSource,
         imuGate,
         jsDriver,
+        fpDriver,
+        legacyDriver,
+        engine,
         onError,
     ]);
     const handleHoldEnd = (0, react_1.useCallback)(async () => {
         if (statusPhase !== 'recording')
             return;
         setStatusPhase('stitching');
-        // Stop pumping new snapshots before finalizing so the engine isn't
-        // racing the final cv::Stitcher pass against late-arriving keyframes.
-        // No-op in AR mode where jsDriver was never started.
+        // Stop pumping new frames before finalizing so the engine isn't
+        // racing the final cv::Stitcher pass against late-arriving
+        // keyframes.  Both stop() calls are no-ops when the
+        // corresponding driver wasn't started (AR mode, or the inactive
+        // driver in non-AR mode).
         jsDriver.stop();
+        fpDriver.stop();
         try {
             // Compose the panorama output path: host-controlled if
             // `outputDir` is set, else the lib's canonical capture dir
@@ -723,6 +789,7 @@ function Camera(props) {
         onError,
         recordingStartedAt,
         jsDriver,
+        fpDriver,
         // F10 Phase 2 review N1 — these four were missing pre-fix.  The
         // callback reads `settings.debug` (to gate the stitchToast),
         // `isNonAR` (to decide whether to read IMU totalAbs translation),
@@ -755,7 +822,26 @@ function Camera(props) {
             // the very first buffered preview frame.  Android takeSnapshot
             // works either way.  Pattern matches AuditCaptureScreen.tsx
             // which has run on `video` (true) for months without issue.
-            video: true, flash: "off", style: react_native_1.StyleSheet.absoluteFill })),
+            video: true, flash: "off", style: react_native_1.StyleSheet.absoluteFill, 
+            // F8 (FrameProcessor port) — host-supplied worklet runs on
+            // the camera producer thread for every frame.  Only wired
+            // in non-AR mode; AR mode uses ARCameraView which doesn't
+            // expose a frame-processor seam.  See
+            // docs/f8-frame-processor-plan.md.
+            cameraProps: effectiveFrameProcessor != null
+                ? { frameProcessor: effectiveFrameProcessor }
+                : undefined, onError: (err) => {
+                // CameraView already filters known transient lifecycle
+                // errors (screen-lock, etc.) before invoking this.  What
+                // reaches here is a real vision-camera runtime issue:
+                // pull `code`/`message` defensively (the type is
+                // `unknown` from CameraView's perspective) and wrap in
+                // a SDK-typed `CameraError` so hosts get a stable shape.
+                const e = err;
+                const codeStr = e?.code ?? 'unknown';
+                const msg = e?.message ?? String(err);
+                onError?.(new CameraError('VISION_CAMERA_RUNTIME', `${codeStr}: ${msg}`, err));
+            } })),
         react_1.default.createElement(CaptureStatusOverlay_1.CaptureStatusOverlay, { phase: statusPhase, topInset: insets.top, recordingStartedAt: recordingStartedAt ?? undefined }),
         settings.debug && (react_1.default.createElement(react_1.default.Fragment, null,
             react_1.default.createElement(CaptureOrientationPill_1.CaptureOrientationPill, { orientation: deviceOrientation, topInset: insets.top }),

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