react-native-image-stitcher 0.7.1 → 0.9.0

package/cpp/stitcher_frame_jsi.cpp

@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// stitcher_frame_jsi.cpp — implementation of the shared C++ JSI
+// host object.  See stitcher_frame_jsi.hpp for class docs.
+
+#include "stitcher_frame_jsi.hpp"
+
+#include <string>
+#include <utility>
+
+namespace retailens {
+
+using facebook::jsi::Array;
+using facebook::jsi::Function;
+using facebook::jsi::HostFunctionType;
+using facebook::jsi::JSError;
+using facebook::jsi::Object;
+using facebook::jsi::PropNameID;
+using facebook::jsi::Runtime;
+using facebook::jsi::String;
+using facebook::jsi::Value;
+
+StitcherFrameJsiHostObject::StitcherFrameJsiHostObject(StitcherFrameData data)
+    : _data(std::move(data)), _isValid(true) {}
+
+void StitcherFrameJsiHostObject::invalidate() {
+  _isValid = false;
+  // Release the pixel reader immediately so the underlying camera
+  // buffer can be reclaimed.  ARKit's ARFrame uses a pooled
+  // CVPixelBuffer; holding past the dispatch scope causes
+  // back-pressure.  ARCore's ArImage must be explicitly released
+  // for the next frame's acquire to succeed.
+  _data.pixelReader.reset();
+}
+
+std::vector<PropNameID> StitcherFrameJsiHostObject::getPropertyNames(
+    Runtime& rt) {
+  std::vector<PropNameID> names;
+  names.push_back(PropNameID::forUtf8(rt, "isValid"));
+  if (!_isValid) return names;
+
+  names.push_back(PropNameID::forUtf8(rt, "width"));
+  names.push_back(PropNameID::forUtf8(rt, "height"));
+  names.push_back(PropNameID::forUtf8(rt, "pixelFormat"));
+  names.push_back(PropNameID::forUtf8(rt, "orientation"));
+  names.push_back(PropNameID::forUtf8(rt, "timestamp"));
+  names.push_back(PropNameID::forUtf8(rt, "pose"));
+  names.push_back(PropNameID::forUtf8(rt, "source"));
+  names.push_back(PropNameID::forUtf8(rt, "toArrayBuffer"));
+  if (!_data.arTrackingState.empty()) {
+    names.push_back(PropNameID::forUtf8(rt, "arTrackingState"));
+  }
+  return names;
+}
+
+Value StitcherFrameJsiHostObject::get(Runtime& rt,
+                                       const PropNameID& propName) {
+  const std::string name = propName.utf8(rt);
+
+  if (name == "isValid") {
+    return Value(_isValid);
+  }
+  // Invalidated host objects expose only `isValid` (returns false).
+  // Every other access throws — matches vc FrameHostObject's contract.
+  // Lets worklets that incorrectly retain a frame across dispatch
+  // boundaries fail loudly rather than read garbage.
+  if (!_isValid) {
+    throw JSError(rt,
+        "[StitcherFrame] cannot access property '" + name +
+        "' after host object was invalidated. "
+        "Frame data is only valid for the duration of the worklet call.");
+  }
+
+  if (name == "width") return Value(static_cast<double>(_data.width));
+  if (name == "height") return Value(static_cast<double>(_data.height));
+  if (name == "pixelFormat") return String::createFromUtf8(rt, _data.pixelFormat);
+  if (name == "orientation") return String::createFromUtf8(rt, _data.orientation);
+  if (name == "timestamp") return Value(_data.timestampNs);
+  if (name == "source") return String::createFromUtf8(rt, _data.source);
+
+  if (name == "pose") {
+    Object pose(rt);
+    Array rotation(rt, 4);
+    rotation.setValueAtIndex(rt, 0, Value(_data.qx));
+    rotation.setValueAtIndex(rt, 1, Value(_data.qy));
+    rotation.setValueAtIndex(rt, 2, Value(_data.qz));
+    rotation.setValueAtIndex(rt, 3, Value(_data.qw));
+    pose.setProperty(rt, "rotation", rotation);
+    if (_data.hasTranslation) {
+      Array translation(rt, 3);
+      translation.setValueAtIndex(rt, 0, Value(_data.tx));
+      translation.setValueAtIndex(rt, 1, Value(_data.ty));
+      translation.setValueAtIndex(rt, 2, Value(_data.tz));
+      pose.setProperty(rt, "translation", translation);
+    }
+    return pose;
+  }
+
+  if (name == "arTrackingState") {
+    if (_data.arTrackingState.empty()) return Value::undefined();
+    return String::createFromUtf8(rt, _data.arTrackingState);
+  }
+
+  if (name == "toArrayBuffer") {
+    // Capture a weak self so the lambda doesn't extend the host
+    // object's lifetime beyond what the runtime intended.  When the
+    // runtime releases its shared_ptr (after dispatch), the weak
+    // ref expires and toArrayBuffer() throws on next call.
+    auto weakSelf = std::weak_ptr<StitcherFrameJsiHostObject>(shared_from_this());
+    HostFunctionType fn = [weakSelf](Runtime& runtime,
+                                       const Value& thisVal,
+                                       const Value* args,
+                                       size_t count) -> Value {
+      auto self = weakSelf.lock();
+      if (!self || !self->_isValid || !self->_data.pixelReader) {
+        throw JSError(runtime,
+            "[StitcherFrame] toArrayBuffer() called on invalidated frame "
+            "(host object was released after the worklet dispatch returned)");
+      }
+      const std::size_t bufSize = self->_data.pixelReader->byteSize();
+
+      // Per-runtime ArrayBuffer cache.  Pattern from vision-camera's
+      // FrameHostObject.mm:124-149.  Without this, every per-frame
+      // worklet call to toArrayBuffer() allocates a fresh ~2MB
+      // vector (1920x1080 NV12 Y-plane) — ~60 MB/s of GC churn at
+      // 30 fps that defeats the point of having a worklet at all.
+      // Caching on `runtime.global()` is safe because (a) each
+      // worklet runtime has its own global, and (b) every call
+      // overwrites the cached buffer before returning, so there's
+      // no time-window for cross-worklet data leaks.
+      static constexpr const char* kCacheKey =
+          "__stitcherFrameArrayBufferCache";
+      auto global = runtime.global();
+      std::shared_ptr<OwningPixelBuffer> owning;
+
+      bool needsAlloc = true;
+      if (global.hasProperty(runtime, kCacheKey)) {
+        auto cached = global.getPropertyAsObject(runtime, kCacheKey);
+        if (cached.isArrayBuffer(runtime)) {
+          auto cachedBuffer = cached.getArrayBuffer(runtime);
+          // Hermes JSI exposes the underlying MutableBuffer via the
+          // shared_ptr the ArrayBuffer was constructed with — but
+          // there's no public getter once handed to JSI.  We retain
+          // a parallel shared_ptr below via a hidden global slot.
+          if (cachedBuffer.size(runtime) == bufSize) {
+            // Size matches — reuse.  Pull the parallel
+            // OwningPixelBuffer ref out of its hidden slot.
+            static constexpr const char* kRefKey =
+                "__stitcherFrameArrayBufferCacheRef";
+            if (global.hasProperty(runtime, kRefKey)) {
+              // The hidden ref is stored as a HostObject wrapping
+              // the shared_ptr; pull it back.  See alloc path below.
+              auto refObj = global.getPropertyAsObject(runtime, kRefKey);
+              if (refObj.isHostObject(runtime)) {
+                struct RefHolder : facebook::jsi::HostObject {
+                  std::shared_ptr<OwningPixelBuffer> buf;
+                  explicit RefHolder(std::shared_ptr<OwningPixelBuffer> b)
+                      : buf(std::move(b)) {}
+                };
+                auto holder =
+                    refObj.getHostObject<RefHolder>(runtime);
+                if (holder && holder->buf) {
+                  owning = holder->buf;
+                  needsAlloc = false;
+                }
+              }
+            }
+          }
+        }
+      }
+
+      if (needsAlloc) {
+        owning = std::make_shared<OwningPixelBuffer>(bufSize);
+        // Store the ArrayBuffer + a parallel ref-holder on global.
+        // The ArrayBuffer's MutableBuffer is the same `owning`; the
+        // ref-holder lets us pull `owning` back out on cache hits.
+        global.setProperty(runtime, kCacheKey,
+            facebook::jsi::ArrayBuffer(runtime, owning));
+        struct RefHolder : facebook::jsi::HostObject {
+          std::shared_ptr<OwningPixelBuffer> buf;
+          explicit RefHolder(std::shared_ptr<OwningPixelBuffer> b)
+              : buf(std::move(b)) {}
+        };
+        global.setProperty(runtime, "__stitcherFrameArrayBufferCacheRef",
+            facebook::jsi::Object::createFromHostObject(runtime,
+                std::make_shared<RefHolder>(owning)));
+      }
+
+      std::size_t written =
+          self->_data.pixelReader->copyTo(owning->bytes(), bufSize);
+      if (written == 0 && bufSize > 0) {
+        throw JSError(runtime,
+            "[StitcherFrame] toArrayBuffer() pixel copy failed "
+            "(reader returned 0 bytes — likely the underlying "
+            "camera buffer was NULL or unreadable; see native log)");
+      }
+
+      // Re-fetch the cached ArrayBuffer to return.  Cheap (just a
+      // property lookup); avoids constructing a new jsi::ArrayBuffer
+      // that wraps the same MutableBuffer (which would be wasteful).
+      return global.getPropertyAsObject(runtime, kCacheKey)
+          .getArrayBuffer(runtime);
+    };
+    return Function::createFromHostFunction(rt,
+        PropNameID::forUtf8(rt, "toArrayBuffer"), 0, fn);
+  }
+
+  // Unknown property — return undefined (matches JS object
+  // semantics).  Worklets accessing arDepth / arAnchors hit this
+  // path in v0.8.0 (stubbed to undefined; populated in v0.8.1+).
+  return Value::undefined();
+}
+
+}  // namespace retailens

