react-native-image-stitcher 0.7.1 → 0.9.0

package/src/stitching/StitcherFrame.ts

@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * v0.8.0 — unified frame contract for the lib's worklet processor.
+ *
+ * Worklets registered via the v0.8.0 `useFrameProcessor` hook (also in
+ * this directory) receive a `StitcherFrame` regardless of capture mode.
+ * The lib-owned worklet runtime guarantees the same JS-visible shape
+ * whether the underlying source is a vision-camera `Frame` (non-AR
+ * mode, sourced from the FP plugin) or an ARKit `ARFrame` / ARCore
+ * `Frame` (AR mode, sourced from a lib-managed delegate that the AR
+ * worklet runtime drives).
+ *
+ * ## Why structural (NOT `extends Frame`)
+ *
+ * vision-camera's iOS `Frame` is `CMSampleBufferRef`-shaped; ARFrame's
+ * `capturedImage` (a `CVPixelBufferRef`) can be wrapped into one
+ * (Phase-0 audit confirmed the iOS path).  But vision-camera's
+ * **Android** `Frame` is `androidx.camera.core.ImageProxy`-coupled —
+ * ARCore does NOT produce `ImageProxy` instances.  Forcing
+ * `StitcherFrame extends Frame` would either (a) require reverse-
+ * engineering ImageProxy on Android (intractable + fragile), or
+ * (b) make the type asymmetric per platform.  Both are worse than
+ * making `StitcherFrame` a structural sibling type that vc Frames
+ * happen to satisfy (because vc Frames carry the same width / height /
+ * orientation / pixelFormat / timestamp / toArrayBuffer surface).
+ *
+ * The `__source: 'vc' | 'ar'` discriminator lets worklets gate on
+ * mode without a typeof / try-catch dance — e.g., skip work that
+ * needs AR tracking state when the source is `'vc'`.
+ *
+ * ## Buffer lifetime
+ *
+ * The underlying camera buffer (CMSampleBufferRef / ImageProxy /
+ * ARFrame.capturedImage) is valid only for the duration of the worklet
+ * call.  Worklets that need to retain frame data MUST copy
+ * synchronously inside the worklet body (via `toArrayBuffer()` or via
+ * a JPEG-encode frame-processor plugin).  Returning a reference and
+ * reading it later will read into freed memory.
+ */
+export interface StitcherFrame {
+  // ── vision-camera-shaped fields (structural compat) ─────────────
+  // Worklets written against a vc `Frame` work unchanged against a
+  // `StitcherFrame` (the fields below are a strict subset of vc
+  // Frame's JS-visible surface).
+
+  /** Pixel width of the camera image. */
+  width: number;
+
+  /** Pixel height of the camera image. */
+  height: number;
+
+  /**
+   * Pixel format identifier.  Both modes today emit `'yuv'` (NV12 on
+   * iOS, NV21 on Android).  Other vision-camera formats may appear
+   * in future releases.
+   *
+   * **`'unknown'` semantics:** the lib reached a code path that
+   * doesn't recognise the underlying camera buffer's pixel format
+   * (e.g., a future ARKit version emits BGRA when historically it
+   * only emitted NV12).  Worklets that depend on a known layout
+   * should treat `'unknown'` as "skip this frame".  `toArrayBuffer()`
+   * still returns bytes when the format is `'unknown'`, but the
+   * layout is undefined — the bytes are the underlying buffer's
+   * first plane and may not be interpretable.  When this happens
+   * the native side also emits an `os_log` / logcat warning.
+   */
+  pixelFormat: 'yuv' | 'rgb' | 'unknown';
+
+  /**
+   * Display orientation tag, matching vision-camera's
+   * `Frame.orientation`.
+   *
+   * **AR-mode limitation (v0.8.0):** AR-source frames return only
+   * the coarse two-value set `'landscape-right' | 'portrait'` (the
+   * lib reads `pose.imageWidth >= pose.imageHeight` as the
+   * discriminator since ARKit's `capturedImage` is always in the
+   * camera's native landscape-right orientation regardless of
+   * device pose).  Worklets that need to distinguish
+   * `landscape-left` (upside-down landscape) or
+   * `portrait-upside-down` should consult device-orientation sensors
+   * separately while running in AR mode.  Non-AR frames (vc source)
+   * return the full four-value set.  Fixing the AR side requires
+   * threading `UIDevice.current.orientation` through; deferred to
+   * v0.8.1+ unless a consumer hits it.
+   */
+  orientation:
+    | 'portrait'
+    | 'portrait-upside-down'
+    | 'landscape-left'
+    | 'landscape-right';
+
+  /**
+   * Monotonic timestamp in **nanoseconds** (matches vision-camera's
+   * `Frame.timestamp` convention).  Use timestamp deltas for
+   * inter-frame timing; the absolute value is implementation-defined
+   * and not comparable to `Date.now()`.
+   */
+  timestamp: number;
+
+  /**
+   * Copies the underlying pixel buffer into a JSI `ArrayBuffer`.
+   * Worklet-callable.  Allocates O(width × height × bytesPerPixel)
+   * each call — avoid in tight inner loops; prefer plugin-side
+   * processing where possible.
+   */
+  toArrayBuffer(): ArrayBuffer;
+
+  // ── Lib additions ─────────────────────────────────────────────
+
+  /**
+   * Camera pose at frame-capture time.  Always present.
+   *
+   * Rotation quaternion order is `(x, y, z, w)`; the lib uses
+   * `q = q_yaw * q_pitch * q_roll` throughout the engine + sensor
+   * fusion.  Same convention surfaced by the v0.7.0
+   * `AcceptedKeyframe.pose` field.
+   *
+   * Translation is metres in world coordinates.  Populated by AR
+   * mode (real ARKit / ARCore camera transform); undefined in
+   * non-AR mode (gyro provides only rotation — no spatial anchor).
+   */
+  pose: {
+    rotation: [number, number, number, number];
+    translation?: [number, number, number];
+  };
+
+  /**
+   * Discriminator for the frame source.  Worklets branch on this to
+   * gate AR-only field access without try/catch.  Standard TS
+   * discriminated-union pattern.
+   *
+   *   - `'vc'` — vision-camera Frame Processor (non-AR mode)
+   *   - `'ar'` — AR-session frame (AR mode); `arDepth` / `arAnchors` /
+   *     `arTrackingState` fields may be populated
+   */
+  source: 'vc' | 'ar';
+
+  // ── AR-only optional fields ───────────────────────────────────
+  // Always undefined in `__source === 'vc'` mode.
+
+  /**
+   * Depth data when available — AR mode + a device that supports
+   * the AR framework's depth API (iPhone Pro LiDAR; ARCore Depth
+   * API on supported Android devices).
+   *
+   * Resolution is typically lower than the camera image (e.g.,
+   * 256×192 on iPhone Pro LiDAR).  `confidenceMap` is per-pixel:
+   * `0` = low, `1` = medium, `2` = high confidence.  `Float32`
+   * depth in metres; `Uint8` confidence.
+   */
+  arDepth?: {
+    width: number;
+    height: number;
+    depthMap: ArrayBuffer;
+    confidenceMap?: ArrayBuffer;
+  };
+
+  /**
+   * Tracked AR anchors visible in this frame.  Empty array if AR
+   * is active but no anchors are tracked.  Undefined in non-AR mode.
+   */
+  arAnchors?: ARAnchor[];
+
+  /**
+   * AR tracking quality.  Worklets that should skip work when
+   * tracking is degraded check this.  Undefined in non-AR mode.
+   */
+  arTrackingState?: 'notAvailable' | 'limited' | 'normal';
+}
+
+/**
+ * v0.8.0 — public AR anchor type.  Subset of ARKit/ARCore anchor info
+ * exposed to JS worklets.  Extend with plane-extent / image-name
+ * fields as the JSI binding learns them.
+ */
+export interface ARAnchor {
+  /** Stable per-session anchor identifier. */
+  id: string;
+  /** Anchor kind.  `'point'` is Android (ARCore) only. */
+  type: 'plane' | 'image' | 'point';
+  /**
+   * 4×4 row-major transform from anchor space to world space.
+   * 16 numbers.
+   */
+  transform: number[];
+}
+
+/**
+ * v0.8.0 — worklet function signature for the unified frame processor.
+ *
+ * Must be a `'worklet'`-prefixed function (so it can run on the
+ * worklet runtime).  Receives a `StitcherFrame` per camera frame; the
+ * return value is ignored (use `runOnJS` / shared values to surface
+ * results back to the JS thread).
+ */
+export type StitcherFrameProcessor = (frame: StitcherFrame) => void;

