react-native-image-stitcher 0.16.2 → 0.18.0

package/cpp/stitcher_proxy_jsi.cpp

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// stitcher_proxy_jsi.cpp — shared C++ JSI host object that exposes
+// the v0.8.0 `__stitcherProxy` API to JS.  See header for the
+// surface + threading rules.
+
+#include "stitcher_proxy_jsi.hpp"
+
+#include "stitcher_worklet_registry.hpp"
+
+#include <atomic>
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace retailens {
+
+namespace {
+
+// AR-metadata extraction toggles (see header).  Atomic: written on the
+// JS thread via __stitcherProxy.setExtractionConfig, read on the AR
+// delegate / GL thread by the platform extraction.  Default all false.
+std::atomic<bool> g_extractDepth{false};
+std::atomic<bool> g_extractAnchors{false};
+std::atomic<bool> g_extractMesh{false};
+
+class StitcherProxyHostObject : public facebook::jsi::HostObject {
+ public:
+  facebook::jsi::Value get(facebook::jsi::Runtime& rt,
+                            const facebook::jsi::PropNameID& propName) override {
+    using facebook::jsi::Function;
+    using facebook::jsi::JSError;
+    using facebook::jsi::PropNameID;
+    using facebook::jsi::String;
+    using facebook::jsi::Value;
+
+    const std::string name = propName.utf8(rt);
+
+    if (name == "install") {
+      // install(workletFn) → string ID.  The host function captures
+      // nothing; the registry is a process-scope singleton.
+      auto fn = [](facebook::jsi::Runtime& runtime,
+                   const Value& /*thisVal*/, const Value* args,
+                   size_t count) -> Value {
+        if (count < 1) {
+          throw JSError(runtime,
+              "[StitcherProxy] install() requires 1 argument (worklet "
+              "function); got 0");
+        }
+        if (!args[0].isObject() ||
+            !args[0].getObject(runtime).isFunction(runtime)) {
+          throw JSError(runtime,
+              "[StitcherProxy] install() argument must be a function "
+              "decorated with 'worklet'");
+        }
+        // The WorkletInvoker ctor extracts the worklet metadata
+        // (`__workletHash` etc.) and throws if absent.  Propagate
+        // to JS so misuse fails loudly.
+        std::string id =
+            StitcherWorkletRegistry::shared().install(runtime, args[0]);
+        return String::createFromUtf8(runtime, id);
+      };
+      return Function::createFromHostFunction(
+          rt, PropNameID::forUtf8(rt, "install"), 1, std::move(fn));
+    }
+
+    if (name == "uninstall") {
+      auto fn = [](facebook::jsi::Runtime& runtime,
+                   const Value& /*thisVal*/, const Value* args,
+                   size_t count) -> Value {
+        if (count < 1 || !args[0].isString()) {
+          // No throw — match the JS-side registry's permissive
+          // uninstall semantics; missing/bad ID is a no-op.
+          return Value::undefined();
+        }
+        std::string id = args[0].getString(runtime).utf8(runtime);
+        StitcherWorkletRegistry::shared().uninstall(id);
+        return Value::undefined();
+      };
+      return Function::createFromHostFunction(
+          rt, PropNameID::forUtf8(rt, "uninstall"), 1, std::move(fn));
+    }
+
+    if (name == "count") {
+      auto fn = [](facebook::jsi::Runtime& runtime,
+                   const Value& /*thisVal*/, const Value* /*args*/,
+                   size_t /*count*/) -> Value {
+        return Value(static_cast<double>(
+            StitcherWorkletRegistry::shared().count()));
+      };
+      return Function::createFromHostFunction(
+          rt, PropNameID::forUtf8(rt, "count"), 0, std::move(fn));
+    }
+
+    if (name == "setExtractionConfig") {
+      // setExtractionConfig(depth, anchors, mesh) — three booleans gating
+      // the platform AR extraction.  Missing/non-bool args default false.
+      auto fn = [](facebook::jsi::Runtime& runtime, const Value& /*thisVal*/,
+                   const Value* args, size_t count) -> Value {
+        g_extractDepth.store(count > 0 && args[0].isBool() && args[0].getBool());
+        g_extractAnchors.store(count > 1 && args[1].isBool() &&
+                               args[1].getBool());
+        g_extractMesh.store(count > 2 && args[2].isBool() && args[2].getBool());
+        return Value::undefined();
+      };
+      return Function::createFromHostFunction(
+          rt, PropNameID::forUtf8(rt, "setExtractionConfig"), 3, std::move(fn));
+    }
+
+    return Value::undefined();
+  }
+
+  std::vector<facebook::jsi::PropNameID> getPropertyNames(
+      facebook::jsi::Runtime& rt) override {
+    std::vector<facebook::jsi::PropNameID> names;
+    names.push_back(facebook::jsi::PropNameID::forUtf8(rt, "install"));
+    names.push_back(facebook::jsi::PropNameID::forUtf8(rt, "uninstall"));
+    names.push_back(facebook::jsi::PropNameID::forUtf8(rt, "count"));
+    names.push_back(
+        facebook::jsi::PropNameID::forUtf8(rt, "setExtractionConfig"));
+    return names;
+  }
+};
+
+}  // namespace
+
+void installStitcherProxy(facebook::jsi::Runtime& runtime) {
+  auto proxy = std::make_shared<StitcherProxyHostObject>();
+  runtime.global().setProperty(
+      runtime, "__stitcherProxy",
+      facebook::jsi::Object::createFromHostObject(runtime, proxy));
+}
+
+ExtractionConfig getExtractionConfig() {
+  return ExtractionConfig{g_extractDepth.load(std::memory_order_relaxed),
+                          g_extractAnchors.load(std::memory_order_relaxed),
+                          g_extractMesh.load(std::memory_order_relaxed)};
+}
+
+}  // namespace retailens

