react-native-image-stitcher 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -16,6 +16,125 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] — 2026-05-27
+
+### Added — layered frame-access helpers
+
+Three new primitives completing the Tier 2 surface in the
+three-tier extensibility pattern.  See `docs/frame-access-tiers.md`
+for the full decision flow + use-case mapping.
+
+#### Layer 1 — `save_frame_as_jpeg` vc Frame Processor plugin (native)
+
+Worklet-callable JPEG encoder. Registers on both platforms:
+
+- **iOS** — `SaveFrameAsJpegPlugin.mm` (CIImage → CGImage → UIImage
+  → UIImageJPEGRepresentation → atomic NSData write).  Registered
+  via `+ (void)load` hook into `FrameProcessorPluginRegistry`.
+- **Android** — `SaveFrameAsJpegPlugin.kt` wrapping the lib's
+  existing `YuvImageConverter.encodeJpegFromNV21` encoder (the
+  same one used by `RNSARCameraView`'s keyframe-accept callback).
+  Registered alongside `cv_flow_gate_process_frame` in
+  `RNImageStitcherPackage.ensureFrameProcessorPluginRegistered`.
+
+Plugin contract (identical on both platforms):
+  - Args: `path` (string, REQUIRED), `quality` (number 0-100,
+    default 75, clamped `[1, 100]`)
+  - Returns: `{ ok: true, path, width, height }` OR
+             `{ ok: false, error: "..." }`
+
+Hosts can call this directly from their own `useFrameProcessor`
+worklet for custom rate-control logic; most consumers use it
+indirectly via Layer 3.
+
+#### Layer 2 — `useThrottledFrameProcessor` hook
+
+```tsx
+const fp = useThrottledFrameProcessor(
+  (frame) => {
+    'worklet';
+    // Worklet-native processing at sub-frame-rate
+  },
+  { sampleHz: 2 },
+  [],
+);
+```
+
+Pure TS throttle gate over `useFrameProcessor` (v0.8.0).  Worklet
+fires up to `sampleHz` times per second; ticks too close together
+dropped via a monotonic-time `useSharedValue` gate.
+
+**Use for**: worklet-native processing — native OCR via
+Vision.framework / ML Kit wrapped as vc Frame Processor plugins,
+TFLite ML inference, LiDAR depth (`frame.arDepth`).  Direct
+buffer/pose/depth access in the worklet; bridge small bbox-result
+payloads to JS via `runOnJS`.
+
+`sampleHz` clamped to `[0.5, 30]`.
+
+#### Layer 3 — `useFrameStream` hook
+
+```tsx
+const fp = useFrameStream(
+  { sampleHz: 2, quality: 75 },
+  (sample) => {
+    // JS-thread callback: sample.jpegPath, sample.pose, sample.timestamp
+    setThumbnail(sample.jpegPath);
+  },
+);
+```
+
+Composes Layer 2 + Layer 1 + `runOnJS` bridge to deliver
+`SampledFrame` objects to a JS-thread handler.  Slot-reuse
+strategy bounds disk usage to ~4 stale JPEGs.
+
+**Use for**: JS-thread consumers — file-path OCR libraries (RN
+modules wrapping ML Kit), cloud upload, thumbnail preview UI,
+JS-side ML (TF.js, transformers.js).
+
+`sampleHz` clamped to `[0.5, 10]`; `quality` clamped `[1, 100]`.
+
+#### Types
+
+  - `SampledFrame` — `{ jpegPath, pose, timestamp, width, height }`
+  - `FrameStreamOptions` — `{ sampleHz, quality?, outputDir? }`
+  - `ThrottledFrameProcessorOptions` — `{ sampleHz }`
+
+All exported from `react-native-image-stitcher`.
+
+### Documentation
+
+- `docs/frame-access-tiers.md` — new comprehensive reference for
+  all four host-facing hooks (`useKeyframeStream`,
+  `useThrottledFrameProcessor`, `useFrameStream`,
+  `useFrameProcessor`) with decision flow, cost envelope, use-case
+  mapping, AR vs non-AR mode tradeoff.
+
+### Example app
+
+`example/App.tsx` now mounts `useFrameStream` at 2 Hz with a
+visible thumbnail overlay (bottom-right corner) — visual proof of
+the Layer 1 + 2 + 3 pipeline working end-to-end on both iPhone
+(60 Hz AR) and Galaxy A35 (30 Hz AR).
+
+### Compatibility
+
+- Strict additive over v0.8.0.  No host changes required.
+- Works in both AR and non-AR modes via v0.8.0's unified
+  `useFrameProcessor`.
+- New hooks return `useFrameProcessor`-shape objects compatible
+  with `<Camera frameProcessor={...}>` (Phase 5 from v0.8.0).
+
+### Notes
+
+- Formal SSIM parity gate (Phase 7 of the v0.9.0 plan) was NOT
+  run for this release — the layered design doesn't touch
+  first-party stitching, so a regression is structurally unlikely.
+  Harness still in place from v0.8.0 (`scripts/ssim-compare.py`)
+  for any host that wants to run it locally.
+
+[0.9.0]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.8.0...v0.9.0
+
 ## [0.8.0] — 2026-05-27
 
 ### Added — `useFrameProcessor` hook for host worklets

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

@@ -55,19 +55,33 @@ class RNImageStitcherPackage : ReactPackage {
                 ) { proxy, options ->
                     CvFlowGateFrameProcessor(proxy, options)
                 }
+                // v0.9.0 Layer 1 — register `save_frame_as_jpeg`
+                // alongside the cv_flow_gate plugin.  Same lifecycle,
+                // same defensive error handling (the outer try/catch
+                // covers both registrations).  Either both register
+                // or neither does — if vc isn't on the classpath,
+                // both calls are skipped together.
+                FrameProcessorPluginRegistry.addFrameProcessorPlugin(
+                    SaveFrameAsJpegPlugin.PLUGIN_NAME,
+                ) { proxy, options ->
+                    SaveFrameAsJpegPlugin(proxy, options)
+                }
                 fpPluginRegistered = true
             } catch (e: NoClassDefFoundError) {
                 android.util.Log.i(
                     "RNImageStitcherPackage",
                     "vision-camera FrameProcessorPluginRegistry not on classpath — "
-                    + "skipping cv_flow_gate_process_frame plugin registration "
-                    + "(host app doesn't appear to use Frame Processors).",
+                    + "skipping cv_flow_gate_process_frame + save_frame_as_jpeg "
+                    + "plugin registration (host app doesn't appear to use "
+                    + "Frame Processors).",
                 )
                 fpPluginRegistered = true  // don't retry every package init
             } catch (e: Throwable) {
                 android.util.Log.w(
                     "RNImageStitcherPackage",
-                    "Failed to register cv_flow_gate_process_frame plugin: ${e.message}",
+                    "Failed to register Frame Processor plugins "
+                    + "(cv_flow_gate_process_frame / save_frame_as_jpeg): "
+                    + e.message,
                 )
                 fpPluginRegistered = true
             }

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

