react-native-image-stitcher 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -16,6 +16,247 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] — 2026-05-27
+
+### Added — layered frame-access helpers
+
+Three new primitives completing the Tier 2 surface in the
+three-tier extensibility pattern.  See `docs/frame-access-tiers.md`
+for the full decision flow + use-case mapping.
+
+#### Layer 1 — `save_frame_as_jpeg` vc Frame Processor plugin (native)
+
+Worklet-callable JPEG encoder. Registers on both platforms:
+
+- **iOS** — `SaveFrameAsJpegPlugin.mm` (CIImage → CGImage → UIImage
+  → UIImageJPEGRepresentation → atomic NSData write).  Registered
+  via `+ (void)load` hook into `FrameProcessorPluginRegistry`.
+- **Android** — `SaveFrameAsJpegPlugin.kt` wrapping the lib's
+  existing `YuvImageConverter.encodeJpegFromNV21` encoder (the
+  same one used by `RNSARCameraView`'s keyframe-accept callback).
+  Registered alongside `cv_flow_gate_process_frame` in
+  `RNImageStitcherPackage.ensureFrameProcessorPluginRegistered`.
+
+Plugin contract (identical on both platforms):
+  - Args: `path` (string, REQUIRED), `quality` (number 0-100,
+    default 75, clamped `[1, 100]`)
+  - Returns: `{ ok: true, path, width, height }` OR
+             `{ ok: false, error: "..." }`
+
+Hosts can call this directly from their own `useFrameProcessor`
+worklet for custom rate-control logic; most consumers use it
+indirectly via Layer 3.
+
+#### Layer 2 — `useThrottledFrameProcessor` hook
+
+```tsx
+const fp = useThrottledFrameProcessor(
+  (frame) => {
+    'worklet';
+    // Worklet-native processing at sub-frame-rate
+  },
+  { sampleHz: 2 },
+  [],
+);
+```
+
+Pure TS throttle gate over `useFrameProcessor` (v0.8.0).  Worklet
+fires up to `sampleHz` times per second; ticks too close together
+dropped via a monotonic-time `useSharedValue` gate.
+
+**Use for**: worklet-native processing — native OCR via
+Vision.framework / ML Kit wrapped as vc Frame Processor plugins,
+TFLite ML inference, LiDAR depth (`frame.arDepth`).  Direct
+buffer/pose/depth access in the worklet; bridge small bbox-result
+payloads to JS via `runOnJS`.
+
+`sampleHz` clamped to `[0.5, 30]`.
+
+#### Layer 3 — `useFrameStream` hook
+
+```tsx
+const fp = useFrameStream(
+  { sampleHz: 2, quality: 75 },
+  (sample) => {
+    // JS-thread callback: sample.jpegPath, sample.pose, sample.timestamp
+    setThumbnail(sample.jpegPath);
+  },
+);
+```
+
+Composes Layer 2 + Layer 1 + `runOnJS` bridge to deliver
+`SampledFrame` objects to a JS-thread handler.  Slot-reuse
+strategy bounds disk usage to ~4 stale JPEGs.
+
+**Use for**: JS-thread consumers — file-path OCR libraries (RN
+modules wrapping ML Kit), cloud upload, thumbnail preview UI,
+JS-side ML (TF.js, transformers.js).
+
+`sampleHz` clamped to `[0.5, 10]`; `quality` clamped `[1, 100]`.
+
+#### Types
+
+  - `SampledFrame` — `{ jpegPath, pose, timestamp, width, height }`
+  - `FrameStreamOptions` — `{ sampleHz, quality?, outputDir? }`
+  - `ThrottledFrameProcessorOptions` — `{ sampleHz }`
+
+All exported from `react-native-image-stitcher`.
+
+### Documentation
+
+- `docs/frame-access-tiers.md` — new comprehensive reference for
+  all four host-facing hooks (`useKeyframeStream`,
+  `useThrottledFrameProcessor`, `useFrameStream`,
+  `useFrameProcessor`) with decision flow, cost envelope, use-case
+  mapping, AR vs non-AR mode tradeoff.
+
+### Example app
+
+`example/App.tsx` now mounts `useFrameStream` at 2 Hz with a
+visible thumbnail overlay (bottom-right corner) — visual proof of
+the Layer 1 + 2 + 3 pipeline working end-to-end on both iPhone
+(60 Hz AR) and Galaxy A35 (30 Hz AR).
+
+### Compatibility
+
+- Strict additive over v0.8.0.  No host changes required.
+- Works in both AR and non-AR modes via v0.8.0's unified
+  `useFrameProcessor`.
+- New hooks return `useFrameProcessor`-shape objects compatible
+  with `<Camera frameProcessor={...}>` (Phase 5 from v0.8.0).
+
+### Notes
+
+- Formal SSIM parity gate (Phase 7 of the v0.9.0 plan) was NOT
+  run for this release — the layered design doesn't touch
+  first-party stitching, so a regression is structurally unlikely.
+  Harness still in place from v0.8.0 (`scripts/ssim-compare.py`)
+  for any host that wants to run it locally.
+
+[0.9.0]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.8.0...v0.9.0
+
+## [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

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));
+}