react-native-image-stitcher 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -16,6 +16,93 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] — 2026-05-26
+
+### Added — Tier 1: `useKeyframeStream`
+
+JS-thread subscription hook for **accepted-keyframe events** — the
+small subset of camera frames the stitching engine actually chose to
+include in the panorama.  Foundation for plugin-pattern host features:
+OCR on each saved keyframe, packet detection, server-side analysis,
+analytics, etc.
+
+Fires 4-6 times per panorama (once per accepted keyframe), NOT per
+camera frame — the lowest-frequency, highest-value frame stream.
+
+```tsx
+import { useKeyframeStream, type AcceptedKeyframe } from 'react-native-image-stitcher';
+
+function OcrPlugin() {
+  useKeyframeStream(useCallback(async (kf: AcceptedKeyframe) => {
+    const text = await runOCR(kf.jpegPath);
+    console.log(`Keyframe ${kf.index} pose=${kf.pose.rotation}:`, text);
+  }, []));
+  return null;
+}
+```
+
+- **`useKeyframeStream(handler)`** exported from
+  `react-native-image-stitcher`.  Subscribes to the existing
+  `IncrementalStateUpdate` event channel; surfaces accepted-keyframe
+  events through a typed callback.  Re-subscribes on handler-identity
+  changes; async handler rejections are surfaced via `console.error`
+  rather than swallowed.
+- **`AcceptedKeyframe` type** exported.  Fields: `jpegPath` (absolute
+  path, no `file://` prefix); `pose` (rotation quaternion + optional
+  translation vector); `timestamp` (ms since epoch); `index`
+  (zero-based position in current panorama).
+- **`IncrementalState.batchKeyframePose?`** + **`batchKeyframeAcceptedAtMs?`**
+  new optional fields.  Populated by the native emit alongside the
+  existing `batchKeyframeThumbnailPath` + `batchKeyframeIndex` on
+  accept events.  Direct readers of `IncrementalState` can consume
+  these without going through the new hook.
+
+### Changed (internal — externally invisible)
+
+- **Native `emitBatchKeyframeAcceptedState` populates pose + timestamp.**
+  Both `IncrementalStitcher.swift::emitBatchKeyframeAcceptedState` and
+  `IncrementalStitcher.kt::emitBatchKeyframeAcceptedState` grew
+  parameters for the pose snapshot (quaternion + translation) and
+  accept-time wall-clock millis.  The existing call sites in the
+  batch-keyframe accept path thread the pose they already have in
+  scope.
+
+### Engine-mode caveat
+
+`useKeyframeStream` only fires under the `batch-keyframe` engine (the
+`<Camera>` component's default).  Live engines (`firstwins-rectilinear`,
+`hybrid`, `slitscan-*`) paint into a live canvas instead of saving
+per-accept JPEGs and do not surface accept events through this channel
+— the hook silently does not fire in those modes.  Live-engine accept
+emit may land as a v0.7.1 follow-up if a real consumer needs it.
+
+### Translation semantics
+
+`AcceptedKeyframe.pose.translation` is always populated by the native
+emit.  In AR mode it carries the real ARKit / ARCore camera transform
+in metres (world coords).  In non-AR (Frame Processor) mode the
+translation reads as `[0, 0, 0]` because gyroscope provides only
+rotation (no spatial anchor).  Hosts that need to distinguish can
+either check the active `frameSourceMode` or threshold the translation
+magnitude.
+
+### Compatibility
+
+Strict additive over v0.6.0.  No host changes required.  Existing
+`subscribeIncrementalState` consumers see new optional fields but
+their existing reads are unaffected.
+
+### Verification
+
+- iPhone 17 Pro (real device, iOS 26.5): hold-and-release AR-mode
+  panorama produced four accepted-keyframe events with real pose
+  data (unit quaternion + non-zero translation in metres matching
+  the physical pan).
+- Android (Galaxy A35): `compileDebugKotlin` BUILD SUCCESSFUL;
+  on-device runtime verification deferred for this release (the
+  Kotlin emit mirrors the iOS emit at the byte-for-byte payload
+  level — same field names, same types, same call-site pattern).
+
 ## [0.6.0] — 2026-05-25
 
 > [!WARNING]
