react-native-image-stitcher 0.5.0 → 0.6.0

package/android/src/main/java/io/imagestitcher/rn/KeyframeGate.kt

@@ -247,9 +247,12 @@ internal class KeyframeGate : AutoCloseable {
      *    the Y plane from the ARCore camera image (YUV_420_888) and
      *    hands it through.  Zero-copy on the way in (the byte[] is
      *    pinned via GetPrimitiveArrayCritical in the JNI).
-     *  - Non-AR mode (`IncrementalStitcher.processFrameAtPath`): the
-     *    JS-driver path supplies a JPEG path; the caller decodes the
-     *    JPEG to grayscale before calling this method.
+     *  - Non-AR mode (`CvFlowGateFrameProcessor` via
+     *    `IncrementalStitcher.consumeFrameFromPlugin`): extracts the
+     *    Y plane from the vision-camera Frame's YUV_420_888 image on
+     *    the producer thread and hands it through.  (Pre-v0.6 a
+     *    JS-driver `processFrameAtPath` path also called this with
+     *    JPEG-decoded grayscale; both were removed in v0.6.)
      *
      * @param grayData    The grayscale plane bytes.  Length must be
      *                    at least `grayStride * grayHeight`.

package/android/src/main/java/io/imagestitcher/rn/RNSARCameraView.kt

@@ -18,7 +18,6 @@ import com.google.ar.core.exceptions.CameraNotAvailableException
 import com.google.ar.core.exceptions.SessionPausedException
 import io.imagestitcher.rn.ar.BackgroundRenderer
 import io.imagestitcher.rn.ar.YuvImageConverter
-import java.io.File
 import java.util.concurrent.atomic.AtomicReference
 import javax.microedition.khronos.egl.EGLConfig
 import javax.microedition.khronos.opengles.GL10
@@ -76,13 +75,6 @@ class RNSARCameraView @JvmOverloads constructor(
     private var surfaceWidth: Int = 0
     private var surfaceHeight: Int = 0
 
-    /// Tmp directory for the per-frame JPEG file we hand to the
-    /// incremental engine.  Created lazily and reused across frames
-    /// — no per-frame allocation.
-    private val tmpJpegFile: File by lazy {
-        File(context.cacheDir, "rlis-arframe.jpg")
-    }
-
     /// Whether to feed the AR session's frames into the incremental
     /// engine.  Toggled by IncrementalStitcher.start/stop
     /// via setIncrementalIngestionActive() below.
@@ -510,28 +502,18 @@ class RNSARCameraView @JvmOverloads constructor(
         val rotationForEncode = if (lastDisplayRotation >= 0)
             lastDisplayRotation else android.view.Surface.ROTATION_0
 
-        // 2026-05-21 (v0.3) — eager JPEG encode is only needed when
-        // the engine is in the legacy hybrid/firstwins live-engine
-        // mode (which feeds JPEG paths into addFrameAtPath every
-        // frame).  In batch-keyframe mode (the production Camera
-        // component's path), the JPEG is encoded LAZILY inside
-        // the onAccept lambda below — only on the ~6 frames per
-        // capture that the C++ KeyframeGate actually keeps.
+        // F8.6 (v0.6) — the eager JPEG encode for live-engine mode
+        // is gone.  Pass the already-packed NV21 directly via
+        // `nv21PixelData`; the engine's new `addFramePixelData`
+        // path builds the BGR cv::Mat in-process via cvtColor,
+        // skipping the JPEG decode round-trip downstream.  In
+        // batch-keyframe mode the engine ignores `nv21PixelData`
+        // (it uses `grayData` + `onAccept` lazily); no behaviour
+        // change there.
         //
-        // 2026-05-22 (#19) — the encode now reads from the already-
-        // packed NV21 bytes (`packed`), NOT from the live Image
-        // (which has been closed above).  Same output, no Image
-        // hold time.
-        val legacyJpegPath: String? = if (module.isBatchKeyframeMode) {
-            null
-        } else {
-            YuvImageConverter.encodeJpegFromNV21(
-                packed,
-                tmpJpegFile.absolutePath,
-                jpegQuality = 70,
-                displayRotation = rotationForEncode,
-            )
-        }
+        // (Was: eager JPEG encode for non-batch-keyframe modes,
+        //  written to `tmpJpegFile`, passed as `legacyJpegPath`.
+        //  See the v0.3 / F8.6 entries in CHANGELOG.md.)
         module.ingestFromARCameraView(
             tx = tArr[0].toDouble(),
             ty = tArr[1].toDouble(),
@@ -553,7 +535,12 @@ class RNSARCameraView @JvmOverloads constructor(
             grayWidth = packed.width,
             grayHeight = packed.height,
             grayStride = packed.width,
-            legacyJpegPath = legacyJpegPath,
+            legacyJpegPath = null,
+            // F8.6 — pixel-data path for live engines.  Batch-
+            // keyframe mode ignores these (bails earlier).
+            nv21PixelData = packed.nv21,
+            nv21PixelWidth = packed.width,
+            nv21PixelHeight = packed.height,
             onAccept = { targetPath ->
                 // Lazy JPEG encode.  Runs ONLY if the C++ KeyframeGate
                 // accepted the frame.  Encodes from the pre-packed

package/dist/camera/Camera.d.ts

@@ -140,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
@@ -182,36 +200,20 @@ export interface CameraProps {
      * 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.
+     * The SDK installs its own frame processor via
+     * `useFrameProcessorDriver`.  Setting this prop is ignored with
+     * a one-time `console.warn` — supplying a host worklet would
+     * race with the SDK's pixel-buffer feed.  Either remove the prop
+     * or fork the SDK if you genuinely need a custom worklet.
      *
-     * 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`).
+     * AR mode is irrelevant: vision-camera's Camera isn't mounted.
      *
-     * 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.
+     * (v0.5 had a `legacyDriver` escape hatch that routed back to
+     * `useIncrementalJSDriver`.  That hook + prop were removed in
+     * v0.6 per the deprecation timeline announced in the v0.5.0
+     * CHANGELOG.)
      */
-    legacyDriver?: boolean;
+    frameProcessor?: ReadonlyFrameProcessor | DrawableFrameProcessor;
 }
 /**
  * The public `<Camera>` component.

package/dist/camera/Camera.js

@@ -97,7 +97,6 @@ const lowMemDevice_1 = require("./lowMemDevice");
 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");
@@ -271,7 +270,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, frameProcessor: hostFrameProcessor, legacyDriver = false, } = props;
+    const { defaultCaptureSource = 'ar', defaultLens = '1x', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, onLensChange, onFramesDropped, onError, frameProcessor: hostFrameProcessor, engine = 'batch-keyframe', } = props;
     const insets = (0, react_native_safe_area_context_1.useSafeAreaInsets)();
     // ── State ───────────────────────────────────────────────────────
     const [arPreference, setArPreference] = (0, react_1.useState)(defaultCaptureSource === 'ar');
@@ -417,58 +416,44 @@ function Camera(props) {
             mod?.markNextFrameAsLastKeyframe?.().catch(() => undefined);
         },
     });
-    // JS-driver for non-AR captures (iOS + Android).  In AR mode the
-    // engine consumes frames from the ARSession stream natively, so this
-    // hook stays idle.
+    // Frame Processor driver for non-AR captures (iOS + Android).
+    // In AR mode the engine consumes frames from the ARSession stream
+    // natively, so this hook stays idle.
     //
     // IMPORTANT: start()/stop() are called imperatively from the hold
     // handlers below — NOT from a useEffect driven by statusPhase.  The
     // hook returns a fresh object identity on every render, and during
     // a recording the engine emits IncrementalStateUpdate events that
-    // cause re-renders multiple times per second.  An effect with
-    // `jsDriver` in its deps would teardown + restart the driver on
-    // every event, resetting the gyro accumulator (yaw/pitch) to zero
-    // each cycle and nulling the cameraRef during the brief gap.  The
-    // user-visible symptom was "only the first keyframe is accepted,
-    // every subsequent snapshot sees pose=(0,0) and is rejected as a
-    // duplicate of the first".  Matching AuditCaptureScreen's proven
-    // imperative pattern (start on hold-start, stop on hold-end) avoids
-    // the re-render churn entirely.
-    const jsDriver = (0, useIncrementalJSDriver_1.useIncrementalJSDriver)();
-    // 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.
+    // cause re-renders multiple times per second.  An effect with the
+    // driver in its deps would teardown + restart on every event,
+    // resetting the gyro accumulator (yaw/pitch) to zero each cycle.
+    // User-visible symptom: "only the first keyframe is accepted, every
+    // subsequent ingest sees pose=(0,0) and is rejected as a duplicate".
+    // The imperative pattern (start on hold-start, stop on hold-end)
+    // avoids the re-render churn entirely.
     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.
+    // Safety: stop the driver if the component unmounts mid-recording.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    (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).
+    (0, react_1.useEffect)(() => () => { fpDriver.stop(); }, []);
+    // One-shot deprecation warning when the host supplies their own
+    // `frameProcessor` prop.  Two worklets racing on the same
+    // producer thread would corrupt the engine's workQueue ordering,
+    // so the SDK's own worklet wins and the host's is silently
+    // ignored.  (v0.5 had a `legacyDriver` opt-out for hosts that
+    // wanted to route around the SDK driver; that was removed in
+    // v0.6 along with `useIncrementalJSDriver`.)
     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.');
+            + '<Camera> is ignored — the SDK installs its own worklet '
+            + 'via useFrameProcessorDriver.  Remove the prop, or fork '
+            + 'the SDK if you genuinely need a custom worklet.');
     }
-    // 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;
+    // The Frame Processor worklet bound to vision-camera's Camera.
+    const effectiveFrameProcessor = fpDriver.frameProcessor;
     // ── Subscribe to engine state for live keyframe thumbs ──────────
     (0, react_1.useEffect)(() => {
         const sub = (0, incremental_1.subscribeIncrementalState)((state) => {
@@ -524,17 +509,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
+            // F8.3 review-of-review (M3 revert): an earlier draft gated
+            // this on the pre-v0.6 `legacyDriver` prop 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 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.
+            // compound → inflated metres → biased toward SCANS.  Now fires
+            // for ALL non-AR captures (the only non-AR driver post-v0.6).
             if (isNonAR) {
                 imuGate.resetAnchor();
             }
@@ -651,18 +636,16 @@ function Camera(props) {
                 snapshotEveryNAccepts: 1,
                 frameRotationDegrees: orientationRotation,
                 captureOrientation: deviceOrientation,
-                // 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',
+                // Non-AR captures use the Frame Processor driver
+                // (vision-camera producer-thread worklet → cv_flow_gate
+                // plugin → IncrementalStitcher.consumeFrame).  AR captures
+                // use the ARSession-driven path.
+                frameSourceMode: isNonAR ? 'frameProcessor' : 'arSession',
                 composeWidth: 1920,
                 composeHeight: 1080,
                 canvasWidth: 5000,
                 canvasHeight: 5000,
-                engine: 'batch-keyframe',
+                engine,
                 config: (0, PanoramaSettingsBridge_1.panoramaSettingsToNativeConfig)({
                     ...settings,
                     captureSource: effectiveCaptureSource,
@@ -673,22 +656,13 @@ function Camera(props) {
             // matching comment on the per-accept reset useEffect above).
             // Keep firing it on every capture start, not just legacy mode.
             imuGate.resetAnchor();
-            // 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.
+            // Start the Frame Processor driver for non-AR captures.  AR
+            // mode feeds natively from ARSession so the driver stays idle.
+            // Imperative pattern (vs useEffect) because the driver's start
+            // resets pose accumulators that should only fire at the
+            // hold-start moment, not on every re-render.
             if (isNonAR) {
-                if (legacyDriver) {
-                    jsDriver.start(visionCameraRef);
-                }
-                else {
-                    fpDriver.start();
-                }
+                fpDriver.start();
             }
         }
         catch (err) {
@@ -703,9 +677,8 @@ function Camera(props) {
         settings,
         effectiveCaptureSource,
         imuGate,
-        jsDriver,
         fpDriver,
-        legacyDriver,
+        engine,
         onError,
     ]);
     const handleHoldEnd = (0, react_1.useCallback)(async () => {
@@ -714,10 +687,7 @@ function Camera(props) {
         setStatusPhase('stitching');
         // 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();
+        // keyframes.  No-op in AR mode (the driver was never started).
         fpDriver.stop();
         try {
             // Compose the panorama output path: host-controlled if
@@ -787,7 +757,6 @@ function Camera(props) {
         onFramesDropped,
         onError,
         recordingStartedAt,
-        jsDriver,
         fpDriver,
         // F10 Phase 2 review N1 — these four were missing pre-fix.  The
         // callback reads `settings.debug` (to gate the stitchToast),

package/dist/index.d.ts

@@ -64,8 +64,6 @@ export { useDeviceOrientation } from './camera/useDeviceOrientation';
 export { IncrementalOutcome, incrementalStitcherIsAvailable, subscribeIncrementalState, getIncrementalNativeModule, cleanupOldKeyframes, } from './stitching/incremental';
 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';

package/dist/index.js

@@ -22,7 +22,7 @@
  * adds RetaiLens-specific features on top.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
+exports.stitchVideo = exports.useFrameProcessorDriver = 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
 // ─────────────────────────────────────────────────────────────────────
@@ -139,11 +139,9 @@ Object.defineProperty(exports, "getIncrementalNativeModule", { enumerable: true,
 Object.defineProperty(exports, "cleanupOldKeyframes", { enumerable: true, get: function () { return incremental_1.cleanupOldKeyframes; } });
 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.
+// vision-camera Frame Processor driver for non-AR captures.  As
+// of v0.6 the only non-AR driver exported (the legacy
+// `useIncrementalJSDriver` was removed; was deprecated in v0.5).
 var useFrameProcessorDriver_1 = require("./stitching/useFrameProcessorDriver");
 Object.defineProperty(exports, "useFrameProcessorDriver", { enumerable: true, get: function () { return useFrameProcessorDriver_1.useFrameProcessorDriver; } });
 // ── Batch stitching ───────────────────────────────────────────────────

package/dist/stitching/incremental.d.ts

@@ -191,23 +191,22 @@ export interface IncrementalStartOptions {
      *     bridge.start() requires `RNSARSession.start()` to
      *     have already been called.
      *
-     *   - 'jsDriver' — engine skips AR-session registration; JS
-     *     feeds frames via `processFrameAtPath`.  Use in iOS non-AR
-     *     captures (vision-camera + gyro).  No AR session required.
-     *     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.
+     *     Android extracts the Y plane to a ByteArray and (since
+     *     F8.6, v0.5.1) routes live-engine ingest through
+     *     `addFramePixelData` without a JPEG round-trip.  Use in
+     *     non-AR captures driven by `useFrameProcessorDriver`.  Pairs
+     *     with `Camera`'s default driver mode.
+     *
+     * `'jsDriver'` was removed in v0.6 (deprecated in v0.5).  Hosts
+     * that used it should switch to `useFrameProcessorDriver` (or
+     * just let `<Camera>` use its default).
      */
-    frameSourceMode?: 'arSession' | 'jsDriver' | 'frameProcessor';
+    frameSourceMode?: 'arSession' | '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

@@ -1,13 +1,14 @@
 /**
  * useFrameProcessorDriver — vision-camera Frame Processor + gyro
- * driver for the incremental panorama engine.  Replaces
- * `useIncrementalJSDriver` in non-AR captures.
+ * driver for the incremental panorama engine.  Sole non-AR driver
+ * from v0.6 onward (replaced the deprecated `useIncrementalJSDriver`
+ * hook, which was removed in v0.6).
  *
- * Why this exists (vs the JS-driver predecessor)
+ * Why this exists (vs the pre-v0.6 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:
+ *   The old JS driver took a JPEG snapshot every ~250 ms and fed the
+ *   path to `IncrementalStitcher.processFrameAtPath` (both removed in
+ *   v0.6).  That path had three costs:
  *
  *     1. JPEG encode (`takeSnapshot` ≈ 30–80 ms on iPhone 16 Pro)
  *     2. Disk write of the JPEG

package/dist/stitching/useFrameProcessorDriver.js

@@ -2,14 +2,15 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * useFrameProcessorDriver — vision-camera Frame Processor + gyro
- * driver for the incremental panorama engine.  Replaces
- * `useIncrementalJSDriver` in non-AR captures.
+ * driver for the incremental panorama engine.  Sole non-AR driver
+ * from v0.6 onward (replaced the deprecated `useIncrementalJSDriver`
+ * hook, which was removed in v0.6).
  *
- * Why this exists (vs the JS-driver predecessor)
+ * Why this exists (vs the pre-v0.6 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:
+ *   The old JS driver took a JPEG snapshot every ~250 ms and fed the
+ *   path to `IncrementalStitcher.processFrameAtPath` (both removed in
+ *   v0.6).  That path had three costs:
  *
  *     1. JPEG encode (`takeSnapshot` ≈ 30–80 ms on iPhone 16 Pro)
  *     2. Disk write of the JPEG
@@ -220,9 +221,9 @@ function useFrameProcessorDriver(options = {}) {
         //   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.
+        // Right-hand-rule convention throughout — same signs the pre-v0.6
+        // `useIncrementalJSDriver` produced.  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 }) => {
@@ -296,8 +297,8 @@ function useFrameProcessorDriver(options = {}) {
             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).
+            // tracking" because there's no ARKit signal to differentiate.
+            // (Same contract as the pre-v0.6 useIncrementalJSDriver.)
             trackingStateRaw: 2,
         });
         // Deps array intentionally minimal: only `plugin` actually

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(