react-native-image-stitcher 0.16.1 → 0.17.0

package/CHANGELOG.md

@@ -14,6 +14,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > during 0.x are bumped to a new MINOR (e.g., 0.1 → 0.2), and the
 > upgrade path is documented in this CHANGELOG.
 
+## [0.17.0] — 2026-06-19
+
+### Added — `arFrameProcessor`: observe AR frames with a host worklet
+
+`<Camera>` gains an **`arFrameProcessor`** prop — a `'worklet'` invoked once per
+**ARKit / ARCore frame** while in AR capture, dispatched natively and running
+*alongside* first-party stitching (composition, not replacement). The worklet
+receives a `StitcherFrame` tagged `source: 'ar'` with the world-space `pose` and
+`arTrackingState`. It fires during preview too (continuous observation), at zero
+per-frame cost when no worklet is registered.
+
+This restores the previously-archived AR host-worklet capability and re-exposes
+it as an explicit prop (rather than the old auto-registering hook). Under the
+hood it installs `globalThis.__stitcherProxy` (JSI) on first use and fans frames
+out through a shared C++ proxy / registry / dispatch layer on both platforms
+(verified against `react-native-worklets-core` 1.6.3).
+
+The non-AR equivalent remains `frameProcessor` (vision-camera); the two modes use
+different runtimes and frame shapes, hence the separate prop. The
+`StitcherFrame` / `StitcherFrameProcessor` type names are unchanged.
+
+Verified on device: the worklet fires per frame on **iOS (ARKit, iPhone 16 Pro)**
+and **Android (ARCore, Galaxy A35)**.
+
+### Fixed
+
+- **Example app crashed at launch on Android** (`PlatformConstants could not be
+  found`). The v0.16.2 OpenCV-reuse demo added an app-level `externalNativeBuild`
+  to `example/android/app/build.gradle` that displaced React Native's own
+  New-Architecture app native build (so core TurboModules weren't compiled in).
+  Removed it; React Native owns the app native build again. **Example-app only —
+  the published SDK was never affected.**
+
+## [0.16.2] — 2026-06-17
+
+### Added — reuse the bundled OpenCV from your host app's native code (Android)
+
+A host app's own native (C++/NDK) code can now reuse the **same** custom
+OpenCV this library bundles (4.10.0, arm64-v8a) — **including `cv::Stitcher`**
+— with no second copy of `libopencv_java4.so` in the APK.
+
+The Android build now publishes the location of its vendored OpenCV SDK via
+`rootProject.ext.rnisOpenCVDir` (and `rnisOpenCVAndroidSdkDir`). A consumer
+points its `externalNativeBuild` at `-DOpenCV_DIR=${rootProject.ext.rnisOpenCVDir}`,
+calls `find_package(OpenCV)`, and links the shared `opencv_java` (core /
+imgproc / calib3d / … resolved at runtime from the already-shipped `.so`)
+plus the whole-archived static `opencv_stitching` (`cv::Stitcher`). A
+build-verified consumer ships in the example app
+(`example/android/app/src/main/cpp/`).
+
+This is additive — no public API or runtime-behaviour change. AGP
+`prefabPublishing` was evaluated and is unworkable for prebuilt OpenCV
+(prefab only exports libraries the module itself builds), so OpenCV's own
+first-class CMake package is used instead. iOS reuse (the vendored
+`opencv2.xcframework`) is unchanged.
+
+### Docs
+
+Documentation site refreshed: an easier **Getting started**, a complete
+**`<Camera>` API** reference (every prop, the v0.16 guidance params —
+`rectCrop` / `showPreview` / `panMode` / `panGuidance` / `maxPanDurationMs` /
+`panTooFastThreshold` / `lateralBudgetCm` / `guidanceCopy` — and the
+`stitcher` / `frameSelection` settings-JSON tables), a fully-loaded
+**Complete example**, the v0.16 **Capture result & errors** union, and new
+**Sharing OpenCV** / **Bring your own OpenCV** guides.
+
 ## [0.16.1] — 2026-06-16
 
 ### Changed — high-level `cv::Stitcher` is now the default pipeline

package/README.md

@@ -29,8 +29,8 @@ Peer dependencies (the host app provides these):
   "react": ">=18.0.0",
   "react-native": ">=0.72.0",
   "react-native-vision-camera": ">=4.7.0",
+  "react-native-worklets-core": ">=1.3.0",
   "react-native-sensors": ">=7.0.0",
-  "expo-sensors": ">=14.0.0",
   "react-native-safe-area-context": ">=4.0.0"
 }
 ```
@@ -71,50 +71,32 @@ cd android && ./gradlew :app:assembleDebug   # Android
 > See [Orientation support](#orientation-support) for the full story
 > (landscape *is* supported on iOS if you need it).
 
-The minimum: resolve camera permission, then mount `<Camera>` with an
-`onCapture` handler.
+The minimum: mount `<Camera>` with an `onCapture` handler. It fires once
+per capture attempt — gate on `result.ok` before reading the output.
 
 ```tsx
