react-native-image-stitcher 0.8.0 → 0.10.0

package/dist/camera/useCapture.js

@@ -19,7 +19,7 @@
  *   - This hook does NOT persist captures.  Host apps hand the
  *     returned CaptureResult to their own storage layer (WatermelonDB
  *     insert, Redux dispatch, whatever).
- *   - Video recording lives in useVideoCapture (TODO).
+ *   - Video recording lives in useVideoCapture.
  *
  * The public API is designed to be minimal and replaceable: host apps
  * that prefer the raw vision-camera API can opt out of this hook and

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/incremental.d.ts

@@ -249,6 +249,47 @@ export interface IncrementalState {
      * keyframes on disk.
      */
     refinedPanoramaPath?: string;
+    /**
+     * v0.10.0 (#15A) — current phase of an in-flight `refinePanorama`
+     * call.  Fires from both the explicit `module.refinePanorama(...)`
+     * JS API path AND the hybrid-engine auto-refine path (which calls
+     * the same native refinePanorama internally).
+     *
+     * Lifecycle:
+     *   - `"validating"` (fraction 0.05) — synchronous input checks
+     *   - `"stitching"`  (fraction 0.10) — OpenCV stitch in flight
+     *   - `"writing"`    (fraction 0.90) — stitch done, JPEG written
+     *   - `"done"`       (fraction 1.00) — success
+     *   - `"error"`      (fraction 1.00) — failure; `refineError` is set
+     *
+     * Coarse on purpose: OpenCV's Stitcher doesn't expose mid-pipeline
+     * progress, so the 0.10 → 0.90 jump is one opaque step.  Use
+     * `refineStage` for a stage label; use `refineProgress` purely for
+     * spinner progress.
+     *
+     * Undefined when no refinement is in flight.
+     */
+    refineStage?: 'validating' | 'stitching' | 'writing' | 'done' | 'error';
+    /**
+     * v0.10.0 (#15A) — coarse progress fraction in `[0, 1]` aligned
+     * with `refineStage`.  See `refineStage` for the per-stage value
+     * mapping.  Undefined when no refinement is in flight.
+     */
+    refineProgress?: number;
+    /**
+     * v0.10.0 (#15A) — number of input frames the in-flight refine is
+     * processing.  Useful for the UI label
+     * (`Stitching 6 frames…`).  Mirrors the `framesRequested` field
+     * returned in the explicit refinePanorama resolution.  Undefined
+     * when no refinement is in flight.
+     */
+    refineFrames?: number;
+    /**
+     * v0.10.0 (#15A) — present only when `refineStage === 'error'`.
+     * Human-readable error message; the same text the rejected promise
+     * carries.  Use to render a one-line failure pill.
+     */
+    refineError?: string;
 }
 export interface IncrementalStartOptions {
     /**

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,234 @@
+"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_vision_camera_1 = require("react-native-vision-camera");
+const react_native_worklets_core_1 = require("react-native-worklets-core");
+const useThrottledFrameProcessor_1 = require("./useThrottledFrameProcessor");
+const files_1 = require("../utils/files");
+/**
+ * `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: the lib's canonical capture dir resolved
+    // via `FileBridge.defaultCaptureDir()`.  Same dir the lib uses
+    // for panorama JPEGs / keyframe JPEGs — guaranteed writable on
+    // both platforms (iOS NSCachesDirectory + Android Context.cacheDir),
+    // created if missing.  Resolved async on first mount; until
+    // resolution completes the worklet's `outputDir` is empty and
+    // the plugin call no-ops silently (a few frames missed at most;
+    // typical resolution time is <50ms).
+    //
+    // Hosts that want a specific path supply `options.outputDir`
+    // and skip the resolution entirely.
+    const [resolvedDefaultDir, setResolvedDefaultDir] = (0, react_1.useState)('');
+    (0, react_1.useEffect)(() => {
+        if (options.outputDir != null)
+            return;
+        let cancelled = false;
+        (0, files_1.getDefaultCaptureDir)()
+            .then((dir) => {
+            if (!cancelled)
+                setResolvedDefaultDir(dir);
+        })
+            .catch((err) => {
+            // eslint-disable-next-line no-console
+            console.warn('[useFrameStream] FileBridge.defaultCaptureDir() failed; ' +
+                'samples will not fire until `options.outputDir` is supplied. ' +
+                String(err));
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [options.outputDir]);
+    const outputDir = options.outputDir ?? resolvedDefaultDir;
+    // 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`.
+    //
+    // Use `useState` (not `useRef`) so the eventual non-null value
+    // triggers a re-render — the worklet closure below captures
+    // `plugin` by value at render time, so without state we'd
+    // capture `null` forever.
+    const [plugin, setPlugin] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        let cancelled = false;
+        let timerId = null;
+        let attempts = 0;
+        const tryAcquire = () => {
+            if (cancelled)
+                return;
+            attempts += 1;
+            const p = react_native_vision_camera_1.VisionCameraProxy.initFrameProcessorPlugin('save_frame_as_jpeg', {});
+            if (p != null) {
+                setPlugin(p);
+                return;
+            }
+            // After ~1s of failed retries, warn once — the plugin should
+            // be registered by then; persistent failure means the host's
+            // native bundle doesn't include `save_frame_as_jpeg`.
+            if (attempts === 60) {
+                // eslint-disable-next-line no-console
+                console.warn('[useFrameStream] save_frame_as_jpeg plugin not found after 1s of retries. ' +
+                    'Verify react-native-image-stitcher native module is installed in your host app.');
+            }
+            timerId = setTimeout(tryAcquire, 16);
+        };
+        tryAcquire();
+        return () => {
+            cancelled = true;
+            if (timerId != null)
+                clearTimeout(timerId);
+        };
+    }, []);
+    return (0, useThrottledFrameProcessor_1.useThrottledFrameProcessor)((frame) => {
+        'worklet';
+        if (plugin == null)
+            return;
+        // Async outputDir resolution may not have completed yet on
+        // the first few frames after mount — bail until it does.
+        if (outputDir === '')
+            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

package/dist/stitching/useThrottledFrameProcessor.js

@@ -0,0 +1,132 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+//
+// v0.9.0 Layer 2 — throttle gate over v0.8.0's `useFrameProcessor`.
+//
+// ## What this is
+//
+// A thin wrapper around `useFrameProcessor` that enforces a maximum
+// invocation rate (`sampleHz`) at the worklet layer.  The host's
+// worklet fires up to `sampleHz` times per second; ticks too close
+// together are dropped via a `useSharedValue<number>` monotonic-time
+// gate inside the worklet body.
+//
+// ## When to use this (vs alternatives)
+//
+//   - **`useFrameProcessor` directly** — every camera frame (~30-60 Hz).
+//     Use for true-realtime processing that wants to see every frame.
+//   - **`useThrottledFrameProcessor`** (this hook) — sub-frame-rate
+//     worklet-native processing.  The worklet runtime has direct
+//     access to `frame.toArrayBuffer()`, `frame.arDepth`,
+//     `frame.arAnchors`, and can call other vc Frame Processor plugins
+//     (native OCR libraries, TFLite ML inference, etc.).  Results
+//     bridged to JS via `runOnJS`.
+//   - **`useFrameStream`** (Layer 3, also in this directory) —
+//     sub-frame-rate JS-thread consumer.  The lib JPEG-encodes each
+//     sample on the producer thread and delivers a `SampledFrame`
+//     (file path + pose + dims) to a JS-thread callback.  Use for
+//     file-path OCR libraries (RN modules wrapping ML Kit etc.),
+//     cloud upload, thumbnail UI.
+//
+// ## Use-case mapping (canonical)
+//
+// | Use case                              | Layer | Why                              |
+// |---------------------------------------|-------|----------------------------------|
+// | OCR via Vision.framework / ML Kit     | **2** | native libs, bbox in frame coords|
+// | TFLite ML detection (via vc plugin)   | **2** | same shape as OCR                |
+// | LiDAR depth → 3D reconstruction       | **2** | depth too large to bridge        |
+// | Pose-only telemetry                   | **2** | tiny payload, no encoding needed |
+// | File-path OCR (RN module)             |   3   | host wants a JPEG, not pixels    |
+// | Cloud upload (sampled JPEG feed)      |   3   | JPEG IS the payload              |
+// | Live thumbnail preview UI             |   3   | `<Image source={{uri: ...}}>`    |
+//
+// See `docs/host-app-integration.md` § "Tier 2 + 3" for recipes.
+//
+// ## Threading
+//
+// The wrapped worklet fires on whatever runtime `useFrameProcessor`
+// dispatches on:
+//   - **Non-AR mode**: vision-camera's Frame Processor runtime
+//     (producer thread).
+//   - **AR mode**: the lib's `RNSARWorkletRuntime` (iOS) /
+//     worklets-core default context (Android) — fired by the AR
+//     session's per-frame dispatch.  See v0.8.0 Phase 4b.i / 4b.iii.
+//
+// Either way, the worklet MUST NOT block — the next frame's
+// processing is gated on this one returning.  Long work belongs
+// behind `runOnJS` / a separate worklet runtime.
+//
+// ## Behaviour at the throttle boundary
+//
+// The hook tracks a monotonic-time shared value of "last sample time".
+// Each tick checks if `frame.timestamp - lastSampleMs.value >=
+// (1000 / sampleHz)`.  If yes, the worklet body runs and the value
+// updates; if no, the worklet returns silently.
+//
+// Edge cases:
+//   - First-ever tick: `lastSampleMs.value` starts at 0; first frame's
+//     timestamp will be >> 0 → first tick always fires.  Subsequent
+//     ticks throttle as expected.
+//   - vc v4 timestamp semantics: per the project's worklet-throttle
+//     gotcha note, `frame.timestamp` is NOT reliably nanoseconds in
+//     vc v4.  The hook treats `frame.timestamp` as ALREADY in
+//     milliseconds (which is what vc v4 actually delivers; the
+//     v0.8.0 StitcherFrame contract documents this).  If a future
+//     vc version changes the unit, the throttle math here needs
+//     re-checking.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useThrottledFrameProcessor = useThrottledFrameProcessor;
+const react_native_worklets_core_1 = require("react-native-worklets-core");
+const useFrameProcessor_1 = require("./useFrameProcessor");
+/**
+ * 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={...}>`.
+ */
+function useThrottledFrameProcessor(worklet, options, deps) {
+    // Clamp + derive interval.  Done outside the worklet so the
+    // useSharedValue / useFrameProcessor hooks see stable values.
+    const sampleHz = Math.max(0.5, Math.min(30, options.sampleHz));
+    const minIntervalMs = 1000 / sampleHz;
+    // Monotonic-time gate.  Initialised to 0 → first tick always
+    // fires (frame.timestamp >> 0).
+    const lastSampleMs = (0, react_native_worklets_core_1.useSharedValue)(0);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    return (0, useFrameProcessor_1.useFrameProcessor)((frame) => {
+        'worklet';
+        const now = frame.timestamp;
+        if (now - lastSampleMs.value < minIntervalMs) {
+            return;
+        }
+        lastSampleMs.value = now;
+        worklet(frame);
+    }, 
+    // The throttle interval is captured in the worklet closure; if
+    // it changes we need to re-bind the worklet so the new
+    // `minIntervalMs` takes effect.  Same for the host's worklet
+    // identity (so deps changes on the host side re-bind too).
+    [minIntervalMs, worklet, ...deps]);
+}
+//# sourceMappingURL=useThrottledFrameProcessor.js.map

package/dist/types.d.ts

@@ -35,6 +35,93 @@ export interface DeviceMetadata {
     cameraId: string;
     flashEnabled: boolean;
 }
+/**
+ * v0.9.0 Layer 3 — one sampled frame delivered by `useFrameStream`
+ * to the JS-thread handler.
+ *
+ * The JPEG file at `jpegPath` is the stream's own copy.  Hosts that
+ * need long-term retention MUST copy the file synchronously inside
+ * the handler — the same path may be overwritten by a subsequent
+ * sample (slot reuse — see the hook's docstring for the rotation
+ * policy).
+ */
+export interface SampledFrame {
+    /** Absolute filesystem path to the JPEG.  No `file://` prefix. */
+    jpegPath: string;
+    /**
+     * Pose at sample time.  `translation` is `undefined` in non-AR
+     * mode (gyro provides rotation only; no spatial anchor).
+     */
+    pose: {
+        rotation: [number, number, number, number];
+        translation?: [number, number, number];
+    };
+    /** Frame timestamp (ms; per the v0.8.0 StitcherFrame contract). */
+    timestamp: number;
+    /** JPEG width / height in pixels. */
+    width: number;
+    height: number;
+}
+/**
+ * v0.9.0 Layer 3 — options for `useFrameStream`.
+ *
+ * For worklet-native processing without JPEG roundtrip (OCR via
+ * Vision/ML Kit, TFLite ML, LiDAR depth), use
+ * `useThrottledFrameProcessor` (Layer 2) instead.
+ */
+export interface FrameStreamOptions {
+    /**
+     * Target sampling rate in Hertz.  Clamped to `[0.5, 10]`.  The
+     * Layer 2 throttle gate enforces the rate inside the worklet;
+     * ticks too close together are dropped silently.
+     *
+     * Clamp upper bound (10 Hz) is intentionally lower than Layer 2's
+     * (30 Hz) — beyond 10 Hz the per-frame JPEG encode + JS-bridge
+     * cost dominates the wall-clock budget.  Hosts that need higher
+     * rates should be on Layer 2 with their own JPEG encoder call
+     * (or no JPEG at all).
+     */
+    sampleHz: number;
+    /**
+     * JPEG quality (0-100).  Default 75.  Clamped silently to
+     * `[1, 100]` by the underlying `save_frame_as_jpeg` native plugin.
+     */
+    quality?: number;
+    /**
+     * Directory to write JPEG files into.  Defaults to a per-app
+     * `<cache>/rnis-frame-stream/` subdirectory.  The directory is
+     * `mkdir -p`'d on first use; hosts that supply an existing
+     * absolute path are responsible for its lifecycle.
+     */
+    outputDir?: string;
+}
+/**
+ * v0.9.0 Layer 2 — options for `useThrottledFrameProcessor`.
+ *
+ * Wraps v0.8.0's `useFrameProcessor` with a monotonic-time throttle
+ * gate so the supplied worklet fires at most `sampleHz` times per
+ * second.  Use for sub-frame-rate worklet-native processing — native
+ * OCR (Vision.framework / ML Kit), TFLite ML detection, LiDAR depth
+ * processing — where the bbox / depth payloads are small enough to
+ * bridge to JS via `runOnJS`.
+ *
+ * For JS-thread JPEG consumers (file-path OCR libraries, cloud
+ * upload, thumbnail UI), use `useFrameStream` (Layer 3) instead.
+ */
+export interface ThrottledFrameProcessorOptions {
+    /**
+     * Target sampling rate in Hertz.  Clamped to `[0.5, 30]`.  Inside
+     * the worklet a monotonic-time gate enforces the rate; ticks too
+     * close together are silently dropped.
+     *
+     * The clamp upper bound (30 Hz) sits at typical AR rates on
+     * mid-range Android devices — beyond that, the host should just
+     * use `useFrameProcessor` directly (no throttle).  The clamp
+     * lower bound (0.5 Hz) prevents accidentally-zero-divide values
+     * + matches `useFrameStream`'s convention.
+     */
+    sampleHz: number;
+}
 export interface CaptureResult {
     /** Unique device-generated UUID */
     deviceUuid: string;