package/cpp/stitcher_proxy_jsi.hpp

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// stitcher_proxy_jsi.hpp — shared C++ JSI host object that's exposed
+// as `globalThis.__stitcherProxy` on the main JS runtime.
+//
+// Originally inlined as an anonymous-namespace class in iOS'
+// `StitcherJsiInstaller.mm` (v0.8.0 Phase 4b.i).  Phase 4b.ii lifts
+// it into shared C++ so 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).
+//
+// Platform-specific code (Obj-C++ on iOS, JNI on Android) only
+// owns the bootstrap: get a handle to the main JS runtime, then
+// call `retailens::installStitcherProxy(runtime)`.
+//
+// ## Surface
+//
+//   __stitcherProxy.install(workletFn)  →  string ID
+//   __stitcherProxy.uninstall(id)       →  undefined
+//   __stitcherProxy.count()             →  number  (diagnostic)
+//
+// `install` wraps the worklet into a `RNWorklet::WorkletInvoker`
+// and stores it in the process-scope C++
+// `retailens::StitcherWorkletRegistry`.  The AR worklet runtime
+// (iOS' `RNSARWorkletRuntime`, Android's `StitcherWorkletRuntime`)
+// reads from that registry to fan out per-frame invocations.
+
+#pragma once
+
+#include <jsi/jsi.h>
+
+namespace retailens {
+
+/// Install `globalThis.__stitcherProxy` on the supplied runtime.
+/// Idempotent — re-installing overwrites the existing global with
+/// a fresh host object; the underlying `StitcherWorkletRegistry`
+/// state is unaffected.
+///
+/// Thread: must be called from a thread that owns `runtime`.
+/// Typically called once at lib bootstrap from a synchronous JS
+/// bridge method (iOS: `RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD`;
+/// Android: `@ReactMethod(isBlockingSynchronousMethod = true)`).
+void installStitcherProxy(facebook::jsi::Runtime& runtime);
+
+/// Per-frame AR-metadata extraction toggles.  Set from JS via
+/// `__stitcherProxy.setExtractionConfig(depth, anchors, mesh)` (driven by
+/// the `<Camera>` enableDepth/enableAnchors/enableMesh props); read by the
+/// platform AR extraction to skip costly work when off.  Defaults: all
+/// false — zero arDepth/arAnchors/mesh cost until a host opts in (the
+/// always-cheap pose/tracking/pixels are unaffected).
+struct ExtractionConfig {
+  bool depth = false;
+  bool anchors = false;
+  bool mesh = false;
+};
+
+/// Thread-safe snapshot of the current extraction config.  Written on the
+/// JS thread (via the proxy), read on the AR delegate / GL thread.
+ExtractionConfig getExtractionConfig();
+
+}  // namespace retailens