@@ -1161,7 +1248,8 @@ Native module names also changed:
 - iOS pod: `RetaiLensCaptureSDK` → `RNImageStitcher`
 - iOS xcframework: shipped as `opencv2.xcframework` (linked from `RNImageStitcher.podspec`)
 
-[Unreleased]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.5.1...v0.6.0
 [0.5.1]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.4.1...v0.5.0

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

@@ -1174,6 +1174,15 @@ class IncrementalStitcher(
                 keyframeMax = keyframeGate.maxCount,
                 isLandscape = imageWidth >= imageHeight,
                 newContentFraction = decision.newContentFraction,
+                // v0.7.0 — Tier 1 hook: pose snapshot + accept timestamp
+                // threaded through to JS via the existing state-update
+                // channel.  `tx,ty,tz,qx,qy,qz,qw` are parameters of
+                // `ingestFromARCameraView`; in AR mode they're real
+                // ARCore pose components, in non-AR mode they're
+                // gyro-synthesised (translation ≈ 0).
+                poseQx = qx, poseQy = qy, poseQz = qz, poseQw = qw,
+                poseTx = tx, poseTy = ty, poseTz = tz,
+                acceptedAtMs = System.currentTimeMillis(),
             )
             return
         }
@@ -2034,6 +2043,13 @@ class IncrementalStitcher(
         // "unknown" behaviour for call sites that don't have a
         // decision in hand.
         newContentFraction: Double,
+        // v0.7.0 — Tier 1 hook fields.  Pose is the AR pose at the
+        // accept moment (gyro-synthesised in non-AR mode — translation
+        // reads as ~zeros).  `acceptedAtMs` is wall-clock ms since
+        // Unix epoch; matches `Date.now()` on the JS side.
+        poseQx: Double, poseQy: Double, poseQz: Double, poseQw: Double,
+        poseTx: Double, poseTy: Double, poseTz: Double,
+        acceptedAtMs: Long,
     ) {
         val state = Arguments.createMap()
         state.putNull("panoramaPath")
@@ -2063,6 +2079,25 @@ class IncrementalStitcher(
         // emitter).
         state.putString("batchKeyframeThumbnailPath", thumbnailPath)
         state.putInt("batchKeyframeIndex", keyframeIndex)
+        // v0.7.0 — Tier 1 hook (useKeyframeStream) reads these.  See
+        // `AcceptedKeyframe` in src/stitching/incremental.ts.  Translation
+        // is always emitted; AR mode populates it from the camera
+        // transform, non-AR mode reads ~zeros (gyro-only, no spatial
+        // anchor).
+        val pose = Arguments.createMap()
+        val rotation = Arguments.createArray()
+        rotation.pushDouble(poseQx)
+        rotation.pushDouble(poseQy)
+        rotation.pushDouble(poseQz)
+        rotation.pushDouble(poseQw)
+        pose.putArray("rotation", rotation)
+        val translation = Arguments.createArray()
+        translation.pushDouble(poseTx)
+        translation.pushDouble(poseTy)
+        translation.pushDouble(poseTz)
+        pose.putArray("translation", translation)
+        state.putMap("batchKeyframePose", pose)
+        state.putDouble("batchKeyframeAcceptedAtMs", acceptedAtMs.toDouble())
         emitState(state)
     }
 

package/dist/index.d.ts

@@ -62,8 +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 { 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.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,6 +139,12 @@ 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; } });
+// 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).

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

package/dist/stitching/useKeyframeStream.d.ts

