react-native-image-stitcher 0.4.0 → 0.5.0

package/android/src/main/java/io/imagestitcher/rn/ar/YuvImageConverter.kt

@@ -14,6 +14,25 @@ import java.io.FileOutputStream
 /**
  * Convert an ARCore `Image` (YUV_420_888) to a JPEG file on disk.
  *
+ * 2026-05-22 (audit follow-up #19) — split into two phases so callers
+ * can release the underlying ARCore `Image` ASAP:
+ *
+ *   1. `packNV21(image)`  — reads the Y/U/V planes into a contiguous
+ *      JVM-side `ByteArray` (NV21 layout).  Fast (~3 ms for 1920×1080).
+ *      The caller can close the `Image` IMMEDIATELY after this returns,
+ *      freeing the ARCore Camera2 ImageReader buffer.
+ *
+ *   2. `encodeJpegFromNV21(packed, …)` — does the slow YUV→JPEG
+ *      conversion (~10-25 ms) on the already-extracted bytes, NOT on
+ *      the Image.  Safe to run after the Image has been closed.
+ *
+ * The pre-#19 single-call `encodeToJpeg(image, …)` API is preserved as
+ * a thin wrapper for callers that don't care about Image hold time
+ * (e.g., one-shot photo capture).  Performance-critical paths
+ * (`RNSARCameraView.forwardToIncremental`, called at ~60 Hz on the
+ * GL render thread) should use the two-step API to keep Image hold
+ * times bounded by the ~3 ms pack step instead of the ~25 ms encode.
+ *
  * Why JPEG → file → re-decode by OpenCV (slightly wasteful)?
  *   The incremental engine's existing API (matching iOS') consumes
  *   image PATHS, not raw planes.  Threading raw YUV through the
@@ -22,56 +41,182 @@ import java.io.FileOutputStream
  *   next to the ~40 ms per-frame engine work — keeping the surface
  *   uniform across iOS / Android paths is worth the few-ms cost.
  *
- * `Image` ownership: caller MUST `image.close()` after this returns.
- * We don't close inside because the caller may want to inspect more
- * fields (timestamp, format) before releasing.
+ * `Image` ownership: the two-step API (`packNV21` + `encodeJpegFromNV21`)
+ * returns control to the caller after the pack step so the caller can
+ * close the Image at the right moment.  The legacy single-call
+ * `encodeToJpeg(image, …)` does NOT close the Image — caller is
+ * responsible for that.
  */
 internal object YuvImageConverter {
 
-    /// Convert + write JPEG.  Returns the path (no file:// prefix)
-    /// or null on any encode/write error (caller-decides whether to
-    /// log + drop the frame).
-    ///
-    /// 2026-05-15 (B3) — `displayRotation` parameter writes the
-    /// appropriate EXIF orientation tag so RN's Image loader (and
-    /// any other consumer that respects EXIF) displays the JPEG
-    /// upright regardless of how the device was held at capture.
-    ///
-    /// Without this, Android's image loaders display the raw sensor
-    /// pixels (typically landscape) as-is — so a portrait-held
-    /// capture's thumbnail appears sideways.  iOS's image loader
-    /// auto-respects EXIF orientation; Android's doesn't always
-    /// (depends on the loader path).  Setting the tag covers both.
-    ///
-    /// `displayRotation` should be the value returned from
-    /// `WindowManager.defaultDisplay.rotation` at capture time
-    /// (Surface.ROTATION_0/_90/_180/_270).  We assume a typical
-    /// back-camera sensor orientation of 90° — true for all
-    /// devices we ship to (Galaxy A35 verified).  Wire through
-    /// CameraCharacteristics.SENSOR_ORIENTATION in a follow-up
-    /// if we ever encounter a device that differs.
-    ///
-    /// Default `displayRotation = Surface.ROTATION_0` (portrait)
-    /// preserves the previous behaviour for legacy callsites that
-    /// haven't been updated yet.
-    fun encodeToJpeg(
-        image: Image,
+    /**
+     * Packed NV21 pixel data extracted from an ARCore `Image`.
+     * Once you hold one of these, the source `Image` can be closed —
+     * all subsequent operations work on the JVM-side byte array.
+     *
+     * NV21 layout (single contiguous byte array):
+     *   bytes [0 .. width*height)              = Y plane (luminance),
+     *                                            densely packed,
+     *                                            row stride = width
+     *   bytes [width*height .. width*height*3/2) = interleaved V-U pairs
+     *                                              at half resolution
+     *
+     * The Y plane portion can be passed directly to the C++
+     * `keyframe_gate` as grayscale pixels with `stride = width`.
+     */
+    data class PackedYuv(
+        val nv21: ByteArray,
+        val width: Int,
+        val height: Int,
+    ) {
+        /** Length of the Y plane portion (bytes [0 .. ySize)). */
+        val ySize: Int get() = width * height
+
+        // equals + hashCode override required because `nv21` is a
+        // mutable array; default `data class` equality uses reference
+        // identity for arrays, which is rarely what callers want.
+        override fun equals(other: Any?): Boolean {
+            if (this === other) return true
+            if (other !is PackedYuv) return false
+            return width == other.width
+                && height == other.height
+                && nv21.contentEquals(other.nv21)
+        }
+        override fun hashCode(): Int {
+            var result = nv21.contentHashCode()
+            result = 31 * result + width
+            result = 31 * result + height
+            return result
+        }
+    }
+
+
+    /**
+     * Pack the Y, U, V planes of a YUV_420_888 `Image` into a
+     * contiguous JVM-side NV21 byte array.  Returns null if the
+     * `Image`'s format isn't YUV_420_888 or doesn't expose 3 planes.
+     *
+     * Performance: ~3 ms for 1920×1080 on a Galaxy A35.  Dominated
+     * by the row-by-row copy through the direct ByteBuffers backing
+     * the camera planes.
+     *
+     * The Y plane is densely repacked (the source rowStride may be
+     * padded, but we discard padding on the way in so the result has
+     * `rowStride = width`).  This is what callers want — `cv::Mat`
+     * wrap on the C++ side prefers tight strides, and downstream
+     * `YuvImage.compressToJpeg` requires densely-packed input.
+     */
+    fun packNV21(image: Image): PackedYuv? {
+        if (image.format != ImageFormat.YUV_420_888) return null
+        val planes = image.planes
+        if (planes.size < 3) return null
+
+        val w = image.width
+        val h = image.height
+        val ySize = w * h
+        val uvSize = w * h / 2
+        val nv21 = ByteArray(ySize + uvSize)
+
+        // ── Y plane (luminance) ─────────────────────────────────
+        val yPlane = planes[0]
+        val yBuf = yPlane.buffer
+        val yRowStride = yPlane.rowStride
+        if (yRowStride == w) {
+            // Source already densely packed — single block copy.
+            // Use duplicate() so we don't mutate the original buffer's
+            // position state (defensive — ARCore may have other readers
+            // of the same underlying buffer, though in practice it
+            // shouldn't).
+            yBuf.duplicate().apply { rewind() }.get(nv21, 0, ySize)
+        } else {
+            // Row-by-row copy when stride > width (padded rows).
+            val dup = yBuf.duplicate()
+            var dstOffset = 0
+            var srcOffset = 0
+            for (row in 0 until h) {
+                dup.position(srcOffset)
+                dup.get(nv21, dstOffset, w)
+                dstOffset += w
+                srcOffset += yRowStride
+            }
+        }
+
+        // ── U + V planes (chroma) ───────────────────────────────
+        // YUV_420_888 has them subsampled 2:1 so each plane physically
+        // covers (w/2) × (h/2).  Pixel stride is 1 (planar) or 2
+        // (semi-planar interleaved).  NV21 expects interleaved V-U.
+        val uPlane = planes[1]
+        val vPlane = planes[2]
+        val uBuf = uPlane.buffer
+        val vBuf = vPlane.buffer
+        val uRowStride = uPlane.rowStride
+        val uPixelStride = uPlane.pixelStride
+        val vRowStride = vPlane.rowStride
+        val vPixelStride = vPlane.pixelStride
+
+        // Fast path — most Android camera2 / ARCore producers emit
+        // semi-planar interleaved data with pixelStride=2.  In that
+        // case the V plane's underlying bytes physically interleave
+        // V-U-V-U... and copying the V plane's full byte range
+        // produces NV21 layout directly.
+        if (uPixelStride == 2 && vPixelStride == 2 &&
+            uRowStride == vRowStride && uRowStride == w) {
+            val vBytes = vBuf.remaining().coerceAtMost(uvSize)
+            // Defensive duplicate() again — same reasoning as Y plane.
+            vBuf.duplicate().apply { rewind() }.get(nv21, ySize, vBytes)
+            return PackedYuv(nv21, w, h)
+        }
+
+        // Slow path — manual interleave for planar (pixelStride=1) or
+        // non-tight semi-planar layouts.
+        var pos = ySize
+        val rowsUv = h / 2
+        val colsUv = w / 2
+        for (row in 0 until rowsUv) {
+            for (col in 0 until colsUv) {
+                val vIdx = row * vRowStride + col * vPixelStride
+                val uIdx = row * uRowStride + col * uPixelStride
+                nv21[pos++] = vBuf.get(vIdx)
+                nv21[pos++] = uBuf.get(uIdx)
+            }
+        }
+        return PackedYuv(nv21, w, h)
+    }
+
+
+    /**
+     * Encode an already-packed NV21 buffer to a JPEG file on disk.
+     *
+     * Returns the output path on success, or null on any encode/write
+     * error (caller decides whether to log + drop the frame).
+     *
+     * `displayRotation` writes the appropriate EXIF orientation tag
+     * so consumers that respect EXIF (RN's Image loader, etc.)
+     * display the JPEG upright regardless of how the device was held
+     * at capture.  Should be the value from
+     * `WindowManager.defaultDisplay.rotation` at capture time
+     * (Surface.ROTATION_0 / _90 / _180 / _270).
+     *
+     * Sensor orientation 90° assumed (back camera) — verified on
+     * Galaxy A35.  Wire `CameraCharacteristics.SENSOR_ORIENTATION`
+     * through in a follow-up if we hit a device that differs.
+     */
+    fun encodeJpegFromNV21(
+        packed: PackedYuv,
         outputPath: String,
         jpegQuality: Int = 70,
         displayRotation: Int = Surface.ROTATION_0,
     ): String? {
-        if (image.format != ImageFormat.YUV_420_888) return null
-        val nv21 = yuv420toNV21(image) ?: return null
         val yuvImage = YuvImage(
-            nv21,
+            packed.nv21,
             ImageFormat.NV21,
-            image.width,
-            image.height,
+            packed.width,
+            packed.height,
             null,
         )
         val baos = ByteArrayOutputStream()
         val ok = yuvImage.compressToJpeg(
-            Rect(0, 0, image.width, image.height),
+            Rect(0, 0, packed.width, packed.height),
             jpegQuality.coerceIn(1, 100),
             baos,
         )
@@ -81,8 +226,9 @@ internal object YuvImageConverter {
         } catch (e: Throwable) {
             return null
         }
+
         // Write EXIF orientation tag based on display rotation.
-        // Sensor orientation 90° assumed (back camera).  The math:
+        // The math:
         //   ROTATION_0  (portrait, sensor 90° CW from screen-up)
         //     → JPEG needs 90° CW to display upright → ROTATE_90 (6)
         //   ROTATION_90 (landscape-left, sensor aligned with screen)
@@ -93,11 +239,11 @@ internal object YuvImageConverter {
         //     → 180° → ROTATE_180 (3)
         //
         // EXIF tag set EVEN when the orientation is normal — keeps
-        // every output JPEG self-describing for downstream
-        // consumers (cv::Stitcher does NOT auto-honour EXIF, see
-        // BatchStitcher.applyExifOrientation; this metadata
-        // exists primarily for the live thumbnail strip + future
-        // RN Image renderers).
+        // every output JPEG self-describing for downstream consumers.
+        // cv::Stitcher does NOT auto-honour EXIF (see
+        // BatchStitcher.applyExifOrientation); this metadata exists
+        // primarily for the live thumbnail strip + future RN Image
+        // renderers.
         val exifOrientation = when (displayRotation) {
             Surface.ROTATION_0   -> ExifInterface.ORIENTATION_ROTATE_90
             Surface.ROTATION_90  -> ExifInterface.ORIENTATION_NORMAL
@@ -114,88 +260,35 @@ internal object YuvImageConverter {
             exif.saveAttributes()
         } catch (e: Throwable) {
             // EXIF write failed — JPEG itself is still valid; just
-            // missing the orientation hint.  Caller doesn't need to
-            // know — non-fatal.
+            // missing the orientation hint.  Non-fatal; caller doesn't
+            // need to know.
         }
         return outputPath
     }
 
+
     /**
-     * Pack a YUV_420_888 `Image` into a contiguous NV21 byte array.
+     * Single-call convenience wrapper: pack the `Image` and encode
+     * to JPEG in one step.  Keeps the `Image` open through the entire
+     * ~25 ms encode — fine for one-shot photo capture, NOT
+     * recommended for the ~60 Hz `forwardToIncremental` path.  See the
+     * file-level docs for the two-step alternative.
      *
-     * The Image API exposes Y, U, V as three planes, each with its
-     * own row stride and pixel stride.  NV21 expects a single
-     * contiguous buffer with Y plane first, then interleaved VU bytes
-     * after.  The repacking handles row + pixel strides that don't
-     * match the dense layout.
+     * Caller still owns the `Image` and MUST close it afterwards;
+     * this function does not.
      */
-    private fun yuv420toNV21(image: Image): ByteArray? {
-        val w = image.width
-        val h = image.height
-        val ySize = w * h
-        val uvSize = w * h / 2
-
-        val nv21 = ByteArray(ySize + uvSize)
-        val planes = image.planes
-        if (planes.size < 3) return null
-
-        // Y plane.
-        val yPlane = planes[0]
-        val yBuf = yPlane.buffer
-        val yRowStride = yPlane.rowStride
-        if (yRowStride == w) {
-            yBuf.get(nv21, 0, ySize)
-        } else {
-            // Row-by-row copy when stride != width.
-            var dstOffset = 0
-            var srcOffset = 0
-            for (row in 0 until h) {
-                yBuf.position(srcOffset)
-                yBuf.get(nv21, dstOffset, w)
-                dstOffset += w
-                srcOffset += yRowStride
-            }
-        }
-
-        // U + V planes.  YUV_420_888 has them subsampled 2:1 so each
-        // covers (w/2) × (h/2).  Pixel stride is 1 (planar) or 2
-        // (semi-planar interleaved).  NV21 requires interleaved VU.
-        val uPlane = planes[1]
-        val vPlane = planes[2]
-        val uBuf = uPlane.buffer
-        val vBuf = vPlane.buffer
-        val uRowStride = uPlane.rowStride
-        val uPixelStride = uPlane.pixelStride
-        val vRowStride = vPlane.rowStride
-        val vPixelStride = vPlane.pixelStride
-
-        // Most camera2 / ARCore implementations on Android already
-        // produce semi-planar interleaved data with pixelStride=2.
-        // In that case Y plane + V plane (offset by 1) form NV21
-        // directly with a single block copy.  Detect + fast-path it.
-        if (uPixelStride == 2 && vPixelStride == 2 &&
-            uRowStride == vRowStride && uRowStride == w) {
-            // The V plane in NV21 layout starts at vBuf's first byte.
-            // Copy the entire V plane (which physically interleaves
-            // with U bytes since pixelStride=2 means consecutive
-            // bytes are V-U-V-U...).
-            val vBytes = vBuf.remaining().coerceAtMost(uvSize)
-            vBuf.get(nv21, ySize, vBytes)
-            return nv21
-        }
-
-        // Slow path — manual interleave.
-        var pos = ySize
-        val rowsUv = h / 2
-        val colsUv = w / 2
-        for (row in 0 until rowsUv) {
-            for (col in 0 until colsUv) {
-                val vIdx = row * vRowStride + col * vPixelStride
-                val uIdx = row * uRowStride + col * uPixelStride
-                nv21[pos++] = vBuf.get(vIdx)
-                nv21[pos++] = uBuf.get(uIdx)
-            }
-        }
-        return nv21
+    fun encodeToJpeg(
+        image: Image,
+        outputPath: String,
+        jpegQuality: Int = 70,
+        displayRotation: Int = Surface.ROTATION_0,
+    ): String? {
+        val packed = packNV21(image) ?: return null
+        return encodeJpegFromNV21(
+            packed,
+            outputPath,
+            jpegQuality = jpegQuality,
+            displayRotation = displayRotation,
+        )
     }
 }

package/dist/camera/Camera.d.ts

@@ -40,6 +40,7 @@
  */
 import React from 'react';
 import { type StyleProp, type ViewStyle } from 'react-native';
+import type { DrawableFrameProcessor, ReadonlyFrameProcessor } from 'react-native-vision-camera';
 export type CaptureSource = 'ar' | 'non-ar';
 export type CameraLens = '1x' | '0.5x';
 export type StitchMode = 'auto' | 'panorama' | 'scans';
@@ -88,7 +89,16 @@ export type CameraCaptureResult = {
  * Errors surfaced via `onError`.  Classified codes so consumers can
  * branch on the kind of failure (toast vs retry vs report).
  */
-export type CameraErrorCode = 'CAMERA_PERMISSION_DENIED' | 'CAMERA_DEVICE_UNAVAILABLE' | 'PHOTO_CAPTURE_FAILED' | 'PANORAMA_START_FAILED' | 'PANORAMA_FINALIZE_FAILED' | 'STITCH_NEED_MORE_IMGS' | 'STITCH_HOMOGRAPHY_FAIL' | 'STITCH_CAMERA_PARAMS_FAIL' | 'STITCH_OOM' | 'OUTPUT_WRITE_FAILED' | 'UNKNOWN';
+export type CameraErrorCode = 'CAMERA_PERMISSION_DENIED' | 'CAMERA_DEVICE_UNAVAILABLE' | 'PHOTO_CAPTURE_FAILED' | 'PANORAMA_START_FAILED' | 'PANORAMA_FINALIZE_FAILED' | 'STITCH_NEED_MORE_IMGS' | 'STITCH_HOMOGRAPHY_FAIL' | 'STITCH_CAMERA_PARAMS_FAIL' | 'STITCH_OOM' | 'OUTPUT_WRITE_FAILED'
+/**
+ * Vision-camera surfaced a runtime error that isn't a known
+ * transient lifecycle event (those are swallowed inside the SDK's
+ * `<CameraView>`).  Examples that DO reach the host as this code:
+ * `format/invalid-format`, `capture/recording-canceled`,
+ * `device/microphone-permission-denied`, ...  The full error
+ * object is on `.cause` for inspection.
+ */
+ | 'VISION_CAMERA_RUNTIME' | 'UNKNOWN';
 export declare class CameraError extends Error {
     readonly code: CameraErrorCode;
     readonly cause?: unknown;
@@ -163,6 +173,45 @@ export interface CameraProps {
     onLensChange?: (lens: CameraLens) => void;
     onFramesDropped?: (info: FramesDroppedInfo) => void;
     onError?: (err: CameraError) => void;
+    /**
+     * Optional vision-camera frame processor.  Only attached to the
+     * non-AR preview (AR mode uses ARCameraView, which doesn't expose
+     * a worklet seam).  Build the worklet on the host side with
+     * `useFrameProcessor` from `react-native-vision-camera`.
+     *
+     * Introduced for F8 (FrameProcessor port) — see
+     * `docs/f8-frame-processor-plan.md`.
+     *
+     * As of v0.5 (F8.3) this prop is **deprecated for the standard
+     * non-AR capture flow**: the SDK now installs its own frame
+     * processor via `useFrameProcessorDriver` that pipes pixel
+     * buffers into the incremental stitcher with synthesised pose.
+     * Setting this prop in the default mode will be IGNORED with a
+     * one-time console.warn — supplying your own worklet would race
+     * with the SDK's pixel-buffer feed.
+     *
+     * Three coexistence rules:
+     *   * Default (modern non-AR): SDK owns the worklet, this prop
+     *     is ignored.
+     *   * `legacyDriver={true}`: SDK uses the old `useIncrementalJSDriver`
+     *     (takeSnapshot path).  Honoured for diagnostics or as an
+     *     escape hatch.
+     *   * AR mode: vision-camera Camera isn't mounted, this prop is
+     *     irrelevant.
+     */
+    frameProcessor?: ReadonlyFrameProcessor | DrawableFrameProcessor;
+    /**
+     * Opt back into the legacy `useIncrementalJSDriver` for non-AR
+     * captures (the v0.4 path: `takeSnapshot` → JPEG → cache file →
+     * `IncrementalStitcher.processFrameAtPath`).
+     *
+     * Default `false` (use the new `useFrameProcessorDriver`, which
+     * runs the gate on the camera producer thread at native frame
+     * rate via a vision-camera Frame Processor plugin).  The legacy
+     * path will be removed in v0.6 — set this only if you hit a
+     * specific issue with the new driver and need to ship a fix.
+     */
+    legacyDriver?: boolean;
 }
 /**
  * The public `<Camera>` component.

package/dist/camera/Camera.js

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