@@ -0,0 +1,162 @@
+// SPDX-License-Identifier: Apache-2.0
+package io.imagestitcher.rn
+
+import android.graphics.ImageFormat
+import android.media.Image
+import android.util.Log
+import androidx.annotation.Keep
+import com.facebook.proguard.annotations.DoNotStrip
+import com.mrousavy.camera.frameprocessors.Frame
+import com.mrousavy.camera.frameprocessors.FrameProcessorPlugin
+import com.mrousavy.camera.frameprocessors.VisionCameraProxy
+import io.imagestitcher.rn.ar.YuvImageConverter
+
+/**
+ * v0.9.0 Layer 1 — Android vc Frame Processor plugin that JPEG-
+ * encodes the supplied frame to a host-supplied path.  Mirror of
+ * iOS' `SaveFrameAsJpegPlugin.mm`.
+ *
+ * Plugin name (must match iOS): `save_frame_as_jpeg`.
+ *
+ * ## Wrapping the existing encoder
+ *
+ * The lib already encodes JPEGs from NV21 bytes via
+ * `YuvImageConverter.encodeJpegFromNV21` — that's the path
+ * `RNSARCameraView.kt`'s keyframe-accept callback uses (line 589,
+ * `onAccept = { targetPath -> ... encodeJpegFromNV21(...) }`).
+ * This plugin reuses that exact encoder so:
+ *   - JPEG output is byte-equivalent to the keyframe-accept output
+ *     (same encoder, same quality knob)
+ *   - No new encoder maintenance burden
+ *
+ * vision-camera's `Frame.image` is an `android.media.Image` in
+ * `YUV_420_888` format (the camera's native).  We pass it through
+ * `YuvImageConverter.packNV21(image)` to extract the dense NV21
+ * byte array + dims, then `encodeJpegFromNV21(packed, file, q, rot)`
+ * does the JPEG write.
+ *
+ * ## Plugin contract (matches iOS surface exactly)
+ *
+ * Arguments dict:
+ *   - `path` (string, REQUIRED): absolute output path.
+ *   - `quality` (number, optional): 0-100 JPEG quality.  Default 75.
+ *     Clamped to [1, 100].
+ *
+ * Returns:
+ *   - On success: `{ "ok" => true, "path" => ..., "width" => ...,
+ *                    "height" => ... }`
+ *   - On failure: `{ "ok" => false, "error" => "..." }`
+ *
+ * Errors surfaced via the result map (not thrown) — host worklets
+ * can branch on `result.ok` without try/catch.  Same convention
+ * as iOS.
+ *
+ * ## Lifetime / threading
+ *
+ * The supplied `Frame` (and its `Image`) is valid only for the
+ * duration of this callback — vision-camera closes the underlying
+ * `Image` on return.  All Image access (NV21 pack + JPEG encode)
+ * happens synchronously inside `callback()`.
+ *
+ * ## Format restriction
+ *
+ * Only `YUV_420_888` input is supported (vc Android's standard).
+ * Anything else returns `{ ok: false, error: "unsupported format" }`.
+ * No format conversion fallback — that would mask bugs in the host
+ * camera config.
+ *
+ * ## Registration
+ *
+ * Registered in `RNImageStitcherPackage.kt`'s companion-object
+ * `ensureFrameProcessorPluginRegistered()`, alongside
+ * `cv_flow_gate_process_frame`.  Same defensive
+ * NoClassDefFoundError handling — if vc isn't on the host's
+ * classpath, registration is silently skipped (and the plugin's
+ * `init { … }` calls below never happen).
+ */
+@DoNotStrip
+@Keep
+class SaveFrameAsJpegPlugin(
+    @Suppress("UNUSED_PARAMETER") proxy: VisionCameraProxy,
+    @Suppress("UNUSED_PARAMETER") options: Map<String, Any>?,
+) : FrameProcessorPlugin() {
+
+    override fun callback(frame: Frame, params: Map<String, Any>?): Any {
+        val path = params?.get("path") as? String
+            ?: return mapOf(
+                "ok" to false,
+                "error" to "missing required `path` argument",
+            )
+        val rawQuality = (params["quality"] as? Number)?.toInt() ?: 75
+        val quality = rawQuality.coerceIn(1, 100)
+
+        // Frame may throw if vc already released it.
+        val image: Image = try {
+            frame.image
+        } catch (e: Throwable) {
+            return mapOf(
+                "ok" to false,
+                "error" to "frame invalid: ${e.message}",
+            )
+        }
+
+        if (image.format != ImageFormat.YUV_420_888) {
+            return mapOf(
+                "ok" to false,
+                "error" to "unsupported format ${image.format} (need YUV_420_888)",
+            )
+        }
+
+        // Pack NV21 — same call site RNSARCameraView uses.
+        val packed = YuvImageConverter.packNV21(image)
+            ?: return mapOf(
+                "ok" to false,
+                "error" to "YuvImageConverter.packNV21 returned null",
+            )
+
+        // Reuse the lib's existing JPEG encoder.  Rotation is 0 here
+        // (the host's frame is in camera-native orientation; if they
+        // want display orientation they can pass an `orientation`
+        // arg in a future version — for v0.9.0 the worklet emits
+        // raw-camera-oriented JPEGs, matching the keyframe-accept
+        // pipeline's behaviour).
+        //
+        // Signature: `encodeJpegFromNV21(packed, outputPath: String,
+        // jpegQuality: Int, displayRotation: Int): String?` — returns
+        // the written path on success, null on failure.
+        val encodedPath: String? = try {
+            YuvImageConverter.encodeJpegFromNV21(
+                packed,
+                path,
+                jpegQuality = quality,
+                displayRotation = 0,
+            )
+        } catch (e: Throwable) {
+            return mapOf(
+                "ok" to false,
+                "error" to "encodeJpegFromNV21 threw: ${e.message}",
+            )
+        }
+        if (encodedPath == null) {
+            return mapOf(
+                "ok" to false,
+                "error" to "encodeJpegFromNV21 returned null",
+            )
+        }
+
+        return mapOf(
+            "ok" to true,
+            "path" to encodedPath,
+            "width" to packed.width,
+            "height" to packed.height,
+        )
+    }
+
+    companion object {
+        private const val TAG = "SaveFrameAsJpegPlugin"
+
+        /// Plugin name; MUST match iOS + the JS-side
+        /// `initFrameProcessorPlugin('save_frame_as_jpeg')` call.
+        const val PLUGIN_NAME = "save_frame_as_jpeg"
+    }
+}