@@ -0,0 +1,69 @@
+import { type AcceptedKeyframe } from './incremental';
+/**
+ * v0.7.0 — Tier 1: subscribe to accepted-keyframe events while a
+ * panorama is in progress.
+ *
+ * Fires 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 such as OCR on the saved JPEG, packet
+ * detection, server-side analysis, or analytics.
+ *
+ * For mid-frequency frame access (sampled stream), see `useFrameStream`
+ * (v0.9.0+).  For per-frame worklet access (~30 Hz), see
+ * `useFrameProcessor` (v0.8.0+).
+ *
+ * ## Engine-mode caveat (v0.7.0)
+ *
+ * Only the `batch-keyframe` engine emits these events.  Live engines
+ * (`firstwins-rectilinear`, `hybrid`, `slitscan-*`) paint into a live
+ * canvas instead of saving per-accept JPEGs, and do not surface accept
+ * events through this channel — the hook silently does not fire when
+ * such an engine is active.  A v0.7.1 follow-up may add live-engine
+ * accept emit if a real consumer needs it.
+ *
+ * ## Payload
+ *
+ * The handler receives an {@link AcceptedKeyframe}:
+ *
+ *   - `jpegPath`: absolute filesystem path, no `file://` prefix.  The
+ *     JPEG 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 `cleanupOldKeyframes`).  Copy
+ *     synchronously inside the handler if long-term retention is
+ *     needed.
+ *   - `pose`: rotation quaternion (always present) + optional
+ *     translation vector (populated in AR mode; undefined in non-AR).
+ *   - `timestamp`: milliseconds since the Unix epoch.
+ *   - `index`: zero-based keyframe position in the current panorama.
+ *
+ * ## Lifecycle
+ *
+ * Re-subscribes on `handler` identity changes.  Wrap the handler in
+ * `useCallback` if it closes over state or props you don't want to
+ * trigger re-subscription on every render.
+ *
+ * Async handlers are fire-and-forget.  Rejected promises are caught
+ * and logged via `console.error`; no backpressure on the native side.
+ * Host code wanting to serialise work across keyframes should manage
+ * that itself (e.g., push into a queue + worker).
+ *
+ * ## Example
+ *
+ * ```tsx
+ * import { useCallback } from 'react';
+ * import { useKeyframeStream } from 'react-native-image-stitcher';
+ *
+ * function OcrPlugin() {
+ *   useKeyframeStream(
+ *     useCallback(async (kf) => {
+ *       const text = await runOCR(kf.jpegPath);
+ *       console.log(`Keyframe ${kf.index} pose=${kf.pose.rotation}:`, text);
+ *     }, []),
+ *   );
+ *   return null;
+ * }
+ * ```
+ */
+export declare function useKeyframeStream(handler: (keyframe: AcceptedKeyframe) => void | Promise<void>): void;
+//# sourceMappingURL=useKeyframeStream.d.ts.map

package/dist/stitching/useKeyframeStream.js

