react-native-image-stitcher 0.8.0 → 0.9.0

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;

package/ios/Sources/RNImageStitcher/SaveFrameAsJpegPlugin.mm

@@ -0,0 +1,185 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// SaveFrameAsJpegPlugin.mm — v0.9.0 Layer 1: vc Frame Processor plugin
+// that JPEG-encodes the supplied frame's pixel buffer to a host-
+// supplied path.  Worklet-callable; thin wrapper around the standard
+// iOS CIImage → CGImage → UIImage → UIImageJPEGRepresentation path.
+//
+// JS-side usage (from a worklet — typically inside `useFrameStream`
+// (Layer 3) or directly from a custom `useFrameProcessor` body):
+//
+//     const plugin = VisionCameraProxy.initFrameProcessorPlugin(
+//       'save_frame_as_jpeg', {},
+//     );
+//
+//     const fp = useFrameProcessor((frame) => {
+//       'worklet';
+//       if (plugin == null) return;
+//       const result = plugin.call(frame, {
+//         path: '/path/to/output.jpg',
+//         quality: 75,  // 0-100; defaults to 75
+//       });
+//       // result: { ok: true, path, width, height }  OR
+//       //         { ok: false, error: "..." }
+//     }, [plugin]);
+//
+// ## Why a separate plugin (not folded into KeyframeGateFrameProcessor)
+//
+// `cv_flow_gate_process_frame` (the existing plugin) drives the lib's
+// FIRST-PARTY stitching pipeline: it consumes the frame, evaluates
+// the keyframe gate, dispatches into `IncrementalStitcher`.  It owns
+// state.
+//
+// `save_frame_as_jpeg` is STATELESS — a pure encode-and-write function.
+// Mixing them would force every JS-side caller of either to pay both
+// codepaths' arg-parsing costs (and would confuse the use-case
+// boundary).  Two plugins, one job each.
+//
+// ## CONDITIONAL COMPILATION
+//
+// Same `__has_include` guard as `KeyframeGateFrameProcessor.mm` — if
+// vision-camera isn't on the host's classpath, this file is a no-op
+// translation unit.  See that file's header for the rationale.
+
+#import <Foundation/Foundation.h>
+
+#if __has_include(<VisionCamera/FrameProcessorPlugin.h>)
+
+#import <VisionCamera/Frame.h>
+#import <VisionCamera/FrameProcessorPlugin.h>
+#import <VisionCamera/FrameProcessorPluginRegistry.h>
+#import <VisionCamera/VisionCameraProxyHolder.h>
+#import <CoreVideo/CoreVideo.h>
+#import <CoreImage/CoreImage.h>
+#import <UIKit/UIKit.h>
+
+@interface SaveFrameAsJpegPlugin : FrameProcessorPlugin
+@end
+
+@implementation SaveFrameAsJpegPlugin
+
+- (instancetype)initWithProxy:(VisionCameraProxyHolder*)proxy
+                   withOptions:(NSDictionary* _Nullable)options {
+  return [super initWithProxy:proxy withOptions:options];
+}
+
+// Helper: read a string arg with a fallback.  Returns nil only when
+// the arg is missing AND no fallback was supplied.
+static NSString* sfj_argString(NSDictionary* args, NSString* key,
+                                NSString* _Nullable fallback) {
+  id v = args[key];
+  if ([v isKindOfClass:[NSString class]]) return (NSString*)v;
+  return fallback;
+}
+
+// Helper: read a numeric arg (NSNumber or NSString-parseable) with a
+// fallback.  Matches the pattern in KeyframeGateFrameProcessor.mm.
+static double sfj_argDouble(NSDictionary* args, NSString* key,
+                             double fallback) {
+  id v = args[key];
+  if ([v isKindOfClass:[NSNumber class]]) return [(NSNumber*)v doubleValue];
+  if ([v isKindOfClass:[NSString class]]) return [(NSString*)v doubleValue];
+  return fallback;
+}
+
+// The host-callable plugin entry point.  vc dispatches each
+// `plugin.call(frame, args)` from a worklet here.
+//
+// ## Arguments
+//
+//   - `path` (string, REQUIRED): absolute filesystem path to write
+//     the JPEG to.  Parent directory must exist (we don't `mkdir -p`).
+//     Existing file is overwritten atomically.
+//   - `quality` (number, optional): 0-100 JPEG quality.  Default 75
+//     (matches `KeyframeGate.onAccept`'s encoder).  Clamped silently
+//     to `[1, 100]`.
+//
+// ## Returns
+//
+//   - On success: `{ ok: YES, path: <path>, width: <px>, height: <px> }`
+//   - On failure: `{ ok: NO, error: "<reason>" }`
+//
+// Errors are surfaced via the result dict, NOT thrown as `JSError` —
+// host worklets that want to react to encoder failures (e.g., to
+// rotate slot paths, or to back off) can branch on `result.ok`
+// without try/catch boilerplate.  Throwing would break the
+// Layer 3 `useFrameStream` flow which only sees the result.
+- (id)callback:(Frame*)frame withArguments:(NSDictionary*)arguments {
+  NSString* path = sfj_argString(arguments, @"path", nil);
+  if (path == nil) {
+    return @{@"ok": @NO, @"error": @"missing required `path` argument"};
+  }
+  double q = sfj_argDouble(arguments, @"quality", 75.0);
+  if (q < 1.0) q = 1.0;
+  if (q > 100.0) q = 100.0;
+
+  CMSampleBufferRef sampleBuffer = frame.buffer;
+  if (sampleBuffer == NULL) {
+    return @{@"ok": @NO, @"error": @"frame.buffer was NULL"};
+  }
+  CVPixelBufferRef pixelBuffer = CMSampleBufferGetImageBuffer(sampleBuffer);
+  if (pixelBuffer == NULL) {
+    return @{@"ok": @NO, @"error": @"CMSampleBufferGetImageBuffer returned NULL"};
+  }
+
+  // CIImage → CGImage → UIImage → JPEG.  Standard iOS path; the
+  // CIContext + colorSpace are cheap to construct per-call (CoreImage
+  // caches GPU resources internally).  If profiling shows this in
+  // the hot path, lift the context to a static; for v0.9.0 baseline,
+  // per-call construction is fine.
+  CIImage* ciImage = [CIImage imageWithCVPixelBuffer:pixelBuffer];
+  if (ciImage == nil) {
+    return @{@"ok": @NO, @"error": @"CIImage imageWithCVPixelBuffer returned nil"};
+  }
+  CIContext* ctx = [CIContext context];
+  CGImageRef cgImage = [ctx createCGImage:ciImage fromRect:ciImage.extent];
+  if (cgImage == NULL) {
+    return @{@"ok": @NO, @"error": @"CIContext createCGImage failed"};
+  }
+  UIImage* uiImage = [UIImage imageWithCGImage:cgImage];
+  size_t width = CGImageGetWidth(cgImage);
+  size_t height = CGImageGetHeight(cgImage);
+  CGImageRelease(cgImage);
+
+  NSData* jpegData = UIImageJPEGRepresentation(uiImage, (CGFloat)(q / 100.0));
+  if (jpegData == nil) {
+    return @{@"ok": @NO, @"error": @"UIImageJPEGRepresentation returned nil"};
+  }
+
+  // Atomic write — under the hood NSData writes to a temp file then
+  // renames.  Avoids torn writes if a reader tries to open the path
+  // mid-write (would otherwise see a partial JPEG and choke).
+  NSError* err = nil;
+  BOOL ok = [jpegData writeToFile:path
+                          options:NSDataWritingAtomic
+                            error:&err];
+  if (!ok) {
+    NSString* msg = err.localizedDescription ?: @"NSData writeToFile returned NO";
+    return @{@"ok": @NO, @"error": msg};
+  }
+
+  return @{
+    @"ok": @YES,
+    @"path": path,
+    @"width": @(width),
+    @"height": @(height),
+  };
+}
+
+// Auto-register the plugin at class-load time.  Name must match what
+// JS passes to `VisionCameraProxy.initFrameProcessorPlugin('save_frame_as_jpeg')`.
+// Same pattern as KeyframeGateFrameProcessor's +load.
++ (void)load {
+  [FrameProcessorPluginRegistry
+    addFrameProcessorPlugin:@"save_frame_as_jpeg"
+            withInitializer:^FrameProcessorPlugin* _Nonnull(
+                VisionCameraProxyHolder* proxy,
+                NSDictionary* _Nullable options) {
+              return [[SaveFrameAsJpegPlugin alloc]
+                  initWithProxy:proxy withOptions:options];
+            }];
+}
+
+@end
+
+#endif // __has_include(<VisionCamera/FrameProcessorPlugin.h>)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.8.0",
+  "version": "0.9.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

