react-native-image-stitcher 0.16.2 → 0.18.0

package/src/stitching/ensureStitcherProxyInstalled.ts

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import { NativeModules } from 'react-native';
+
+/**
+ * v0.8.0 Phase 4b — one-shot installer that asks the native side
+ * to install `globalThis.__stitcherProxy` on the main JS runtime.
+ *
+ * ## When this runs
+ *
+ * The first call to `useFrameProcessor` triggers this.  Idempotent:
+ * once the global is installed, subsequent calls short-circuit.
+ *
+ * ## What it does
+ *
+ * Calls into the platform-native `StitcherJsiInstaller` RN module
+ * which is registered with a `RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(install)`
+ * on iOS (see `ios/Sources/RNImageStitcher/StitcherJsiInstaller.mm`)
+ * and — Phase 4b.ii — an analogous Kotlin TurboModule on Android.
+ *
+ * The native module reaches into the main JS runtime via
+ * `RCTCxxBridge.runtime` (iOS) / the equivalent Android JSI access
+ * pattern and installs a host object on `globalThis.__stitcherProxy`
+ * exposing `install(workletFn)` / `uninstall(id)` / `count()`.
+ *
+ * ## Failure modes (and what happens then)
+ *
+ * 1. **Module not registered** (Android in Phase 4b.i; old iOS
+ *    builds without the new pod files).  `NativeModules
+ *    .StitcherJsiInstaller` is `undefined`.  This function returns
+ *    `false` and the hook falls back to the JS-side
+ *    `StitcherWorkletRegistry` — host worklets are registered
+ *    on the JS side but never fan out to AR mode.  No crash, no
+ *    regression vs. Phase 4a.
+ *
+ * 2. **JSI runtime unreachable** (e.g., remote debug mode).  The
+ *    sync method returns `false`.  Same JS-side-registry fallback.
+ *
+ * 3. **Native install succeeds but global not yet visible.**
+ *    The native call is SYNCHRONOUS (`BLOCKING_SYNCHRONOUS_METHOD`),
+ *    so by the time the function returns the global is installed.
+ *    No race here.
+ *
+ * ## Why a separate module
+ *
+ * The install method is a one-time runtime bootstrap, not a
+ * per-call API.  Putting it on its own RN module (vs. on the
+ * existing `StitcherBridge` / `IncrementalStitcherBridge`) keeps
+ * the responsibility surface narrow and the failure mode easy
+ * to diagnose ("`__stitcherProxy` not installed" → check
+ * `StitcherJsiInstaller` module registration first).
+ */
+
+interface StitcherJsiInstallerModule {
+  install(): boolean;
+}
+
+/**
+ * `__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(): boolean {
+  return typeof __DEV__ !== 'undefined' && __DEV__;
+}
+
+let installed = false;
+
+export function ensureStitcherProxyInstalled(): boolean {
+  if (installed) return true;
+  // Already installed by an earlier hook mount.  Cheap fast-path.
+  if (typeof (globalThis as { __stitcherProxy?: unknown }).__stitcherProxy !== 'undefined') {
+    installed = true;
+    return true;
+  }
+
+  const mod = (NativeModules as { StitcherJsiInstaller?: StitcherJsiInstallerModule })
+    .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`.
+ */
+export function _resetStitcherProxyInstallStateForTests(): void {
+  installed = false;
+  warnedAboutMissingModule = false;
+  warnedAboutFailedInstall = false;
+}

package/src/stitching/useStitcherWorklet.ts

@@ -126,18 +126,18 @@ import type {
   FrameProcessorPlugin,
 } from 'react-native-vision-camera';
 
-import type { StitcherFrame } from './StitcherFrame';
+import type { CameraFrame } from './CameraFrame';
 
 /**
  * Frames the lib's stitching worklet accepts.  Accepting either a
  * vc `Frame` (what the host's `useFrameProcessor` body sees) or the
- * lib's `StitcherFrame` (what the lib's `useFrameProcessor` body
+ * lib's `CameraFrame` (what the lib's `useFrameProcessor` body
  * sees) keeps the same `useStitcherWorklet` usable from both kinds
  * of host worklet bodies without a cast on the call site.  The
  * worklet only reads `width` / `height`; the rest of the frame
  * object is forwarded verbatim to the native plugin.
  */
-export type StitcherWorkletInput = Frame | StitcherFrame;
+export type StitcherWorkletInput = Frame | CameraFrame;
 
 
 export interface UseStitcherWorkletOptions {
@@ -173,7 +173,7 @@ export interface UseStitcherWorkletOptions {
 
 export interface StitcherWorkletHandle {
   /**
-   * Worklet function: pass a `StitcherFrame` to perform one frame of
+   * Worklet function: pass a `CameraFrame` to perform one frame of
    * the lib's first-party stitching (throttle + pose synthesis +
    * native plugin call).  Safe to call from inside another
    * `'worklet'`-prefixed function (this is the canonical
@@ -341,7 +341,7 @@ export function useStitcherWorklet(
     // 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
+    // because AR frames are `CameraFrameHostObject` 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
@@ -353,13 +353,13 @@ export function useStitcherWorklet(
     // hook (the AR-side stitching path runs natively, independent
     // of the composed worklet body).
     //
-    // The `(frame as StitcherFrame).source` cast is safe: vc
+    // The `(frame as CameraFrame).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;
+    // does — see `CameraFrameHostObject.mm`) get short-circuited.
+    if ((frame as CameraFrame).source === 'ar') return;
 
     // Throttle (verbatim from useFrameProcessorDriver).
     sharedFrameCounter.value += 1;
@@ -388,7 +388,7 @@ export function useStitcherWorklet(
     const fy = h * sharedFyNumerator.value;
 
     // vc's `plugin.call` is typed against vc's `Frame`.  The worklet
-    // accepts the union (`Frame | StitcherFrame`); cast through
+    // accepts the union (`Frame | CameraFrame`); cast through
     // `unknown` because the union doesn't satisfy vc's interface
     // even though structurally both members do.
     plugin.call(frame as unknown as Frame, {