react-native-image-stitcher 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -16,6 +16,184 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] — 2026-05-27
+
+### Added — `useFrameProcessor` hook for host worklets
+
+Hosts can now attach a `'worklet'`-prefixed function that fires on
+every AR (and non-AR) capture frame, alongside the lib's own
+first-party stitching.  Use case: real-time OCR, packet detection,
+ML inference, custom telemetry — anything that wants per-frame
+pixel access in a worklet runtime.
+
+```tsx
+import { useFrameProcessor, type StitcherFrame }
+  from 'react-native-image-stitcher';
+
+const fp = useFrameProcessor((frame: StitcherFrame) => {
+  'worklet';
+  // frame.toArrayBuffer(), frame.pose, frame.source ('ar' | 'vc'), …
+}, []);
+```
+
+**AR mode** (iPhone via ARKit, Android via ARCore): worklets fire
+on every AR frame at the device's native rate (~30 Hz on A35,
+~60 Hz on iPhone 16 Pro).  Auto-registered into a process-scope
+native registry via `globalThis.__stitcherProxy.install(workletFn)`.
+The AR-session dispatch path fans out to both the lib's first-party
+stitching AND every registered host worklet, with **per-worklet
+failure isolation** (one host worklet throwing does NOT break
+others or the lib's stitching).
+
+**Non-AR mode** (vision-camera): pass the hook's return through
+`<Camera frameProcessor={fp}>` to enable.  Honest tradeoff: vc's
+`<Camera>` accepts ONE processor, so supplying a host processor
+displaces the lib's first-party stitching in non-AR mode.  Hosts
+that want both running concurrently should use AR mode (which
+natively composes both).  Composition for non-AR is tracked as
+v0.9+.
+
+### Added — `StitcherFrame` contract
+
+Unified frame shape across AR and non-AR modes (`src/stitching/
+StitcherFrame.ts`):
+
+  - `width` / `height` / `pixelFormat` / `orientation` / `timestamp`
+    / `toArrayBuffer()` — vc-shape parity
+  - `pose: { rotation: [x,y,z,w], translation?: [x,y,z] }` — always
+    present in AR mode; rotation-only in non-AR
+  - `source: 'ar' | 'vc'` discriminator for safe AR-field access
+  - `arDepth?`, `arAnchors?`, `arTrackingState?` — populated in AR
+    mode on supported devices
+
+### Added — JSI proxy host object
+
+`globalThis.__stitcherProxy` installed on lib bootstrap (iOS:
+`StitcherJsiInstaller` RN module via `RCTBridgeProxy.runtime` in
+bridgeless mode; Android: `StitcherJsiInstallerModule` via
+`ReactApplicationContext.getJavaScriptContextHolder()`).  Exposes
+`install` / `uninstall` / `count` host functions backed by a
+shared C++ `retailens::StitcherWorkletRegistry` (process-scope,
+mutex-serialised, snapshot-isolated).
+
+### Changed — AR-mode dispatch architecture
+
+Internal-only refactor (strict additive BC for hosts that don't
+use `useFrameProcessor`):
+
+  - **iOS**: `ARSessionDelegate.session(_:didUpdate:)` now routes
+    through `RNSARWorkletRuntime.dispatchFrame:pose:` instead of
+    directly invoking the engine.  First-party callback (Phase 3c)
+    runs synchronously on the caller thread (preserves ARKit's
+    pool-reuse contract); host worklet fan-out (Phase 4b.i)
+    dispatches asynchronously onto a dedicated worklets-core
+    context.
+
+  - **Android**: `RNSARCameraView.onDrawFrame` now wraps the
+    existing `module.ingestFromARCameraView(...)` call in
+    `StitcherWorkletRuntime.runFirstParty { ... }` (Phase 3c) and
+    follows with `StitcherWorkletRuntime.dispatchToHostWorklets(...)`
+    (Phase 4b.iii).  Per-frame fan-out runs every AR frame when host
+    worklets are registered (not just during capture).
+
+### Performance posture
+
+  - **First-party-only deployments** (no `useFrameProcessor`):
+    zero per-frame cost added.  `hasHostWorklets()` atomic-read
+    short-circuits before any dispatch path.
+  - **Host worklets registered, idle preview**: Android pays
+    ~6-10ms per AR frame (NV21 pack + JNI byte copy + worklet
+    dispatch).  iOS uses `CFBridgingRetain` (no per-frame copy,
+    but ARKit pool back-pressure on next frame).  Both acceptable
+    for v0.8.0; future optimization → zero-copy NV21 transfer via
+    direct `ByteBuffer` (Android).
+
+### Added — SSIM parity gate harness
+
+`scripts/ssim-compare.py` — pixel-wise SSIM comparison between
+panorama JPEGs (Pillow + numpy + scikit-image; threshold 0.98).
+Procedure in `docs/phase-7-parity-gate.md`.
+
+> **v0.8.0 release note:** the formal SSIM parity gate was NOT
+> run for this release.  Verification rests on manual visual
+> inspection of v0.8.0 panorama output on iPhone 16 Pro (Phase
+> 4b.i) and Galaxy A35 (Phase 4b.iii) — both produced stitched
+> panoramas matching the v0.7.x behaviour subjectively.  The
+> harness is in place for v0.8.1+ / future releases where the
+> gate is mandatory.
+
+### Migration guide
+
+No host-side changes required for the common case.  Hosts that
+want to attach worklets:
+
+1. Add `react-native-worklets-core` if not already a peer dep
+   (already in v0.7.x's peer-deps list).
+2. Replace `useFrameProcessor` imports from
+   `react-native-vision-camera` with the lib's own export:
+   ```diff
+   - import { useFrameProcessor } from 'react-native-vision-camera';
+   + import { useFrameProcessor } from 'react-native-image-stitcher';
+   ```
+3. Worklet body now receives `StitcherFrame` instead of vc's
+   `Frame` — see `src/stitching/StitcherFrame.ts` for the contract.
+
+## [0.7.1] — 2026-05-26
+
+### Fixed — CI binary-packaging bloat
+
+The v0.7.0 release (and likely v0.5.1 before it — both built by
+CI) shipped uncompressed binary archives that consumers downloaded
+on every `npm install`.  Sizes vs. the manual recipe used for
+v0.6.0:
+
+| Platform | v0.7.0 (CI, unstripped) | v0.7.1 (CI, stripped) | Saving |
+|---|---|---|---|
+| iOS zip   | 43 MB  | ~26 MB | -17 MB  |
+| Android zip | 165 MB | ~42 MB | -123 MB |
+
+The lib itself is unchanged; consumers on the `^0.7.0` semver range
+automatically pick up v0.7.1 and start getting the smaller download.
+No source-code changes; binary-only re-release.
+
+#### Root cause
+
+- **iOS**: `scripts/build-opencv-ios.sh` produced an xcframework
+  containing both the device slice (`ios-arm64`) and the simulator
+  slice (`ios-arm64_x86_64-simulator`).  vision-camera + ARKit
+  don't work on the simulator and the example app targets devices
+  only, so the simulator slice was dead weight in every download.
+- **Android**: `scripts/build-opencv-android.sh` ran OpenCV's
+  `build_sdk.py` for all four NDK ABIs (per the script's own
+  contract — produces a multi-arch fat SDK).  The lib's
+  `android/build.gradle` sets `ndk.abiFilters arm64-v8a` so only
+  arm64-v8a binaries reach any consumer APK, but the zip carried
+  `armeabi-v7a` / `x86` / `x86_64` libs in three sibling dirs
+  (`sdk/native/libs/`, `staticlibs/`, `3rdparty/libs/`) plus
+  `samples/` (~10 MB) and `apk/` (~5 MB) — none of it ever loaded
+  at runtime.
+
+#### Fix
+
+Both build scripts now strip the dead-weight pieces immediately
+after the OpenCV build completes, before zipping for upload.
+Sentinel checks fail loudly if a strip removes the required
+arm64-v8a artifacts (defends against a future refactor of the
+strip block).  Pattern matches the manual recipe in
+`feedback_binary_release_packaging.md` (project memory).
+
+The iOS strip auto-detects the simulator entry's index in the
+xcframework's `Info.plist::AvailableLibraries` via a
+`plutil -convert json | python3` one-liner — the index isn't fixed
+across OpenCV builds and previous manual recipes that hardcoded
+`AvailableLibraries.1` would have silently stripped the wrong
+slice if the order changed.
+
+#### Compatibility
+
+Strict additive over v0.7.0.  No code changes — the lib's runtime
+and public API surface are byte-identical.
+
 ## [0.7.0] — 2026-05-26
 
 ### Added — Tier 1: `useKeyframeStream`
@@ -1248,7 +1426,8 @@ Native module names also changed:
 - iOS pod: `RetaiLensCaptureSDK` → `RNImageStitcher`
 - iOS xcframework: shipped as `opencv2.xcframework` (linked from `RNImageStitcher.podspec`)
 
-[Unreleased]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.7.1...HEAD
+[0.7.1]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.5.1...v0.6.0
 [0.5.1]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.5.0...v0.5.1

package/android/build.gradle

@@ -88,12 +88,30 @@ android {
         externalNativeBuild {
             cmake {
                 arguments "-DOPENCV_ANDROID_SDK=${file("$projectDir/vendor/OpenCV-android-sdk").absolutePath}",
-                          "-DANDROID_STL=c++_static"
+                          // v0.8.0 Phase 3 — switched from c++_static
+                          // to c++_shared.  Required for linking
+                          // ReactAndroid::jsi (RN's prefab uses
+                          // shared libc++).  STL probe at
+                          // android/src/main/cpp/CMakeLists.txt:99-118
+                          // confirms OpenCV's libopencv_stitching.a is
+                          // already built with __ndk1 (c++_shared), so
+                          // the static archive link continues to
+                          // work cleanly.  Pre-Phase-3 it worked only
+                          // because the JNI shim's .so boundary used
+                          // POD types — fragile.  Now properly aligned.
+                          "-DANDROID_STL=c++_shared"
                 cppFlags "-std=c++17"
             }
         }
     }
 
+    // v0.8.0 Phase 3 — consume React Native's prefab packages
+    // (ReactAndroid::jsi + fbjni::fbjni) for the JSI host object.
+    // RN 0.71+ ships these as prefabs; this lib targets RN 0.84.
+    buildFeatures {
+        prefab true
+    }
+
     // ── JNI shim build path ─────────────────────────────────────────
     // Gradle compiles cpp/image_stitcher_jni.cpp into
     // libimage_stitcher.so for the ABIs filtered above.  The shim
@@ -248,6 +266,22 @@ dependencies {
         // still builds for non-camera consumers.
         android.sourceSets.main.java.exclude '**/CvFlowGateFrameProcessor.kt'
     }
+
+    // v0.8.0 Phase 4b.ii — react-native-worklets-core's Android
+    // prefab (`rnworklets`) is consumed by the native shim
+    // (`stitcher_worklet_registry.cpp` constructs
+    // `RNWorklet::WorkletInvoker`s).  `implementation` not
+    // `compileOnly` because we need the prefab's `.so` available at
+    // both link time AND runtime — without the runtime presence,
+    // `dlopen` would fail when our `libimage_stitcher.so` is loaded.
+    //
+    // Host apps that use this lib already declare worklets-core as
+    // a peer dep (see package.json's peerDependencies); RN
+    // autolinking + Gradle deduplicates, so the host doesn't get
+    // a second copy.
+    if (findProject(':react-native-worklets-core') != null) {
+        implementation project(':react-native-worklets-core')
+    }
 }
 
 // Helper from the React Native gradle convention to read host-app

package/android/src/main/cpp/CMakeLists.txt

@@ -80,6 +80,35 @@ if(NOT EXISTS "${SHARED_CPP_DIR}/keyframe_gate.hpp")
         "Expected react-native-image-stitcher/cpp/ — was the package layout broken?")
 endif()
 
