react-native-image-stitcher 0.4.0 → 0.5.0

package/ios/Sources/RNImageStitcher/IncrementalStitcher.swift

@@ -362,6 +362,29 @@ public final class IncrementalStitcher: NSObject {
     private var hasFirstFrameTranslation: Bool = false
     private var consumeFrameCounter: Int = 0
 
+    /// F8.3 — gate for `consumeFrameFromPlugin` (the vision-camera
+    /// Frame Processor producer-thread entry point).  TRUE only when
+    /// the current capture was started with
+    /// `frameSourceMode == "frameProcessor"`.  In any other mode
+    /// (especially the legacy `"jsDriver"` path which feeds via
+    /// `processFrameAtPath`), the plugin would double-feed the
+    /// engine — pixel buffers from the producer thread + JPEG paths
+    /// from the JS interval, racing on the same workQueue — so we
+    /// drop the producer-thread call.
+    ///
+    /// Set under `stateLock` in `start()`, cleared under `stateLock`
+    /// in `cancel()` and `finalize()`, ALSO read under `stateLock`
+    /// from `consumeFrameFromPlugin`.  The lock-protected read is
+    /// the simplest correctness story under Swift's
+    /// implementation-defined memory model — an earlier draft did an
+    /// unlocked read on the assumption "Bool loads are atomic on
+    /// arm64", but that's only true for the *instruction*, not for
+    /// compiler reordering / CSE if the property dispatch ever
+    /// changes from `@objc` (Obj-C dynamic, opaque to the optimiser)
+    /// to a Swift-only call (where the load could be hoisted).
+    /// Adversarial-review H1.
+    @objc public private(set) var frameProcessorIngestEnabled: Bool = false
+
     /// V16 — pose-driven keyframe gate.  When `enabled` (set from the
     /// JS `frameSelectionMode = "pose-based"` config), each ARFrame is
     /// projected onto the latched ARKit plane and accepted only when
@@ -916,6 +939,11 @@ public final class IncrementalStitcher: NSObject {
             self.batchKeyframeMode = false
         }
         self.isRunning = true
+        // F8.3 — enable the Frame Processor plugin's producer-thread
+        // ingest only for the new "frameProcessor" mode.  Any other
+        // mode (arSession, jsDriver) keeps it OFF; see the ivar's
+        // declaration comment for why.
+        self.frameProcessorIngestEnabled = (frameSourceMode == "frameProcessor")
         self.snapshotJpegQuality = max(1, min(100, snapshotJpegQuality))
         self.snapshotEveryNAccepts = max(1, snapshotEveryNAccepts)
         self.acceptsSinceSnapshot = 0
@@ -1044,14 +1072,30 @@ public final class IncrementalStitcher: NSObject {
 
         stateLock.unlock()
 
-        // Register with the AR session — only when running in the
-        // AR-frame-stream-driven mode.  In jsDriver mode (iOS non-AR
-        // captures) the AR session is intentionally stopped so the
-        // vision-camera holds the camera; frames arrive via
-        // processFrameAtPath from JS instead.  Registering as the
-        // consumer here would either crash (no running session) or
-        // mis-route frames once an AR session somewhere else came up.
-        if frameSourceMode != "jsDriver" {
+        // Register with the AR session's consumer registry — ONLY
+        // for AR mode.  Other modes don't need it:
+        //
+        //   * `arSession`      — REGISTER.  ARKit's frame delegate
+        //                        (RNSARSession.swift:572) calls
+        //                        `consumer.consumeFrame(...)`.
+        //   * `frameProcessor` — DO NOT register.  The vision-
+        //                        camera plugin calls us directly via
+        //                        `consumeFrameFromPlugin`; we own
+        //                        the camera, ARKit is intentionally
+        //                        stopped.  Registering here would
+        //                        let any sibling code that briefly
+        //                        starts an `ARSession` mid-capture
+        //                        (analytics SDK, future "AR preview"
+        //                        toggle, etc.) silently feed frames
+        //                        in parallel with our producer-
+        //                        thread plugin, racing on
+        //                        `stateLock.try()` and corrupting
+        //                        the gate's novelty math.
+        //                        (Adversarial-review C1.)
+        //   * `jsDriver`       — DO NOT register.  Legacy path uses
+        //                        `processFrameAtPath`; bypasses
+        //                        consumeFrame entirely.
+        if frameSourceMode == "arSession" {
             RNSARSession.shared.incrementalConsumer = self
         }
     }
@@ -1259,6 +1303,13 @@ public final class IncrementalStitcher: NSObject {
         self.keyframePaths = []
         self.keyframePoses = []
         self.isRunning = false
+        // F8.3 — disable the Frame Processor plugin's producer-thread
+        // ingest at the SAME lock-protected moment we flip isRunning,
+        // so any in-flight producer-thread frame either sees both
+        // (and proceeds with a now-doomed call that consumeFrame
+        // drops via its own !isRunning guard) or sees neither (and
+        // skips entirely).
+        self.frameProcessorIngestEnabled = false
         let drops = self.droppedBackpressure
         stateLock.unlock()
 
@@ -2048,6 +2099,9 @@ public final class IncrementalStitcher: NSObject {
         self.keyframePaths = []
         self.keyframePoses = []
         self.isRunning = false
+        // F8.3 — mirror the finalize() flip: cut producer-thread
+        // ingest the moment we go !isRunning.
+        self.frameProcessorIngestEnabled = false
         self.lastState = nil
         // V16 — reset the keyframe gate so the next start() begins
         // with a clean polygon state and counter.  Safe to do under
@@ -3039,3 +3093,69 @@ public final class IncrementalStitcher: NSObject {
 }
 
 extension IncrementalStitcher: ARFrameConsumer {}
+
+// MARK: - F8.3 — Frame Processor entry point
+//
+// `consumeFrameFromPlugin` is a thin @objc-compatible wrapper around
+// `consumeFrame(pixelBuffer:pose:)` that takes primitive args instead
+// of a `RNSARFramePose` instance.  It exists so the
+// `KeyframeGateFrameProcessor.mm` plugin (ObjC++ producer-thread code)
+// can submit a frame without needing to construct a Swift class
+// across the bridging header.
+//
+// Threading: the worklet runs on vision-camera's producer thread
+// (NOT ARKit's delegate queue).  Both threads ultimately serialise on
+// `consumeFrame`'s `stateLock.try()`, which is the documented
+// reentrancy boundary.
+//
+// In non-AR (Frame Processor) mode the caller supplies:
+//   * `pixelBuffer` from `frame.buffer` (vision-camera YUV biplanar)
+//   * `tx`/`ty`/`tz` = 0 (no AR translation; gyro only gives rotation)
+//   * `qx,qy,qz,qw` from JS-thread gyro-integrated yaw+pitch (synthesised
+//     as `q = q_yaw * q_pitch` — same convention as
+//     `useIncrementalJSDriver`'s pose synthesis)
+//   * `fx`/`fy` from frame dims + assumed FoV
+//   * `cx`/`cy` at image centre
+//   * `trackingStateRaw = 2` (= `.tracking`) — non-AR captures don't have
+//     a real ARKit tracking-quality signal; reporting `.tracking` keeps
+//     the engine's `trackingPoor` path inactive, matching the legacy
+//     `useIncrementalJSDriver` contract.
+extension IncrementalStitcher {
+    @objc public func consumeFrameFromPlugin(
+        pixelBuffer: CVPixelBuffer,
+        tx: Double, ty: Double, tz: Double,
+        qx: Double, qy: Double, qz: Double, qw: Double,
+        fx: Double, fy: Double, cx: Double, cy: Double,
+        imageWidth: Int, imageHeight: Int,
+        timestampMs: Double,
+        trackingStateRaw: Int
+    ) {
+        // F8.3 — drop the call unless this capture was started in
+        // frameProcessor mode.  Read under stateLock so the producer
+        // thread can't observe a stale TRUE during a cancel/finalize
+        // teardown (adversarial-review H1).  The lock-protected
+        // read costs ~1 µs at producer-thread rate; negligible vs
+        // the deep-copy that follows on accepts.
+        stateLock.lock()
+        let enabled = self.frameProcessorIngestEnabled
+        stateLock.unlock()
+        guard enabled else { return }
+
+        // Map the raw enum integer.  Unknown values fall back to
+        // `.notAvailable` so the engine's existing tracking-poor
+        // branches catch them — failing CLOSED is safer than
+        // silently claiming healthy tracking when the JS side sent
+        // garbage (adversarial-review C2).
+        let trackingState =
+            RNSARTrackingState(rawValue: trackingStateRaw) ?? .notAvailable
+        let pose = RNSARFramePose(
+            tx: tx, ty: ty, tz: tz,
+            qx: qx, qy: qy, qz: qz, qw: qw,
+            fx: fx, fy: fy, cx: cx, cy: cy,
+            imageWidth: imageWidth, imageHeight: imageHeight,
+            timestampMs: timestampMs,
+            trackingState: trackingState
+        )
+        consumeFrame(pixelBuffer: pixelBuffer, pose: pose)
+    }
+}

package/ios/Sources/RNImageStitcher/KeyframeGateFrameProcessor.mm

@@ -0,0 +1,196 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// KeyframeGateFrameProcessor.mm — F8.3 vision-camera Frame Processor
+// plugin: a thin pose-injector that hands every producer-thread frame
+// to `IncrementalStitcher.consumeFrameFromPlugin`.
+//
+// JS-side usage (from a worklet):
+//
+//     import { VisionCameraProxy, useFrameProcessor } from
+//       'react-native-vision-camera';
+//
+//     const plugin = VisionCameraProxy.initFrameProcessorPlugin(
+//       'cv_flow_gate_process_frame', {},
+//     );
+//
+//     const fp = useFrameProcessor((frame) => {
+//       'worklet';
+//       if (plugin == null) return;
+//       plugin.call(frame, {
+//         qx, qy, qz, qw,         // gyro-integrated quaternion
+//         fx, fy, cx, cy,         // synthesised intrinsics
+//         imageWidth, imageHeight,
+//         // tx/ty/tz default to 0 (no AR translation in non-AR mode)
+//         // trackingStateRaw default = 2 (= .tracking)
+//       });
+//     }, [plugin]);
+//
+// F8.3 SCOPE — the plugin owns NO gate state and NO per-frame
+// decision logic.  It just:
+//   1. Extracts `CVPixelBuffer` from the vision-camera frame.
+//   2. Builds a pose from the worklet's `arguments` dict (with
+//      defaults safe for non-AR mode).
+//   3. Calls `[IncrementalStitcher.shared consumeFrameFromPlugin:…]`
+//      which routes into the SAME entry point AR mode uses
+//      (`consumeFrame(pixelBuffer:pose:)`).
+//
+// The KeyframeGate evaluation, work-queue dispatch, deep-copy, and
+// engine ingest all happen INSIDE `consumeFrame` — exactly as they
+// already do for AR mode.  Single source of truth, no duplication.
+//
+// CONDITIONAL COMPILATION — this file imports vision-camera headers.
+// The SDK's podspec does NOT declare a Pod dependency on VisionCamera
+// because we don't want non-camera-using consumers to be forced to
+// pull it.  The `__has_include` guard means: if the consumer's pod
+// install pulled vision-camera (which it will, since `<Camera>`
+// requires it as a peer dep), this plugin compiles in.  Otherwise the
+// file is a no-op translation unit.
+
+#import <Foundation/Foundation.h>
+
+#if __has_include(<VisionCamera/FrameProcessorPlugin.h>)
+
+#import <VisionCamera/Frame.h>
+#import <VisionCamera/FrameProcessorPlugin.h>
+#import <VisionCamera/FrameProcessorPluginRegistry.h>
+#import <VisionCamera/VisionCameraProxyHolder.h>
+#import <CoreVideo/CoreVideo.h>
+
+// Forward-declare only the Swift APIs we use here.  Importing the
+// full `RNImageStitcher-Swift.h` would force this TU to also import
+// React (`RCTEventEmitter`, `RCTViewManager`) and ARKit
+// (`ARSessionDelegate`), because the generated header exposes every
+// `@objc` symbol in the module.  We don't need any of those.
+//
+// Risk: this declaration must stay in sync with the Swift extension
+// at the bottom of `IncrementalStitcher.swift`.  Both files are
+// committed together; signature drift would be caught at link time
+// (unresolved selector) and at the next build.
+@class IncrementalStitcher;
+@interface IncrementalStitcher : NSObject
++ (IncrementalStitcher * _Nonnull)shared;
+- (void)consumeFrameFromPluginWithPixelBuffer:(CVPixelBufferRef _Nonnull)pixelBuffer
+                                           tx:(double)tx
+                                           ty:(double)ty
+                                           tz:(double)tz
+                                           qx:(double)qx
+                                           qy:(double)qy
+                                           qz:(double)qz
+                                           qw:(double)qw
+                                           fx:(double)fx
+                                           fy:(double)fy
+                                           cx:(double)cx
+                                           cy:(double)cy
+                                   imageWidth:(NSInteger)imageWidth
+                                  imageHeight:(NSInteger)imageHeight
+                                  timestampMs:(double)timestampMs
+                             trackingStateRaw:(NSInteger)trackingStateRaw;
+@end
+
+// Read a Double from the per-call `arguments` dict with a default.
+// Used to extract pose params; tolerant of missing keys (non-AR mode
+// may send only the rotation fields, not translation/intrinsics).
+static double kg_argDouble(NSDictionary* args, NSString* key, double defaultValue) {
+  if (args == nil) return defaultValue;
+  NSNumber* n = args[key];
+  return [n isKindOfClass:[NSNumber class]] ? n.doubleValue : defaultValue;
+}
+static NSInteger kg_argInt(NSDictionary* args, NSString* key, NSInteger defaultValue) {
+  if (args == nil) return defaultValue;
+  NSNumber* n = args[key];
+  return [n isKindOfClass:[NSNumber class]] ? n.integerValue : defaultValue;
+}
+
+@interface KeyframeGateFrameProcessor : FrameProcessorPlugin
+@end
+
+@implementation KeyframeGateFrameProcessor
+
+- (instancetype)initWithProxy:(VisionCameraProxyHolder*)proxy
+                  withOptions:(NSDictionary* _Nullable)options {
+  // No per-instance setup.  All gate tunables (overlapThreshold,
+  // maxCount, flow params, strategy, ...) live on
+  // `IncrementalStitcher` and are configured at its `start()` time
+  // from the host-app settings.  The plugin is a stateless
+  // pose-injector.
+  return [super initWithProxy:proxy withOptions:options];
+}
+
+- (id)callback:(Frame*)frame withArguments:(NSDictionary* _Nullable)arguments {
+  CMSampleBufferRef sampleBuffer = frame.buffer;
+  if (sampleBuffer == NULL) {
+    return @{@"submitted": @NO, @"error": @"no sample buffer"};
+  }
+
+  CVPixelBufferRef pixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer);
+  if (pixelBuffer == NULL) {
+    return @{@"submitted": @NO, @"error": @"no pixel buffer"};
+  }
+
+  // Frame dims for the pose.  Read from plane 0 if planar (YUV) else
+  // whole buffer; this is the dimensionality the stitcher expects.
+  size_t planeCount = CVPixelBufferGetPlaneCount(pixelBuffer);
+  NSInteger width  = (NSInteger)(planeCount >= 1
+      ? CVPixelBufferGetWidthOfPlane(pixelBuffer, 0)
+      : CVPixelBufferGetWidth(pixelBuffer));
+  NSInteger height = (NSInteger)(planeCount >= 1
+      ? CVPixelBufferGetHeightOfPlane(pixelBuffer, 0)
+      : CVPixelBufferGetHeight(pixelBuffer));
+
+  // Pose from worklet args.  Defaults are safe non-AR values:
+  //   * tx/ty/tz = 0 (no translation in non-AR; gyro only gives rot)
+  //   * qw = 1 (identity quaternion if JS hasn't supplied rotation)
+  //   * fx/fy/cx/cy = 0 → JS-driver caller MUST supply these (the
+  //     engine derives FoV from intrinsics; 0 would yield NaN FoV).
+  //     We default the principal point to image centre as a safer
+  //     fallback if only fx/fy are missing.
+  //   * trackingStateRaw = 2 → `.tracking` (non-AR captures don't
+  //     have a real tracking-quality signal; engine's `trackingPoor`
+  //     path stays inactive, matching legacy `useIncrementalJSDriver`).
+  double tx = kg_argDouble(arguments, @"tx", 0.0);
+  double ty = kg_argDouble(arguments, @"ty", 0.0);
+  double tz = kg_argDouble(arguments, @"tz", 0.0);
+  double qx = kg_argDouble(arguments, @"qx", 0.0);
+  double qy = kg_argDouble(arguments, @"qy", 0.0);
+  double qz = kg_argDouble(arguments, @"qz", 0.0);
+  double qw = kg_argDouble(arguments, @"qw", 1.0);
+  double fx = kg_argDouble(arguments, @"fx", 0.0);
+  double fy = kg_argDouble(arguments, @"fy", 0.0);
+  double cx = kg_argDouble(arguments, @"cx", (double)width  / 2.0);
+  double cy = kg_argDouble(arguments, @"cy", (double)height / 2.0);
+  double timestampMs = kg_argDouble(arguments, @"timestampMs", 0.0);
+  NSInteger trackingState = kg_argInt(arguments, @"trackingStateRaw", 2);
+
+  // Submit.  consumeFrame internally early-returns if isRunning ==
+  // false, so it's safe to call every producer-thread frame whether
+  // or not a capture is in progress.  ~1-2 µs of overhead per
+  // "stitcher not running" frame; negligible at 30 fps.
+  [IncrementalStitcher.shared
+      consumeFrameFromPluginWithPixelBuffer:pixelBuffer
+                                         tx:tx ty:ty tz:tz
+                                         qx:qx qy:qy qz:qz qw:qw
+                                         fx:fx fy:fy cx:cx cy:cy
+                                 imageWidth:width
+                                imageHeight:height
+                                timestampMs:timestampMs
+                           trackingStateRaw:trackingState];
+
+  return @{@"submitted": @YES};
+}
+
+// Auto-register the plugin at class-load time.  Name must match what
+// JS passes to `VisionCameraProxy.initFrameProcessorPlugin(...)`.
++ (void)load {
+  [FrameProcessorPluginRegistry
+    addFrameProcessorPlugin:@"cv_flow_gate_process_frame"
+            withInitializer:^FrameProcessorPlugin* _Nonnull(
+                VisionCameraProxyHolder* proxy,
+                NSDictionary* _Nullable options) {
+              return [[KeyframeGateFrameProcessor alloc]
+                  initWithProxy:proxy withOptions:options];
+            }];
+}
+
+@end
+
+#endif // __has_include(<VisionCamera/FrameProcessorPlugin.h>)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.4.0",
+  "version": "0.5.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",
@@ -61,6 +61,7 @@
     "react-native-safe-area-context": "^4.0.0",
     "react-native-sensors": "^7.0.0",
     "react-native-vision-camera": "^4.0.0",
+    "react-native-worklets-core": "^1.3.0",
     "rxjs": "^7.0.0",
     "ts-jest": "^29.1.0",
     "typescript": "^5.5.0"
@@ -69,6 +70,7 @@
     "react": ">=18.0.0",
     "react-native": ">=0.72.0",
     "react-native-vision-camera": ">=4.7.0",
+    "react-native-worklets-core": ">=1.3.0",
     "react-native-sensors": ">=7.0.0",
     "react-native-safe-area-context": ">=4.0.0"
   }

package/src/camera/Camera.tsx

@@ -56,7 +56,11 @@ import {
   type ViewStyle,
 } from 'react-native';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
-import type { Camera as VisionCamera } from 'react-native-vision-camera';
+import type {
+  Camera as VisionCamera,
+  DrawableFrameProcessor,
+  ReadonlyFrameProcessor,
+} from 'react-native-vision-camera';
 
 import { useARSession } from '../ar/useARSession';
 import { ARCameraView, type ARCameraViewHandle } from './ARCameraView';
@@ -86,6 +90,7 @@ import {
   type IncrementalState,
 } from '../stitching/incremental';
 import { useIncrementalJSDriver } from '../stitching/useIncrementalJSDriver';
+import { useFrameProcessorDriver } from '../stitching/useFrameProcessorDriver';
 import { useIncrementalStitcher } from '../stitching/useIncrementalStitcher';
 import { useIMUTranslationGate } from '../sensors/useIMUTranslationGate';
 import { toBareFilePath, toFileUri } from '../utils/paths';
@@ -164,6 +169,15 @@ export type CameraErrorCode =
   | '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';
 
 
@@ -256,6 +270,47 @@ 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;
 }
 
 
@@ -530,6 +585,8 @@ export function Camera(props: CameraProps): React.JSX.Element {
     onLensChange,
     onFramesDropped,
     onError,
+    frameProcessor: hostFrameProcessor,
+    legacyDriver = false,
   } = props;
 
   const insets = useSafeAreaInsets();
@@ -727,10 +784,45 @@ export function Camera(props: CameraProps): React.JSX.Element {
   // imperative pattern (start on hold-start, stop on hold-end) avoids
   // the re-render churn entirely.
   const jsDriver = 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 = 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
-  useEffect(() => () => { jsDriver.stop(); }, []);
+  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 = 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 ──────────
   useEffect(() => {
@@ -787,6 +879,17 @@ export function Camera(props: CameraProps): React.JSX.Element {
     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();
       }
@@ -917,7 +1020,13 @@ export function Camera(props: CameraProps): React.JSX.Element {
         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,
@@ -928,15 +1037,26 @@ export function Camera(props: CameraProps): React.JSX.Element {
           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) {
       setStatusPhase('idle');
@@ -957,16 +1077,21 @@ export function Camera(props: CameraProps): React.JSX.Element {
     effectiveCaptureSource,
     imuGate,
     jsDriver,
+    fpDriver,
+    legacyDriver,
     onError,
   ]);
 
   const handleHoldEnd = 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
@@ -1044,6 +1169,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
     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),
@@ -1101,6 +1227,30 @@ export function Camera(props: CameraProps): React.JSX.Element {
           video
           flash="off"
           style={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 as { code?: string; message?: string };
+            const codeStr = e?.code ?? 'unknown';
+            const msg = e?.message ?? String(err);
+            onError?.(new CameraError(
+              'VISION_CAMERA_RUNTIME',
+              `${codeStr}: ${msg}`,
+              err,
+            ));
+          }}
         />
       )}