package/cpp/stitcher_frame_jsi.hpp

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// stitcher_frame_jsi.hpp — shared C++ JSI host object for the v0.8.0
+// `StitcherFrame` contract.  Compiles on both iOS and Android; each
+// platform provides only the PixelBufferReader implementation and
+// the construction call site (Obj-C++ on iOS; JNI on Android).
+//
+// The JSI dispatch logic (`get` / `getPropertyNames`) is identical
+// across platforms — the host object exposes the same JS-visible
+// surface regardless of frame source, by design of the
+// `StitcherFrame` contract.
+
+#pragma once
+
+#include <jsi/jsi.h>
+
+#include <cstdint>
+#include <memory>
+#include <vector>
+
+#include "stitcher_frame_data.hpp"
+
+namespace retailens {
+
+/// Owning byte buffer that satisfies the `jsi::MutableBuffer`
+/// contract.  Backs the `ArrayBuffer` returned by
+/// `StitcherFrame.toArrayBuffer()`.
+///
+/// **Lifetime:** tied to the JSI ArrayBuffer's GC root.  The buffer
+/// persists until Hermes / JSC garbage-collects the ArrayBuffer
+/// (not deterministic with frame timing).  To avoid per-frame
+/// allocation churn (30 fps × 2 MB = ~60 MB/s in the AR-mode pan
+/// case), `toArrayBuffer()` caches a single instance per JSI
+/// runtime on `runtime.global()` and reuses it across frames —
+/// reallocating only when the requested size changes.  Pattern
+/// adopted from vision-camera's `FrameHostObject.mm:124-149`.
+class OwningPixelBuffer : public facebook::jsi::MutableBuffer {
+ public:
+  explicit OwningPixelBuffer(std::size_t sizeBytes)
+      : _storage(sizeBytes, 0) {}
+
+  // jsi::MutableBuffer interface
+  uint8_t* data() override { return _storage.data(); }
+  size_t size() const override { return _storage.size(); }
+
+  /// Direct accessor for the native side to memcpy into before
+  /// handing the buffer to JSI.  Not part of jsi::MutableBuffer.
+  uint8_t* bytes() { return _storage.data(); }
+
+ private:
+  std::vector<uint8_t> _storage;
+};
+
+/// v0.8.0 — JSI host object representing one `StitcherFrame`.  See
+/// `src/stitching/StitcherFrame.ts` for the JS-visible contract.
+///
+/// Construct on the worklet runtime's thread, hand to
+/// `jsi::Object::createFromHostObject`, dispatch to a registered
+/// worklet, then invalidate (typically immediately after dispatch
+/// returns — the underlying pixel buffer's lifetime is bound to
+/// the calling AR-session callback scope).
+class StitcherFrameJsiHostObject
+    : public facebook::jsi::HostObject,
+      public std::enable_shared_from_this<StitcherFrameJsiHostObject> {
+ public:
+  /// Factory.  ALWAYS use this — `shared_from_this()` (called inside
+  /// `get` for `toArrayBuffer`) requires the instance to be owned
+  /// by a `shared_ptr` from the moment of construction.  A raw
+  /// `new StitcherFrameJsiHostObject(...)` would throw
+  /// `std::bad_weak_ptr` on the first `toArrayBuffer()` JSI call.
+  ///
+  /// Private constructor + public factory enforces this at the
+  /// language level; callers can't accidentally construct without
+  /// `std::make_shared`.
+  static std::shared_ptr<StitcherFrameJsiHostObject> create(
+      StitcherFrameData data) {
+    // `std::make_shared` would require a public ctor; route through
+    // a tagged-dispatch private constructor instead.
+    struct EnableMakeShared : StitcherFrameJsiHostObject {
+      explicit EnableMakeShared(StitcherFrameData d)
+          : StitcherFrameJsiHostObject(std::move(d)) {}
+    };
+    return std::make_shared<EnableMakeShared>(std::move(data));
+  }
+
+  // jsi::HostObject interface
+  facebook::jsi::Value get(
+      facebook::jsi::Runtime& rt,
+      const facebook::jsi::PropNameID& name) override;
+  std::vector<facebook::jsi::PropNameID> getPropertyNames(
+      facebook::jsi::Runtime& rt) override;
+
+  /// Mark the host object's backing data as no longer accessible.
+  /// Subsequent JSI reads of valid-required properties throw.
+  /// Releases the pixel reader (and its underlying ARFrame /
+  /// ArImage retain) immediately.  Idempotent.
+  void invalidate();
+
+  bool isValid() const { return _isValid; }
+
+ private:
+  explicit StitcherFrameJsiHostObject(StitcherFrameData data);
+
+  StitcherFrameData _data;
+  bool _isValid;
+};
+
+}  // namespace retailens

package/cpp/stitcher_proxy_jsi.cpp

@@ -0,0 +1,109 @@
+// 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 <memory>
+#include <string>
+#include <vector>
+
+namespace retailens {
+
+namespace {
+
+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));
+    }
+
+    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"));
+    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));
+}
+
+}  // namespace retailens

package/cpp/stitcher_proxy_jsi.hpp

@@ -0,0 +1,46 @@
+// 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);
+
+}  // 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 "stitcher_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,
+                             StitcherFrameData 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.
+  // `StitcherFrameJsiHostObject::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 StitcherFrameData (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 = StitcherFrameJsiHostObject::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
+// `StitcherFrameData` 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 "stitcher_frame_data.hpp"
+
+#include <jsi/jsi.h>
+
+namespace RNWorklet {
+class JsiWorkletContext;
+}
+
+namespace retailens {
+
+/// Fan out a `StitcherFrameData` 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 `StitcherFrameJsiHostObject` (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,
+                             StitcherFrameData data);
+
+}  // namespace retailens