package/cpp/stitcher_worklet_dispatch.cpp

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// stitcher_worklet_dispatch.cpp — implementation of the v0.8.0
+// Phase 4b.iii per-frame fan-out helper.  See header for contract.
+
+#include "stitcher_worklet_dispatch.hpp"
+
+#include "camera_frame_jsi.hpp"
+#include "stitcher_worklet_registry.hpp"
+
+#include <react-native-worklets-core/WKTJsiWorklet.h>
+#include <react-native-worklets-core/WKTJsiWorkletContext.h>
+
+#include <exception>
+#include <memory>
+#include <utility>
+#include <vector>
+
+#if defined(__ANDROID__)
+#include <android/log.h>
+#define DISPATCH_LOG_ERROR(...) \
+  __android_log_print(ANDROID_LOG_ERROR, "StitcherWorkletDispatch", __VA_ARGS__)
+#else
+// iOS path uses `os_log` from its caller (RNSARWorkletRuntime.mm);
+// this shared helper isn't invoked from iOS in v0.8.0.  Fall back
+// to fprintf for any non-Android build that picks this up.
+#include <cstdio>
+#define DISPATCH_LOG_ERROR(...) std::fprintf(stderr, __VA_ARGS__)
+#endif
+
+namespace retailens {
+
+void dispatchToHostWorklets(RNWorklet::JsiWorkletContext* context,
+                             CameraFrameData data) {
+  // Fast-path early-exit when no host worklets are registered.
+  // The Android caller (`StitcherWorkletRuntime.dispatchToHostWorklets`)
+  // already runs in a hot per-frame loop; saving the host-object
+  // alloc + dispatch hop on every frame is meaningful — typical
+  // first-party-only deployments will hit this path.
+  auto invokers = StitcherWorkletRegistry::shared().snapshot();
+  if (invokers.empty()) {
+    return;
+  }
+
+  if (context == nullptr) {
+    DISPATCH_LOG_ERROR(
+        "dispatchToHostWorklets: context is null; "
+        "did Worklets.install() run on the JS side?");
+    return;
+  }
+
+  // Build the JSI host object on the worklet thread (inside the
+  // lambda) so JSI access happens on the target runtime.
+  // `CameraFrameJsiHostObject::create` uses the `make_shared`-via-
+  // factory pattern (required by `shared_from_this()` inside the
+  // `toArrayBuffer` lambda); see its header.
+  //
+  // Capture `data` by-move so the CameraFrameData (including the
+  // pixel reader's shared_ptr) lives until the lambda runs.
+  // Capture `invokers` by-move as well.
+  context->invokeOnWorkletThread(
+      [invokers = std::move(invokers), data = std::move(data)](
+          RNWorklet::JsiWorkletContext* /*ctx*/,
+          facebook::jsi::Runtime& rt) mutable {
+        auto hostObj = CameraFrameJsiHostObject::create(std::move(data));
+        facebook::jsi::Object frameJsi =
+            facebook::jsi::Object::createFromHostObject(rt, hostObj);
+        facebook::jsi::Value frameVal(rt, frameJsi);
+
+        for (const auto& entry : invokers) {
+          if (!entry.invoker) continue;
+          try {
+            entry.invoker->call(rt, facebook::jsi::Value::undefined(),
+                                 &frameVal, 1);
+          } catch (const facebook::jsi::JSError& jsErr) {
+            // Per-worklet failure isolation: one host worklet
+            // throwing must NOT stop the lib's own path or other
+            // host worklets.  Log + continue.  Same three-level
+            // catch hierarchy iOS' `RNSARWorkletRuntime` uses.
+            DISPATCH_LOG_ERROR(
+                "host worklet '%s' threw JS error: %s",
+                entry.id.c_str(), jsErr.what());
+          } catch (const std::exception& e) {
+            DISPATCH_LOG_ERROR(
+                "host worklet '%s' threw native exception: %s",
+                entry.id.c_str(), e.what());
+          } catch (...) {
+            DISPATCH_LOG_ERROR(
+                "host worklet '%s' threw unknown exception",
+                entry.id.c_str());
+          }
+        }
+
+        // Invalidate after all worklets finish.  Releases the
+        // PixelBufferReader's shared_ptr, which (when its refcount
+        // drops to 0) drops the underlying buffer — for Android
+        // that's the std::vector of copied NV21 bytes; for iOS it
+        // would be the CFBridgingRetain'd ARFrame.
+        hostObj->invalidate();
+      });
+}
+
+}  // namespace retailens