-import {
-  Camera,
-  type CameraCaptureResult,
-  type CameraError,
-} from 'react-native-image-stitcher';
+import { Camera, type CameraCaptureResult } from 'react-native-image-stitcher';
 
 export function CaptureScreen() {
-  const handleCapture = (result: CameraCaptureResult) => {
-    // `onCapture` fires on success AND failure — gate on `ok` first.
-    if (!result.ok) {
-      console.warn('capture failed:', result.error.code, result.error.message);
-      return;
-    }
-    // Non-fatal quality signals (e.g. <70% of frames used). Always present.
-    if (result.warnings.length > 0) {
-      console.warn('warnings:', result.warnings.map((w) => w.code));
-    }
-    if (result.type === 'photo') {
-      console.log('Photo:', result.uri, result.width, result.height);
-    } else {
-      console.log(
-        'Panorama:',
-        result.uri,
-        `${result.framesIncluded}/${result.framesRequested} frames`,
-        `stitched as ${result.stitchModeResolved ?? 'n/a'}`,
-      );
-    }
-  };
-
   return (
     <Camera
-      onCapture={handleCapture}
-      // onError still fires on failure too (an unchanged mirror of the
-      // ok:false result above).
-      onError={(err: CameraError) => console.warn(err.code, err.message)}
+      onCapture={(result: CameraCaptureResult) => {
+        if (!result.ok) {
+          console.warn('capture failed:', result.error.code);
+          return;
+        }
+        // result.type is 'photo' or 'panorama'; both carry uri/width/height.
+        console.log(result.type, result.uri, result.width, result.height);
+      }}
     />
   );
 }
 ```
 
+> **Camera permission is the host's job.** The SDK never requests it for
+> you — resolve it (e.g. with vision-camera's `useCameraPermission`)
+> before mounting `<Camera>`.
+
 ### A complete capture screen
 
 A realistic screen: requests permission up front, shows a capture

package/RNImageStitcher.podspec

@@ -60,6 +60,18 @@ Pod::Spec.new do |s|
 
   s.dependency 'React-Core'
 
+  # react-native-worklets-core — provides the `RNWorklet::WorkletInvoker`
+  # + `JsiWorkletContext` primitives the AR-mode JSI fan-out is built on
+  # (StitcherJsiInstaller.mm / RNSARWorkletRuntime.mm + the shared
+  # cpp/stitcher_worklet_{registry,dispatch}.cpp).  In practice this pod
+  # is already in every host's graph (vision-camera depends on it), but
+  # declaring it here makes the dependency explicit and guarantees its
+  # headers are present even for a host that uses AR mode without
+  # vision-camera.  The bare `WKTJsiWorklet.h` includes in the .mm files
+  # resolve via the HEADER_SEARCH_PATHS entry below (the package's own
+  # node_modules copy of the worklets-core cpp/ dir).
+  s.dependency 'react-native-worklets-core'
+
   # ─────────────────────────────────────────────────────────────────────
   # OpenCV — pre-built custom xcframework fetched by postinstall
   # ─────────────────────────────────────────────────────────────────────
@@ -84,6 +96,19 @@ Pod::Spec.new do |s|
     'CLANG_CXX_LANGUAGE_STANDARD' => 'c++17',
     'CLANG_CXX_LIBRARY' => 'libc++',
     'OTHER_CPLUSPLUSFLAGS' => '$(inherited) -std=c++17',
-    'HEADER_SEARCH_PATHS' => '$(inherited) "${PODS_TARGET_SRCROOT}/cpp"',
+    # HEADER_SEARCH_PATHS:
+    #   - "${PODS_TARGET_SRCROOT}/cpp" — the shared C++ port's own
+    #     headers (keyframe_gate.hpp, stitcher_frame_jsi.hpp, …).
+    #   - the worklets-core cpp/ dir — so the bare `#include
+    #     "WKTJsiWorklet.h"` / "WKTJsiWorkletContext.h" lines in
+    #     StitcherJsiInstaller.mm + RNSARWorkletRuntime.mm resolve.
+    #     PODS_ROOT is `<host>/ios/Pods`; the package's worklets-core
+    #     copy lives at `<host>/node_modules/react-native-worklets-core/
+    #     cpp`, i.e. `${PODS_ROOT}/../node_modules/...`.  (The shared
+    #     cpp/*.cpp files instead use the namespace-prefixed
+    #     `<react-native-worklets-core/WKTJsiWorklet.h>` form, which
+    #     resolves against `${PODS_ROOT}/Headers/Public` — already on
+    #     the inherited path — and works on Android's prefab too.)
+    'HEADER_SEARCH_PATHS' => '$(inherited) "${PODS_TARGET_SRCROOT}/cpp" "${PODS_ROOT}/../node_modules/react-native-worklets-core/cpp"',
   }
 end

