react-native-image-stitcher 0.7.1 → 0.8.0

package/ios/Sources/RNImageStitcher/StitcherJsiInstaller.mm

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// StitcherJsiInstaller.mm — implementation.  Installs
+// `globalThis.__stitcherProxy` on the main JS runtime.
+//
+// ## Why a host object rather than two globalThis functions
+//
+// We could install `__stitcherProxy_install` + `__stitcherProxy_uninstall`
+// directly on `globalThis`.  Wrapping them in a host object is
+// slightly more code but:
+//   - Namespaces the proxy under a single global property
+//     (easier to feature-detect; one `if (globalThis.__stitcherProxy)`
+//     instead of two).
+//   - Matches vc's pattern (`global.VisionCameraProxy`), so future
+//     readers recognise the shape.
+//   - Keeps room to grow (e.g., add `__stitcherProxy.snapshot()` for
+//     diagnostics) without polluting globalThis further.
+
+#import "StitcherJsiInstaller.h"
+
+#import <Foundation/Foundation.h>
+#import <React/RCTBridge.h>
+#import <React/RCTBridge+Private.h>
+#import <React/RCTUtils.h>
+#import <os/log.h>
+
+#include <jsi/jsi.h>
+
+#include "stitcher_proxy_jsi.hpp"
+
+using namespace facebook;
+
+// The host object class + install logic moved to shared C++ in
+// `cpp/stitcher_proxy_jsi.{hpp,cpp}` (v0.8.0 Phase 4b.ii).  The
+// Android JNI installer reuses the same `install` / `uninstall` /
+// `count` host functions verbatim — the JSI dispatch is identical
+// across platforms (matches the StitcherFrame host object's design).
+
+#pragma mark - RN module
+
+@implementation StitcherJsiInstaller
+
+// RN injects `_bridge` at module init (legacy bridge → RCTBridge*;
+// bridgeless / new arch → RCTBridgeProxy*, which forwards `runtime`
+// access via NSProxy `forwardInvocation:`).  Using the injected
+// `_bridge` instead of `[RCTBridge currentBridge]` is the
+// bridgeless-compatible idiom — `currentBridge` is nil under new
+// arch.  Pattern lifted from `react-native-worklets-core/ios/Worklets.mm`.
+@synthesize bridge = _bridge;
+
+RCT_EXPORT_MODULE()
+
++ (BOOL)requiresMainQueueSetup {
+  return YES;
+}
+
+- (void)setBridge:(RCTBridge*)bridge {
+  _bridge = bridge;
+}
+
+// Synchronous install method.  JS calls this once at lib bootstrap
+// to install the global proxy on the main JS runtime.  Returns
+// `@YES` on success or `@NO` if the JSI runtime wasn't reachable
+// (remote debug mode pre-Hermes; bridge not yet ready; etc.).
+//
+// `RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD` is the documented
+// pattern for "run native code synchronously on the JS thread to
+// install JSI bindings."  Same pattern worklets-core + vision-camera
+// use for their installs.
+//
+// **Bridgeless mode:** `_bridge` is an `RCTBridgeProxy` (NSProxy
+// subclass) that forwards `-runtime` / `-jsCallInvoker` invocations
+// to the underlying RCTHost-backed runtime.  The `(RCTCxxBridge*)`
+// cast is a no-op at runtime (NSProxy ignores static type) but
+// keeps the Obj-C compiler happy about property access.
+RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(install) {
+  if (_bridge == nil) {
+    os_log_error(OS_LOG_DEFAULT,
+        "[StitcherJsiInstaller] _bridge is nil; the module was "
+        "instantiated without bridge injection.  Cannot install "
+        "__stitcherProxy.");
+    return @NO;
+  }
+
+  RCTCxxBridge* cxxBridge = (RCTCxxBridge*)_bridge;
+  if (cxxBridge.runtime == nullptr) {
+    os_log_error(OS_LOG_DEFAULT,
+        "[StitcherJsiInstaller] _bridge.runtime is nullptr; the JS "
+        "runtime hasn't been initialized yet OR remote debugger is "
+        "attached.  Cannot install __stitcherProxy.");
+    return @NO;
+  }
+
+  jsi::Runtime& runtime = *(jsi::Runtime*)cxxBridge.runtime;
+  retailens::installStitcherProxy(runtime);
+
+  os_log_info(OS_LOG_DEFAULT,
+      "[StitcherJsiInstaller] installed globalThis.__stitcherProxy "
+      "on main JS runtime.");
+  return @YES;
+}
+
+@end

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "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",

package/src/camera/Camera.tsx

