react-native-image-stitcher 0.14.2 → 0.15.0

package/android/src/main/java/io/imagestitcher/rn/StitcherJsiInstallerModule.kt

@@ -1,103 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-package io.imagestitcher.rn
-
-import android.util.Log
-import com.facebook.react.bridge.ReactApplicationContext
-import com.facebook.react.bridge.ReactContextBaseJavaModule
-import com.facebook.react.bridge.ReactMethod
-
-/**
- * v0.8.0 Phase 4b.ii — Android-side JSI installer for the host
- * worklet proxy.  Mirror of iOS' `StitcherJsiInstaller`.
- *
- * The module exposes one synchronous method, `install()`, which JS
- * calls once at lib bootstrap (via the
- * `ensureStitcherProxyInstalled` helper in
- * `src/stitching/ensureStitcherProxyInstalled.ts`).  We reach into
- * the main JS runtime via `ReactApplicationContext.getJavaScriptContextHolder().get()`
- * — the canonical bridgeless-compatible accessor in modern RN
- * (worklets-core's `WorkletsModule` uses the same pattern, verified
- * working on RN 0.84.1 + new arch + Hermes).
- *
- * The native `nativeInstall(jsiRuntimeRef)` JNI then casts the long
- * back to a `jsi::Runtime*` and calls into the shared C++
- * `retailens::installStitcherProxy(runtime)` (in
- * `cpp/stitcher_proxy_jsi.{hpp,cpp}`).  Identical destination on
- * both platforms — `globalThis.__stitcherProxy` exposes the same
- * `install` / `uninstall` / `count` host functions.
- *
- * ## Returning `Boolean` (not `Promise`) from a sync method
- *
- * `isBlockingSynchronousMethod = true` + `Boolean` return is the
- * documented pattern for "I'm doing one-shot native setup that
- * needs to complete before the next JS line runs."  Same shape as
- * `WorkletsModule.install()`.
- *
- * ## What we DON'T do here (Phase 4b.ii follow-up)
- *
- * Phase 4b.ii's MVP installs the proxy ONLY.  Host worklets that
- * register through `__stitcherProxy.install` land in the native
- * `retailens::StitcherWorkletRegistry`.  Per-frame fan-out from
- * Android's `StitcherWorkletRuntime` is a separate piece of work
- * (Phase 4b.ii follow-up) — needs the Kotlin↔JNI bridge that
- * constructs a `StitcherFrameJsiHostObject` from an `ArImage` +
- * pose and posts it through a worklet runtime.  Until that lands,
- * Android-registered worklets behave exactly like iOS-registered
- * worklets BEFORE Phase 4b.i: they exist in the registry but
- * aren't invoked.
- *
- * The proxy install itself is still useful as a foundation —
- * verifies the JNI handshake works, exercises the bridgeless
- * runtime accessor, and gives us a `count()` smoke test for the
- * device verification step.
- */
-class StitcherJsiInstallerModule(
-    private val reactContext: ReactApplicationContext,
-) : ReactContextBaseJavaModule(reactContext) {
-    override fun getName(): String = NAME
-
-    @ReactMethod(isBlockingSynchronousMethod = true)
-    fun install(): Boolean {
-        return try {
-            // `getJavaScriptContextHolder().get()` returns a raw
-            // `jsi::Runtime*` boxed as `Long`.  Same accessor
-            // worklets-core's `WorkletsModule.install()` uses;
-            // documented to work in both legacy + bridgeless modes
-            // on RN 0.71+.
-            val holder = reactContext.javaScriptContextHolder
-            if (holder == null) {
-                Log.e(TAG, "getJavaScriptContextHolder() returned null; runtime unreachable")
-                return false
-            }
-            val runtimeRef = holder.get()
-            if (runtimeRef == 0L) {
-                Log.e(TAG, "JavaScriptContextHolder.get() returned 0; runtime not initialized yet")
-                return false
-            }
-            val ok = nativeInstall(runtimeRef)
-            if (!ok) {
-                Log.e(TAG, "nativeInstall(runtimeRef=$runtimeRef) returned false")
-            }
-            ok
-        } catch (t: Throwable) {
-            Log.e(TAG, "install() threw — falling back to JS-side registry", t)
-            false
-        }
-    }
-
-    private external fun nativeInstall(jsiRuntimeRef: Long): Boolean
-
-    companion object {
-        const val NAME = "StitcherJsiInstaller"
-        private const val TAG = "StitcherJsiInstaller"
-
-        init {
-            // The Phase 3a JNI shim (`libimage_stitcher.so`) absorbed
-            // the JSI-install JNI binding from Phase 4b.ii.  Loading
-            // it once is enough — Android's loader deduplicates,
-            // so even if `IncrementalStitcher.kt`'s init block
-            // already loaded the lib, calling again is a cheap no-op.
-            System.loadLibrary("image_stitcher")
-        }
-    }
-}