package/android/build.gradle

@@ -112,6 +112,40 @@ android {
         prefab true
     }
 
+    // ── Host OpenCV reuse: why NOT prefab publishing ─────────────────
+    //
+    // Goal: let a HOST app's own native (C++/NDK) code reuse the SAME
+    // custom OpenCV (4.10.0, arm64-v8a) this AAR already bundles — both
+    // libopencv_java4.so (cv::Mat, imgproc, features2d, calib3d, flann,
+    // photo, video …) AND cv::Stitcher (which lives in the static
+    // archive libopencv_stitching.a, NOT in the fat .so).
+    //
+    // We evaluated AGP `prefabPublishing` first (the idiomatic AAR way)
+    // and it CANNOT carry this OpenCV.  Empirically verified: AGP's
+    // prefab modules only export libraries the module's own
+    // externalNativeBuild PRODUCES (here: just `image_stitcher`).  A
+    // prebuilt jniLib (.so) or a prebuilt static archive (.a) is not an
+    // accepted prefab `libraryName` — the configure fails with
+    // `[CXX1404] did not find implicitly required targets`.  So neither
+    // libopencv_java4.so nor libopencv_stitching.a can ride a prefab.
+    //
+    // Instead we expose the bundled OpenCV's OWN first-class CMake
+    // package — which already defines every module (incl. opencv_stitching
+    // as a STATIC IMPORTED target and opencv_java as a SHARED IMPORTED
+    // target) — to consumers via a rootProject ext property.  A host
+    // points its externalNativeBuild at `-DOpenCV_DIR=<that dir>`, does
+    // `find_package(OpenCV REQUIRED)`, then links the SHARED `opencv_java`
+    // (cv::Mat & friends resolved at runtime from the AAR's already-shipped
+    // libopencv_java4.so — NO second copy) plus the whole-archived STATIC
+    // `opencv_stitching` (cv::Stitcher, a small private copy since it isn't
+    // in the fat .so).  This is the idiomatic Android OpenCV-consumption
+    // path.  See example/android/app for the working consumer.
+    //
+    // Set unconditionally at configure time so it's readable from the
+    // host app module regardless of project evaluation order.
+    rootProject.ext.rnisOpenCVAndroidSdkDir = "$opencvSdkDir/native"
+    rootProject.ext.rnisOpenCVDir = "$opencvSdkDir/native/jni"
+
     // ── JNI shim build path ─────────────────────────────────────────
     // Gradle compiles cpp/image_stitcher_jni.cpp into
     // libimage_stitcher.so for the ABIs filtered above.  The shim
@@ -267,6 +301,26 @@ dependencies {
         android.sourceSets.main.java.exclude '**/CvFlowGateFrameProcessor.kt'
     }
 
+    // v0.8.0 Phase 4b.ii/iii — react-native-worklets-core, consumed
+    // for its `rnworklets` PREFAB module (RNWorklet::JsiWorkletContext /
+    // WorkletInvoker) by the AR frame-processor JSI fan-out
+    // (src/main/cpp/stitcher_jsi_install_jni.cpp + the shared cpp/
+    // stitcher_*_jsi.cpp).  `find_package(react-native-worklets-core ...)`
+    // in CMakeLists.txt needs this gradle project on the path so AGP
+    // wires the prefab into the native build.  Same consumption pattern
+    // react-native-vision-camera uses for Frame Processors.
+    //
+    // `findProject(...)` guard mirrors the vision-camera block above:
+    // the SDK still compiles in hosts that don't install worklets-core
+    // (those hosts simply don't use the AR frame processor — the JSI
+    // sources still compile, but the prefab link only happens when the
+    // host provides worklets-core).  Autolinking adds the project for
+    // any host that depends on vision-camera (which transitively pulls
+    // in worklets-core).
+    if (findProject(':react-native-worklets-core') != null) {
+        implementation project(':react-native-worklets-core')
+    }
+
     // v0.10.0 audit #11A — Android JUnit test scaffold.  JVM unit
     // tests for pure-Kotlin data wrappers + algorithm helpers that
     // don't need an Android device.  Run via

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