package/src/stitching/StitcherWorkletRegistry.ts

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: Apache-2.0
+
+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;
+}
+
+class Registry {
+  private entries: StitcherWorkletEntry[] = [];
+  private 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: {
+    worklet: StitcherFrameProcessor;
+    isFirstParty?: boolean;
+  }): string {
+    const isFirstParty = opts.isFirstParty ?? false;
+    const id = isFirstParty
+      ? `fp-${this.nextHostCounter++}`
+      : `host-${this.nextHostCounter++}`;
+    const entry: StitcherWorkletEntry = {
+      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: string): void {
+    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(): readonly StitcherWorkletEntry[] {
+    return [...this.entries];
+  }
+
+  /**
+   * Total number of registered worklets (first-party + host).
+   * Useful for diagnostics + tests.
+   */
+  get count(): number {
+    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(): void {
+    this.entries = [];
+    this.nextHostCounter = 0;
+  }
+}
+
+/**
+ * Process-scope singleton.  Imported by `useFrameProcessor` (in
+ * this directory) + by the Phase 4b native-handoff code (TBD).
+ */
+export const StitcherWorkletRegistry = new Registry();

package/src/stitching/__tests__/StitcherWorkletRegistry.test.ts

@@ -0,0 +1,176 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit tests for the v0.8.0 Phase 4a `StitcherWorkletRegistry` singleton.
+ *
+ * The registry is the JS-side staging area for host worklets — the
+ * Phase 4b native handoff will read from it to fan out invocations on
+ * the AR runtime.  These tests pin the invariants the native handoff
+ * is going to rely on:
+ *
+ *   - Stable, unique IDs out of `register`.
+ *   - Registration order preserved within the host-entry partition.
+ *   - First-party entries always sort to the front of `getEntries`.
+ *   - `unregister` is a no-op for unknown IDs (no throw — the native
+ *     handoff may race a JS-side unregister with a frame in flight).
+ *   - `getEntries` returns a snapshot — mutating the returned array
+ *     can't corrupt registry state.
+ *   - `_resetForTests` returns the registry to a pristine state
+ *     (used by these tests; documented as test-only in the source).
+ */
+
+import { StitcherWorkletRegistry } from '../StitcherWorkletRegistry';
+import type { StitcherFrameProcessor } from '../StitcherFrame';
+
+// Fresh no-op worklet stubs.  These are NOT real worklets — they have
+// no `'worklet'` directive — but the registry doesn't care about
+// invocation, only about identity + ordering.
+const makeWorklet = (label: string): StitcherFrameProcessor => {
+  const fn = (_frame: unknown) => {
+    void label;
+  };
+  return fn as unknown as StitcherFrameProcessor;
+};
+
+describe('StitcherWorkletRegistry', () => {
+  beforeEach(() => {
+    StitcherWorkletRegistry._resetForTests();
+  });
+
+  describe('register', () => {
+    it('returns a non-empty string ID', () => {
+      const id = StitcherWorkletRegistry.register({ worklet: makeWorklet('a') });
+      expect(typeof id).toBe('string');
+      expect(id.length).toBeGreaterThan(0);
+    });
+
+    it('issues distinct IDs across calls', () => {
+      const id1 = StitcherWorkletRegistry.register({ worklet: makeWorklet('a') });
+      const id2 = StitcherWorkletRegistry.register({ worklet: makeWorklet('b') });
+      expect(id1).not.toBe(id2);
+    });
+
+    it('issues distinct IDs even for the same worklet identity', () => {
+      // Hosts that re-render and re-register without unregistering get
+      // a fresh slot — the hook itself handles cleanup via deps, but
+      // the registry treats each `register` as independent.
+      const w = makeWorklet('shared');
+      const id1 = StitcherWorkletRegistry.register({ worklet: w });
+      const id2 = StitcherWorkletRegistry.register({ worklet: w });
+      expect(id1).not.toBe(id2);
+      expect(StitcherWorkletRegistry.count).toBe(2);
+    });
+
+    it('host entries default to isFirstParty=false', () => {
+      StitcherWorkletRegistry.register({ worklet: makeWorklet('host') });
+      const [entry] = StitcherWorkletRegistry.getEntries();
+      expect(entry.isFirstParty).toBe(false);
+    });
+
+    it('first-party flag passes through to the entry', () => {
+      StitcherWorkletRegistry.register({
+        worklet: makeWorklet('fp'),
+        isFirstParty: true,
+      });
+      const [entry] = StitcherWorkletRegistry.getEntries();
+      expect(entry.isFirstParty).toBe(true);
+    });
+  });
+
+  describe('getEntries ordering', () => {
+    it('preserves host registration order when no first-party entries', () => {
+      const wa = makeWorklet('a');
+      const wb = makeWorklet('b');
+      const wc = makeWorklet('c');
+      StitcherWorkletRegistry.register({ worklet: wa });
+      StitcherWorkletRegistry.register({ worklet: wb });
+      StitcherWorkletRegistry.register({ worklet: wc });
+      const entries = StitcherWorkletRegistry.getEntries();
+      expect(entries.map((e) => e.worklet)).toEqual([wa, wb, wc]);
+    });
+
+    it('sorts first-party entries before host entries regardless of registration order', () => {
+      const host1 = makeWorklet('host1');
+      const fp1 = makeWorklet('fp1');
+      const host2 = makeWorklet('host2');
+      const fp2 = makeWorklet('fp2');
+      // Interleave registrations.
+      StitcherWorkletRegistry.register({ worklet: host1 });
+      StitcherWorkletRegistry.register({ worklet: fp1, isFirstParty: true });
+      StitcherWorkletRegistry.register({ worklet: host2 });
+      StitcherWorkletRegistry.register({ worklet: fp2, isFirstParty: true });
+      const entries = StitcherWorkletRegistry.getEntries();
+      // First-party block first (in registration order),
+      // then host block (in registration order).
+      expect(entries.map((e) => e.worklet)).toEqual([fp1, fp2, host1, host2]);
+    });
+
+    it('returns a snapshot — mutating the returned array does not affect the registry', () => {
+      StitcherWorkletRegistry.register({ worklet: makeWorklet('a') });
+      const entries = StitcherWorkletRegistry.getEntries();
+      // Cast away readonly so we can attempt a mutation.
+      (entries as unknown as unknown[]).push({} as never);
+      // Registry's own count is unchanged.
+      expect(StitcherWorkletRegistry.count).toBe(1);
+      expect(StitcherWorkletRegistry.getEntries()).toHaveLength(1);
+    });
+  });
+
+  describe('unregister', () => {
+    it('removes a previously-registered entry by ID', () => {
+      const id = StitcherWorkletRegistry.register({ worklet: makeWorklet('a') });
+      expect(StitcherWorkletRegistry.count).toBe(1);
+      StitcherWorkletRegistry.unregister(id);
+      expect(StitcherWorkletRegistry.count).toBe(0);
+    });
+
+    it('is a no-op for an unknown ID (no throw)', () => {
+      StitcherWorkletRegistry.register({ worklet: makeWorklet('a') });
+      expect(() => StitcherWorkletRegistry.unregister('host-9999')).not.toThrow();
+      expect(StitcherWorkletRegistry.count).toBe(1);
+    });
+
+    it('removes the right entry when multiple are registered', () => {
+      const id1 = StitcherWorkletRegistry.register({ worklet: makeWorklet('a') });
+      const id2 = StitcherWorkletRegistry.register({ worklet: makeWorklet('b') });
+      const id3 = StitcherWorkletRegistry.register({ worklet: makeWorklet('c') });
+      StitcherWorkletRegistry.unregister(id2);
+      const remainingIds = StitcherWorkletRegistry.getEntries().map((e) => e.id);
+      expect(remainingIds).toEqual([id1, id3]);
+    });
+
+    it('survives double-unregister of the same ID', () => {
+      const id = StitcherWorkletRegistry.register({ worklet: makeWorklet('a') });
+      StitcherWorkletRegistry.unregister(id);
+      expect(() => StitcherWorkletRegistry.unregister(id)).not.toThrow();
+      expect(StitcherWorkletRegistry.count).toBe(0);
+    });
+  });
+
+  describe('count', () => {
+    it('starts at 0 after reset', () => {
+      expect(StitcherWorkletRegistry.count).toBe(0);
+    });
+
+    it('reflects register/unregister deltas', () => {
+      expect(StitcherWorkletRegistry.count).toBe(0);
+      const id1 = StitcherWorkletRegistry.register({ worklet: makeWorklet('a') });
+      expect(StitcherWorkletRegistry.count).toBe(1);
+      StitcherWorkletRegistry.register({ worklet: makeWorklet('b') });
+      expect(StitcherWorkletRegistry.count).toBe(2);
+      StitcherWorkletRegistry.unregister(id1);
+      expect(StitcherWorkletRegistry.count).toBe(1);
+    });
+  });
+
+  describe('_resetForTests', () => {
+    it('clears all entries', () => {
+      StitcherWorkletRegistry.register({ worklet: makeWorklet('a') });
+      StitcherWorkletRegistry.register({ worklet: makeWorklet('b'), isFirstParty: true });
+      StitcherWorkletRegistry.register({ worklet: makeWorklet('c') });
+      expect(StitcherWorkletRegistry.count).toBe(3);
+      StitcherWorkletRegistry._resetForTests();
+      expect(StitcherWorkletRegistry.count).toBe(0);
+      expect(StitcherWorkletRegistry.getEntries()).toEqual([]);
+    });
+  });
+});

package/src/stitching/__tests__/ensureStitcherProxyInstalled.test.ts

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit tests for the v0.8.0 Phase 4b `ensureStitcherProxyInstalled`
+ * helper.  The native install path can't be exercised in jest (no
+ * JSI runtime), so these tests cover only the JS-side branches:
+ *
+ *   - Idempotency (second call short-circuits).
+ *   - "module missing" path returns false + warns once.
+ *   - "install returns false" path returns false + warns once.
+ *   - "install throws" path returns false + warns once.
+ *   - "install succeeds" path returns true + caches.
+ *
+ * NativeModules is stubbed via the jest mock at
+ * `jest.mocks/react-native.js`; per-test customization swaps in a
+ * scenario-specific module.
+ */
+
+import { NativeModules } from 'react-native';
+
+import {
+  _resetStitcherProxyInstallStateForTests,
+  ensureStitcherProxyInstalled,
+} from '../ensureStitcherProxyInstalled';
+
+type MutableGlobal = Record<string, unknown>;
+
+describe('ensureStitcherProxyInstalled', () => {
+  beforeEach(() => {
+    _resetStitcherProxyInstallStateForTests();
+    // Clear any previous __stitcherProxy from prior test cases so the
+    // module's "already installed" fast-path doesn't bypass our
+    // scenario-specific NativeModules stub.
+    delete (globalThis as MutableGlobal).__stitcherProxy;
+    // Wipe the NativeModules.StitcherJsiInstaller entry so each test
+    // starts with a clean slate (the mock module is a shared object
+    // across the whole test file).
+    (NativeModules as MutableGlobal).StitcherJsiInstaller = undefined;
+  });
+
+  it('returns false when the native module is missing', () => {
+    expect(ensureStitcherProxyInstalled()).toBe(false);
+  });
+
+  it('returns true when install() returns true', () => {
+    const install = jest.fn(() => true);
+    (NativeModules as MutableGlobal).StitcherJsiInstaller = { install };
+    expect(ensureStitcherProxyInstalled()).toBe(true);
+    expect(install).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns false when install() returns false', () => {
+    const install = jest.fn(() => false);
+    (NativeModules as MutableGlobal).StitcherJsiInstaller = { install };
+    expect(ensureStitcherProxyInstalled()).toBe(false);
+    expect(install).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns false when install() throws', () => {
+    const install = jest.fn(() => {
+      throw new Error('boom');
+    });
+    (NativeModules as MutableGlobal).StitcherJsiInstaller = { install };
+    expect(ensureStitcherProxyInstalled()).toBe(false);
+    expect(install).toHaveBeenCalledTimes(1);
+  });
+
+  it('is idempotent — second call short-circuits without re-invoking install()', () => {
+    const install = jest.fn(() => true);
+    (NativeModules as MutableGlobal).StitcherJsiInstaller = { install };
+    expect(ensureStitcherProxyInstalled()).toBe(true);
+    expect(ensureStitcherProxyInstalled()).toBe(true);
+    expect(install).toHaveBeenCalledTimes(1);
+  });
+
+  it('short-circuits if __stitcherProxy is already on globalThis (e.g., other consumer installed it first)', () => {
+    // Simulate a different SDK instance having installed the proxy.
+    (globalThis as MutableGlobal).__stitcherProxy = {
+      install: jest.fn(),
+      uninstall: jest.fn(),
+      count: jest.fn(() => 0),
+    };
+    const install = jest.fn();
+    (NativeModules as MutableGlobal).StitcherJsiInstaller = { install };
+    expect(ensureStitcherProxyInstalled()).toBe(true);
+    // We did NOT call our own native install — we accepted the
+    // already-installed proxy.
+    expect(install).not.toHaveBeenCalled();
+  });
+
+  it('treats `install: undefined` as a missing module (not a crash)', () => {
+    (NativeModules as MutableGlobal).StitcherJsiInstaller = {};
+    expect(ensureStitcherProxyInstalled()).toBe(false);
+  });
+});