react-native-image-stitcher 0.14.2 → 0.15.0

package/dist/stitching/useFrameProcessor.d.ts

@@ -1,119 +0,0 @@
-import { type DependencyList } from 'react';
-import { type DrawableFrameProcessor, type ReadonlyFrameProcessor } from 'react-native-vision-camera';
-import type { StitcherFrameProcessor } from './StitcherFrame';
-/**
- * v0.8.0 Phase 4a — public hook for hosts to attach a per-frame
- * worklet that runs in BOTH AR and non-AR capture modes.
- *
- * ## Quick start
- *
- * ```tsx
- * import { useFrameProcessor, type StitcherFrame } from 'react-native-image-stitcher';
- *
- * function MyOcrOverlay() {
- *   const processor = useFrameProcessor((frame: StitcherFrame) => {
- *     'worklet';
- *     // Pixel data is in `frame.toArrayBuffer()`.
- *     // AR-only fields: `frame.arDepth`, `frame.arAnchors`, `frame.arTrackingState`.
- *     // Discriminate via `frame.source === 'ar'` / `'vc'`.
- *   }, []);
- *   return <Camera frameProcessor={processor} ... />;
- * }
- * ```
- *
- * ## Two behaviours, depending on mode
- *
- * **Non-AR mode (today, fully working):** the worklet runs on
- * vision-camera's Frame Processor runtime.  Same thread + same
- * cost envelope as a plain `useFrameProcessor` from
- * `react-native-vision-camera`.  The lib's own first-party
- * stitching plugin runs alongside on the same producer-thread
- * runtime (composition is handled by vision-camera's own dispatch
- * order).
- *
- * Your worklet receives whatever vision-camera delivers — vc's raw
- * `Frame`.  This is a structural subset of `StitcherFrame`: the
- * vc-shaped fields (`width`, `height`, `pixelFormat`, `orientation`,
- * `timestamp`, `toArrayBuffer`) are guaranteed; the
- * `StitcherFrame`-only fields (`source`, `pose`, `arDepth`,
- * `arAnchors`, `arTrackingState`) are **undefined** at runtime
- * because the lib does NOT wrap or augment vc's `Frame` in Phase 4a
- * (cross-worklet-boundary field injection is Phase 4b work).
- * Worklets that need to read `source` / `pose` MUST guard for
- * `undefined`:
- *
- * ```ts
- * if (frame.source === 'ar') { ... }   // false in non-AR mode
- * if (frame.pose) { ... }              // skipped in non-AR mode
- * ```
- *
- * **AR mode — iOS Phase 4b.i (this release):** the worklet is
- * installed into the native registry via
- * `globalThis.__stitcherProxy.install(workletFn)`, where
- * `__stitcherProxy` is a JSI host object installed at lib
- * bootstrap by the native `StitcherJsiInstaller` module.  The
- * AR worklet runtime (`RNSARWorkletRuntime`) reads from the
- * native registry on each `dispatchFrame:pose:` call and fans
- * out invocations — your worklet fires alongside the lib's
- * first-party stitching path.
- *
- * **AR mode — Android Phase 4b.ii (deferred):** the native
- * installer + JNI bridge from `StitcherWorkletRuntime.kt`'s
- * `runFirstParty {...}` path to a parallel C++ registry land in
- * a follow-up release.  Until then, on Android the hook falls
- * back to the JS-side `StitcherWorkletRegistry`; AR-mode host
- * worklets register but do not invoke.  No regression vs.
- * Phase 4a; iOS gets the API first.
- *
- * ### When Phase 4b.ii lands (Android)
- *
- * The hook's call signature does NOT change.  Android hosts that
- * write code today against this API will see their worklets
- * start firing in AR mode automatically when Phase 4b.ii is
- * merged.  No migration required.
- *
- * ## Frame contract
- *
- * The worklet receives a {@link StitcherFrame} (see
- * `src/stitching/StitcherFrame.ts` for the full contract +
- * lifecycle).  Highlights:
- *
- *   - **`source`** discriminator: `'vc'` or `'ar'`.  Branch on this
- *     before reading `arDepth` / `arAnchors` / `arTrackingState`
- *     so non-AR captures don't break.
- *   - **`pose`** always present.  `pose.translation` is `undefined`
- *     in non-AR mode (gyro provides only rotation; no spatial
- *     anchor).
- *   - **Buffer lifetime**: pixel data is valid only for the
- *     duration of the worklet call.  Worklets that need to retain
- *     data must `toArrayBuffer()` synchronously inside the
- *     worklet body — returning a reference and reading it later
- *     reads freed memory.
- *
- * ## Threading
- *
- * The worklet runs on the producer thread (vision-camera's
- * runtime in non-AR mode; the AR-session callback thread under
- * Phase 4b).  Worklets MUST NOT block the producer thread for
- * more than a few ms — the next frame's processing is gated on
- * the previous frame returning.  Long work belongs on a queue
- * crossed via Reanimated / worklets-core's `runOnJS`.
- *
- * @param worklet  The host's frame processor function.  Must be
- *                 `'worklet'`-prefixed at the call site.  TS
- *                 cannot enforce the prefix; the runtime will
- *                 throw at attempt to invoke a non-worklet
- *                 function.
- * @param deps     Standard React deps array.  When `deps` change,
- *                 the previous registration is removed and the
- *                 new worklet is registered.  Same semantics as
- *                 vision-camera's `useFrameProcessor`.
- *
- * @returns A vision-camera frame-processor object that
- *          `<Camera frameProcessor={...}>` accepts.  In non-AR
- *          mode this is what drives the per-frame worklet
- *          invocation; in AR mode it's currently a no-op (vc
- *          isn't mounted in AR mode anyway).
- */
-export declare function useFrameProcessor(worklet: StitcherFrameProcessor, deps: DependencyList): ReadonlyFrameProcessor | DrawableFrameProcessor;
-//# sourceMappingURL=useFrameProcessor.d.ts.map

