react-native-image-stitcher 0.7.1 → 0.9.0

package/dist/stitching/StitcherWorkletRegistry.d.ts

@@ -0,0 +1,117 @@
+import type { StitcherFrameProcessor } from './StitcherFrame';
+/**
+ * v0.8.0 Phase 4a — process-scope registry of host-supplied worklets
+ * that the v0.8.0 `useFrameProcessor` hook registers into.
+ *
+ * ## What this is (Phase 4a)
+ *
+ * A plain JS singleton holding an ordered list of registered
+ * worklets.  Hosts mount the `useFrameProcessor` hook (in this
+ * directory); the hook registers its worklet into this singleton
+ * on mount and unregisters on unmount.  Each entry carries:
+ *
+ *   - `id`: stable identifier issued by `register`; passed to
+ *     `unregister`.
+ *   - `worklet`: the host's `StitcherFrameProcessor` function.
+ *     MUST be `'worklet'`-prefixed at the call site (TS can't
+ *     enforce that — convention).
+ *   - `isFirstParty`: `false` for host-supplied worklets;
+ *     reserved for the lib's own first-party stitching path which
+ *     today is wired natively (not through this registry).
+ *
+ * Order is stable: first-party entries (none in Phase 4a) come
+ * first, then host entries by registration order.  Re-registration
+ * of the same worklet by identity yields a new entry — hosts that
+ * re-render and call `register` again ARE responsible for calling
+ * `unregister` first.  The `useFrameProcessor` hook handles this
+ * via its `deps` dependency array.
+ *
+ * ## What this is NOT (Phase 4b)
+ *
+ * **The native AR worklet runtime does NOT yet read this registry.**
+ * Worklets registered here for AR-mode captures will not fire
+ * until Phase 4b lands the cross-runtime handoff (a
+ * worklets-core `SharedValue` mirror that `RNSARWorkletRuntime`
+ * reads on each `dispatchFrame:pose:` call; the runtime then
+ * constructs a `StitcherFrameHostObject` + invokes each
+ * registered worklet via `RNWorklet::WorkletInvoker::call`).
+ *
+ * In non-AR mode the host-supplied worklet IS invoked, but via
+ * vision-camera's Frame Processor runtime directly (the
+ * `useFrameProcessor` hook returns vc's processor object which
+ * `<Camera>` passes to vision-camera).  So Phase 4a's public API
+ * is fully functional for non-AR; AR is API-stable but
+ * runtime-deferred.
+ *
+ * ## Singleton lifetime
+ *
+ * The registry is a module-level instance.  It lives for the
+ * lifetime of the JS runtime (= until app reload).  Entries
+ * accumulate only via `register` and shed only via `unregister`
+ * — no GC / weak-ref logic.  Hosts that mount `useFrameProcessor`
+ * inside React components MUST rely on the hook's effect cleanup
+ * to unregister on unmount, or they'll leak entries until
+ * reload.  The hook handles this correctly today.
+ *
+ * ## Why a singleton (vs context provider)
+ *
+ * The native AR worklet runtime is itself a process-scope
+ * singleton (`RNSARWorkletRuntime`, `StitcherWorkletRuntime`).
+ * The Phase 4b handoff between TS and native is necessarily
+ * process-scope.  Wrapping the registry in a React context
+ * would force every consumer to be in the same provider tree
+ * which is friction for layer-2 hosts that compose
+ * `<ARCameraView>` / `useIncrementalStitcher` themselves.  The
+ * singleton is the right shape; the React-level ergonomics are
+ * provided by the `useFrameProcessor` hook.
+ */
+export interface StitcherWorkletEntry {
+    readonly id: string;
+    readonly worklet: StitcherFrameProcessor;
+    readonly isFirstParty: boolean;
+}
+declare class Registry {
+    private entries;
+    private nextHostCounter;
+    /**
+     * Register a worklet.  Returns a stable ID for `unregister`.
+     *
+     * Entries are appended in registration order; first-party
+     * entries (if any are added in future) sort to the front.
+     */
+    register(opts: {
+        worklet: StitcherFrameProcessor;
+        isFirstParty?: boolean;
+    }): string;
+    /**
+     * Remove a previously-registered worklet by ID.  No-op if the ID
+     * isn't found.  Hosts call this in their effect's cleanup.
+     */
+    unregister(id: string): void;
+    /**
+     * Snapshot the current entries.  Returned array is a copy —
+     * mutations don't affect the registry.  Phase 4b's native
+     * handoff will read a `SharedValue` mirror of this list so the
+     * AR runtime doesn't need a JS-thread hop on the hot per-frame
+     * path; for Phase 4a this method is the JS-side accessor.
+     */
+    getEntries(): readonly StitcherWorkletEntry[];
+    /**
+     * Total number of registered worklets (first-party + host).
+     * Useful for diagnostics + tests.
+     */
+    get count(): number;
+    /**
+     * Test-only — clear all entries.  NOT exported from
+     * `src/index.ts`.  Used in unit tests to reset state between
+     * cases.
+     */
+    _resetForTests(): void;
+}
+/**
+ * Process-scope singleton.  Imported by `useFrameProcessor` (in
+ * this directory) + by the Phase 4b native-handoff code (TBD).
+ */
+export declare const StitcherWorkletRegistry: Registry;
+export {};
+//# sourceMappingURL=StitcherWorkletRegistry.d.ts.map