package/cpp/stitcher_worklet_dispatch.hpp

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// stitcher_worklet_dispatch.hpp — shared C++ helper that fans out a
+// `CameraFrameData` to every host worklet registered in the
+// process-scope `retailens::StitcherWorkletRegistry`.
+//
+// v0.8.0 Phase 4b.iii — used by Android's per-frame fan-out path
+// (`StitcherWorkletRuntime.dispatchToHostWorklets` → JNI binding →
+// this function).  Designed to be platform-neutral so iOS' inline
+// dispatch in `RNSARWorkletRuntime.mm` could refactor onto this
+// helper in a later cleanup pass.
+//
+// ## Threading
+//
+// `dispatchToHostWorklets` is safe to call from ANY thread.  It
+// posts a lambda onto `context`'s worklet thread via
+// `JsiWorkletContext::invokeOnWorkletThread`.  The caller's thread
+// returns immediately (async); the lambda runs later on the
+// worklet thread.
+//
+// `data` is moved into the lambda — including the
+// `std::shared_ptr<PixelBufferReader>` which owns the pixel bytes.
+// The reader (and any underlying buffer it holds) lives until the
+// dispatch lambda completes + the resulting jsi::Object is GC'd by
+// the worklet runtime.
+
+#pragma once
+
+#include "camera_frame_data.hpp"
+
+#include <jsi/jsi.h>
+
+namespace RNWorklet {
+class JsiWorkletContext;
+}
+
+namespace retailens {
+
+/// Fan out a `CameraFrameData` to every registered host worklet.
+///
+/// Behaviour:
+///
+///   1. Fast-path early-exit when `StitcherWorkletRegistry::shared()`
+///      is empty.  No host object is constructed; the caller's
+///      thread returns immediately.
+///   2. Otherwise, the function snapshots the registry, constructs
+///      a `CameraFrameJsiHostObject` (deferred until inside the
+///      worklet-thread lambda so JSI access happens on the
+///      target runtime), and dispatches via
+///      `context->invokeOnWorkletThread(...)`.
+///   3. Each registered `RNWorklet::WorkletInvoker` is called with
+///      the host object as its single argument.  Per-worklet failure
+///      isolation: exceptions thrown by one invoker do NOT stop
+///      the next invoker (each call is try/catch'd).
+///   4. After all invokers return, the host object is invalidated;
+///      its underlying `PixelBufferReader` is released so the
+///      caller-provided buffer (NV21 bytes / CVPixelBuffer / etc.)
+///      can be reclaimed.
+///
+/// @param context  Worklet runtime to dispatch on.  On Android this
+///                 is typically `RNWorklet::JsiWorkletContext::
+///                 getDefaultInstance()` (worklets-core's default,
+///                 set up by `Worklets.install()`).  iOS uses its
+///                 own context (`RNSARWorkletRuntime::_ctx`).
+///                 MUST be non-null and initialized.
+/// @param data     Frame data + pixel reader.  Moved into the
+///                 worklet-thread lambda.
+void dispatchToHostWorklets(RNWorklet::JsiWorkletContext* context,
+                             CameraFrameData data);
+
+}  // namespace retailens