package/dist/stitching/useFrameProcessor.js

@@ -1,196 +0,0 @@
-"use strict";
-// SPDX-License-Identifier: Apache-2.0
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.useFrameProcessor = useFrameProcessor;
-const react_1 = require("react");
-const react_native_vision_camera_1 = require("react-native-vision-camera");
-const ensureStitcherProxyInstalled_1 = require("./ensureStitcherProxyInstalled");
-const StitcherWorkletRegistry_1 = require("./StitcherWorkletRegistry");
-/**
- * v0.8.0 Phase 4a — public hook for hosts to attach a per-frame
- * worklet that runs in BOTH AR and non-AR capture modes.
- *
- * ## Quick start
- *
- * ```tsx
- * import { useFrameProcessor, type StitcherFrame } from 'react-native-image-stitcher';
- *
- * function MyOcrOverlay() {
- *   const processor = useFrameProcessor((frame: StitcherFrame) => {
- *     'worklet';
- *     // Pixel data is in `frame.toArrayBuffer()`.
- *     // AR-only fields: `frame.arDepth`, `frame.arAnchors`, `frame.arTrackingState`.
- *     // Discriminate via `frame.source === 'ar'` / `'vc'`.
- *   }, []);
- *   return <Camera frameProcessor={processor} ... />;
- * }
- * ```
- *
- * ## Two behaviours, depending on mode
- *
- * **Non-AR mode (today, fully working):** the worklet runs on
- * vision-camera's Frame Processor runtime.  Same thread + same
- * cost envelope as a plain `useFrameProcessor` from
- * `react-native-vision-camera`.  The lib's own first-party
- * stitching plugin runs alongside on the same producer-thread
- * runtime (composition is handled by vision-camera's own dispatch
- * order).
- *
- * Your worklet receives whatever vision-camera delivers — vc's raw
- * `Frame`.  This is a structural subset of `StitcherFrame`: the
- * vc-shaped fields (`width`, `height`, `pixelFormat`, `orientation`,
- * `timestamp`, `toArrayBuffer`) are guaranteed; the
- * `StitcherFrame`-only fields (`source`, `pose`, `arDepth`,
- * `arAnchors`, `arTrackingState`) are **undefined** at runtime
- * because the lib does NOT wrap or augment vc's `Frame` in Phase 4a
- * (cross-worklet-boundary field injection is Phase 4b work).
- * Worklets that need to read `source` / `pose` MUST guard for
- * `undefined`:
- *
- * ```ts
- * if (frame.source === 'ar') { ... }   // false in non-AR mode
- * if (frame.pose) { ... }              // skipped in non-AR mode
- * ```
- *
- * **AR mode — iOS Phase 4b.i (this release):** the worklet is
- * installed into the native registry via
- * `globalThis.__stitcherProxy.install(workletFn)`, where
- * `__stitcherProxy` is a JSI host object installed at lib
- * bootstrap by the native `StitcherJsiInstaller` module.  The
- * AR worklet runtime (`RNSARWorkletRuntime`) reads from the
- * native registry on each `dispatchFrame:pose:` call and fans
- * out invocations — your worklet fires alongside the lib's
- * first-party stitching path.
- *
- * **AR mode — Android Phase 4b.ii (deferred):** the native
- * installer + JNI bridge from `StitcherWorkletRuntime.kt`'s
- * `runFirstParty {...}` path to a parallel C++ registry land in
- * a follow-up release.  Until then, on Android the hook falls
- * back to the JS-side `StitcherWorkletRegistry`; AR-mode host
- * worklets register but do not invoke.  No regression vs.
- * Phase 4a; iOS gets the API first.
- *
- * ### When Phase 4b.ii lands (Android)
- *
- * The hook's call signature does NOT change.  Android hosts that
- * write code today against this API will see their worklets
- * start firing in AR mode automatically when Phase 4b.ii is
- * merged.  No migration required.
- *
- * ## Frame contract
- *
- * The worklet receives a {@link StitcherFrame} (see
- * `src/stitching/StitcherFrame.ts` for the full contract +
- * lifecycle).  Highlights:
- *
- *   - **`source`** discriminator: `'vc'` or `'ar'`.  Branch on this
- *     before reading `arDepth` / `arAnchors` / `arTrackingState`
- *     so non-AR captures don't break.
- *   - **`pose`** always present.  `pose.translation` is `undefined`
- *     in non-AR mode (gyro provides only rotation; no spatial
- *     anchor).
- *   - **Buffer lifetime**: pixel data is valid only for the
- *     duration of the worklet call.  Worklets that need to retain
- *     data must `toArrayBuffer()` synchronously inside the
- *     worklet body — returning a reference and reading it later
- *     reads freed memory.
- *
- * ## Threading
- *
- * The worklet runs on the producer thread (vision-camera's
- * runtime in non-AR mode; the AR-session callback thread under
- * Phase 4b).  Worklets MUST NOT block the producer thread for
- * more than a few ms — the next frame's processing is gated on
- * the previous frame returning.  Long work belongs on a queue
- * crossed via Reanimated / worklets-core's `runOnJS`.
- *
- * @param worklet  The host's frame processor function.  Must be
- *                 `'worklet'`-prefixed at the call site.  TS
- *                 cannot enforce the prefix; the runtime will
- *                 throw at attempt to invoke a non-worklet
- *                 function.
- * @param deps     Standard React deps array.  When `deps` change,
- *                 the previous registration is removed and the
- *                 new worklet is registered.  Same semantics as
- *                 vision-camera's `useFrameProcessor`.
- *
- * @returns A vision-camera frame-processor object that
- *          `<Camera frameProcessor={...}>` accepts.  In non-AR
- *          mode this is what drives the per-frame worklet
- *          invocation; in AR mode it's currently a no-op (vc
- *          isn't mounted in AR mode anyway).
- */
-function useFrameProcessor(worklet, deps) {
-    // Non-AR path: delegate to vision-camera's hook.  The returned
-    // processor object is what `<Camera>` hands to vc.  Worklet
-    // fires on vc's producer-thread runtime.
-    //
-    // Cast rationale: vc's hook expects `(frame: Frame) => void`.
-    // Our worklet is typed `(frame: StitcherFrame) => void`.
-    // `StitcherFrame` is a structural superset of `Frame` (it adds
-    // required `source` + `pose` and the optional AR fields), so
-    // assigning a function that consumes `StitcherFrame` to a
-    // `Frame`-consuming slot is unsound at the type level — TS is
-    // right to reject the direct assignment.  At RUNTIME the worklet
-    // will see vc's raw `Frame`; the `source` / `pose` / AR fields
-    // are undefined (the hook's docstring above documents this and
-    // tells hosts to guard).  We double-cast through `unknown` to
-    // suppress, accepting the explicit type-system gap as the price
-    // of Phase 4a's pre-Phase-4b deferral on cross-runtime frame
-    // wrapping.
-    const vcProcessor = (0, react_native_vision_camera_1.useFrameProcessor)(worklet, deps);
-    // AR path: install into the native registry if available (iOS
-    // Phase 4b.i — and Android Phase 4b.ii once it lands).  Falls
-    // back to the JS-side `StitcherWorkletRegistry` when the native
-    // installer isn't present (Android in 4b.i; remote debug mode;
-    // unit tests).  The fallback path matches Phase 4a's
-    // register-but-not-invoke semantics.
-    //
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    (0, react_1.useEffect)(() => {
-        const nativeReady = (0, ensureStitcherProxyInstalled_1.ensureStitcherProxyInstalled)();
-        if (nativeReady &&
-            typeof globalThis.__stitcherProxy !== 'undefined') {
-            // Native path — install through the JSI proxy.  Errors here
-            // most commonly mean the worklet doesn't have the
-            // `'worklet'` directive at the call site (the worklets-core
-            // babel plugin didn't transform it).  Surface them via the
-            // proxy's own throw with a host-side log so the failure is
-            // obvious.
-            let id;
-            try {
-                id = globalThis.__stitcherProxy.install(worklet);
-            }
-            catch (err) {
-                // Guard `__DEV__` read so the hook works in any environment
-                // that imports it without defining the flag (jest, SSR,
-                // custom tooling).
-                if (typeof __DEV__ !== 'undefined' && __DEV__) {
-                    console.error('[react-native-image-stitcher] __stitcherProxy.install ' +
-                        'threw — is the worklet function decorated with ' +
-                        "`'worklet';` and processed by react-native-worklets-core's " +
-                        'babel plugin?  Original error: ' +
-                        String(err));
-                }
-                return; // No cleanup needed — nothing was installed.
-            }
-            return () => {
-                try {
-                    globalThis.__stitcherProxy.uninstall(id);
-                }
-                catch {
-                    // Uninstall is best-effort; an exception here means the
-                    // proxy was already gone (e.g., app reload mid-cleanup).
-                }
-            };
-        }
-        // Fallback — JS-side registry.  Same as Phase 4a.
-        const jsId = StitcherWorkletRegistry_1.StitcherWorkletRegistry.register({
-            worklet,
-            isFirstParty: false,
-        });
-        return () => StitcherWorkletRegistry_1.StitcherWorkletRegistry.unregister(jsId);
-    }, deps);
-    return vcProcessor;
-}
-//# sourceMappingURL=useFrameProcessor.js.map

package/dist/stitching/useFrameStream.d.ts

@@ -1,34 +0,0 @@
-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

@@ -1,234 +0,0 @@
-"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

@@ -1,33 +0,0 @@
-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