package/dist/stitching/StitcherWorkletRegistry.js

@@ -0,0 +1,78 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StitcherWorkletRegistry = void 0;
+class Registry {
+    constructor() {
+        this.entries = [];
+        this.nextHostCounter = 0;
+    }
+    /**
+     * Register a worklet.  Returns a stable ID for `unregister`.
+     *
+     * Entries are appended in registration order; first-party
+     * entries (if any are added in future) sort to the front.
+     */
+    register(opts) {
+        const isFirstParty = opts.isFirstParty ?? false;
+        const id = isFirstParty
+            ? `fp-${this.nextHostCounter++}`
+            : `host-${this.nextHostCounter++}`;
+        const entry = {
+            id,
+            worklet: opts.worklet,
+            isFirstParty,
+        };
+        this.entries.push(entry);
+        // Re-sort so first-party always runs before host entries.
+        // Stable sort: registration order is preserved within each
+        // partition.  Single-pass O(n log n) is fine — registration
+        // is rare (per-`<Camera>`-mount, not per-frame).
+        this.entries.sort((a, b) => {
+            if (a.isFirstParty !== b.isFirstParty) {
+                return a.isFirstParty ? -1 : 1;
+            }
+            return 0;
+        });
+        return id;
+    }
+    /**
+     * Remove a previously-registered worklet by ID.  No-op if the ID
+     * isn't found.  Hosts call this in their effect's cleanup.
+     */
+    unregister(id) {
+        this.entries = this.entries.filter((e) => e.id !== id);
+    }
+    /**
+     * Snapshot the current entries.  Returned array is a copy —
+     * mutations don't affect the registry.  Phase 4b's native
+     * handoff will read a `SharedValue` mirror of this list so the
+     * AR runtime doesn't need a JS-thread hop on the hot per-frame
+     * path; for Phase 4a this method is the JS-side accessor.
+     */
+    getEntries() {
+        return [...this.entries];
+    }
+    /**
+     * Total number of registered worklets (first-party + host).
+     * Useful for diagnostics + tests.
+     */
+    get count() {
+        return this.entries.length;
+    }
+    /**
+     * Test-only — clear all entries.  NOT exported from
+     * `src/index.ts`.  Used in unit tests to reset state between
+     * cases.
+     */
+    _resetForTests() {
+        this.entries = [];
+        this.nextHostCounter = 0;
+    }
+}
+/**
+ * Process-scope singleton.  Imported by `useFrameProcessor` (in
+ * this directory) + by the Phase 4b native-handoff code (TBD).
+ */
+exports.StitcherWorkletRegistry = new Registry();
+//# sourceMappingURL=StitcherWorkletRegistry.js.map

