react-native-image-stitcher 0.16.2 → 0.17.0

package/CHANGELOG.md

@@ -14,6 +14,39 @@ 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)

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

@@ -301,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

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

@@ -0,0 +1,103 @@
+// 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")
+        }
+    }
+}