@@ -0,0 +1,120 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useKeyframeStream = useKeyframeStream;
+const react_1 = require("react");
+const incremental_1 = require("./incremental");
+/**
+ * v0.7.0 — Tier 1: subscribe to accepted-keyframe events while a
+ * panorama is in progress.
+ *
+ * Fires 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 such as OCR on the saved JPEG, packet
+ * detection, server-side analysis, or analytics.
+ *
+ * For mid-frequency frame access (sampled stream), see `useFrameStream`
+ * (v0.9.0+).  For per-frame worklet access (~30 Hz), see
+ * `useFrameProcessor` (v0.8.0+).
+ *
+ * ## Engine-mode caveat (v0.7.0)
+ *
+ * Only the `batch-keyframe` engine emits these events.  Live engines
+ * (`firstwins-rectilinear`, `hybrid`, `slitscan-*`) paint into a live
+ * canvas instead of saving per-accept JPEGs, and do not surface accept
+ * events through this channel — the hook silently does not fire when
+ * such an engine is active.  A v0.7.1 follow-up may add live-engine
+ * accept emit if a real consumer needs it.
+ *
+ * ## Payload
+ *
+ * The handler receives an {@link AcceptedKeyframe}:
+ *
+ *   - `jpegPath`: absolute filesystem path, no `file://` prefix.  The
+ *     JPEG 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 `cleanupOldKeyframes`).  Copy
+ *     synchronously inside the handler if long-term retention is
+ *     needed.
+ *   - `pose`: rotation quaternion (always present) + optional
+ *     translation vector (populated in AR mode; undefined in non-AR).
+ *   - `timestamp`: milliseconds since the Unix epoch.
+ *   - `index`: zero-based keyframe position in the current panorama.
+ *
+ * ## Lifecycle
+ *
+ * Re-subscribes on `handler` identity changes.  Wrap the handler in
+ * `useCallback` if it closes over state or props you don't want to
+ * trigger re-subscription on every render.
+ *
+ * Async handlers are fire-and-forget.  Rejected promises are caught
+ * and logged via `console.error`; no backpressure on the native side.
+ * Host code wanting to serialise work across keyframes should manage
+ * that itself (e.g., push into a queue + worker).
+ *
+ * ## Example
+ *
+ * ```tsx
+ * import { useCallback } from 'react';
+ * import { useKeyframeStream } from 'react-native-image-stitcher';
+ *
+ * function OcrPlugin() {
+ *   useKeyframeStream(
+ *     useCallback(async (kf) => {
+ *       const text = await runOCR(kf.jpegPath);
+ *       console.log(`Keyframe ${kf.index} pose=${kf.pose.rotation}:`, text);
+ *     }, []),
+ *   );
+ *   return null;
+ * }
+ * ```
+ */
+function useKeyframeStream(handler) {
+    (0, react_1.useEffect)(() => {
+        const sub = (0, incremental_1.subscribeIncrementalState)((state) => {
+            // The `batch-keyframe` engine emits four optional fields together
+            // on accept events.  Non-accept emits (snapshot updates,
+            // refinement progress, live-engine state ticks, etc.) leave
+            // `batchKeyframeThumbnailPath` undefined — that's our
+            // accept-event sentinel.
+            const jpegPath = state.batchKeyframeThumbnailPath;
+            const index = state.batchKeyframeIndex;
+            if (jpegPath === undefined || index === undefined) {
+                return;
+            }
+            // `batchKeyframePose` + `batchKeyframeAcceptedAtMs` are
+            // populated alongside the path + index by the post-v0.7.0
+            // native emit.  Defensive defaults guard against a host
+            // running on a slightly-older native binary (e.g., during a
+            // partial upgrade) — identity quaternion + `Date.now()`.
+            // Published v0.7.0 native always populates both.
+            const pose = state.batchKeyframePose ?? {
+                rotation: [0, 0, 0, 1],
+            };
+            const timestamp = state.batchKeyframeAcceptedAtMs ?? Date.now();
+            const keyframe = {
+                jpegPath,
+                pose,
+                timestamp,
+                index,
+            };
+            // Fire-and-forget.  Async handler rejections are surfaced via
+            // console.error so they don't disappear into the void.
+            const result = handler(keyframe);
+            if (result && typeof result.catch === 'function') {
+                result.catch((err) => {
+                    // eslint-disable-next-line no-console
+                    console.error('[useKeyframeStream] handler threw:', err);
+                });
+            }
+        });
+        // `subscribeIncrementalState` returns null when the native module
+        // isn't linked (Expo Go, unit tests without the bridge, etc.).
+        // In that case we have nothing to clean up.
+        if (sub === null)
+            return;
+        return () => sub.remove();
+    }, [handler]);
+}
+//# sourceMappingURL=useKeyframeStream.js.map

package/ios/Sources/RNImageStitcher/IncrementalStitcher.swift

