react-native-image-stitcher 0.5.1 → 0.7.0

package/ios/Sources/RNImageStitcher/IncrementalStitcherBridge.swift

@@ -20,7 +20,6 @@
 import Foundation
 import React
 import os.log
-import ImageIO        // CGImageSource + kCGImagePropertyOrientation for EXIF read in processFrameAtPath
 
 @objc(IncrementalStitcherBridge)
 public final class IncrementalStitcherBridge: RCTEventEmitter {
@@ -75,10 +74,12 @@ public final class IncrementalStitcherBridge: RCTEventEmitter {
     /// Resolves with `{ ok: true }`.  Rejects when `frameSourceMode`
     /// (options dict) is 'arSession' (the default) AND the AR session
     /// isn't running — that path needs ARKit to deliver frames.
-    /// When `frameSourceMode` is 'jsDriver' the AR-session check is
-    /// skipped and the engine expects JS to feed frames via
-    /// `processFrameAtPath` (used by iOS non-AR captures since
-    /// 2026-05-18 / Issue #2 regression fix).
+    /// When `frameSourceMode` is 'frameProcessor' the AR-session check
+    /// is skipped and the engine expects the vision-camera Frame
+    /// Processor plugin (`CvFlowGateFrameProcessor`) to feed frames
+    /// via `consumeFrameFromPlugin`.  The pre-v0.6 'jsDriver' mode
+    /// (push frames in from JS via `processFrameAtPath`) has been
+    /// removed.
     @objc(start:resolver:rejecter:)
     public func start(
         options: NSDictionary,
@@ -251,127 +252,6 @@ public final class IncrementalStitcherBridge: RCTEventEmitter {
         resolver(["ok": true])
     }
 
-    /// 2026-05-18 (Issue #2 v2) — JS-driven frame ingestion for iOS
-    /// non-AR mode.  Mirrors Android's `processFrameAtPath` exactly:
-    /// the JPEG at `path` is already saved on disk by vision-camera
-    /// in its native EXIF-correct orientation.  We DO NOT decode the
-    /// image here.  Instead:
-    ///
-    ///   - Build a synthetic `RNSARFramePose` from the
-    ///     JS-supplied quaternion + intrinsics (no translation;
-    ///     non-AR captures don't have it).
-    ///   - Hand the path + pose to
-    ///     `IncrementalStitcher.addBatchKeyframePath`, which
-    ///     evaluates the shared-C++ KeyframeGate and (if accepted)
-    ///     records the path in the finalize-time keyframe list +
-    ///     emits the same state event the AR-delegate path emits.
-    ///   - `cv::imread` at finalize handles EXIF orientation
-    ///     natively, so the output panorama reads upright with no
-    ///     iOS-specific orientation handling needed in this bridge.
-    ///
-    /// History: Issue #2 v1 (commit 0e40f17) tried to decode the
-    /// JPEG into a CVPixelBuffer and reuse the existing AR
-    /// `consumeFrame(pixelBuffer:pose:)` path.  That introduced two
-    /// orientation bugs (CGContext Y-flip + UIImage.size vs
-    /// cgImage.width dim swap) → upside-down output AND canvas-
-    /// dimension overflow → OOM crashes (user-reported 2026-05-18).
-    /// Architecturally Android never decoded the image either, so
-    /// the right fix was to mirror that.
-    ///
-    /// `options` keys:
-    ///   - path (NSString, required) — local file path (no file://)
-    ///   - qx, qy, qz, qw (Double, required) — quaternion, JS-side
-    ///     gyro-integrated
-    ///   - fx, fy, cx, cy (Double, required) — intrinsics in sensor px
-    ///   - imageWidth, imageHeight (Int, required)
-    ///   - trackingPoor (Bool, optional, default false)
-    ///   - timestampMs (Double, optional, default = now)
-    ///
-    /// Only batch-keyframe captures are supported on this path right
-    /// now — other engines (hybrid / firstwins) need real pixel data
-    /// during the live phase, which isn't trivially derivable from a
-    /// JPEG path.  Reject with `E_NOT_BATCH_KEYFRAME` so the JS host
-    /// can fall back to the legacy stitchVideo path if needed.
-    @objc(processFrameAtPath:resolver:rejecter:)
-    public func processFrameAtPath(
-        options: NSDictionary,
-        resolver: @escaping RCTPromiseResolveBlock,
-        rejecter: @escaping RCTPromiseRejectBlock
-    ) {
-        guard let pathRaw = options["path"] as? String, !pathRaw.isEmpty else {
-            rejecter("E_NO_PATH", "processFrameAtPath: missing 'path'", nil)
-            return
-        }
-        // Strip optional file:// prefix — JS callers sometimes send
-        // file URIs, native APIs want filesystem paths.
-        let cleanPath = pathRaw.hasPrefix("file://")
-            ? String(pathRaw.dropFirst("file://".count))
-            : pathRaw
-
-        let engine = IncrementalStitcher.shared
-        guard engine.isBatchKeyframeMode else {
-            rejecter("E_NOT_BATCH_KEYFRAME",
-                     "processFrameAtPath only supports batch-keyframe "
-                     + "engine mode on iOS.  Configure "
-                     + "incrementalEngine='batch-keyframe' in start() "
-                     + "options, or fall back to the stitchVideo path.",
-                     nil)
-            return
-        }
-
-        let qx = (options["qx"] as? Double) ?? 0
-        let qy = (options["qy"] as? Double) ?? 0
-        let qz = (options["qz"] as? Double) ?? 0
-        let qw = (options["qw"] as? Double) ?? 1   // identity quat default
-        let fx = (options["fx"] as? Double) ?? 1000.0
-        let fy = (options["fy"] as? Double) ?? 1000.0
-        let cx = (options["cx"] as? Double) ?? 540.0
-        let cy = (options["cy"] as? Double) ?? 960.0
-        let imageWidth = (options["imageWidth"] as? Int) ?? 1080
-        let imageHeight = (options["imageHeight"] as? Int) ?? 1920
-        let trackingPoor = (options["trackingPoor"] as? Bool) ?? false
-        let timestampMs = (options["timestampMs"] as? Double)
-            ?? (Date().timeIntervalSince1970 * 1000.0)
-        let trackingState: RNSARTrackingState =
-            trackingPoor ? .limited : .tracking
-
-        let pose = RNSARFramePose(
-            tx: 0, ty: 0, tz: 0,           // no translation in non-AR
-            qx: qx, qy: qy, qz: qz, qw: qw,
-            fx: fx, fy: fy, cx: cx, cy: cy,
-            imageWidth: imageWidth, imageHeight: imageHeight,
-            timestampMs: timestampMs,
-            trackingState: trackingState
-        )
-
-        // 2026-05-18 (Iss #1 diag) — read EXIF Orientation tag from the
-        // keyframe JPEG before handing it to the engine.  vision-camera
-        // writes a JPEG with an EXIF tag matching the physical capture
-        // orientation (1=no rotation, 3=180°, 6=90°CW, 8=90°CCW).  The
-        // bake-rotation table in cpp/stitcher.cpp assumes the post-imread
-        // Mat is in user-view orientation (post-EXIF apply).  If the EXIF
-        // tag isn't what we expect for a given physical orientation, the
-        // input Mat to cv::Stitcher will be a different shape than the AR
-        // path produces (AR keyframes hardcode EXIF=6, commit 7b828f1) —
-        // which would explain why iOS non-AR landscape captures stitch
-        // but bake the wrong way.  CGImageSource is cheap (metadata-only;
-        // no decode).
-        var exifOrientation: Int = -1
-        if let src = CGImageSourceCreateWithURL(
-            URL(fileURLWithPath: cleanPath) as CFURL, nil
-        ),
-           let props = CGImageSourceCopyPropertiesAtIndex(src, 0, nil) as? [CFString: Any],
-           let o = props[kCGImagePropertyOrientation] as? Int {
-            exifOrientation = o
-        }
-        os_log(.fault, log: OSLog(subsystem: "com.tiger.retailens",
-                                  category: "stitcher.diag"),
-               "[V16-batch-keyframe.js] processFrameAtPath EXIF=%d imageW=%d imageH=%d path=%{public}@",
-               Int32(exifOrientation), Int32(imageWidth), Int32(imageHeight), cleanPath)
-
-        let accepted = engine.addBatchKeyframePath(path: cleanPath, pose: pose)
-        resolver(["ok": true, "accepted": accepted])
-    }
 
     /// 2026-05-18 (Iss 3) — bridge for `cleanupKeyframes`.  See the
     /// Swift method's docstring for behaviour.  Options dict keys:

package/ios/Sources/RNImageStitcher/KeyframeGateFrameProcessor.mm

@@ -140,13 +140,13 @@ static NSInteger kg_argInt(NSDictionary* args, NSString* key, NSInteger defaultV
   // Pose from worklet args.  Defaults are safe non-AR values:
   //   * tx/ty/tz = 0 (no translation in non-AR; gyro only gives rot)
   //   * qw = 1 (identity quaternion if JS hasn't supplied rotation)
-  //   * fx/fy/cx/cy = 0 → JS-driver caller MUST supply these (the
-  //     engine derives FoV from intrinsics; 0 would yield NaN FoV).
-  //     We default the principal point to image centre as a safer
-  //     fallback if only fx/fy are missing.
+  //   * fx/fy/cx/cy = 0 → the Frame Processor worklet caller MUST
+  //     supply these (the engine derives FoV from intrinsics; 0 would
+  //     yield NaN FoV).  We default the principal point to image
+  //     centre as a safer fallback if only fx/fy are missing.
   //   * trackingStateRaw = 2 → `.tracking` (non-AR captures don't
-  //     have a real tracking-quality signal; engine's `trackingPoor`
-  //     path stays inactive, matching legacy `useIncrementalJSDriver`).
+  //     have a real tracking-quality signal; reporting `.tracking`
+  //     keeps the engine's `trackingPoor` path inactive).
   double tx = kg_argDouble(arguments, @"tx", 0.0);
   double ty = kg_argDouble(arguments, @"ty", 0.0);
   double tz = kg_argDouble(arguments, @"tz", 0.0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Pose-aware panorama capture + stitching for React Native. One <Camera> component, both tap-to-photo and hold-to-pan modes, both AR-backed and IMU-fallback capture paths.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/camera/Camera.tsx

@@ -89,7 +89,6 @@ import {
   subscribeIncrementalState,
   type IncrementalState,
 } from '../stitching/incremental';
-import { useIncrementalJSDriver } from '../stitching/useIncrementalJSDriver';
 import { useFrameProcessorDriver } from '../stitching/useFrameProcessorDriver';
 import { useIncrementalStitcher } from '../stitching/useIncrementalStitcher';
 import { useIMUTranslationGate } from '../sensors/useIMUTranslationGate';
@@ -303,37 +302,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;
 }
 
 
@@ -609,7 +591,6 @@ export function Camera(props: CameraProps): React.JSX.Element {
     onFramesDropped,
     onError,
     frameProcessor: hostFrameProcessor,
-    legacyDriver = false,
     engine = 'batch-keyframe',
   } = props;
 
@@ -790,63 +771,49 @@ export function Camera(props: CameraProps): React.JSX.Element {
     },
   });
 
-  // 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 = 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 = 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
-  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).
+  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 = 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 ──────────
   useEffect(() => {
@@ -903,17 +870,17 @@ export function Camera(props: CameraProps): React.JSX.Element {
     const accepted = incrementalState?.acceptedCount ?? 0;
     if (accepted > lastAcceptedCountRef.current) {
       lastAcceptedCountRef.current = accepted;
-      // F8.3 review-of-review (M3 revert): originally gated this to
-      // `legacyDriver` because the Frame Processor driver doesn't
-      // consult `imuGate` for its own pose synthesis.  That ignored a
-      // load-bearing side effect: `imuGate.resetAnchor()` bounds the
-      // IIR-integrator drift window per-accept, and
-      // `imuGate.getTotalAbsMetres()` is read at finalize time
-      // (Camera.tsx:1097) as `imuTranslationMetres` into the native
+      // 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();
       }
@@ -1044,13 +1011,11 @@ export function Camera(props: CameraProps): React.JSX.Element {
         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,
@@ -1066,21 +1031,13 @@ export function Camera(props: CameraProps): React.JSX.Element {
       // 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) {
       setStatusPhase('idle');
@@ -1100,9 +1057,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
     settings,
     effectiveCaptureSource,
     imuGate,
-    jsDriver,
     fpDriver,
-    legacyDriver,
     engine,
     onError,
   ]);
@@ -1112,10 +1067,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
     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
@@ -1193,7 +1145,6 @@ export function Camera(props: CameraProps): React.JSX.Element {
     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/src/index.ts

@@ -175,16 +175,16 @@ export {
   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';
-// 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.).
+export { useKeyframeStream } from './stitching/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).
 export { useFrameProcessorDriver } from './stitching/useFrameProcessorDriver';
 export type {
   UseFrameProcessorDriverOptions,

package/src/stitching/incremental.ts

@@ -61,6 +61,53 @@ export enum IncrementalOutcome {
 }
 
 
+/**
+ * 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
@@ -152,6 +199,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
@@ -200,23 +274,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/src/stitching/useFrameProcessorDriver.ts

@@ -1,14 +1,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
@@ -303,9 +304,9 @@ export function useFrameProcessorDriver(
     //   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.
     setUpdateIntervalForType(SensorTypes.gyroscope, gyroIntervalMs);
     gyroSubRef.current = gyroscope.subscribe({
       next: ({ x, y, z }) => {
@@ -382,8 +383,8 @@ export function useFrameProcessorDriver(
       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