package/cpp/stitcher_worklet_registry.cpp

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// stitcher_worklet_registry.cpp — implementation of the v0.8.0
+// Phase 4b native worklet registry.  See header for the public
+// contract + threading rules.
+
+#include "stitcher_worklet_registry.hpp"
+
+// Cross-platform worklets-core header include.  On iOS the
+// CocoaPods setup publishes worklets-core headers via
+// `HEADER_SEARCH_PATHS` at the root of `Pods/Headers/Public/`,
+// so `<WKTJsiWorklet.h>` works.  On Android the prefab puts
+// headers under a `react-native-worklets-core/` subdirectory of
+// the include path (matches the prefab name).  The angled
+// namespace-prefixed include works on BOTH — `<x/y.h>` resolves
+// to `Pods/Headers/Public/x/y.h` on iOS (CocoaPods auto-creates
+// symlinked subdirs per pod) and to `build/headers/.../x/y.h` on
+// Android.  Pattern lifted from vc's
+// `node_modules/react-native-vision-camera/android/src/main/cpp/`.
+#include <react-native-worklets-core/WKTJsiWorklet.h>
+
+#include <algorithm>
+#include <sstream>
+
+namespace retailens {
+
+StitcherWorkletRegistry& StitcherWorkletRegistry::shared() {
+  static StitcherWorkletRegistry s_instance;
+  return s_instance;
+}
+
+std::string StitcherWorkletRegistry::install(
+    facebook::jsi::Runtime& mainRuntime,
+    const facebook::jsi::Value& workletValue) {
+  // Construct the invoker outside the lock — the WorkletInvoker
+  // constructor calls into worklets-core which acquires its own
+  // locks; nesting our lock around that would invite a deadlock if
+  // worklets-core ever called back into our code synchronously.
+  auto invoker = std::make_shared<RNWorklet::WorkletInvoker>(
+      mainRuntime, workletValue);
+
+  std::lock_guard<std::mutex> lock(_mutex);
+  std::ostringstream idStream;
+  idStream << "host-" << _nextId++;
+  std::string id = idStream.str();
+  _entries.push_back({id, std::move(invoker)});
+  return id;
+}
+
+void StitcherWorkletRegistry::uninstall(const std::string& id) {
+  std::lock_guard<std::mutex> lock(_mutex);
+  // erase-remove with a predicate (single-pass O(n) — n is tiny in
+  // practice, typically 0-3).
+  _entries.erase(
+      std::remove_if(_entries.begin(), _entries.end(),
+                     [&id](const StitcherWorkletEntry& e) {
+                       return e.id == id;
+                     }),
+      _entries.end());
+}
+
+std::vector<StitcherWorkletEntry> StitcherWorkletRegistry::snapshot() {
+  std::lock_guard<std::mutex> lock(_mutex);
+  // Copy the vector — entries hold shared_ptrs so this is O(n)
+  // refcount bumps, no deep copies.  Returning by value lets the
+  // caller iterate without holding the lock.
+  return _entries;
+}
+
+std::size_t StitcherWorkletRegistry::count() {
+  std::lock_guard<std::mutex> lock(_mutex);
+  return _entries.size();
+}
+
+void StitcherWorkletRegistry::_resetForTests() {
+  std::lock_guard<std::mutex> lock(_mutex);
+  _entries.clear();
+  _nextId = 0;
+}
+
+std::string StitcherWorkletRegistry::_installEntryForTests(
+    std::shared_ptr<RNWorklet::WorkletInvoker> invoker) {
+  std::lock_guard<std::mutex> lock(_mutex);
+  std::ostringstream idStream;
+  idStream << "host-" << _nextId++;
+  std::string id = idStream.str();
+  _entries.push_back({id, std::move(invoker)});
+  return id;
+}
+
+}  // namespace retailens

package/cpp/stitcher_worklet_registry.hpp