package/android/src/main/java/io/imagestitcher/rn/StitcherWorkletRuntime.kt

@@ -1,256 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-package io.imagestitcher.rn
-
-import android.os.HandlerThread
-import android.util.Log
-import java.util.concurrent.atomic.AtomicBoolean
-
-/**
- * v0.8.0 Phase 3b — Android twin of iOS' `RNSARWorkletRuntime`.
- * Owns the per-AR-frame worklet runtime + the thread it dispatches
- * on.  Symmetric API shape to the iOS class so the cross-platform
- * dispatch story (Phase 3c) lands in lockstep.
- *
- * ## Phase 3b scope (this commit)
- *
- * - Singleton accessor + lifecycle (installIfNeeded / isInstalled).
- * - Dedicated `HandlerThread` for worklet dispatch — keeps work off
- *   the GLSurfaceView GL render thread (audit caveat #4 from the
- *   Phase-0 audit).
- * - `dispatchFrame()` stub — Phase 3c will fill in:
- *     1. Build `StitcherFrameHostObject` from ARCore Frame + pose
- *        (via the shared C++ JSI host object now linked into
- *        `libimage_stitcher.so` post-Phase-3a).
- *     2. Run first-party stitching synchronously on the caller
- *        thread (`onDrawFrame`'s GL thread, today).
- *     3. If host worklets are registered, dispatch the host object
- *        onto this runtime's `HandlerThread` + invoke each worklet
- *        via JNI → `RNWorklet::WorkletInvoker::call`.
- *     4. Invalidate the host object after all worklets return.
- *
- * ## Worklet-runtime construction model
- *
- * Unlike iOS (where the lib's `.mm` directly `std::make_shared`s
- * a `RNWorklet::JsiWorkletContext`), Android can't construct the
- * context purely from native C++ without JNI plumbing.  Phase 3c
- * will choose between two paths:
- *
- *   - **Option A:** JS-side code calls
- *     `Worklets.createContext("stitcher.ar")` at AR-mode start;
- *     hands the resulting context pointer to this Kotlin class via
- *     a small JSI plugin.  Minimal new JNI.  **Phase 3b's
- *     HandlerThread becomes dead code** under this option — the
- *     JS-side `Worklets.createContext` picks its own thread.  We'd
- *     need to remove the HandlerThread + change `installIfNeeded`
- *     into a no-op until a `setContextHandle(Long)` setter lands.
- *   - **Option B:** Direct JNI binding to worklets-core's C++
- *     constructor.  More native code but no JS dependency at runtime.
- *     **Phase 3b's HandlerThread is exactly the right scaffold**
- *     under this option — its looper becomes the JsiWorkletContext's
- *     `workletCallInvoker` target.
- *
- * **Phase 3b assumption: Option B is the more likely path.**  The
- * scaffolding below (HandlerThread + serial dispatch) fits Option
- * B; if Phase 3c picks Option A instead, the HandlerThread becomes
- * unused and Phase 3c will refactor accordingly.
- *
- * @see [RNSARWorkletRuntime] iOS equivalent
- * @see docs/plans/handoff/2026-05-26-v0.8.0-phase-0-audit.md
- *      worklets-core API rationale (Audit 2: `JsiWorkletContext`).
- * @see docs/plans/handoff/2026-05-26-v0.8.0-phases-2-5-implementation-guide.md
- *      Phase 3c implementation plan.
- */
-object StitcherWorkletRuntime {
-    private const val TAG = "StitcherWorkletRuntime"
-
-    /// Single-flight install guard.  `compareAndSet` makes the
-    /// runtime construction race-safe across concurrent first-mount
-    /// calls from multiple `<Camera>` instances.
-    private val installed = AtomicBoolean(false)
-
-    /// Dedicated dispatch thread.  Constructed eagerly so we can
-    /// validate the thread starts cleanly during `installIfNeeded`.
-    /// Off the GLSurfaceView GL render thread (audit caveat #4)
-    /// + off the main thread.  Phase 3c will configure the worklet
-    /// context's `workletCallInvoker` to post onto this thread's
-    /// looper.
-    private val dispatchThread: HandlerThread by lazy {
-        HandlerThread("io.imagestitcher.ar-worklet-runtime").apply { start() }
-    }
-
-    /// Construct the underlying worklet context if not yet installed.
-    /// Idempotent — repeated calls are no-ops.
-    ///
-    /// Phase 3b: starts the dispatch thread; no JsiWorkletContext
-    /// construction yet (deferred to Phase 3c).
-    /// Phase 3c: also wires the JsiWorkletContext + binds it to the
-    /// dispatch thread's looper.
-    @JvmStatic
-    fun installIfNeeded() {
-        if (!installed.compareAndSet(false, true)) {
-            return
-        }
-        // Force the lazy `dispatchThread` to initialise.  If the
-        // OS denies thread creation (extreme memory pressure on a
-        // budget device), `HandlerThread.start()` won't throw but
-        // the looper won't be available — the Phase 3c dispatch
-        // logic will need to defend against that.  For Phase 3b
-        // we only care that this method returns without throwing.
-        //
-        // Log `Thread.id` (Java-side monotonic, always non-zero) —
-        // NOT `HandlerThread.threadId` (Linux tid set after first
-        // Looper-prepared message; reading from this caller thread
-        // immediately after .start() returns -1 until scheduled).
-        val javaThreadId = dispatchThread.id
-        Log.i(TAG, "installed runtime; dispatch java-thread id=$javaThreadId")
-    }
-
-    /// Diagnostics + tests.  Returns `true` after a successful
-    /// `installIfNeeded()`.
-    @JvmStatic
-    fun isInstalled(): Boolean = installed.get()
-
-    /// v0.8.0 Phase 3c — first-party stitching dispatch.  Invokes
-    /// the supplied block synchronously on the caller thread
-    /// (`onDrawFrame`'s GL render thread today).
-    ///
-    /// Phase 3c minimum-viable: this is the closure-based equivalent
-    /// of iOS' first-party callback.  The block is the original
-    /// `module.ingestFromARCameraView(...)` call site moved
-    /// verbatim into a lambda — no behaviour change, just an
-    /// indirection so Phase 4 can interpose host-worklet fanout
-    /// without touching the engine ingest path.
-    ///
-    /// **Why synchronous + on the caller thread:** the engine's
-    /// `ingestFromARCameraView` takes ownership of the ARCore
-    /// `Image`-derived NV21 buffer (via the v0.10.0 `TransferredNV21`
-    /// wrapper).  ARCore's `Image.close()` happens after this call
-    /// returns, so the consumer must finish reading the bytes before
-    /// we return — exactly what synchronous block invocation
-    /// provides.  Phase 4 will copy the buffer for off-thread
-    /// access in host worklets; Phase 3c keeps the sync contract.
-    ///
-    /// If `installIfNeeded()` hasn't been called yet, the block
-    /// still runs (no-op on the registry side).  Defensive — the
-    /// caller may call this method before `installIfNeeded` is
-    /// wired up.
-    @JvmStatic
-    fun runFirstParty(block: () -> Unit) {
-        // Synchronous invocation — Phase 4 will extend this to also
-        // post the registered host worklets onto `dispatchThread`.
-        // Not `inline`: Phase 4 will need to read `dispatchThread`
-        // (private) from inside this function body, and Kotlin's
-        // inline functions can't access private members from call
-        // sites outside the declaring class.  Per-frame lambda
-        // alloc is ~ns and the alternative (callers passing a
-        // method reference) doesn't materially change cost.
-        block()
-    }
-
-    /// v0.8.0 Phase 4b.iii — fan out one AR frame to every host
-    /// worklet registered in the shared C++ `StitcherWorkletRegistry`
-    /// (populated from JS via `__stitcherProxy.install(workletFn)`).
-    ///
-    /// Called from `RNSARCameraView.onDrawFrame` immediately after
-    /// `runFirstParty { ... }` returns, with the already-extracted
-    /// AR frame data (pose + NV21 bytes + dimensions + tracking
-    /// state).
-    ///
-    /// **Fast-path:** the native side queries the registry's count
-    /// FIRST and returns before copying any bytes when no host
-    /// worklets are registered.  In the common first-party-only
-    /// deployment, this method costs one JNI call + one C++ atomic
-    /// read per frame — negligible.
-    ///
-    /// **When host worklets ARE registered:** the JNI layer copies
-    /// the NV21 byte array into an owned C++ `std::vector` (so the
-    /// async dispatch can outlive ARCore's `Image.close()` scope),
-    /// builds a `StitcherFrameJsiHostObject`, and posts a lambda
-    /// onto worklets-core's default `JsiWorkletContext`'s worklet
-    /// thread.  The lambda iterates the registry's
-    /// `WorkletInvoker`s, calls each with the JSI host object as
-    /// its argument, and invalidates the host object after the
-    /// last invoker returns.  Per-worklet failure isolation: one
-    /// host worklet throwing does NOT stop the lib's stitching or
-    /// the other host worklets.
-    ///
-    /// **Threading:** this method returns synchronously on the
-    /// caller's thread.  The actual worklet invocations happen
-    /// asynchronously on the worklets-core thread; the caller does
-    /// NOT block on them.
-    ///
-    /// **Caller-thread contract:** the caller (`RNSARCameraView`'s
-    /// `onDrawFrame`) MUST have already invoked `runFirstParty`
-    /// before calling this method.  The first-party stitching
-    /// path holds the synchronous ARCore Image consumption
-    /// contract; the host-worklet dispatch does not.
-    ///
-    /// @param nv21Bytes      Pre-packed NV21 byte array.  COPIED
-    ///                       into a native owned buffer; caller can
-    ///                       release the reference after return.
-    /// @param width          Camera image width (pixels).
-    /// @param height         Camera image height (pixels).
-    /// @param qx,qy,qz,qw    Pose rotation quaternion (unit length).
-    /// @param tx,ty,tz       Pose translation (metres, world coords).
-    /// @param timestampNs    Frame timestamp in nanoseconds.
-    /// @param trackingState  One of "" / "notAvailable" / "limited"
-    ///                       / "normal".  Empty string ⇒ JS-side
-    ///                       `arTrackingState` is `undefined`.
-    @JvmStatic
-    fun dispatchToHostWorklets(
-        nv21Bytes: ByteArray,
-        width: Int,
-        height: Int,
-        qx: Double, qy: Double, qz: Double, qw: Double,
-        tx: Double, ty: Double, tz: Double,
-        timestampNs: Double,
-        trackingState: String,
-    ) {
-        if (!installed.get()) return
-        nativeDispatchToHostWorklets(
-            nv21Bytes, width, height,
-            qx, qy, qz, qw,
-            tx, ty, tz,
-            timestampNs, trackingState,
-        )
-    }
-
-    /// v0.8.0 Phase 4b.iii — number of registered host worklets.
-    /// Cheap (microsecond) call into the native registry.  Used by
-    /// `RNSARCameraView.onDrawFrame` to gate the per-frame
-    /// NV21-pack + dispatch path: when no worklets are registered
-    /// AND no capture is active, the entire `forwardToIncremental`
-    /// branch can be skipped, saving the ~3-5ms NV21 pack cost per
-    /// idle preview frame.
-    @JvmStatic
-    fun hasHostWorklets(): Boolean {
-        if (!installed.get()) return false
-        return nativeRegistryCount() > 0
-    }
-
-    @JvmStatic
-    private external fun nativeRegistryCount(): Int
-
-    /// JNI binding: `android/src/main/cpp/stitcher_jsi_install_jni.cpp`'s
-    /// `nativeDispatchToHostWorklets`.  Fast-path early-exit lives
-    /// inside the native function — see its docstring.
-    @JvmStatic
-    private external fun nativeDispatchToHostWorklets(
-        nv21Bytes: ByteArray,
-        width: Int,
-        height: Int,
-        qx: Double, qy: Double, qz: Double, qw: Double,
-        tx: Double, ty: Double, tz: Double,
-        timestampNs: Double,
-        trackingState: String,
-    )
-
-    init {
-        // The JSI install module (`StitcherJsiInstallerModule`)
-        // already loads `libimage_stitcher` at class load.  We
-        // load it again here defensively in case
-        // `StitcherWorkletRuntime` is referenced before the install
-        // module — `System.loadLibrary` is idempotent.
-        System.loadLibrary("image_stitcher")
-    }
-}

package/cpp/stitcher_frame_jsi.cpp

@@ -1,214 +0,0 @@
-// 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

@@ -1,108 +0,0 @@
-// 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