@@ -66,6 +66,20 @@ add_library(opencv_stitching STATIC IMPORTED)
 set_target_properties(opencv_stitching PROPERTIES
     IMPORTED_LOCATION "${OPENCV_STITCHING_A}")
 
+# ── React Native + worklets-core prefabs (v0.8.0 Phase 4b.ii/iii) ──
+#
+# The AR frame-processor's JSI fan-out (stitcher_jsi_install_jni.cpp +
+# the shared cpp/stitcher_*_jsi.cpp) needs RN's JSI runtime, fbjni, and
+# react-native-worklets-core's `RNWorklet::JsiWorkletContext` /
+# `WorkletInvoker`.  RN 0.71+ ships jsi + the native-modules umbrella as
+# prefab packages; worklets-core ships a `rnworklets` prefab module.
+# `buildFeatures.prefab true` (android/build.gradle) makes these
+# discoverable.  We mirror react-native-vision-camera's consumption of
+# the SAME prefabs in this example app (verified working on RN 0.84.1).
+find_package(ReactAndroid REQUIRED CONFIG)
+find_package(fbjni REQUIRED CONFIG)
+find_package(react-native-worklets-core REQUIRED CONFIG)
+
 # ── Shared C++ port (KeyframeGate) ────────────────────────────────
 #
 # `cpp/` at the SDK root holds C++ that's compiled into BOTH the iOS
@@ -91,12 +105,26 @@ 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 4b.ii/iii — AR frame-processor JSI fan-out.  The JNI
+    # binding (stitcher_jsi_install_jni.cpp) installs
+    # `globalThis.__stitcherProxy` and fans each AR frame out to the
+    # registered host worklets.  The 4 shared cpp/ JSI files below are
+    # the SAME source the iOS pod compiles — one cross-platform JSI
+    # surface (proxy host object + native worklet registry + per-frame
+    # dispatch helper + StitcherFrame JSI host object).
+    stitcher_jsi_install_jni.cpp
+    "${SHARED_CPP_DIR}/stitcher_proxy_jsi.cpp"
+    "${SHARED_CPP_DIR}/stitcher_worklet_registry.cpp"
+    "${SHARED_CPP_DIR}/stitcher_worklet_dispatch.cpp"
+    "${SHARED_CPP_DIR}/stitcher_frame_jsi.cpp")
 
 target_include_directories(image_stitcher PRIVATE
     "${OPENCV_INCLUDE_DIR}"
     # cpp/ holds keyframe_gate.hpp + ar_frame_pose.h that the JNI
-    # bindings include without relative-path spelunking.
+    # bindings include without relative-path spelunking.  Also the
+    # shared JSI sources (stitcher_proxy_jsi.hpp, stitcher_frame_data.hpp,
+    # stitcher_worklet_*.hpp, stitcher_frame_jsi.hpp).
     "${SHARED_CPP_DIR}")
 
 # Link order matters:
@@ -118,7 +146,22 @@ target_link_libraries(image_stitcher
     opencv_stitching
     -Wl,--no-whole-archive
     opencv_java
-    log)
+    log
+    # v0.8.0 Phase 4b.ii/iii — JSI fan-out deps.  Mirrors
+    # react-native-vision-camera's link set on RN 0.84.1:
+    #   ReactAndroid::jsi         — facebook::jsi::Runtime / Value / Object
+    #   ReactAndroid::reactnative — RN's native-modules umbrella prefab
+    #                               (RN >= 0.76; CallInvoker + friends that
+    #                               worklets-core's context depends on)
+    #   fbjni::fbjni              — JNI helpers worklets-core links against
+    #   react-native-worklets-core::rnworklets — JsiWorkletContext +
+    #                               WorkletInvoker.  Carries its own
+    #                               include dir so <react-native-worklets-core/
+    #                               WKTJsiWorkletContext.h> resolves.
+    ReactAndroid::jsi
+    ReactAndroid::reactnative
+    fbjni::fbjni
+    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/RNImageStitcherPackage.kt

