react-native-image-stitcher 0.5.1 → 0.7.0

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

@@ -200,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, engine = 'batch-keyframe', } = 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,13 +636,11 @@ 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,
@@ -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,7 @@ function Camera(props) {
         settings,
         effectiveCaptureSource,
         imuGate,
-        jsDriver,
         fpDriver,
-        legacyDriver,
         engine,
         onError,
     ]);
@@ -715,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
@@ -788,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

@@ -62,10 +62,9 @@ export type { TakePhotoCallOptions } from './camera/useCapture';
 export { useVideoCapture } from './camera/useVideoCapture';
 export { useDeviceOrientation } from './camera/useDeviceOrientation';
 export { IncrementalOutcome, incrementalStitcherIsAvailable, subscribeIncrementalState, getIncrementalNativeModule, cleanupOldKeyframes, } from './stitching/incremental';
-export type { IncrementalState } from './stitching/incremental';
+export type { IncrementalState, AcceptedKeyframe } from './stitching/incremental';
 export { useIncrementalStitcher } from './stitching/useIncrementalStitcher';
-export { useIncrementalJSDriver } from './stitching/useIncrementalJSDriver';
-export type { UseIncrementalJSDriverOptions, IncrementalJSDriverHandle, } from './stitching/useIncrementalJSDriver';
+export { useKeyframeStream } from './stitching/useKeyframeStream';
 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.useKeyframeStream = 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,15 @@ 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.
+// v0.7.0 — Tier 1 subscriber API.  Fires on each accepted keyframe
+// in batch-keyframe captures (see hook's docstring for engine-mode
+// caveat).  Foundation for plugin-pattern host features (OCR per
+// keyframe, packet detection, server-side analysis, etc.).
+var useKeyframeStream_1 = require("./stitching/useKeyframeStream");
+Object.defineProperty(exports, "useKeyframeStream", { enumerable: true, get: function () { return useKeyframeStream_1.useKeyframeStream; } });
+// 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

@@ -54,6 +54,48 @@ export declare enum IncrementalOutcome {
      */
     SkippedKeyframeMaxReached = 9
 }
+/**
+ * v0.7.0 (Tier 1) — public payload type for an accepted keyframe.
+ * Delivered to subscribers of the `useKeyframeStream` hook.
+ *
+ * Emits once per keyframe accepted by the stitching engine — typically
+ * 4-6 times per panorama, not per camera frame.  Use for low-frequency
+ * per-keyframe host work (OCR on the saved JPEG, packet detection,
+ * server-side analysis, analytics, etc.).
+ *
+ * Caveat: only the `batch-keyframe` engine emits these events as of
+ * v0.7.0.  Live engines (`firstwins-rectilinear`, `hybrid`,
+ * `slitscan-*`) paint into a live canvas instead of saving per-accept
+ * JPEGs and do not currently surface accept events through this
+ * channel; the hook silently does not fire there.  A v0.7.1 follow-up
+ * may add live-engine accept emit if a real consumer needs it.
+ *
+ * The JPEG at `jpegPath` is the engine's own copy under the active
+ * capture's session directory.  It persists for the lifetime of the
+ * panorama and is cleaned up automatically when the panorama finalises
+ * or is abandoned (or via explicit `cleanupKeyframes`).  Host code
+ * wanting to retain it long-term must copy synchronously inside the
+ * handler.
+ */
+export interface AcceptedKeyframe {
+    /** Absolute filesystem path to the keyframe JPEG.  No `file://` prefix. */
+    jpegPath: string;
+    /**
+     * Pose snapshot at the moment of acceptance.  Quaternion
+     * convention: `(x, y, z, w)`; lib uses
+     * `q = q_yaw * q_pitch * q_roll`.  Translation in metres (world
+     * coords) is present in AR mode and undefined in non-AR mode (no
+     * spatial anchor — only gyro-derived rotation is available).
+     */
+    pose: {
+        rotation: [number, number, number, number];
+        translation?: [number, number, number];
+    };
+    /** Milliseconds since the Unix epoch when the engine accepted this keyframe. */
+    timestamp: number;
+    /** Zero-based index of this keyframe within the in-progress panorama. */
+    index: number;
+}
 export interface IncrementalState {
     /**
      * Path to the latest panorama snapshot JPEG (file path, no
@@ -145,6 +187,33 @@ export interface IncrementalState {
      * for the thumbnail strip.
      */
     batchKeyframeIndex?: number;
+    /**
+     * v0.7.0 (Tier 1) — pose snapshot at the moment the engine
+     * accepted this keyframe.  Populated alongside
+     * `batchKeyframeThumbnailPath` + `batchKeyframeIndex` on the
+     * keyframe-accepted state emit from the `batch-keyframe` engine.
+     * Undefined for other engines and for non-accept events.
+     *
+     * Quaternion convention: `(x, y, z, w)`; lib uses
+     * `q = q_yaw * q_pitch * q_roll`.  AR mode populates `translation`
+     * from the AR camera transform (metres, world coords).  Non-AR
+     * mode omits `translation` (no spatial anchor — only gyro-derived
+     * rotation is available).
+     *
+     * Foundation for the `useKeyframeStream` Tier 1 host hook.
+     */
+    batchKeyframePose?: {
+        rotation: [number, number, number, number];
+        translation?: [number, number, number];
+    };
+    /**
+     * v0.7.0 (Tier 1) — monotonic timestamp (milliseconds since the
+     * Unix epoch) when the engine accepted this keyframe.  Populated
+     * alongside the other `batchKeyframe*` fields on the
+     * keyframe-accepted emit.  Undefined for other engines and for
+     * non-accept events.
+     */
+    batchKeyframeAcceptedAtMs?: number;
     /**
      * 2026-05-16 — realtime+batch fusion (Option A "Replace on
      * completion").  True between the moment a hybrid-engine
@@ -191,23 +260,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