+# ── React Native prefab packages for JSI ──────────────────────────
+#
+# v0.8.0 Phase 3 — activating the previously-deferred JSI integration.
+# The shared C++ host object (cpp/stitcher_frame_jsi.cpp) depends on
+# `facebook::jsi`.  ReactAndroid ships JSI as a prefab starting
+# RN 0.71+; the lib targets RN 0.84 so this is always available.
+#
+# `buildFeatures { prefab true }` in android/build.gradle enables
+# consumption + `ANDROID_STL=c++_shared` aligns the STL with what
+# the prefabs require.  The Phase-2 STL probe (`llvm-nm
+# libopencv_stitching.a | grep '__ndk1'`) confirmed OpenCV's
+# stitching archive was already built with c++_shared (768
+# __ndk1 symbols + 0 __cxx11 / NSt3) — switching the lib's flag
+# from c++_static to c++_shared just aligns + matches.  The
+# previous c++_static was working only because the JNI shim's
+# `.so` boundary used POD/C types; the new c++_shared is properly
+# matched throughout.
+find_package(ReactAndroid REQUIRED CONFIG)
+find_package(fbjni REQUIRED CONFIG)
+
+# v0.8.0 Phase 4b.ii — react-native-worklets-core prefab.  The
+# Gradle module name is `react-native-worklets-core`; inside it
+# publishes a library named `rnworklets` (matches vc's consumption
+# pattern in node_modules/react-native-vision-camera/android/CMakeLists.txt).
+# We consume both the headers (for `WKTJsiWorklet.h` etc.) AND
+# the .so (for `RNWorklet::WorkletInvoker` + `JsiWrapper::unwrap`
+# symbols, which are defined in worklets-core's WKTJsiWrapper.cpp).
+find_package(react-native-worklets-core REQUIRED CONFIG)
+
 # ── Our shim ───────────────────────────────────────────────────────
 add_library(image_stitcher SHARED
     image_stitcher_jni.cpp
@@ -90,7 +119,30 @@ add_library(image_stitcher SHARED
     # retry + dimension/memory instrumentation.  Used to live in this
     # file (image_stitcher_jni.cpp).  See cpp/stitcher.hpp for design
     # rationale.
-    "${SHARED_CPP_DIR}/stitcher.cpp")
+    "${SHARED_CPP_DIR}/stitcher.cpp"
+    # v0.8.0 Phase 3 — shared JSI host object for `StitcherFrame`.
+    # Compiles to identical dispatch on both platforms; iOS consumes
+    # it via the .mm shim at
+    # `ios/Sources/RNImageStitcher/StitcherFrameHostObject.mm`.
+    # See cpp/stitcher_frame_jsi.hpp for the class API.
+    "${SHARED_CPP_DIR}/stitcher_frame_jsi.cpp"
+    # v0.8.0 Phase 4b.ii — shared C++ registry of host-supplied
+    # worklets + the `globalThis.__stitcherProxy` host object that
+    # JS calls into.  iOS picked these up via the podspec glob in
+    # Phase 4b.i; Android adds them here.
+    "${SHARED_CPP_DIR}/stitcher_worklet_registry.cpp"
+    "${SHARED_CPP_DIR}/stitcher_proxy_jsi.cpp"
+    # v0.8.0 Phase 4b.iii — shared per-frame fan-out helper.  Posts
+    # a `StitcherFrameData` onto worklets-core's default context's
+    # worklet thread; iterates the host worklet registry; invalidates
+    # the JSI host object after dispatch completes.
+    "${SHARED_CPP_DIR}/stitcher_worklet_dispatch.cpp"
+    # v0.8.0 Phase 4b.ii — Android JNI bindings for the JSI install
+    # (`StitcherJsiInstallerModule.nativeInstall`).  Reaches into the
+    # main JS runtime via the `long` JSI handle Kotlin pulls from
+    # `ReactApplicationContext.getJavaScriptContextHolder()`.  See
+    # worklets-core's `WorkletsModule.java` for the canonical pattern.
+    stitcher_jsi_install_jni.cpp)
 
 target_include_directories(image_stitcher PRIVATE
     "${OPENCV_INCLUDE_DIR}"
@@ -117,7 +169,17 @@ target_link_libraries(image_stitcher
     opencv_stitching
     -Wl,--no-whole-archive
     opencv_java
-    log)
+    log
+    # v0.8.0 Phase 3 — JSI for the shared C++ host object
+    # (cpp/stitcher_frame_jsi.cpp's `facebook::jsi::HostObject`
+    # subclass).  fbjni for the Phase 3c JNI bridge between Kotlin
+    # worklet runtime + C++ host object construction.
+    ReactAndroid::jsi
+    fbjni::fbjni
+    # v0.8.0 Phase 4b.ii — worklets-core's `RNWorklet::WorkletInvoker`
+    # is constructed in the C++ registry's `install` method and
+    # invoked from the Android per-frame dispatch path.
+    react-native-worklets-core::rnworklets)
 
 target_compile_options(image_stitcher PRIVATE
     -fvisibility=hidden

package/android/src/main/cpp/stitcher_jsi_install_jni.cpp

@@ -0,0 +1,227 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// stitcher_jsi_install_jni.cpp — JNI binding for the Android-side
+// JSI install (v0.8.0 Phase 4b.ii).
+//
+// Kotlin's `StitcherJsiInstallerModule.nativeInstall(jsiRuntimeRef)`
+// calls into this file.  We unbox the `jsi::Runtime*` from the
+// Java `long` and hand it to the shared
+// `retailens::installStitcherProxy(runtime)` function which sets
+// `globalThis.__stitcherProxy`.  Same destination as iOS — the
+// host object class lives in `cpp/stitcher_proxy_jsi.{hpp,cpp}`.
+//
+// ## Why a `long` ref, not a JSI handle wrapper class
+//
+// `ReactApplicationContext.getJavaScriptContextHolder()` returns a
+// `JavaScriptContextHolder` whose `.get()` returns a Java `long`
+// that's the raw pointer to the C++ `jsi::Runtime*`.  Same
+// contract as worklets-core's `WorkletsModule.nativeInstall`
+// (verified at the same call site).  Caller is responsible for
+// ensuring the runtime outlives this call — in practice, the
+// runtime IS the JS thread's runtime which lives the whole
+// process lifetime, so this is structurally always safe in our
+// usage.
+//
+// ## Threading
+//
+// Kotlin invokes this from a `@ReactMethod(isBlockingSynchronousMethod
+// = true)` so we're already on the JS thread.  Synchronous JSI
+// access is safe.
+
+#include "stitcher_proxy_jsi.hpp"
+
+// v0.8.0 Phase 4b.iii — per-frame fan-out support.  The shared
+// `dispatchToHostWorklets` posts to worklets-core's default context;
+// this JNI file's `nativeDispatchToHostWorklets` constructs the
+// `StitcherFrameData` from raw bytes + pose + dims and forwards it.
+#include "stitcher_frame_data.hpp"
+#include "stitcher_worklet_dispatch.hpp"
+#include "stitcher_worklet_registry.hpp"
+
+#include <react-native-worklets-core/WKTJsiWorkletContext.h>
+
+#include <jni.h>
+#include <jsi/jsi.h>
+
+#include <android/log.h>
+
+#include <cstdint>
+#include <cstring>
+#include <memory>
+#include <utility>
+#include <vector>
+
+#define LOG_TAG "StitcherJsiInstaller"
+#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__)
+#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__)
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_io_imagestitcher_rn_StitcherJsiInstallerModule_nativeInstall(
+    JNIEnv* /*env*/, jobject /*thiz*/, jlong jsiRuntimeRef) {
+  if (jsiRuntimeRef == 0) {
+    // ReactApplicationContext.getJavaScriptContextHolder().get()
+    // returns 0 when the runtime isn't ready (rare — JS would have
+    // had to call us before its own runtime was up; impossible in
+    // practice).  Defensive.
+    return JNI_FALSE;
+  }
+  auto* runtime = reinterpret_cast<facebook::jsi::Runtime*>(jsiRuntimeRef);
+  retailens::installStitcherProxy(*runtime);
+  LOGI("installed globalThis.__stitcherProxy on main JS runtime.");
+  return JNI_TRUE;
+}
+
+// ─── v0.8.0 Phase 4b.iii — Android NV21 PixelBufferReader ──────────
+//
+// Owns a heap-allocated `std::vector<uint8_t>` of pre-copied NV21
+// bytes.  Constructed by `nativeDispatchToHostWorklets` after one
+// JNI byte-array copy from Kotlin; outlives the AR render thread
+// scope via `StitcherFrameData::pixelReader`'s `shared_ptr` —
+// dropped when the host object is invalidated.
+
+namespace {
+
+class AndroidNV21BufferReader : public retailens::PixelBufferReader {
+ public:
+  explicit AndroidNV21BufferReader(std::vector<uint8_t>&& bytes)
+      : _bytes(std::move(bytes)) {}
+
+  std::size_t byteSize() const override { return _bytes.size(); }
+
+  std::size_t copyTo(uint8_t* dst, std::size_t maxBytes) override {
+    if (dst == nullptr) return 0;
+    std::size_t n = std::min(maxBytes, _bytes.size());
+    if (n > 0) {
+      std::memcpy(dst, _bytes.data(), n);
+    }
+    return n;
+  }
+
+ private:
+  std::vector<uint8_t> _bytes;
+};
+
+}  // namespace
+
+// ─── v0.8.0 Phase 4b.iii — registry count accessor ─────────────────
+//
+// Cheap (microsecond) accessor for the per-frame gate in
+// `RNSARCameraView.onDrawFrame`.  Avoids the NV21 byte-pack cost
+// when no host worklets are registered AND no capture is active.
+// Same atomic-read the JSI host object's `count()` host function
+// goes through.
+extern "C" JNIEXPORT jint JNICALL
+Java_io_imagestitcher_rn_StitcherWorkletRuntime_nativeRegistryCount(
+    JNIEnv* /*env*/, jobject /*thiz*/) {
+  return static_cast<jint>(
+      retailens::StitcherWorkletRegistry::shared().count());
+}
+
+// ─── v0.8.0 Phase 4b.iii — per-frame dispatch JNI binding ──────────
+//
+// Called from Kotlin's `StitcherWorkletRuntime.dispatchToHostWorklets`
+// after the first-party stitching block has returned (the AR-frame
+// data is still in scope on the Kotlin side because
+// `RNSARCameraView.onDrawFrame` reads the ARCore Frame, builds the
+// NV21 byte[], invokes first-party via `runFirstParty { ... }`,
+// THEN calls into here).
+//
+// The byte[] is COPIED into our owned vector — ARCore's pixel data
+// becomes inaccessible shortly after `onDrawFrame` returns, and our
+// async dispatch must outlive that scope.  Cost: one ~3MB memcpy
+// per frame at 1080p NV21 (~90 MB/s at 30 fps; <5 ms on a mid-range
+// Android device).  Fast-path early-exit when the registry is empty
+// skips the copy entirely.
+//
+// trackingState: Kotlin passes one of "" / "notAvailable" / "limited"
+// / "normal" (empty string = field unset → JS sees undefined).
+extern "C" JNIEXPORT void JNICALL
+Java_io_imagestitcher_rn_StitcherWorkletRuntime_nativeDispatchToHostWorklets(
+    JNIEnv* env, jobject /*thiz*/,
+    jbyteArray nv21Bytes,
+    jint width, jint height,
+    jdouble qx, jdouble qy, jdouble qz, jdouble qw,
+    jdouble tx, jdouble ty, jdouble tz,
+    jdouble timestampNs,
+    jstring trackingState) {
+  // Fast-path early-exit BEFORE the JNI byte-array copy.  Saves the
+  // ~3MB memcpy + JSI host object alloc on every frame in the
+  // common first-party-only case.
+  if (retailens::StitcherWorkletRegistry::shared().count() == 0) {
+    return;
+  }
+
+  if (nv21Bytes == nullptr) {
+    LOGE("nativeDispatchToHostWorklets: nv21Bytes is null");
+    return;
+  }
+
+  const jsize byteLen = env->GetArrayLength(nv21Bytes);
+  if (byteLen <= 0) {
+    LOGE("nativeDispatchToHostWorklets: nv21Bytes is empty");
+    return;
+  }
+
+  // Copy into our owned vector.  `GetByteArrayRegion` is the
+  // canonical "copy" path — `GetByteArrayElements + Release` MAY
+  // pin the JVM array (zero-copy) but the contract isn't
+  // guaranteed; we need our own buffer for the async dispatch
+  // anyway, so the explicit copy is cleaner.
+  std::vector<uint8_t> bytes(static_cast<std::size_t>(byteLen));
+  env->GetByteArrayRegion(
+      nv21Bytes, 0, byteLen,
+      reinterpret_cast<jbyte*>(bytes.data()));
+
+  // Extract trackingState string (may be null on the Kotlin side
+  // for non-AR or pre-tracking frames — guard accordingly).
+  std::string trackingStateStr;
+  if (trackingState != nullptr) {
+    const char* cs = env->GetStringUTFChars(trackingState, nullptr);
+    if (cs != nullptr) {
+      trackingStateStr = cs;
+      env->ReleaseStringUTFChars(trackingState, cs);
+    }
+  }
+
+  // Build StitcherFrameData.  Field semantics match the iOS
+  // `StitcherFrameHostObject::fromARFrame:pose:` factory; this is
+  // the Android equivalent path.
+  retailens::StitcherFrameData data;
+  data.source = "ar";
+  data.width = static_cast<int32_t>(width);
+  data.height = static_cast<int32_t>(height);
+  // ARCore's camera image is YUV_420_888 on Android, mapped to NV21
+  // by the existing `YuvImageConverter.packNV21` path — the byte[]
+  // we receive is interleaved Y then VU.  Worklets gate on this
+  // string identifier (`'yuv'` vs `'unknown'`); v0.8.0 always
+  // emits `'yuv'` for AR mode on Android (NV21).
+  data.pixelFormat = "yuv";
+  // Android AR-mode camera image is always landscape-natural; the
+  // mapping matches iOS' coarse two-value set.  Hosts that need
+  // exact display orientation read it from the device-orientation
+  // sensors (see `useDeviceOrientation` hook).
+  data.orientation = (width >= height) ? "landscape-right" : "portrait";
+  data.timestampNs = timestampNs;
+  data.qx = qx;
+  data.qy = qy;
+  data.qz = qz;
+  data.qw = qw;
+  data.tx = tx;
+  data.ty = ty;
+  data.tz = tz;
+  data.hasTranslation = true;  // AR mode always has translation
+  data.arTrackingState = trackingStateStr;
+  data.pixelReader =
+      std::make_shared<AndroidNV21BufferReader>(std::move(bytes));
+
+  // Dispatch on worklets-core's default context.  That context is
+  // initialised by JS' `Worklets.install()` (which runs at lib
+  // bootstrap when worklets-core's module is imported); by the
+  // time host worklets are registered, the default context is up.
+  // The shared dispatch helper handles the registry snapshot,
+  // host-object construction (inside the worklet thread), per-
+  // worklet failure isolation, and invalidation.
+  retailens::dispatchToHostWorklets(
+      RNWorklet::JsiWorkletContext::getDefaultInstance(),
+      std::move(data));
+}

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

@@ -1001,14 +1001,17 @@ class IncrementalStitcher(
         // per accepted frame on a mid-tier device.  Pass null to use
         // the legacy JPEG path.
         //
-        // OWNERSHIP: the engine retains a reference to `nv21PixelData`
-        // until `workScope`'s coroutine consumes it (~50 ms later).
-        // Callers MUST treat the array as transferred — do not
-        // mutate it or return it to a buffer pool after calling
-        // this method.  If a caller needs to recycle the buffer,
-        // pass `.copyOf()` (currently no caller does — the F8.4
-        // Frame Processor plugin allocates a fresh array per frame).
-        nv21PixelData: ByteArray? = null,
+        // OWNERSHIP: wrapped in `TransferredNV21` (audit #4A,
+        // v0.10.0).  The wrapper enforces single-use: the engine
+        // calls `.takeOnce()` on the producer thread before
+        // dispatching to `workScope`; subsequent attempts to extract
+        // the bytes throw.  Callers MUST construct a fresh
+        // `TransferredNV21` per frame and MUST NOT hand the same
+        // instance to two consumers (e.g., a sync gate-eval + an
+        // async workScope.launch).  The Frame Processor plugin and
+        // the AR camera view both allocate fresh NV21 arrays per
+        // frame; the wrapper is a defensive-programming guard.
+        nv21PixelData: TransferredNV21? = null,
         nv21PixelWidth: Int = 0,
         nv21PixelHeight: Int = 0,
     ) {
@@ -1215,11 +1218,20 @@ class IncrementalStitcher(
             )
             return
         }
+        // v0.10.0 audit #4A — extract the wrapped bytes ONCE on the
+        // producer thread before dispatching to workScope.  This
+        // makes the transfer-of-ownership explicit + caught early:
+        // if a caller accidentally passes the same TransferredNV21
+        // instance to a sync consumer earlier, takeOnce() would
+        // have already thrown there.  Capturing `pixelBytes` by
+        // value inside the coroutine sidesteps any chance of the
+        // wrapper being read from two threads.
+        val pixelBytes: ByteArray? = if (hasPixelData) nv21PixelData!!.takeOnce() else null
         workScope.launch {
             val state: WritableMap? = if (firstwins != null) {
                 val tele = if (hasPixelData) {
                     firstwins.addFramePixelData(
-                        nv21 = nv21PixelData!!,
+                        nv21 = pixelBytes!!,
                         nv21Width = nv21PixelWidth,
                         nv21Height = nv21PixelHeight,
                         qx = qx, qy = qy, qz = qz, qw = qw,
@@ -1246,7 +1258,7 @@ class IncrementalStitcher(
             } else {
                 val tele = if (hasPixelData) {
                     hybrid!!.addFramePixelData(
-                        nv21 = nv21PixelData!!,
+                        nv21 = pixelBytes!!,
                         nv21Width = nv21PixelWidth,
                         nv21Height = nv21PixelHeight,
                         qx = qx, qy = qy, qz = qz, qw = qw,
@@ -1410,7 +1422,14 @@ class IncrementalStitcher(
             // `addFramePixelData` instead of JPEG-decoding a
             // separately-written path.  Batch-keyframe mode
             // ignores these (it uses `grayData` + `onAccept`).
-            nv21PixelData = nv21Bytes,
+            //
+            // v0.10.0 audit #4A — wrap in TransferredNV21 so the
+            // engine takes ownership exactly once on the producer
+            // thread (engine calls `.takeOnce()` before workScope).
+            // Misuse (handing this same instance to two consumers)
+            // throws at the second `.takeOnce()` site, not silently
+            // corrupting frames.
+            nv21PixelData = TransferredNV21(nv21Bytes),
             nv21PixelWidth = width,
             nv21PixelHeight = height,
             onAccept = { targetPath ->

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

@@ -87,6 +87,10 @@ class RNImageStitcherPackage : ReactPackage {
             RNSARSession(reactContext),
             IncrementalStitcher(reactContext),
             FileBridge(reactContext),
+            // v0.8.0 Phase 4b.ii — Android JSI installer for the
+            // host-worklet `__stitcherProxy` global.  Mirror of
+            // iOS' `StitcherJsiInstaller`.
+            StitcherJsiInstallerModule(reactContext),
         )
     }