@@ -101,6 +101,12 @@ class RNImageStitcherPackage : ReactPackage {
             RNSARSession(reactContext),
             IncrementalStitcher(reactContext),
             FileBridge(reactContext),
+            // v0.8.0 Phase 4b.ii — surfaces `NativeModules.StitcherJsiInstaller`
+            // so JS' `ensureStitcherProxyInstalled()` can call its
+            // blocking-sync `install()` to install `globalThis.__stitcherProxy`
+            // on the main JS runtime (AR frame-processor host-worklet
+            // registration).  Mirror of iOS' StitcherJsiInstaller.
+            StitcherJsiInstallerModule(reactContext),
         )
     }
 

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

@@ -383,17 +383,30 @@ class RNSARCameraView @JvmOverloads constructor(
             cameraPosWorld,
         )
 
+        // v0.8.0 Phase 4b.iii — ensure the host-worklet runtime is
+        // installed before any per-frame fan-out can run.  Idempotent
+        // (AtomicBoolean CAS): the first frame starts the dispatch
+        // thread; every later frame is a single atomic read.  Kept on
+        // the GL thread because that's the only thread guaranteed to
+        // run once the AR session is live.
+        StitcherWorkletRuntime.installIfNeeded()
+
         // Push pose into the AR session log.  Mirrors iOS' delegate
         // path; the existing RNSARFramePose / appendPose
         // contract was already in place for Phase 4.
         appendPose(camera, frame.timestamp)
 
-        // Forward to the incremental stitcher only when capture is
-        // engaged.  (The v0.8.0 host-worklet dispatch — which also
-        // forwarded preview frames whenever host worklets were
-        // registered — was archived in the 2026-06 batch-keyframe
-        // cleanup.)
-        if (ingestActive) {
+        // Forward to the incremental stitcher when capture is engaged,
+        // OR when an AR frame-processor host worklet is registered (the
+        // v0.8.0 Phase 4b.iii fan-out forwards preview frames whenever
+        // host worklets exist, even with capture off — the host worklet
+        // observes the live AR stream).  `forwardToIncremental` does the
+        // NV21 pack once and gates the first-party ingest internally on
+        // `ingestActive`; the host-worklet dispatch is gated on the
+        // native registry count.  `hasHostWorklets()` is a cheap atomic
+        // read (microseconds) so the common capture-off / no-worklet
+        // preview path stays near-free.
+        if (ingestActive || StitcherWorkletRuntime.hasHostWorklets()) {
             forwardToIncremental(frame, camera)
         }
 
@@ -656,6 +669,42 @@ class RNSARCameraView @JvmOverloads constructor(
             },
         )
         }  // closes `if (ingestActive)` (v0.8.0 Phase 4b.iii)
+
+        // ── v0.8.0 Phase 4b.iii — AR frame-processor host-worklet fan-out ──
+        //
+        // After the first-party stitching ingest (above), fan the SAME
+        // already-packed NV21 frame + pose out to every host worklet the
+        // JS `arFrameProcessor` registered via `__stitcherProxy.install`.
+        // This is independent of `ingestActive`: a host worklet observes
+        // the live AR stream whether or not the user has engaged capture
+        // (the onDrawFrame gate already let us in when host worklets
+        // exist).  `dispatchToHostWorklets` does a cheap native
+        // registry-count fast-path early-exit + (only when worklets are
+        // registered) copies the bytes into an owned native buffer and
+        // dispatches asynchronously on worklets-core's default context,
+        // so the GL render thread is NOT blocked on worklet execution.
+        //
+        // We reuse `packed.nv21` (full NV21: Y plane then interleaved
+        // VU) + `qarr` / `tArr` (already read above) — no extra Image
+        // hold, no second pack.  ARCore camera pose is full 6DoF, so
+        // translation is always valid.
+        val arTracking = when (camera.trackingState) {
+            TrackingState.TRACKING -> "normal"
+            TrackingState.PAUSED -> "limited"
+            TrackingState.STOPPED -> "notAvailable"
+            else -> "notAvailable"
+        }
+        StitcherWorkletRuntime.dispatchToHostWorklets(
+            nv21Bytes = packed.nv21,
+            width = packed.width,
+            height = packed.height,
+            qx = qarr[0].toDouble(), qy = qarr[1].toDouble(),
+            qz = qarr[2].toDouble(), qw = qarr[3].toDouble(),
+            tx = tArr[0].toDouble(), ty = tArr[1].toDouble(),
+            tz = tArr[2].toDouble(),
+            timestampNs = frame.timestamp.toDouble(),
+            trackingState = arTracking,
+        )
     }
 
     /// v0.13.2 — map the JS physical device orientation to the