react-native-image-stitcher 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -16,6 +16,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.1] — 2026-05-28
+
+### Fixed — AR-mode composed worklets silently throw
+
+`useStitcherWorklet`'s `call(frame)` was invoking the vision-camera
+Frame Processor plugin on every frame regardless of mode.  In AR
+mode the frame is a `StitcherFrameHostObject` (no `__frame` JSI
+marker), so the vc plugin threw `getPropertyAsObject: property
+'__frame' is undefined`.  The throw was caught silently by
+`RNSARWorkletRuntime`'s per-worklet error isolation (logged to
+`os_log`, not surfaced to JS), causing any host code AFTER
+`stitcher.call(frame)` in the composed worklet body —
+`runOnJS` callbacks, `Worklets.createRunOnJS` dispatches, further
+host worklet logic — to silently never execute in AR mode.
+
+The hook's module docstring already promised AR mode would no-op
+("AR mode is unaffected — the AR-session dispatch path already
+composes natively"), but the code didn't enforce it.  v0.11.1 adds
+an early-return on `frame.source === 'ar'` in `useStitcherWorklet`'s
+worklet body.  AR stitching continues to run natively via
+`RNSARSession.swift`'s first-party callback path
+(`consumer.consumeFrame(arFrame, pose)` at line 510-511), which is
+the architectural contract for AR-mode stitching since v0.8.0.
+
+This bug was latent in v0.11.0 — surfaced by Test 2 of
+`docs/v0.11.0-manual-verification-checklist.md` on Ram's iPhone.
+
+Also added: `StitcherJsiInstaller::install` now eagerly initializes
+the worklets-core default `JsiWorkletContext` singleton during JSI
+bootstrap.  This is defense-in-depth — worklets-core's own `Worklets`
+module also initializes the default, but eager init from our
+installer makes `runOnJS` from AR-mode worklets robust to host-app
+import order (no dependency on worklets-core's `Worklets` module
+loading before our AR runtime constructs its context).
+
+### Added — Jest test for AR-source short-circuit
+
+New test file `src/stitching/__tests__/useStitcherWorklet.test.ts`
+pins the AR no-op contract.  5 new tests; full suite now 74/74 pass
+(was 69/69 in v0.11.0).
+
 ## [0.11.0] — 2026-05-28
 
 ### Added — `useStitcherWorklet` for non-AR composition

package/dist/stitching/useStitcherWorklet.js

@@ -223,6 +223,31 @@ function useStitcherWorklet(options = {}) {
         '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;

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.11.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/stitching/__tests__/useStitcherWorklet.test.ts

@@ -0,0 +1,202 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit tests for `useStitcherWorklet`.
+ *
+ * Coverage focus (v0.11.1):
+ *
+ *   - **AR-source short-circuit.**  The hook's docstring promises
+ *     that AR-mode hosts can call `stitcher.call(frame)` from a
+ *     single composed worklet body without per-mode branching; AR
+ *     stitching runs natively via the AR-side dispatcher.  Pre-
+ *     v0.11.1 the code didn't enforce that — `stitcher.call` would
+ *     invoke the vc Frame Processor plugin even on AR-source
+ *     frames, which throws `getPropertyAsObject: property '__frame'
+ *     is undefined` because AR frames are `StitcherFrameHostObject`
+ *     instances and don't carry vc's JSI `Frame` proxy marker.  The
+ *     throw was caught silently by the per-worklet error handler in
+ *     `RNSARWorkletRuntime.mm`, surfacing only as an `os_log` entry
+ *     — invisible to JS, which is why composed hosts saw their
+ *     post-`stitcher.call` lines (`fireFrameProcessorLog`,
+ *     `runOnJS` callbacks) silently never execute in AR mode.  Test
+ *     2 of `docs/v0.11.0-manual-verification-checklist.md`
+ *     reproduced this on Ram's iPhone.  This test pins the fix.
+ *
+ *   - **vc-source happy path.**  vc-source frames (and frames whose
+ *     `source` is `undefined` — which is what vc's raw `Frame`
+ *     looks like; the lib doesn't wrap vc frames in Phase 4a) MUST
+ *     still invoke the plugin.
+ *
+ * ## Why mock React's hooks directly
+ *
+ * The hook owns state via `useState` (the JSI plugin handle) and
+ * side effects via `useEffect` (plugin acquisition retry loop + gyro
+ * subscription).  The existing test pattern in this directory (see
+ * `useThrottledFrameProcessor.test.ts`) doesn't use a React renderer
+ * — instead it mocks the hooks the SUT calls so the SUT can be
+ * executed as a plain function.  Same approach here: we mock
+ * `useState` to return a pre-resolved plugin, `useCallback` to
+ * return the function as-is, `useEffect` as a no-op (we don't need
+ * the plugin-acquisition retry or gyro for the call-routing test).
+ */
+
+import type { StitcherFrame } from '../StitcherFrame';
+
+// ─── Mock vision-camera ──────────────────────────────────────────
+const pluginCallSpy = jest.fn();
+const fakePlugin = { call: pluginCallSpy } as unknown as object;
+
+jest.mock('react-native-vision-camera', () => ({
+  VisionCameraProxy: {
+    initFrameProcessorPlugin: jest.fn(() => fakePlugin),
+  },
+}));
+
+// ─── Mock react-native-worklets-core ─────────────────────────────
+jest.mock('react-native-worklets-core', () => ({
+  useSharedValue: (initial: number) => ({ value: initial }),
+}));
+
+// ─── Mock react-native-sensors ───────────────────────────────────
+jest.mock('react-native-sensors', () => ({
+  gyroscope: { subscribe: jest.fn(() => ({ unsubscribe: jest.fn() })) },
+  setUpdateIntervalForType: jest.fn(),
+  SensorTypes: { gyroscope: 'gyroscope' },
+}));
+
+// ─── Mock React's hooks so the SUT runs as a plain function ──────
+//
+// `useState` returns the plugin pre-resolved.  `useCallback` returns
+// the function identity (deps array ignored — we're not testing
+// re-render semantics).  `useEffect` is a no-op (no plugin retry,
+// no gyro subscription).  This lets us call the hook synchronously
+// and exercise the worklet body via the returned `call` function.
+jest.mock('react', () => {
+  const actual = jest.requireActual('react');
+  return {
+    ...actual,
+    useState: <T,>(initial: T): [T, (next: T) => void] => {
+      // For the [plugin, setPlugin] tuple: return the fake plugin
+      // immediately rather than starting at `null`.  This skips the
+      // plugin-acquisition retry path and lets `call` actually
+      // invoke `plugin.call(...)`.
+      const resolved = (initial === null ? fakePlugin : initial) as T;
+      return [resolved, () => {}];
+    },
+    useEffect: () => {},
+    useCallback: <T,>(fn: T): T => fn,
+  };
+});
+
+// SUT — imported AFTER mocks so the hook sees them.
+// eslint-disable-next-line import/first
+import { useStitcherWorklet } from '../useStitcherWorklet';
+
+describe('useStitcherWorklet', () => {
+  beforeEach(() => {
+    pluginCallSpy.mockReset();
+  });
+
+  describe('AR-source short-circuit (v0.11.1 fix)', () => {
+    it('does NOT invoke the vc plugin for AR-source frames', () => {
+      const { call } = useStitcherWorklet();
+      const arFrame: StitcherFrame = {
+        width: 1920,
+        height: 1080,
+        pixelFormat: 'yuv',
+        orientation: 'landscape-right',
+        timestamp: 0,
+        toArrayBuffer: () => new ArrayBuffer(0),
+        source: 'ar',
+        pose: { rotation: [0, 0, 0, 1] },
+      };
+      call(arFrame);
+      expect(pluginCallSpy).not.toHaveBeenCalled();
+    });
+
+    it('does NOT invoke the vc plugin for AR-source frames even when called repeatedly', () => {
+      const { call } = useStitcherWorklet();
+      const arFrame: StitcherFrame = {
+        width: 1920,
+        height: 1080,
+        pixelFormat: 'yuv',
+        orientation: 'landscape-right',
+        timestamp: 0,
+        toArrayBuffer: () => new ArrayBuffer(0),
+        source: 'ar',
+        pose: { rotation: [0, 0, 0, 1] },
+      };
+      for (let i = 0; i < 30; i++) call(arFrame);
+      expect(pluginCallSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('vc-source happy path', () => {
+    it('invokes the vc plugin for vc-source frames', () => {
+      const { call } = useStitcherWorklet();
+      const vcFrame: StitcherFrame = {
+        width: 1920,
+        height: 1080,
+        pixelFormat: 'yuv',
+        orientation: 'landscape-right',
+        timestamp: 0,
+        toArrayBuffer: () => new ArrayBuffer(0),
+        source: 'vc',
+        pose: { rotation: [0, 0, 0, 1] },
+      };
+      call(vcFrame);
+      expect(pluginCallSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('invokes the vc plugin for frames with undefined source (raw vc Frame)', () => {
+      // vc's raw `Frame` doesn't carry the `source` field — the lib's
+      // Phase 4a deferral means we don't wrap vc frames into
+      // `StitcherFrame`.  The AR-source check must treat undefined
+      // as "not AR" to preserve the non-AR worklet path.
+      const { call } = useStitcherWorklet();
+      const rawVcFrame = {
+        width: 1920,
+        height: 1080,
+        pixelFormat: 'yuv',
+        orientation: 'landscape-right',
+        timestamp: 0,
+        toArrayBuffer: () => new ArrayBuffer(0),
+        // `source` intentionally absent
+      } as unknown as StitcherFrame;
+      call(rawVcFrame);
+      expect(pluginCallSpy).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('plugin.call payload shape', () => {
+    it('passes the frame + a numeric-intrinsics params object', () => {
+      const { call } = useStitcherWorklet();
+      const vcFrame: StitcherFrame = {
+        width: 1920,
+        height: 1080,
+        pixelFormat: 'yuv',
+        orientation: 'landscape-right',
+        timestamp: 0,
+        toArrayBuffer: () => new ArrayBuffer(0),
+        source: 'vc',
+        pose: { rotation: [0, 0, 0, 1] },
+      };
+      call(vcFrame);
+      expect(pluginCallSpy).toHaveBeenCalledWith(
+        vcFrame,
+        expect.objectContaining({
+          tx: 0, ty: 0, tz: 0,
+          qx: expect.any(Number),
+          qy: expect.any(Number),
+          qz: expect.any(Number),
+          qw: expect.any(Number),
+          fx: expect.any(Number),
+          fy: expect.any(Number),
+          cx: 960,
+          cy: 540,
+          imageWidth: 1920,
+          imageHeight: 1080,
+        }),
+      );
+    });
+  });
+});

package/src/stitching/useStitcherWorklet.ts

@@ -336,6 +336,31 @@ export function useStitcherWorklet(
     '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 as StitcherFrame).source === 'ar') return;
+
     // Throttle (verbatim from useFrameProcessorDriver).
     sharedFrameCounter.value += 1;
     const N = sharedEvalEveryN.value;