@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// stitcher_worklet_registry.hpp — process-scope native registry of
+// host-supplied worklets (v0.8.0 Phase 4b).
+//
+// ## What this is
+//
+// The native-side counterpart to the JS-side `StitcherWorkletRegistry`
+// singleton (`src/stitching/StitcherWorkletRegistry.ts`).  When the
+// public `useFrameProcessor` hook is mounted from JS, it calls into a
+// JSI installable (`globalThis.__stitcherProxy.install(workletFn)`)
+// that wraps the worklet's JSI value into a
+// `RNWorklet::WorkletInvoker` and stores it here.  Unmount calls
+// `__stitcherProxy.uninstall(id)` which removes the entry.
+//
+// The AR worklet runtime's per-frame dispatch (`RNSARWorkletRuntime::
+// dispatchFrame:pose:` on iOS) reads from this registry to fan out
+// invocations across all registered host worklets.  The vc-mode
+// path (non-AR) does NOT touch this registry — vision-camera owns
+// the Frame Processor runtime in that mode and our public hook
+// passes the worklet through to vc unchanged.
+//
+// ## Threading
+//
+// `install` / `uninstall` are called from the main JS thread
+// (`useFrameProcessor`'s `useEffect` body).
+//
+// `snapshot` is called from the AR session callback thread (the
+// caller thread of `RNSARWorkletRuntime::dispatchFrame:pose:`).  The
+// snapshot returns shared_ptrs, so even if `uninstall` races on the
+// JS thread between the snapshot and the worklet runtime's
+// invocation, the WorkletInvoker stays alive until the caller drops
+// the shared_ptr.  WorkletInvoker itself does NOT need its caller
+// to live on a particular thread — the `call` method takes the
+// target `jsi::Runtime&` as an argument, so callers from any
+// thread can invoke it on any runtime they own.
+//
+// Mutation is serialised through `_mutex` (std::mutex).  Reads via
+// `snapshot` lock briefly to copy the entry vector; that's microseconds
+// at most (registry typically has 0-3 entries).  No worklet invocation
+// happens under the lock.
+//
+// ## Lifetime
+//
+// The registry is a `static`-local singleton, constructed on first
+// `shared()` call (function-static init = thread-safe per the C++11
+// memory model).  It outlives every JS / native runtime in the
+// process.  Entries are only added by `install` and only removed by
+// `uninstall` — no GC, no weak refs.  Hosts that bypass the
+// `useFrameProcessor` hook and call `install` directly without ever
+// calling `uninstall` leak entries (matches the JS-side singleton's
+// contract).
+//
+// ## Why a singleton (not per-runtime / per-AR-session)
+//
+// The AR worklet runtime (`RNSARWorkletRuntime` / `StitcherWorkletRuntime`)
+// is itself a process-scope singleton.  The hook lifecycle is
+// per-component-mount.  Registering against a per-AR-session registry
+// would mean re-registering each time AR mode starts — but the host
+// worklet's identity hasn't changed.  Process-scope = "registry
+// matches the host's mental model of `useFrameProcessor` semantics".
+
+#pragma once
+
+#include <jsi/jsi.h>
+
+#include <memory>
+#include <mutex>
+#include <string>
+#include <utility>
+#include <vector>
+
+// Forward-declare to avoid pulling the whole worklets-core header
+// into every translation unit that just needs to hold an invoker
+// pointer.  The .cpp includes the full header.
+namespace RNWorklet {
+class WorkletInvoker;
+}
+
+namespace retailens {
+
+/// One registered host worklet.  Public so callers iterating via
+/// `snapshot` can read both the ID and the invoker.
+struct StitcherWorkletEntry {
+  std::string id;
+  std::shared_ptr<RNWorklet::WorkletInvoker> invoker;
+};
+
+class StitcherWorkletRegistry {
+ public:
+  /// Process-scope singleton.  Thread-safe lazy init via C++11
+  /// function-static.
+  static StitcherWorkletRegistry& shared();
+
+  /// Install a host worklet.  Wraps the JSI value (the worklet's
+  /// `'worklet'`-decorated function from the main JS runtime) into
+  /// a `WorkletInvoker` and stores it.  Returns a stable string ID
+  /// the caller passes to `uninstall`.
+  ///
+  /// Thread: must be called from a thread that owns `mainRuntime`
+  /// (typically the main JS thread).  The wrapped `WorkletInvoker`
+  /// can then be invoked from any thread on any runtime via
+  /// `call(rt, ...)`.
+  std::string install(facebook::jsi::Runtime& mainRuntime,
+                       const facebook::jsi::Value& workletValue);
+
+  /// Remove a previously-installed entry by ID.  No-op for unknown
+  /// IDs (matches the JS-side `StitcherWorkletRegistry` semantics).
+  void uninstall(const std::string& id);
+
+  /// Snapshot the current entries.  The returned vector holds
+  /// shared_ptrs to `WorkletInvoker`; mutations against the
+  /// registry after `snapshot` returns do not affect the snapshot.
+  /// Callers iterate without holding the registry lock.
+  std::vector<StitcherWorkletEntry> snapshot();
+
+  /// Current entry count.  Used by `dispatchFrame:` for the
+  /// fast-path early-exit (no fan-out cost when no host worklets
+  /// are registered).
+  std::size_t count();
+
+  /// Test-only — clear all entries.  Used by C++ unit tests; not
+  /// exposed through the JSI surface.
+  void _resetForTests();
+
+  /// Test-only — install a pre-constructed entry directly, bypassing
+  /// the JSI runtime path.  Mirrors `install` but accepts an already-
+  /// constructed (or null) `WorkletInvoker` so tests can exercise
+  /// `count`/`snapshot`/`uninstall`/thread-safety without standing
+  /// up a full JSI runtime + worklets-core stack.  Tests typically
+  /// pass `nullptr` — the registry never dereferences the pointer.
+  /// Not exposed through the JSI surface.
+  std::string _installEntryForTests(
+      std::shared_ptr<RNWorklet::WorkletInvoker> invoker);
+
+ private:
+  StitcherWorkletRegistry() = default;
+  StitcherWorkletRegistry(const StitcherWorkletRegistry&) = delete;
+  StitcherWorkletRegistry& operator=(const StitcherWorkletRegistry&) = delete;
+
+  std::mutex _mutex;
+  std::vector<StitcherWorkletEntry> _entries;
+  int _nextId = 0;
+};
+
+}  // namespace retailens