@@ -294,21 +294,71 @@ export interface CameraProps {
   onError?: (err: CameraError) => void;
 
   /**
-   * Optional vision-camera frame processor.  Only attached to the
-   * non-AR preview (AR mode uses ARCameraView, which doesn't expose
-   * a worklet seam).  Build the worklet on the host side with
-   * `useFrameProcessor` from `react-native-vision-camera`.
+   * Optional host-supplied vision-camera frame processor.
    *
-   * Introduced for F8 (FrameProcessor port) — see
-   * `docs/f8-frame-processor-plan.md`.
+   * ## When to set this prop
    *
-   * The SDK installs its own frame processor via
-   * `useFrameProcessorDriver`.  Setting this prop is ignored with
-   * a one-time `console.warn` — supplying a host worklet would
-   * race with the SDK's pixel-buffer feed.  Either remove the prop
-   * or fork the SDK if you genuinely need a custom worklet.
+   * v0.8.0+ canonical answer: use the lib's own `useFrameProcessor`
+   * hook, NOT `react-native-vision-camera`'s.  The lib's hook:
    *
-   * AR mode is irrelevant: vision-camera's Camera isn't mounted.
+   *   - **AR mode**: auto-registers the worklet in the native
+   *     `__stitcherProxy` registry; the AR session's per-frame
+   *     dispatch fans out to it alongside the lib's first-party
+   *     stitching.  No prop wiring needed — just mount the hook
+   *     anywhere in the tree.
+   *   - **Non-AR mode**: returns a vc processor object that this
+   *     prop accepts.  Wiring it through enables the host's
+   *     worklet to fire on vc's Frame Processor runtime.
+   *
+   * ```tsx
+   * import { Camera, useFrameProcessor, type StitcherFrame }
+   *   from 'react-native-image-stitcher';
+   *
+   * function MyScreen() {
+   *   const fp = useFrameProcessor((frame: StitcherFrame) => {
+   *     'worklet';
+   *     // ...
+   *   }, []);
+   *   return <Camera frameProcessor={fp} ... />;
+   * }
+   * ```
+   *
+   * ## Non-AR mode tradeoff (HONEST)
+   *
+   * 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.
+   *
+   * 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.
+   *
+   * 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.
+   *
+   * ## AR mode behaviour
+   *
+   * In AR mode (`defaultCaptureSource="ar"` or runtime-toggled),
+   * vc's `<Camera>` isn't mounted; this prop has no effect.
+   * Host worklets registered via the lib's `useFrameProcessor`
+   * fire automatically through the AR-session dispatch path
+   * (iOS Phase 4b.i / Android Phase 4b.iii).
+   *
+   * ## Backwards compatibility
+   *
+   * The pre-v0.8.0 behaviour (warn + ignore) is preserved when the
+   * supplied processor is recognisably from
+   * `react-native-vision-camera`'s `useFrameProcessor` directly
+   * (no `__stitcherFrame` marker).  Hosts should migrate to the
+   * lib's `useFrameProcessor` to benefit from AR-mode dispatch.
    *
    * (v0.5 had a `legacyDriver` escape hatch that routed back to
    * `useIncrementalJSDriver`.  That hook + prop were removed in
@@ -791,29 +841,44 @@ export function Camera(props: CameraProps): React.JSX.Element {
   // eslint-disable-next-line react-hooks/exhaustive-deps
   useEffect(() => () => { fpDriver.stop(); }, []);
 
-  // One-shot deprecation warning when the host supplies their own
-  // `frameProcessor` prop.  Two worklets racing on the same
-  // producer thread would corrupt the engine's workQueue ordering,
-  // so the SDK's own worklet wins and the host's is silently
-  // ignored.  (v0.5 had a `legacyDriver` opt-out for hosts that
-  // wanted to route around the SDK driver; that was removed in
-  // v0.6 along with `useIncrementalJSDriver`.)
-  const hostFrameProcessorIgnoredWarnedRef = useRef(false);
+  // v0.8.0 Phase 5 — 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.
+  //
+  //   - 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
-    && !hostFrameProcessorIgnoredWarnedRef.current
+    && !hostFrameProcessorAcceptedWarnedRef.current
   ) {
-    hostFrameProcessorIgnoredWarnedRef.current = true;
+    hostFrameProcessorAcceptedWarnedRef.current = true;
     // eslint-disable-next-line no-console
-    console.warn(
-      '[react-native-image-stitcher] The `frameProcessor` prop on '
-      + '<Camera> is ignored — the SDK installs its own worklet '
-      + 'via useFrameProcessorDriver.  Remove the prop, or fork '
-      + 'the SDK if you genuinely need a custom worklet.',
+    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).',
     );
   }
   // The Frame Processor worklet bound to vision-camera's Camera.
-  const effectiveFrameProcessor = fpDriver.frameProcessor;
+  // Host's wins if supplied; lib's internal driver otherwise.
+  const effectiveFrameProcessor = hostFrameProcessor ?? fpDriver.frameProcessor;
 
   // ── Subscribe to engine state for live keyframe thumbs ──────────
   useEffect(() => {

package/src/index.ts

@@ -182,6 +182,22 @@ export { useIncrementalStitcher } from './stitching/useIncrementalStitcher';
 // caveat).  Foundation for plugin-pattern host features (OCR per
 // keyframe, packet detection, server-side analysis, etc.).
 export { useKeyframeStream } from './stitching/useKeyframeStream';
+// v0.8.0 — unified frame contract for the worklet processor.  Same
+// JS-visible shape regardless of capture mode (AR vs non-AR).
+export type {
+  StitcherFrame,
+  StitcherFrameProcessor,
+  ARAnchor,
+} from './stitching/StitcherFrame';
+// v0.8.0 Phase 4a — public host-worklet hook.  Hosts that want a
+// per-frame callback (OCR overlay, packet detection, ML inference)
+// use this to attach a `'worklet'`-prefixed function that fires
+// on the camera producer thread.  Non-AR mode is fully wired
+// today via vision-camera passthrough; AR-mode dispatch is
+// API-stable but registration-only until Phase 4b lands the
+// cross-runtime handoff (the AR runtime iterating the registry).
+// See the hook's docstring + StitcherFrame.ts for the contract.
+export { useFrameProcessor } from './stitching/useFrameProcessor';
 // vision-camera Frame Processor driver for non-AR captures.  As
 // of v0.6 the only non-AR driver exported (the legacy
 // `useIncrementalJSDriver` was removed; was deprecated in v0.5).

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();