react-native-image-stitcher 0.4.1 → 0.5.1

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;

package/ios/Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //
 // Package.swift — SwiftPM manifest used **only for command-line testing**
 // of the algorithm layer (QualityChecker.swift).  Production builds
@@ -38,26 +38,40 @@ let package = Package(
     .target(
       name: "RNImageStitcher",
       path: "Sources/RNImageStitcher",
-      // Excluded from `swift test` because they depend on either
-      // React (which isn't a SwiftPM dep) or OpenCV (which only
-      // ships as an iOS XCFramework via the podspec — no macOS
-      // build).  The host app's CocoaPods workspace picks them up.
-      exclude: [
-        // React-dependent
-        "QualityCheckerBridge.swift",
-        "QualityCheckerBridge.m",
-        "StitcherBridge.swift",
-        "StitcherBridge.m",
-        // OpenCV-dependent (Phase 2 stitcher)
-        "OpenCVStitcher.h",
-        "OpenCVStitcher.mm",
-        // OpenCV-dependent (V16 Phase 1 keyframe collector)
-        "OpenCVKeyframeCollector.h",
-        "OpenCVKeyframeCollector.mm",
-        // Stitcher.swift is `#if canImport(UIKit)`-gated so it
-        // compiles to nothing on macOS; including it keeps the
-        // file available to the Pods build without breaking
-        // `swift test`.
+      // F8.3.H2-target — instead of an `exclude` list (which broke
+      // every time a new .mm landed, e.g.
+      // `KeyframeGateFrameProcessor.mm` in F8.1, because SwiftPM
+      // still scans the directory and rejects "mixed language
+      // source files" if it sees both .swift and .mm), we use an
+      // explicit `sources` allowlist of files that compile cleanly
+      // on macOS (where `swift test` runs).
+      //
+      // What's in the allowlist:
+      //   * QualityChecker.swift — Accelerate / CoreImage; macOS-OK.
+      //   * KeyframeGate.swift — Foundation + simd; macOS-OK.
+      //
+      // What's NOT (intentionally):
+      //   * Anything with `import UIKit` / `import ARKit` — iOS only.
+      //     CocoaPods compiles them for the host app via the podspec
+      //     source_files glob; SwiftPM macOS doesn't need them.
+      //   * .mm / .m / .h files — same.  Picked up by CocoaPods.
+      //   * RN-bridge Swift files (`*Bridge.swift`) — `import React`,
+      //     not a SwiftPM dep.
+      //
+      // The Frame Processor plugin's Swift⇄ObjC selector pin
+      // (formerly relied on by `FrameProcessorPluginSelectorTests`)
+      // is enforced as a compile-time `#selector(...)` reference
+      // inside `IncrementalStitcher.swift` itself — see the
+      // `_consumeFrameFromPluginSelectorPin` static.  Drift breaks
+      // the SDK build, which is a stronger guarantee than a test
+      // that needs iOS-Simulator infrastructure to run.
+      sources: [
+        "QualityChecker.swift",
+        // KeyframeGate.swift depends on `KeyframeGateBridge` (ObjC
+        // class in .mm) and `RNSARFramePose` (from a UIKit-using
+        // Swift file), so it doesn't compile standalone under
+        // SwiftPM on macOS — only the CocoaPods build sees the
+        // full type graph.
       ]
     ),
     .testTarget(

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
@@ -453,6 +476,13 @@ public final class IncrementalStitcher: NSObject {
 
     private override init() {
         super.init()
+        // F8.3.H2 — runtime check that Swift's auto-bridged ObjC
+        // selector for `consumeFrameFromPlugin(...)` matches the
+        // selector string the plugin's .mm dispatches.  Asserts in
+        // dev builds; no-ops in release.  See the
+        // `_consumeFrameFromPluginSelectorPin` declaration below for
+        // the full rationale.
+        IncrementalStitcher._verifyConsumeFrameFromPluginSelector()
     }
 
     /// 2026-05-18 (iOS cross-orientation fix) — bridge entry-point
@@ -916,6 +946,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 +1079,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 +1310,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 +2106,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 +3100,122 @@ 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)
+    }
+
+    // F8.3.H2 — compile-time + runtime guard for the Swift⇄ObjC
+    // selector contract that `KeyframeGateFrameProcessor.mm`
+    // depends on.
+    //
+    // The .mm file forward-declares `IncrementalStitcher` and
+    // dispatches `[shared consumeFrameFromPluginWithPixelBuffer:tx:
+    // …:trackingStateRaw:]` by NAME — ObjC's late-binding means
+    // signature drift would silently link but crash at runtime
+    // with `NSInvalidArgumentException: unrecognized selector`
+    // on the first non-AR frame.
+    //
+    // This `#selector(...)` reference forces the Swift compiler
+    // to resolve the exact method signature.  If anyone renames a
+    // parameter label or adds/removes an argument, the
+    // `_consumeFrameFromPluginSelectorPin` expression fails to
+    // compile — the SDK won't build until the .mm's forward
+    // declaration is updated to match.  Stronger guarantee than a
+    // test that needs iOS-Simulator infrastructure to run.
+    //
+    // The runtime check below additionally pins the exact
+    // SELECTOR STRING the .mm dispatches.  In dev/debug builds it
+    // asserts; in release builds it's a no-op (the static let is
+    // initialised lazily and never read otherwise, so the runtime
+    // cost is one-time + tiny).  Drift between Swift's auto-
+    // generated selector name and the .mm's expected string
+    // (e.g., if Swift's bridging rules change) trips the assert.
+    private static let _consumeFrameFromPluginSelectorPin: Selector =
+        #selector(IncrementalStitcher.consumeFrameFromPlugin(
+            pixelBuffer:
+            tx: ty: tz:
+            qx: qy: qz: qw:
+            fx: fy: cx: cy:
+            imageWidth: imageHeight:
+            timestampMs:
+            trackingStateRaw:))
+
+    @inline(never)
+    private static func _verifyConsumeFrameFromPluginSelector() {
+        let expected =
+            "consumeFrameFromPluginWithPixelBuffer:tx:ty:tz:"
+            + "qx:qy:qz:qw:fx:fy:cx:cy:"
+            + "imageWidth:imageHeight:timestampMs:trackingStateRaw:"
+        let actual = NSStringFromSelector(_consumeFrameFromPluginSelectorPin)
+        assert(
+            actual == expected,
+            "Frame Processor selector drift — Swift's auto-bridged "
+            + "ObjC selector for consumeFrameFromPlugin is "
+            + "\(actual) but KeyframeGateFrameProcessor.mm's "
+            + "forward declaration expects \(expected).  Update the "
+            + ".mm to match (or fix the assumption here).",
+        )
+    }
+}