react-native-image-stitcher 0.10.0 → 0.11.1

package/dist/stitching/useStitcherWorklet.js

@@ -0,0 +1,300 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * useStitcherWorklet — exposes the lib's first-party stitching as a
+ * callable worklet function for host-composed Frame Processors.
+ *
+ * v0.11.0 — closes the v0.8.0 Phase 5 either-or constraint by letting
+ * hosts COMPOSE: write ONE `useFrameProcessor` worklet body that calls
+ * BOTH your custom logic AND the lib's first-party stitching, instead
+ * of one displacing the other.  See `docs/host-app-integration.md`
+ * § Tier 3 composition for the pattern.
+ *
+ * ## Why this is a separate hook
+ *
+ * vision-camera v4 lets a `<Camera>` mount accept exactly ONE frame
+ * processor.  Pre-v0.11.0, hosts that passed a `frameProcessor` prop
+ * to the lib's `<Camera>` REPLACED the lib's first-party stitching
+ * processor in non-AR mode.  Composing required hand-writing both
+ * worklet bodies in the host's processor.  v0.11.0 extracts the
+ * lib's worklet body into this hook so hosts can compose with a
+ * single call:
+ *
+ *   const stitcher = useStitcherWorklet();
+ *   const fp = useFrameProcessor((frame) => {
+ *     'worklet';
+ *     hostPreLogic(frame);
+ *     stitcher.call(frame);   // ← lib's first-party stitching
+ *     hostPostLogic(frame);
+ *   }, [stitcher.call]);
+ *   return <Camera frameProcessor={fp} ... />;
+ *
+ * AR mode is unaffected — the AR-session dispatch path (v0.8.0 Phase
+ * 4b.i / 4b.iii) already composes natively.
+ *
+ * ## What this owns
+ *
+ *   - vc Frame Processor plugin acquisition for
+ *     `cv_flow_gate_process_frame` (the same plugin the legacy
+ *     `useFrameProcessorDriver` used; reentrant by construction).
+ *   - Shared values backing pose (yaw / pitch / roll), throttle
+ *     counter, every-N gate, and FoV-derived intrinsics scalars.
+ *   - Gyro subscription on the JS thread (always-on between mount
+ *     and unmount; subscription cost is tiny).
+ *   - The worklet body itself: throttle → pose synthesis →
+ *     `plugin.call(frame, params)`.
+ *
+ * ## Lifecycle
+ *
+ *   - Gyro auto-subscribes on mount, auto-unsubscribes on unmount.
+ *     Composed hosts get pose tracking for free.
+ *   - `reset()` zeros the accumulated yaw / pitch / roll between
+ *     captures.  `useFrameProcessorDriver` calls this on `start()` to
+ *     preserve pre-v0.11.0 per-capture pose-reset behaviour;
+ *     composed hosts should call it at the start of each capture too
+ *     (otherwise pose drifts across captures).
+ *
+ * ## Behaviour delta from pre-v0.11.0
+ *
+ *   Before: `useFrameProcessorDriver.start()` subscribed the gyro;
+ *   `stop()` unsubscribed.  The subscription was tied to the
+ *   capture lifecycle.
+ *
+ *   After: the gyro is subscribed for the lifetime of this hook
+ *   (i.e., as long as the component using it is mounted).  In the
+ *   default `<Camera>` integration the hook mounts when the camera
+ *   screen mounts, so the practical effect is the same; in
+ *   custom-composed integrations the host controls mount/unmount
+ *   by mounting/unmounting the component that calls
+ *   `useStitcherWorklet`.  The battery delta is small: gyroscope
+ *   sampling at 33ms costs ≪1% CPU on every Android/iOS device
+ *   the lib supports.
+ *
+ *   `pose reset` semantics are preserved via the new explicit
+ *   `reset()` method.  Hosts that previously relied on `start()`
+ *   to zero pose now call `stitcher.reset()` at the capture start.
+ *
+ * ## Pose synthesis (verbatim from `useFrameProcessorDriver`)
+ *
+ *   Quaternion: q = q_yaw * q_pitch * q_roll (Tait-Bryan YPR, body
+ *   frame).  Expanded:
+ *     qx = cy*sp*cr + sy*cp*sr
+ *     qy = sy*cp*cr - cy*sp*sr
+ *     qz = cy*cp*sr - sy*sp*cr
+ *     qw = cy*cp*cr + sy*sp*sr
+ *
+ *   When roll=0 this collapses to the legacy 2-axis form so captures
+ *   held level produce bit-identical poses to the pre-v0.6 driver
+ *   (and bit-identical to v0.10.x's `useFrameProcessorDriver`).
+ *
+ * ## Throttling (verbatim)
+ *
+ *   `evalEveryNFrames` controls how often the worklet calls the
+ *   plugin.  Default 1.  Independent of — and stacks on top of —
+ *   the stitcher's own internal `flowEvalEveryNFrames` in
+ *   `KeyframeGate.swift`; effective cadence is the product.
+ *
+ * ## Pairing with `IncrementalStitcher.start`
+ *
+ *   The plugin's per-frame call into `consumeFrameFromPlugin` is
+ *   gated by `IncrementalStitcher.frameProcessorIngestEnabled`,
+ *   which is TRUE only when the stitcher was started with
+ *   `frameSourceMode === 'frameProcessor'`.  Hosts MUST call
+ *   `incrementalStitcher.start({ frameSourceMode: 'frameProcessor',
+ *   ... })` to actually get frames into the engine — otherwise the
+ *   worklet runs to completion but the wrapper drops the call.
+ *   `Camera.tsx` does this wiring automatically when the host opts
+ *   into the lib's `useFrameProcessorDriver`.  Hosts that compose
+ *   their own worklet via this hook must do the wiring themselves.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useStitcherWorklet = useStitcherWorklet;
+const react_1 = require("react");
+const react_native_sensors_1 = require("react-native-sensors");
+// Reanimated's `useSharedValue` is the documented vision-camera
+// idiom, but it's a heavy peer dep.  `react-native-worklets-core`
+// (already a transitive dep via vision-camera v4 on RN 0.84) exposes
+// the same API surface (a `value` getter/setter readable from
+// worklets and the JS thread) and is sufficient for our use.
+const react_native_worklets_core_1 = require("react-native-worklets-core");
+const react_native_vision_camera_1 = require("react-native-vision-camera");
+function useStitcherWorklet(options = {}) {
+    const { gyroIntervalMs = 33, fovHorizDegrees = 65, fovVertDegrees = 50, evalEveryNFrames = 1, } = options;
+    // ── Plugin acquisition ──────────────────────────────────────────
+    //
+    // `initFrameProcessorPlugin` can return `undefined` if called
+    // before vision-camera's plugin registry has finished initialising
+    // (race observed in F8.1.a).  Mount-once useEffect with a 16ms
+    // retry until success.  Verbatim from `useFrameProcessorDriver`.
+    const [plugin, setPlugin] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        let cancelled = false;
+        let timerId = null;
+        const tryAcquire = () => {
+            if (cancelled)
+                return;
+            const p = react_native_vision_camera_1.VisionCameraProxy.initFrameProcessorPlugin('cv_flow_gate_process_frame', {});
+            if (p != null) {
+                setPlugin(p);
+                return;
+            }
+            timerId = setTimeout(tryAcquire, 16);
+        };
+        tryAcquire();
+        return () => {
+            cancelled = true;
+            if (timerId != null)
+                clearTimeout(timerId);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // ── Shared values (worklet ↔ JS thread) ─────────────────────────
+    const sharedYaw = (0, react_native_worklets_core_1.useSharedValue)(0);
+    const sharedPitch = (0, react_native_worklets_core_1.useSharedValue)(0);
+    const sharedRoll = (0, react_native_worklets_core_1.useSharedValue)(0);
+    const sharedFrameCounter = (0, react_native_worklets_core_1.useSharedValue)(0);
+    const sharedEvalEveryN = (0, react_native_worklets_core_1.useSharedValue)(Math.max(1, evalEveryNFrames));
+    const sharedFxNumerator = (0, react_native_worklets_core_1.useSharedValue)(1.0 / (2.0 * Math.tan((fovHorizDegrees * Math.PI / 180) / 2)));
+    const sharedFyNumerator = (0, react_native_worklets_core_1.useSharedValue)(1.0 / (2.0 * Math.tan((fovVertDegrees * Math.PI / 180) / 2)));
+    // Prop-derived shared values stay in sync via cheap effects.
+    (0, react_1.useEffect)(() => {
+        sharedEvalEveryN.value = Math.max(1, evalEveryNFrames);
+    }, [evalEveryNFrames, sharedEvalEveryN]);
+    (0, react_1.useEffect)(() => {
+        sharedFxNumerator.value =
+            1.0 / (2.0 * Math.tan((fovHorizDegrees * Math.PI / 180) / 2));
+    }, [fovHorizDegrees, sharedFxNumerator]);
+    (0, react_1.useEffect)(() => {
+        sharedFyNumerator.value =
+            1.0 / (2.0 * Math.tan((fovVertDegrees * Math.PI / 180) / 2));
+    }, [fovVertDegrees, sharedFyNumerator]);
+    // ── Gyro subscription (always-on while mounted) ─────────────────
+    //
+    // v0.11.0 — moved here from `useFrameProcessorDriver.start()`.
+    // The composition pattern needs gyro running whenever
+    // `useStitcherWorklet` is in use; gating the subscription on a
+    // separate start/stop pair would force every composed host to
+    // wire its own lifecycle.  Cost is tiny: ≪1% CPU at 33ms
+    // sampling.  See module header "Behaviour delta from pre-v0.11.0".
+    (0, react_1.useEffect)(() => {
+        let lastGyroAt = null;
+        (0, react_native_sensors_1.setUpdateIntervalForType)(react_native_sensors_1.SensorTypes.gyroscope, gyroIntervalMs);
+        const sub = react_native_sensors_1.gyroscope.subscribe({
+            next: ({ x, y, z }) => {
+                const now = Date.now();
+                if (lastGyroAt === null) {
+                    lastGyroAt = now;
+                    return;
+                }
+                const dt = (now - lastGyroAt) / 1000.0;
+                lastGyroAt = now;
+                sharedYaw.value += y * dt;
+                sharedPitch.value += x * dt;
+                sharedRoll.value += z * dt;
+            },
+            error: (err) => {
+                // eslint-disable-next-line no-console
+                console.warn('[useStitcherWorklet] gyro error', err);
+            },
+        });
+        return () => {
+            sub.unsubscribe();
+        };
+    }, [gyroIntervalMs, sharedYaw, sharedPitch, sharedRoll]);
+    // ── Explicit reset (for per-capture pose zero-ing) ──────────────
+    const reset = (0, react_1.useCallback)(() => {
+        sharedYaw.value = 0;
+        sharedPitch.value = 0;
+        sharedRoll.value = 0;
+        sharedFrameCounter.value = 0;
+    }, [sharedYaw, sharedPitch, sharedRoll, sharedFrameCounter]);
+    // ── Worklet body ────────────────────────────────────────────────
+    //
+    // Returned as `handle.call`.  Re-created when `plugin` changes
+    // (which happens at most once at acquire time); deps array on the
+    // useCallback ensures consumers' `useFrameProcessor([handle.call])`
+    // re-binds when the worklet identity changes.
+    //
+    // The `'worklet'` directive marks this function for the
+    // worklets-core transformer so it can be serialised into the
+    // producer-thread runtime; that's the contract that lets a host
+    // `useFrameProcessor` worklet body call it without a thread hop.
+    const call = (0, react_1.useCallback)((frame) => {
+        'worklet';
+        if (plugin == null)
+            return;
+        // v0.11.1 — AR-source frames are stitched natively by the AR-
+        // side dispatcher (`RNSARSession.swift:510-511` → the first-
+        // party callback installed in `RNSARWorkletRuntime`).  Calling
+        // the vc Frame Processor plugin here would throw
+        // `getPropertyAsObject: property '__frame' is undefined`
+        // because AR frames are `StitcherFrameHostObject` instances
+        // and don't carry the vc `Frame` proxy's JSI marker.  The
+        // throw is caught silently by the per-worklet error handler
+        // (`RNSARWorkletRuntime.mm:284-301`) and bubbles up only to
+        // `os_log` — invisible to JS, which is why pre-v0.11.1
+        // composed hosts saw their post-`stitcher.call` lines
+        // (`fireFrameProcessorLog`, `runOnJS` callbacks) silently
+        // never execute in AR mode.  Silent no-op here matches the
+        // module-header promise that AR mode is "unaffected" by this
+        // hook (the AR-side stitching path runs natively, independent
+        // of the composed worklet body).
+        //
+        // The `(frame as StitcherFrame).source` cast is safe: vc
+        // `Frame` doesn't carry a `source` property so the check
+        // returns `undefined !== 'ar'` → `true`, and the worklet
+        // proceeds normally.  Only frames that explicitly tag
+        // themselves as AR-source (which our native AR dispatcher
+        // does — see `StitcherFrameHostObject.mm`) get short-circuited.
+        if (frame.source === 'ar')
+            return;
+        // Throttle (verbatim from useFrameProcessorDriver).
+        sharedFrameCounter.value += 1;
+        const N = sharedEvalEveryN.value;
+        if (N > 1 && (sharedFrameCounter.value % N) !== 0)
+            return;
+        // Pose synthesis (verbatim from useFrameProcessorDriver).
+        const halfYaw = sharedYaw.value / 2;
+        const halfPitch = sharedPitch.value / 2;
+        const halfRoll = sharedRoll.value / 2;
+        const cy_ = Math.cos(halfYaw);
+        const sy_ = Math.sin(halfYaw);
+        const cp = Math.cos(halfPitch);
+        const sp = Math.sin(halfPitch);
+        const cr = Math.cos(halfRoll);
+        const sr = Math.sin(halfRoll);
+        const qx = cy_ * sp * cr + sy_ * cp * sr;
+        const qy = sy_ * cp * cr - cy_ * sp * sr;
+        const qz = cy_ * cp * sr - sy_ * sp * cr;
+        const qw = cy_ * cp * cr + sy_ * sp * sr;
+        // Intrinsics from FoV + actual frame dims.
+        const w = frame.width;
+        const h = frame.height;
+        const fx = w * sharedFxNumerator.value;
+        const fy = h * sharedFyNumerator.value;
+        // vc's `plugin.call` is typed against vc's `Frame`.  The worklet
+        // accepts the union (`Frame | StitcherFrame`); cast through
+        // `unknown` because the union doesn't satisfy vc's interface
+        // even though structurally both members do.
+        plugin.call(frame, {
+            tx: 0, ty: 0, tz: 0,
+            qx, qy, qz, qw,
+            fx, fy,
+            cx: w / 2, cy: h / 2,
+            imageWidth: w, imageHeight: h,
+            timestampMs: 0,
+            trackingStateRaw: 2, // RNSARTrackingState.tracking (no AR signal in non-AR mode)
+        });
+    }, [
+        plugin,
+        sharedFrameCounter,
+        sharedEvalEveryN,
+        sharedYaw,
+        sharedPitch,
+        sharedRoll,
+        sharedFxNumerator,
+        sharedFyNumerator,
+    ]);
+    return { call, reset, isReady: plugin != null };
+}
+//# sourceMappingURL=useStitcherWorklet.js.map

package/ios/Sources/RNImageStitcher/StitcherJsiInstaller.mm

@@ -22,11 +22,37 @@
 #import <React/RCTBridge.h>
 #import <React/RCTBridge+Private.h>
 #import <React/RCTUtils.h>
+#import <ReactCommon/CallInvoker.h>
+// `RCTCxxBridge` (and its bridgeless-mode `RCTBridgeProxy` forwarder)
+// exposes `-jsCallInvoker` returning `std::shared_ptr<CallInvoker>`,
+// but the property declaration lives in `<ReactCommon/RCTTurboModule.h>`
+// which isn't on our pod's HEADER_SEARCH_PATHS (worklets-core gets it
+// via its own ReactCommon dep).  Rather than enlarging our pod's
+// dependency surface, forward-declare the property in an anonymous
+// category — the runtime dispatches to RN's actual implementation.
+// Pattern matches `WKTJsiWorkletContext.cpp`'s approach to keep the
+// pod self-contained.
+@interface RCTCxxBridge ()
+@property (nonatomic, readonly) std::shared_ptr<facebook::react::CallInvoker> jsCallInvoker;
+@end
 #import <os/log.h>
 
 #include <jsi/jsi.h>
 
 #include "stitcher_proxy_jsi.hpp"
+// v0.11.1 — worklets-core JsiWorkletContext.  We initialize the
+// SINGLETON default instance here so that other contexts in this
+// library that use the 2-arg `JsiWorkletContext(name, workletInvoker)`
+// constructor inherit a working `_jsCallInvoker` (and thus their
+// `runOnJS` / `Worklets.createRunOnJS` callbacks actually route back
+// to the main JS thread).  Specifically: `RNSARWorkletRuntime`'s AR-
+// side worklet context (see `RNSARWorkletRuntime.mm:155`) uses the
+// 2-arg ctor; pre-v0.11.1 that left its inherited `_jsCallInvoker`
+// nullptr, and `invokeOnJsThread` silently no-op'd (see
+// `WKTJsiWorkletContext.cpp:124-131`).  Test 2 of the v0.11.0
+// manual-verification checklist surfaced this as "AR-mode host
+// worklets register but their runOnJS callbacks never fire."
+#include "WKTJsiWorkletContext.h"
 
 using namespace facebook;
 
@@ -94,9 +120,40 @@ RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(install) {
   jsi::Runtime& runtime = *(jsi::Runtime*)cxxBridge.runtime;
   retailens::installStitcherProxy(runtime);
 
+  // v0.11.1 — initialize the singleton default JsiWorkletContext so
+  // that downstream 2-arg ctors (RNSARWorkletRuntime) inherit a
+  // working `_jsCallInvoker`.  Without this, AR-mode host worklets'
+  // `runOnJS` / `Worklets.createRunOnJS` callbacks silently no-op
+  // (`WKTJsiWorkletContext.cpp:124-131` early-returns when
+  // `_jsCallInvoker == nullptr`).  See file-top comment for the full
+  // diagnosis (Test 2 of v0.11.0 manual-verification checklist).
+  //
+  // Idempotent at the worklets-core level: re-initialization is
+  // tolerated; the default instance is a process-scope singleton
+  // and we're called once per JS-runtime bootstrap.  In bridgeless
+  // mode `cxxBridge.jsCallInvoker` is forwarded via RCTBridgeProxy
+  // to the underlying RCTHost's `CallInvoker` (same forwarding
+  // pattern as `cxxBridge.runtime` above).
+  auto jsCallInvoker = cxxBridge.jsCallInvoker;
+  if (jsCallInvoker == nullptr) {
+    os_log_error(OS_LOG_DEFAULT,
+        "[StitcherJsiInstaller] cxxBridge.jsCallInvoker is nullptr; "
+        "AR-mode host worklets' runOnJS will not fire.  Proxy installed "
+        "but worklet-bridging is impaired.");
+    // Proxy is still installed; only the runOnJS path is impaired.
+    // Return @YES so JS callers don't fall back to the JS-side registry.
+    return @YES;
+  }
+  auto jsInvokerAdapter =
+      [jsCallInvoker](std::function<void()>&& fp) {
+        jsCallInvoker->invokeAsync(std::move(fp));
+      };
+  RNWorklet::JsiWorkletContext::getDefaultInstance()->initialize(
+      "stitcher.default", &runtime, jsInvokerAdapter);
+
   os_log_info(OS_LOG_DEFAULT,
       "[StitcherJsiInstaller] installed globalThis.__stitcherProxy "
-      "on main JS runtime.");
+      "AND initialized default JsiWorkletContext on main JS runtime.");
   return @YES;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "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",
@@ -53,6 +53,7 @@
   },
   "homepage": "https://github.com/bhargavkanda/react-native-image-stitcher#readme",
   "devDependencies": {
+    "@react-native-community/cli": "20.1.0",
     "@types/jest": "^29.5.0",
     "@types/react": "^19.0.0",
     "jest": "^29.7.0",

package/src/camera/Camera.tsx

@@ -323,26 +323,42 @@ export interface CameraProps {
    * }
    * ```
    *
-   * ## Non-AR mode tradeoff (HONEST)
+   * ## Non-AR mode composition (v0.11.0+)
    *
    * vision-camera's `<Camera>` accepts ONLY ONE frame processor.
    * The lib's internal `useFrameProcessorDriver` produces the
    * processor that drives first-party panorama stitching in non-AR
-   * mode.  If you supply your own via this prop, **the lib's
-   * first-party stitching is replaced** — panorama capture in
-   * non-AR mode will not produce stitched output until you remove
-   * the prop or fork the SDK to compose both worklets manually.
+   * mode.  If you supply your own via this prop, the lib's
+   * default processor is REPLACED — but as of v0.11.0 you can
+   * COMPOSE first-party stitching back into your worklet body
+   * using `useStitcherWorklet`:
    *
-   * For the common case (host wants worklet + lib wants stitching
-   * concurrently), prefer AR mode: the AR-mode path natively fans
-   * out to both the lib's first-party stitching AND every
-   * registered host worklet on every frame, with per-worklet
-   * failure isolation.
+   * ```tsx
+   * import {
+   *   Camera, useFrameProcessor, useStitcherWorklet,
+   *   type StitcherFrame,
+   * } from 'react-native-image-stitcher';
    *
-   * Composition for non-AR mode (lib stitching + host worklet on
-   * the same vc processor) is tracked as a v0.9+ follow-up;
-   * needs the lib's first-party logic exposed as a vc Frame
-   * Processor plugin the host's worklet can call.
+   * function MyScreen() {
+   *   const stitcher = useStitcherWorklet();
+   *   const fp = useFrameProcessor((frame: StitcherFrame) => {
+   *     'worklet';
+   *     hostPreLogic(frame);
+   *     stitcher.call(frame);   // ← first-party stitching
+   *     hostPostLogic(frame);
+   *   }, [stitcher.call]);
+   *   return <Camera frameProcessor={fp} ... />;
+   * }
+   * ```
+   *
+   * Hosts that DON'T call `useStitcherWorklet` from their worklet
+   * body replace first-party stitching for non-AR captures (a
+   * one-shot console.info documents this when the prop is first
+   * supplied).  AR mode is unaffected either way — the AR-mode
+   * dispatch path (v0.8.0 Phase 4b.i / 4b.iii) natively fans out
+   * to both the lib's first-party stitching AND every registered
+   * host worklet on every frame, with per-worklet failure
+   * isolation.
    *
    * ## AR mode behaviour
    *
@@ -841,24 +857,23 @@ export function Camera(props: CameraProps): React.JSX.Element {
   // eslint-disable-next-line react-hooks/exhaustive-deps
   useEffect(() => () => { fpDriver.stop(); }, []);
 
-  // v0.8.0 Phase 5 — frameProcessor prop semantics:
+  // v0.8.0 Phase 5 / v0.11.0 — frameProcessor prop semantics:
   //
-  //   - Host supplied? → use host's processor; lib's first-party
-  //     stitching is DISABLED in non-AR mode (vc accepts only one
-  //     processor).  One-shot console.info documents the tradeoff
-  //     so the host isn't surprised by "panorama capture stopped
-  //     producing output" in non-AR mode.  AR-mode capture is
-  //     unaffected — the AR-session dispatch path fans out to BOTH
-  //     first-party and host worklets independently.
+  //   - Host supplied? → use host's processor.  The host's worklet
+  //     body controls whether first-party stitching also fires:
+  //     call `stitcher.call(frame)` (from `useStitcherWorklet`)
+  //     inside the body to compose; omit to replace.  One-shot
+  //     console.info documents the choice so the host can spot a
+  //     missing `useStitcherWorklet` call before they go hunting
+  //     for "why is non-AR panorama capture not producing output".
+  //     AR-mode capture is unaffected either way — the AR-session
+  //     dispatch path fans out to BOTH first-party stitching AND
+  //     every host worklet independently.
   //
   //   - No host processor? → use `fpDriver.frameProcessor` which is
   //     the lib's internal worklet driving first-party stitching
   //     via `useFrameProcessorDriver`.  Default behaviour for the
   //     common "I just want panorama capture" case.
-  //
-  // The pre-v0.8.0 behaviour (host's prop silently ignored with
-  // a warning) is gone — Phase 5 plumbs the prop through.  The
-  // tradeoff is honestly documented in the CameraProps docstring.
   const hostFrameProcessorAcceptedWarnedRef = useRef(false);
   if (
     hostFrameProcessor != null
@@ -868,12 +883,13 @@ export function Camera(props: CameraProps): React.JSX.Element {
     // eslint-disable-next-line no-console
     console.info(
       '[react-native-image-stitcher] Host frameProcessor supplied — '
-      + 'non-AR mode will run YOUR worklet instead of the lib\'s '
-      + 'first-party stitching plugin (vc accepts only one frame '
-      + 'processor).  Non-AR panorama capture will not produce '
-      + 'stitched output until this prop is removed.  AR-mode '
-      + 'capture is unaffected (AR-session dispatch fans out to '
-      + 'both first-party and host worklets independently).',
+      + 'non-AR mode will run YOUR composed worklet.  If you want '
+      + 'first-party panorama stitching alongside your own logic, '
+      + 'call `useStitcherWorklet()` and invoke `stitcher.call(frame)` '
+      + 'from your worklet body (see `<Camera>` `frameProcessor` '
+      + 'JSDoc for the composition pattern).  AR-mode capture is '
+      + 'unaffected (AR-session dispatch fans out to both '
+      + 'first-party and host worklets independently).',
     );
   }
   // The Frame Processor worklet bound to vision-camera's Camera.

package/src/index.ts

@@ -226,6 +226,19 @@ export type {
   FrameProcessorDriverHandle,
 } from './stitching/useFrameProcessorDriver';
 
+// v0.11.0 — composable first-party stitching as a worklet function.
+// Hosts that want to COMPOSE their own per-frame logic with the
+// lib's stitching (instead of REPLACING it via the <Camera>
+// `frameProcessor` prop) call this hook + invoke `stitcher.call`
+// inside their own `useFrameProcessor` body.  See
+// `docs/host-app-integration.md` § Tier 3 for the full pattern.
+export { useStitcherWorklet } from './stitching/useStitcherWorklet';
+export type {
+  UseStitcherWorkletOptions,
+  StitcherWorkletHandle,
+  StitcherWorkletInput,
+} from './stitching/useStitcherWorklet';
+
 // ── Batch stitching ───────────────────────────────────────────────────
 // Feed a video file straight to OpenCV's cv::Stitcher, bypassing the
 // incremental pipeline.  Useful when you have content captured