@@ -198,6 +198,25 @@ export type {
 // cross-runtime handoff (the AR runtime iterating the registry).
 // See the hook's docstring + StitcherFrame.ts for the contract.
 export { useFrameProcessor } from './stitching/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).
+export { useThrottledFrameProcessor } from './stitching/useThrottledFrameProcessor';
+export type { ThrottledFrameProcessorOptions } from './types';
+// 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.
+export { useFrameStream } from './stitching/useFrameStream';
+export type { FrameStreamOptions, SampledFrame } from './types';
 // 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/__tests__/useThrottledFrameProcessor.test.ts

@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit tests for the v0.9.0 Layer 2 `useThrottledFrameProcessor` hook.
+ *
+ * The worklet runtime can't run in jest (no JSI, no worklets-core).
+ * What we CAN test:
+ *
+ *   - The `sampleHz` clamping (`[0.5, 30]`)
+ *   - `minIntervalMs` math (1000 / sampleHz)
+ *   - The deps propagation (host's deps → useFrameProcessor's deps)
+ *   - The throttle gate logic (extracted as a pure function for
+ *     isolated verification — see `_throttleGateForTests`).
+ *
+ * The hook itself is tested via a thin React-renderer-free harness:
+ * we mock `useFrameProcessor` + `useSharedValue` so we can verify
+ * the call shape without booting the worklet runtime.
+ */
+
+import { useThrottledFrameProcessor } from '../useThrottledFrameProcessor';
+
+// ─── Mock vision-camera + worklets-core ─────────────────────────────
+// These are minimal-shim mocks — enough surface for the hook to call
+// `useFrameProcessor(workletBody, deps)` and `useSharedValue(0)`.
+
+const useFrameProcessorMock = jest.fn();
+const useSharedValueMock = jest.fn();
+
+jest.mock('../useFrameProcessor', () => ({
+  useFrameProcessor: (...args: unknown[]) => useFrameProcessorMock(...args),
+}));
+
+jest.mock('react-native-worklets-core', () => ({
+  useSharedValue: (initial: number) => useSharedValueMock(initial),
+}));
+
+describe('useThrottledFrameProcessor', () => {
+  beforeEach(() => {
+    useFrameProcessorMock.mockReset();
+    useSharedValueMock.mockReset();
+    // Default behaviour for useSharedValue: return an object with a
+    // mutable `.value` field (mirrors worklets-core's API).
+    useSharedValueMock.mockImplementation((initial: number) => ({
+      value: initial,
+    }));
+  });
+
+  describe('sampleHz clamping', () => {
+    it('clamps below 0.5 to 0.5', () => {
+      const noop = (() => {}) as unknown as Parameters<typeof useThrottledFrameProcessor>[0];
+      useThrottledFrameProcessor(noop, { sampleHz: 0.1 }, []);
+      // useFrameProcessor receives the wrapped worklet; the deps
+      // array's first entry is `minIntervalMs`.  For sampleHz=0.5,
+      // minIntervalMs = 2000.
+      const [, deps] = useFrameProcessorMock.mock.calls[0]!;
+      expect(deps[0]).toBeCloseTo(2000);
+    });
+
+    it('clamps above 30 to 30', () => {
+      const noop = (() => {}) as unknown as Parameters<typeof useThrottledFrameProcessor>[0];
+      useThrottledFrameProcessor(noop, { sampleHz: 999 }, []);
+      const [, deps] = useFrameProcessorMock.mock.calls[0]!;
+      // sampleHz=30 → minIntervalMs = 33.333...
+      expect(deps[0]).toBeCloseTo(1000 / 30);
+    });
+
+    it('passes through in-range sampleHz unchanged', () => {
+      const noop = (() => {}) as unknown as Parameters<typeof useThrottledFrameProcessor>[0];
+      useThrottledFrameProcessor(noop, { sampleHz: 2 }, []);
+      const [, deps] = useFrameProcessorMock.mock.calls[0]!;
+      expect(deps[0]).toBeCloseTo(500);
+    });
+
+    it('accepts boundary values exactly', () => {
+      const noop = (() => {}) as unknown as Parameters<typeof useThrottledFrameProcessor>[0];
+      useThrottledFrameProcessor(noop, { sampleHz: 0.5 }, []);
+      let deps = useFrameProcessorMock.mock.calls[0]![1];
+      expect(deps[0]).toBeCloseTo(2000);
+
+      useFrameProcessorMock.mockClear();
+      useThrottledFrameProcessor(noop, { sampleHz: 30 }, []);
+      deps = useFrameProcessorMock.mock.calls[0]![1];
+      expect(deps[0]).toBeCloseTo(1000 / 30);
+    });
+  });
+
+  describe('deps propagation', () => {
+    it('appends host deps after the internal interval + worklet deps', () => {
+      const noop = (() => {}) as unknown as Parameters<typeof useThrottledFrameProcessor>[0];
+      const hostDep1 = { id: 'a' };
+      const hostDep2 = 42;
+      useThrottledFrameProcessor(noop, { sampleHz: 2 }, [hostDep1, hostDep2]);
+      const [, deps] = useFrameProcessorMock.mock.calls[0]!;
+      // Expected shape: [minIntervalMs, worklet, ...hostDeps]
+      expect(deps).toHaveLength(4);
+      expect(deps[0]).toBeCloseTo(500);
+      expect(deps[1]).toBe(noop);
+      expect(deps[2]).toBe(hostDep1);
+      expect(deps[3]).toBe(hostDep2);
+    });
+
+    it('with empty host deps: deps = [minIntervalMs, worklet]', () => {
+      const noop = (() => {}) as unknown as Parameters<typeof useThrottledFrameProcessor>[0];
+      useThrottledFrameProcessor(noop, { sampleHz: 2 }, []);
+      const [, deps] = useFrameProcessorMock.mock.calls[0]!;
+      expect(deps).toHaveLength(2);
+      expect(deps[0]).toBeCloseTo(500);
+      expect(deps[1]).toBe(noop);
+    });
+  });
+
+  describe('throttle gate', () => {
+    // The throttle logic lives INSIDE the wrapped worklet body, which
+    // jest can't execute directly (it's a `'worklet'`-prefixed
+    // function).  But the wrapped function IS just a plain JS
+    // function until the worklets-core babel plugin transforms it,
+    // so we can call it manually with mock frames + a mock
+    // shared-value gate.
+    //
+    // The body's logic:
+    //   if (frame.timestamp - lastSampleMs.value < minIntervalMs) return;
+    //   lastSampleMs.value = frame.timestamp;
+    //   worklet(frame);
+
+    it('fires the worklet on the first frame regardless of timestamp', () => {
+      const hostWorklet = jest.fn();
+      useThrottledFrameProcessor(hostWorklet, { sampleHz: 2 }, []);
+      const [wrappedBody] = useFrameProcessorMock.mock.calls[0]!;
+
+      const frame = { timestamp: 12345 } as Parameters<typeof hostWorklet>[0];
+      wrappedBody(frame);
+
+      expect(hostWorklet).toHaveBeenCalledTimes(1);
+      expect(hostWorklet).toHaveBeenCalledWith(frame);
+    });
+
+    it('skips a frame too close to the previous sample', () => {
+      const hostWorklet = jest.fn();
+      useThrottledFrameProcessor(hostWorklet, { sampleHz: 2 }, []); // 500ms interval
+      const [wrappedBody] = useFrameProcessorMock.mock.calls[0]!;
+
+      wrappedBody({ timestamp: 1000 } as never);
+      wrappedBody({ timestamp: 1100 } as never); // 100ms after — too soon
+      wrappedBody({ timestamp: 1200 } as never); // 200ms after — too soon
+
+      expect(hostWorklet).toHaveBeenCalledTimes(1);
+    });
+
+    it('fires again exactly at the interval boundary', () => {
+      const hostWorklet = jest.fn();
+      useThrottledFrameProcessor(hostWorklet, { sampleHz: 2 }, []); // 500ms
+      const [wrappedBody] = useFrameProcessorMock.mock.calls[0]!;
+
+      wrappedBody({ timestamp: 1000 } as never);
+      wrappedBody({ timestamp: 1500 } as never); // exactly at boundary
+
+      expect(hostWorklet).toHaveBeenCalledTimes(2);
+    });
+
+    it('fires again past the interval boundary', () => {
+      const hostWorklet = jest.fn();
+      useThrottledFrameProcessor(hostWorklet, { sampleHz: 2 }, []); // 500ms
+      const [wrappedBody] = useFrameProcessorMock.mock.calls[0]!;
+
+      wrappedBody({ timestamp: 1000 } as never);
+      wrappedBody({ timestamp: 1600 } as never); // 600ms after
+
+      expect(hostWorklet).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('shared value lifecycle', () => {
+    it('initializes lastSampleMs to 0', () => {
+      const noop = (() => {}) as unknown as Parameters<typeof useThrottledFrameProcessor>[0];
+      useThrottledFrameProcessor(noop, { sampleHz: 2 }, []);
+      expect(useSharedValueMock).toHaveBeenCalledWith(0);
+    });
+  });
+});