package/dist/stitching/ensureStitcherProxyInstalled.d.ts

@@ -0,0 +1,8 @@
+export declare function ensureStitcherProxyInstalled(): boolean;
+/**
+ * Test-only — reset module-internal state.  Used by jest to allow
+ * multiple test cases to re-trigger the install path independently.
+ * NOT exported from `src/index.ts`.
+ */
+export declare function _resetStitcherProxyInstallStateForTests(): void;
+//# sourceMappingURL=ensureStitcherProxyInstalled.d.ts.map

package/dist/stitching/ensureStitcherProxyInstalled.js

@@ -0,0 +1,81 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureStitcherProxyInstalled = ensureStitcherProxyInstalled;
+exports._resetStitcherProxyInstallStateForTests = _resetStitcherProxyInstallStateForTests;
+const react_native_1 = require("react-native");
+/**
+ * `__DEV__` is RN's global dev-flag.  Guard the read with `typeof`
+ * so the helper works in any environment that imports it without
+ * defining __DEV__ (jest, SSR, custom tooling).  Same pattern RN's
+ * own debug code uses.
+ */
+function isDev() {
+    return typeof __DEV__ !== 'undefined' && __DEV__;
+}
+let installed = false;
+function ensureStitcherProxyInstalled() {
+    if (installed)
+        return true;
+    // Already installed by an earlier hook mount.  Cheap fast-path.
+    if (typeof globalThis.__stitcherProxy !== 'undefined') {
+        installed = true;
+        return true;
+    }
+    const mod = react_native_1.NativeModules
+        .StitcherJsiInstaller;
+    if (mod == null || typeof mod.install !== 'function') {
+        // Module not present — Android until Phase 4b.ii lands, or
+        // an old iOS build.  Surface this once at debug-info level so
+        // the host can see "your worklets are JS-registered only" in
+        // logcat / Console.app without a noisy per-frame warning.
+        if (isDev() && !warnedAboutMissingModule) {
+            warnedAboutMissingModule = true;
+            console.info('[react-native-image-stitcher] StitcherJsiInstaller native ' +
+                'module not found; host worklets registered in JS-side ' +
+                'registry only.  AR-mode dispatch requires the native install ' +
+                '(iOS Phase 4b.i — included in v0.8.0; Android Phase 4b.ii ' +
+                '— follow-up release).');
+        }
+        return false;
+    }
+    try {
+        const ok = mod.install();
+        if (!ok) {
+            // Native module ran but couldn't install (JSI runtime
+            // unreachable).  Same fallback as the missing-module case.
+            if (isDev() && !warnedAboutFailedInstall) {
+                warnedAboutFailedInstall = true;
+                console.info('[react-native-image-stitcher] StitcherJsiInstaller.install() ' +
+                    'returned false (JSI runtime unreachable — remote debug ' +
+                    'mode?).  Falling back to JS-side host worklet registry.');
+            }
+            return false;
+        }
+        installed = true;
+        return true;
+    }
+    catch (err) {
+        if (isDev() && !warnedAboutFailedInstall) {
+            warnedAboutFailedInstall = true;
+            console.info('[react-native-image-stitcher] StitcherJsiInstaller.install() ' +
+                'threw: ' +
+                String(err) +
+                '.  Falling back to JS-side host worklet registry.');
+        }
+        return false;
+    }
+}
+let warnedAboutMissingModule = false;
+let warnedAboutFailedInstall = false;
+/**
+ * Test-only — reset module-internal state.  Used by jest to allow
+ * multiple test cases to re-trigger the install path independently.
+ * NOT exported from `src/index.ts`.
+ */
+function _resetStitcherProxyInstallStateForTests() {
+    installed = false;
+    warnedAboutMissingModule = false;
+    warnedAboutFailedInstall = false;
+}
+//# sourceMappingURL=ensureStitcherProxyInstalled.js.map

package/dist/stitching/useFrameProcessor.d.ts

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

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

@@ -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