package/dist/index.d.ts

@@ -67,6 +67,10 @@ export { useIncrementalStitcher } from './stitching/useIncrementalStitcher';
 export { useKeyframeStream } from './stitching/useKeyframeStream';
 export type { StitcherFrame, StitcherFrameProcessor, ARAnchor, } from './stitching/StitcherFrame';
 export { useFrameProcessor } from './stitching/useFrameProcessor';
+export { useThrottledFrameProcessor } from './stitching/useThrottledFrameProcessor';
+export type { ThrottledFrameProcessorOptions } from './types';
+export { useFrameStream } from './stitching/useFrameStream';
+export type { FrameStreamOptions, SampledFrame } from './types';
 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.useFrameProcessor = 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;
+exports.stitchVideo = exports.useFrameProcessorDriver = exports.useFrameStream = exports.useThrottledFrameProcessor = exports.useFrameProcessor = 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
 // ─────────────────────────────────────────────────────────────────────
@@ -155,6 +155,25 @@ Object.defineProperty(exports, "useKeyframeStream", { enumerable: true, get: fun
 // See the hook's docstring + StitcherFrame.ts for the contract.
 var useFrameProcessor_1 = require("./stitching/useFrameProcessor");
 Object.defineProperty(exports, "useFrameProcessor", { enumerable: true, get: function () { return useFrameProcessor_1.useFrameProcessor; } });
+// v0.9.0 Layer 2 — `useThrottledFrameProcessor`.  Throttle gate over
+// `useFrameProcessor` for sub-frame-rate worklet-native processing
+// (native OCR via Vision.framework / ML Kit, TFLite ML detection,
+// LiDAR depth).  The worklet runtime has direct access to
+// `frame.toArrayBuffer()` / `frame.arDepth`; bridge small payloads
+// (bboxes, depth-derived metrics) to JS via `runOnJS`.  For JS-thread
+// JPEG consumers (file-path OCR libs, cloud upload, thumbnail UI),
+// prefer `useFrameStream` (Layer 3, ships in the same release).
+var useThrottledFrameProcessor_1 = require("./stitching/useThrottledFrameProcessor");
+Object.defineProperty(exports, "useThrottledFrameProcessor", { enumerable: true, get: function () { return useThrottledFrameProcessor_1.useThrottledFrameProcessor; } });
+// v0.9.0 Layer 3 — `useFrameStream`.  JS-thread sampled-frame
+// stream over Layer 1 (`save_frame_as_jpeg` vc plugin) + Layer 2
+// (`useThrottledFrameProcessor`).  Use for JS-thread consumers:
+// file-path OCR libs (RN modules), cloud upload, thumbnail UI.
+// For worklet-native processing (Vision/ML Kit as vc plugins,
+// TFLite ML, LiDAR depth), prefer `useThrottledFrameProcessor`
+// (Layer 2) — lower latency, no JPEG roundtrip.
+var useFrameStream_1 = require("./stitching/useFrameStream");
+Object.defineProperty(exports, "useFrameStream", { enumerable: true, get: function () { return useFrameStream_1.useFrameStream; } });
 // 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/useFrameStream.d.ts

@@ -0,0 +1,34 @@
+import { useThrottledFrameProcessor } from './useThrottledFrameProcessor';
+import type { FrameStreamOptions, SampledFrame } from '../types';
+/**
+ * `useFrameStream` — Layer 3.  See module docstring for the full
+ * design + use-case mapping.  Quick start:
+ *
+ * ```tsx
+ * import { Camera, useFrameStream } from 'react-native-image-stitcher';
+ *
+ * function MyScreen() {
+ *   const fp = useFrameStream(
+ *     { sampleHz: 2, quality: 75 },
+ *     (sample) => {
+ *       setThumbnail(sample.jpegPath);
+ *     },
+ *   );
+ *   return <Camera frameProcessor={fp} ... />;
+ * }
+ * ```
+ *
+ * @param options  `{ sampleHz, quality?, outputDir? }`.  `sampleHz`
+ *                 clamped to `[0.5, 10]`.
+ * @param handler  JS-thread callback fired per sample.  Receives a
+ *                 `SampledFrame`.  May return a Promise; rejections
+ *                 are caught + logged (not re-thrown) so one
+ *                 misbehaving handler doesn't break the stream.
+ *
+ * @returns A `useFrameProcessor`-shaped processor object — pass to
+ *          `<Camera frameProcessor={...}>` for non-AR mode wiring.
+ *          (AR mode auto-registration via `__stitcherProxy` is
+ *          handled inside `useFrameProcessor`.)
+ */
+export declare function useFrameStream(options: FrameStreamOptions, handler: (sample: SampledFrame) => void | Promise<void>): ReturnType<typeof useThrottledFrameProcessor>;
+//# sourceMappingURL=useFrameStream.d.ts.map

package/dist/stitching/useFrameStream.js

@@ -0,0 +1,219 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+//
+// v0.9.0 Layer 3 — JS-thread sampled-frame stream over Layer 1 +
+// Layer 2.
+//
+// ## What this is
+//
+// A hook that:
+//   1. Throttles a worklet via `useThrottledFrameProcessor` (Layer 2)
+//      to fire at `sampleHz` Hz.
+//   2. Inside the worklet, calls the `save_frame_as_jpeg` vc Frame
+//      Processor plugin (Layer 1) to JPEG-encode the frame to a
+//      bounded-rotation slot on disk.
+//   3. Bridges the resulting `SampledFrame` (file path + pose +
+//      dims) to a JS-thread callback via `runOnJS`.
+//
+// The host gets a per-sample callback on the JS thread with a file
+// path they can pass to `<Image>`, an OCR RN module, a cloud-upload
+// library, etc.  Zero worklet boilerplate.
+//
+// ## When to use this (vs alternatives)
+//
+//   - **`useFrameStream`** (this hook) — JS-thread consumers.  File-
+//     path OCR libraries, cloud upload, thumbnail UI, sampled
+//     server-side analysis.
+//   - **`useThrottledFrameProcessor`** (Layer 2) — worklet-native
+//     consumers.  Native OCR (Vision.framework / ML Kit) wrapped as
+//     vc plugins, TFLite ML inference, LiDAR depth processing.
+//     Lower latency; no JPEG roundtrip.
+//   - **`useFrameProcessor`** — every camera frame; full control.
+//
+// ## Slot reuse / disk usage
+//
+// JPEG files are written to `<outputDir>/stream-<N>.jpg` where N
+// cycles 0..3 based on `frame.timestamp / 1000`.  At most 4 stale
+// JPEGs ever exist on disk; the same file is rewritten on each
+// rotation, so disk usage is bounded.
+//
+// Hosts that need long-term retention (e.g., archive each sample
+// for later upload) MUST copy the file synchronously inside the
+// handler — the slot may be overwritten by the next sample.
+//
+// ## Backpressure
+//
+// If the JS handler returns slower than `1/sampleHz`, subsequent
+// ticks DO still fire (the throttle is time-based, not handler-
+// completion-based).  This means multiple handler invocations can
+// be in flight simultaneously.  For most use cases that's fine
+// (the handlers are pure or commute).  Hosts that need serialised
+// handling should track in-flight state themselves and early-return.
+//
+// ## AR vs non-AR
+//
+// Works in both modes because it composes over
+// `useThrottledFrameProcessor` → `useFrameProcessor`.  In AR mode
+// the worklet auto-registers via `__stitcherProxy` (v0.8.0 Phase
+// 4b.i/iii); in non-AR mode the returned processor object is
+// passed to `<Camera frameProcessor={...}>`.  The hook returns
+// the processor object so hosts can wire it up either way.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFrameStream = useFrameStream;
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+const react_native_vision_camera_1 = require("react-native-vision-camera");
+const react_native_worklets_core_1 = require("react-native-worklets-core");
+const useThrottledFrameProcessor_1 = require("./useThrottledFrameProcessor");
+/**
+ * `useFrameStream` — Layer 3.  See module docstring for the full
+ * design + use-case mapping.  Quick start:
+ *
+ * ```tsx
+ * import { Camera, useFrameStream } from 'react-native-image-stitcher';
+ *
+ * function MyScreen() {
+ *   const fp = useFrameStream(
+ *     { sampleHz: 2, quality: 75 },
+ *     (sample) => {
+ *       setThumbnail(sample.jpegPath);
+ *     },
+ *   );
+ *   return <Camera frameProcessor={fp} ... />;
+ * }
+ * ```
+ *
+ * @param options  `{ sampleHz, quality?, outputDir? }`.  `sampleHz`
+ *                 clamped to `[0.5, 10]`.
+ * @param handler  JS-thread callback fired per sample.  Receives a
+ *                 `SampledFrame`.  May return a Promise; rejections
+ *                 are caught + logged (not re-thrown) so one
+ *                 misbehaving handler doesn't break the stream.
+ *
+ * @returns A `useFrameProcessor`-shaped processor object — pass to
+ *          `<Camera frameProcessor={...}>` for non-AR mode wiring.
+ *          (AR mode auto-registration via `__stitcherProxy` is
+ *          handled inside `useFrameProcessor`.)
+ */
+function useFrameStream(options, handler) {
+    const sampleHz = Math.max(0.5, Math.min(10, options.sampleHz));
+    const quality = options.quality ?? 75;
+    // Default output dir: a per-app cache subdirectory.  Hosts that
+    // want a known path supply their own via `options.outputDir`.
+    // `Platform.OS`-specific cache paths are read once at hook mount.
+    const outputDir = (0, react_1.useMemo)(() => {
+        if (options.outputDir != null)
+            return options.outputDir;
+        // Both platforms expose a cache directory at a predictable path
+        // via React Native APIs; we use a small inline computation to
+        // avoid pulling `react-native-fs` as a hard dep.  The lib's
+        // existing JPEG encode targets the app's data dir via similar
+        // logic in `RNSARCameraView.kt` / `IncrementalStitcher.swift`.
+        //
+        // We just generate a relative-ish path under /tmp/ for cross-
+        // platform simplicity; the native plugin writes wherever it's
+        // told to (absolute path), so as long as the directory exists
+        // the encode succeeds.  Hosts that care about file lifecycle
+        // should supply `outputDir` explicitly.
+        return react_native_1.Platform.OS === 'ios'
+            ? '/tmp/rnis-frame-stream'
+            : '/data/local/tmp/rnis-frame-stream';
+    }, [options.outputDir]);
+    // Ensure outputDir exists on the native side.  We could use
+    // react-native-fs but to keep the dep surface minimal, we just
+    // attempt to create via a tiny native call — or, simpler, accept
+    // that the plugin's write call will fail if the dir doesn't
+    // exist + log a clear error.  For v0.9.0 baseline we defer
+    // mkdir to the host (document it in the option's JSDoc) OR fall
+    // back to the platform's tmpdir which already exists.
+    //
+    // The tmpdir defaults above always exist on iOS + Android, so
+    // the common case "host doesn't supply outputDir" Just Works.
+    // Stable JS-side handler reference for `runOnJS`.  The hook re-
+    // captures `handler` on every render but the ref keeps the
+    // worklet closure pointing at the latest callback (avoid stale
+    // captures).
+    const handlerRef = (0, react_1.useRef)(handler);
+    handlerRef.current = handler;
+    const onSampleJS = (0, react_1.useCallback)((sample) => {
+        const result = handlerRef.current(sample);
+        if (result != null &&
+            typeof result.catch === 'function') {
+            result.catch((err) => {
+                // eslint-disable-next-line no-console
+                console.error('[useFrameStream] handler threw:', err);
+            });
+        }
+    }, []);
+    const onSampleOnJS = (0, react_1.useMemo)(() => react_native_worklets_core_1.Worklets.createRunOnJS(onSampleJS), [onSampleJS]);
+    // ── Plugin acquisition (Layer 1) ─────────────────────────────────
+    //
+    // `initFrameProcessorPlugin` can return `undefined` if the native
+    // registry hasn't initialised yet (rare race on app start).  We
+    // retry every 16ms (one display frame) until success — matches
+    // the pattern in `useFrameProcessorDriver`.
+    const pluginRef = (0, react_1.useRef)(null);
+    (0, react_1.useEffect)(() => {
+        let cancelled = false;
+        let timerId = null;
+        const tryAcquire = () => {
+            if (cancelled)
+                return;
+            const p = react_native_vision_camera_1.VisionCameraProxy.initFrameProcessorPlugin('save_frame_as_jpeg', {});
+            if (p != null) {
+                pluginRef.current = p;
+                return;
+            }
+            timerId = setTimeout(tryAcquire, 16);
+        };
+        tryAcquire();
+        return () => {
+            cancelled = true;
+            if (timerId != null)
+                clearTimeout(timerId);
+        };
+    }, []);
+    // The worklet body — fires at sampleHz, calls the JPEG plugin,
+    // bridges the result to JS.  Note we read `pluginRef.current`
+    // inside the worklet via the captured `plugin` value below;
+    // worklets-core handles the JS↔worklet reference.
+    const plugin = pluginRef.current;
+    return (0, useThrottledFrameProcessor_1.useThrottledFrameProcessor)((frame) => {
+        'worklet';
+        if (plugin == null)
+            return;
+        // Slot rotation: compute slot from frame timestamp.  At
+        // sampleHz=2 (500ms interval), the slot index changes every
+        // ~1s, giving each slot ~2 samples before being overwritten.
+        // That's overkill for the "stream-of-samples" use case but
+        // matches the docstring's "at most 4 stale JPEGs" guarantee.
+        const slot = Math.floor(frame.timestamp / 1000) % 4;
+        const path = `${outputDir}/stream-${slot}.jpg`;
+        // vc's `FrameProcessorPlugin.call` expects vc's `Frame` type.
+        // `StitcherFrame` is structurally a superset (it adds `source`,
+        // `pose`, AR-only fields).  Cast through `unknown` — same
+        // pattern v0.8.0's `useFrameProcessor` uses when handing a
+        // StitcherFrame-typed worklet to vc.
+        const result = plugin.call(frame, {
+            path,
+            quality,
+        });
+        if (result == null ||
+            result.ok !== true) {
+            // Native side reported an error (path not writable, format
+            // wrong, etc.).  Silently skip this sample — the next tick
+            // will retry.  The plugin already logs the specific reason
+            // on the native side.
+            return;
+        }
+        const r = result;
+        onSampleOnJS({
+            jpegPath: r.path,
+            pose: frame.pose,
+            timestamp: frame.timestamp,
+            width: r.width,
+            height: r.height,
+        });
+    }, { sampleHz }, [plugin, outputDir, quality, onSampleOnJS]);
+}
+//# sourceMappingURL=useFrameStream.js.map

package/dist/stitching/useThrottledFrameProcessor.d.ts

@@ -0,0 +1,33 @@
+import type { DependencyList } from 'react';
+import { useFrameProcessor } from './useFrameProcessor';
+import type { StitcherFrameProcessor } from './StitcherFrame';
+import type { ThrottledFrameProcessorOptions } from '../types';
+/**
+ * Throttled variant of `useFrameProcessor`.  See the module
+ * docstring for the full use-case mapping; quick version:
+ *
+ * ```tsx
+ * const fp = useThrottledFrameProcessor(
+ *   (frame) => {
+ *     'worklet';
+ *     // worklet-native OCR / ML / depth processing here
+ *   },
+ *   { sampleHz: 2 },
+ *   [],
+ * );
+ * return <Camera frameProcessor={fp} ... />;
+ * ```
+ *
+ * @param worklet  Host's frame-processor worklet.  Must be
+ *                 `'worklet'`-prefixed.  Runs at most `sampleHz`
+ *                 times per second.
+ * @param options  `{ sampleHz }` — clamped to `[0.5, 30]`.
+ * @param deps     Standard React deps array.  Treated the same as
+ *                 `useFrameProcessor`'s deps — when they change the
+ *                 inner worklet is re-bound.
+ *
+ * @returns A `useFrameProcessor`-shaped processor object, pass it
+ *          to `<Camera frameProcessor={...}>`.
+ */
+export declare function useThrottledFrameProcessor(worklet: StitcherFrameProcessor, options: ThrottledFrameProcessorOptions, deps: DependencyList): ReturnType<typeof useFrameProcessor>;
+//# sourceMappingURL=useThrottledFrameProcessor.d.ts.map