@@ -2160,7 +2160,13 @@ public final class IncrementalStitcher: NSObject {
         keyframeIndex: Int,
         keyframeCount: Int,
         keyframeMax: Int,
-        isLandscape: Bool
+        isLandscape: Bool,
+        // v0.7.0 — Tier 1 hook fields.  `pose` is the AR pose at the
+        // accept moment (gyro-synthesised in non-AR mode — translation
+        // will read as ~zeros).  `acceptedAtMs` is wall-clock ms since
+        // Unix epoch; matches `Date.now()` on the JS side.
+        pose: RNSARFramePose,
+        acceptedAtMs: Double
     ) {
         let state = IncrementalStateObject(
             panoramaPath: nil,
@@ -2184,6 +2190,16 @@ public final class IncrementalStitcher: NSObject {
         // carry — JS reads these directly from the userInfo blob.
         dict["batchKeyframeThumbnailPath"] = thumbnailPath
         dict["batchKeyframeIndex"] = keyframeIndex
+        // v0.7.0 — Tier 1 hook (useKeyframeStream) reads these.  See
+        // `AcceptedKeyframe` in src/stitching/incremental.ts.  Translation
+        // is always emitted; AR mode populates it from the camera
+        // transform, non-AR mode reads ~zeros (gyro-only, no spatial
+        // anchor).
+        dict["batchKeyframePose"] = [
+            "rotation": [pose.qx, pose.qy, pose.qz, pose.qw],
+            "translation": [pose.tx, pose.ty, pose.tz],
+        ] as [String: Any]
+        dict["batchKeyframeAcceptedAtMs"] = acceptedAtMs
         NotificationCenter.default.post(
             name: .retailensIncrementalStateUpdate,
             object: nil,
@@ -2637,7 +2653,12 @@ public final class IncrementalStitcher: NSObject {
                         keyframeIndex: Int(record.index),
                         keyframeCount: count,
                         keyframeMax: self.keyframeGate.maxCount,
-                        isLandscape: pose.imageWidth >= pose.imageHeight
+                        isLandscape: pose.imageWidth >= pose.imageHeight,
+                        // v0.7.0 — Tier 1 hook: pose snapshot + accept
+                        // timestamp threaded through to JS via the
+                        // existing state-update channel.
+                        pose: pose,
+                        acceptedAtMs: Date().timeIntervalSince1970 * 1000
                     )
                 } catch let err as NSError {
                     os_log(.fault, log: Self.diagLog,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.6.0",
+  "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/index.ts

@@ -175,8 +175,13 @@ export {
   getIncrementalNativeModule,
   cleanupOldKeyframes,
 } from './stitching/incremental';
-export type { IncrementalState } from './stitching/incremental';
+export type { IncrementalState, AcceptedKeyframe } from './stitching/incremental';
 export { useIncrementalStitcher } from './stitching/useIncrementalStitcher';
+// 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).

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

package/src/stitching/useKeyframeStream.ts

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import { useEffect } from 'react';
+
+import {
+  subscribeIncrementalState,
+  type AcceptedKeyframe,
+  type IncrementalState,
+} from './incremental';
+
+/**
+ * v0.7.0 — Tier 1: subscribe to accepted-keyframe events while a
+ * panorama is in progress.
+ *
+ * Fires 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 such as OCR on the saved JPEG, packet
+ * detection, server-side analysis, or analytics.
+ *
+ * For mid-frequency frame access (sampled stream), see `useFrameStream`
+ * (v0.9.0+).  For per-frame worklet access (~30 Hz), see
+ * `useFrameProcessor` (v0.8.0+).
+ *
+ * ## Engine-mode caveat (v0.7.0)
+ *
+ * Only the `batch-keyframe` engine emits these events.  Live engines
+ * (`firstwins-rectilinear`, `hybrid`, `slitscan-*`) paint into a live
+ * canvas instead of saving per-accept JPEGs, and do not surface accept
+ * events through this channel — the hook silently does not fire when
+ * such an engine is active.  A v0.7.1 follow-up may add live-engine
+ * accept emit if a real consumer needs it.
+ *
+ * ## Payload
+ *
+ * The handler receives an {@link AcceptedKeyframe}:
+ *
+ *   - `jpegPath`: absolute filesystem path, no `file://` prefix.  The
+ *     JPEG 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 `cleanupOldKeyframes`).  Copy
+ *     synchronously inside the handler if long-term retention is
+ *     needed.
+ *   - `pose`: rotation quaternion (always present) + optional
+ *     translation vector (populated in AR mode; undefined in non-AR).
+ *   - `timestamp`: milliseconds since the Unix epoch.
+ *   - `index`: zero-based keyframe position in the current panorama.
+ *
+ * ## Lifecycle
+ *
+ * Re-subscribes on `handler` identity changes.  Wrap the handler in
+ * `useCallback` if it closes over state or props you don't want to
+ * trigger re-subscription on every render.
+ *
+ * Async handlers are fire-and-forget.  Rejected promises are caught
+ * and logged via `console.error`; no backpressure on the native side.
+ * Host code wanting to serialise work across keyframes should manage
+ * that itself (e.g., push into a queue + worker).
+ *
+ * ## Example
+ *
+ * ```tsx
+ * import { useCallback } from 'react';
+ * import { useKeyframeStream } from 'react-native-image-stitcher';
+ *
+ * function OcrPlugin() {
+ *   useKeyframeStream(
+ *     useCallback(async (kf) => {
+ *       const text = await runOCR(kf.jpegPath);
+ *       console.log(`Keyframe ${kf.index} pose=${kf.pose.rotation}:`, text);
+ *     }, []),
+ *   );
+ *   return null;
+ * }
+ * ```
+ */
+export function useKeyframeStream(
+  handler: (keyframe: AcceptedKeyframe) => void | Promise<void>,
+): void {
+  useEffect(() => {
+    const sub = subscribeIncrementalState((state: IncrementalState) => {
+      // The `batch-keyframe` engine emits four optional fields together
+      // on accept events.  Non-accept emits (snapshot updates,
+      // refinement progress, live-engine state ticks, etc.) leave
+      // `batchKeyframeThumbnailPath` undefined — that's our
+      // accept-event sentinel.
+      const jpegPath = state.batchKeyframeThumbnailPath;
+      const index = state.batchKeyframeIndex;
+      if (jpegPath === undefined || index === undefined) {
+        return;
+      }
+
+      // `batchKeyframePose` + `batchKeyframeAcceptedAtMs` are
+      // populated alongside the path + index by the post-v0.7.0
+      // native emit.  Defensive defaults guard against a host
+      // running on a slightly-older native binary (e.g., during a
+      // partial upgrade) — identity quaternion + `Date.now()`.
+      // Published v0.7.0 native always populates both.
+      const pose = state.batchKeyframePose ?? {
+        rotation: [0, 0, 0, 1] as [number, number, number, number],
+      };
+      const timestamp = state.batchKeyframeAcceptedAtMs ?? Date.now();
+
+      const keyframe: AcceptedKeyframe = {
+        jpegPath,
+        pose,
+        timestamp,
+        index,
+      };
+
+      // Fire-and-forget.  Async handler rejections are surfaced via
+      // console.error so they don't disappear into the void.
+      const result = handler(keyframe);
+      if (result && typeof (result as Promise<void>).catch === 'function') {
+        (result as Promise<void>).catch((err) => {
+          // eslint-disable-next-line no-console
+          console.error('[useKeyframeStream] handler threw:', err);
+        });
+      }
+    });
+    // `subscribeIncrementalState` returns null when the native module
+    // isn't linked (Expo Go, unit tests without the bridge, etc.).
+    // In that case we have nothing to clean up.
+    if (sub === null) return;
+    return () => sub.remove();
+  }, [handler]);
+}