react-native-image-stitcher 0.14.1 → 0.15.0

package/src/index.ts

@@ -39,6 +39,12 @@ export type {
   FramesDroppedInfo,
 } from './camera/Camera';
 
+// Recoverable-stitch-failure → friendly Alert copy.  Hosts call this in
+// their onError handler to surface actionable guidance ("pan more slowly",
+// "pivot in place") instead of the raw cv::Stitcher diagnostic.
+export { userFacingStitchError } from './camera/cameraErrorMessages';
+export type { UserFacingStitchError } from './camera/cameraErrorMessages';
+
 // ─────────────────────────────────────────────────────────────────────
 // AR foundation (public since 0.1.0)
 // ─────────────────────────────────────────────────────────────────────
@@ -128,8 +134,6 @@ export type { PanoramaSettingsModalProps } from './camera/PanoramaSettingsModal'
 export {
   DEFAULT_PANORAMA_SETTINGS,
   DEFAULT_FLOW_GATE_SETTINGS,
-  DEFAULT_SLITSCAN_SETTINGS,
-  DEFAULT_HYBRID_SETTINGS,
 } from './camera/PanoramaSettings';
 export type {
   CaptureBaseSettings,
@@ -137,14 +141,6 @@ export type {
   BatchStitcherSettings,
   FrameSelectionSettings,
   FlowGateSettings,
-  SlitscanSettings,
-  SlitscanPaintingSettings,
-  SlitscanRegistrationSettings,
-  SlitscanAdvancedSettings,
-  Ncc1dSettings,
-  Ncc2dSettings,
-  PlaneProjectionSettings,
-  HybridSettings,
 } from './camera/PanoramaSettings';
 
 // Settings → native config adapters.  Layer 2 hosts building their
@@ -153,8 +149,6 @@ export type {
 // the single source of truth for the JS↔native wire format.
 export {
   panoramaSettingsToNativeConfig,
-  slitscanSettingsToNativeConfig,
-  hybridSettingsToNativeConfig,
 } from './camera/PanoramaSettingsBridge';
 export type { NativeConfigDict } from './camera/PanoramaSettingsBridge';
 export { ViewportCropOverlay } from './camera/ViewportCropOverlay';
@@ -206,34 +200,11 @@ export type {
   StitcherFrameProcessor,
   ARAnchor,
 } from './stitching/StitcherFrame';
-// v0.8.0 Phase 4a — public host-worklet hook.  Hosts that want a
-// per-frame callback (OCR overlay, packet detection, ML inference)
-// use this to attach a `'worklet'`-prefixed function that fires
-// on the camera producer thread.  Non-AR mode is fully wired
-// today via vision-camera passthrough; AR-mode dispatch is
-// API-stable but registration-only until Phase 4b lands the
-// cross-runtime handoff (the AR runtime iterating the registry).
-// See the hook's docstring + StitcherFrame.ts for the contract.
-export { useFrameProcessor } from './stitching/useFrameProcessor';
-// v0.9.0 Layer 2 — `useThrottledFrameProcessor`.  Throttle gate over
-// `useFrameProcessor` for sub-frame-rate worklet-native processing
-// (native OCR via Vision.framework / ML Kit, TFLite ML detection,
-// LiDAR depth).  The worklet runtime has direct access to
-// `frame.toArrayBuffer()` / `frame.arDepth`; bridge small payloads
-// (bboxes, depth-derived metrics) to JS via `runOnJS`.  For JS-thread
-// JPEG consumers (file-path OCR libs, cloud upload, thumbnail UI),
-// prefer `useFrameStream` (Layer 3, ships in the same release).
-export { useThrottledFrameProcessor } from './stitching/useThrottledFrameProcessor';
-export type { ThrottledFrameProcessorOptions } from './types';
-// v0.9.0 Layer 3 — `useFrameStream`.  JS-thread sampled-frame
-// stream over Layer 1 (`save_frame_as_jpeg` vc plugin) + Layer 2
-// (`useThrottledFrameProcessor`).  Use for JS-thread consumers:
-// file-path OCR libs (RN modules), cloud upload, thumbnail UI.
-// For worklet-native processing (Vision/ML Kit as vc plugins,
-// TFLite ML, LiDAR depth), prefer `useThrottledFrameProcessor`
-// (Layer 2) — lower latency, no JPEG roundtrip.
-export { useFrameStream } from './stitching/useFrameStream';
-export type { FrameStreamOptions, SampledFrame } from './types';
+// NOTE: the host-worklet / frame-stream hooks `useFrameProcessor`,
+// `useThrottledFrameProcessor` and `useFrameStream` (v0.8–v0.9) were
+// archived in the batch-keyframe cleanup — they drove the third-party
+// `__stitcherProxy` observer API, not batch-keyframe capture. Source is
+// preserved under archive/src/stitching/ to build on later.
 // vision-camera Frame Processor driver for non-AR captures.  As
 // of v0.6 the only non-AR driver exported (the legacy
 // `useIncrementalJSDriver` was removed; was deprecated in v0.5).

package/src/stitching/incremental.ts

@@ -422,9 +422,9 @@ export interface IncrementalStartOptions {
    * 'slitscan' fall back to 'slitscan-both' with a deprecation warning
    * in the native log.
    */
-  engine?: 'hybrid' | 'slitscan-rotate' | 'slitscan-both' | 'batch-keyframe' |
-           // Deprecated — kept for type-compat during the V14 → V15 transition:
-           'firstwins' | 'firstwins-zoomed' | 'firstwins-rectilinear' | 'slitscan';
+  // Only 'batch-keyframe' remains; the live engines were archived in the
+  // batch-keyframe cleanup (see archive/).
+  engine?: 'batch-keyframe';
   /**
    * V15 — per-stage correction config overrides.  Mode-driven defaults
    * are applied first (see RLISStitcherConfig +configForMode:); fields
@@ -441,143 +441,6 @@ export interface IncrementalStartOptions {
  * fields optional (omit to accept the engine-mode default).
  */
 export interface StitcherConfig {
-  // Slit shaping (slit-scan engine only)
-  /** Fraction of pan-axis the rectilinear slit retains per frame.
-   *  Range 0.10 – 0.70, default 0.30 in V15 slit-scan modes. */
-  kPanAxisFractionRect: number;
-  /** Minimum pan-axis advance (px) before a frame is accepted.
-   *  0 = accept on every consumeFrame (Apple-dense slit-scan, V15
-   *  default).  50 = V13.0g default. */
-  kMinAcceptDeltaPx: number;
-
-  // Per-stage correction toggles
-  /** V13.0e+ ORB triangulation + median-Z parallax correction. */
-  enableTriangulation: boolean;
-  /** V13.0g per-accept incremental Δt accumulator on top of triangulation. */
-  enableTriAccumulator: boolean;
-  /** V15 1D NCC perpendicular-axis wobble correction (slitscan-rotate
-   *  default).  Independent of the other correction stages. */
-  enable1dNcc: boolean;
-  /** 1D NCC search radius in pixels (5 – 60). */
-  nccSearchRadius1d: number;
-  /** V13.0g 2D NCC fine-alignment after triangulation. */
-  enable2dNcc: boolean;
-  /** V14.0a RANSAC homography per slit + cv::warpPerspective.  When
-   *  enabled and successful, supersedes the rectangular paste path. */
-  enableRansacHomography: boolean;
-
-  // Paint mode (slit-scan engine only)
-  /** 'FirstPaintedWins' protects already-painted pixels (V13.0e+
-   *  default).  'FeatherBlend' alpha-blends new content into already-
-   *  painted overlap pixels (V13.0d-style; V15 slitscan-both default). */
-  paintMode: 'FirstPaintedWins' | 'FeatherBlend';
-
-  // Hybrid engine
-  /** 'Cylindrical' (V12.x – V14.0a behaviour) or 'Planar' (V15 default;
-   *  cv::detail::PlaneWarper).  Planar is well-behaved for pans <60°. */
-  hybridProjection: 'Cylindrical' | 'Planar';
-
-  /** V15.0c — where on the camera frame the per-accept sliver is taken.
-   *  'Center' (V13.x default), 'Bottom' (leading edge for top-to-bottom
-   *  pan), or 'Top' (leading edge for bottom-to-top pan). */
-  sliverPosition: 'Center' | 'Bottom' | 'Top';
-
-  /** V15.0c — when true, the FIRST accepted frame paints the entire
-   *  camera frame at canvas (0, 0); subsequent frames still use the
-   *  configured sliver clip.  Default false; set true when sliverPosition
-   *  is Bottom/Top so the canvas is anchored with full-frame content. */
-  firstFrameFullFrame: boolean;
-
-  /** **DEPRECATED in V15.0d** — use `planeSource` instead.
-   *
-   *  V15.0b boolean toggle for the plane-projected stitch path.
-   *  Kept for backward compat: when `planeSource` is left at its
-   *  default (Disabled), `useDetectedPlane = true` upgrades it to
-   *  ARKitDetected.  New callers should set `planeSource` directly. */
-  useDetectedPlane: boolean;
-
-  /** V15.0d — source of the plane used by the V15.0b plane-projected
-   *  stitch path.
-   *
-   *  - 'Disabled' (default): no plane projection; slit-scan path runs.
-   *  - 'ARKitDetected': use ARKit's first vertical plane that aligns
-   *    with the camera's view direction (filter threshold:
-   *    `arkitPlaneAlignmentThreshold`).  Falls back to slit-scan
-   *    silently when no aligned plane is found.
-   *  - 'Virtual': synthesize a plane at first frame: origin =
-   *    camera_pos + `virtualPlaneDepthMeters` × camera_forward;
-   *    normal = -camera_forward.  Always works; no ARKit dependency.
-   *
-   *  Field testing showed ARKit plane detection often picks the WRONG
-   *  surface (side wall, doorframe) — Virtual mode is the safer
-   *  default for arbitrary scenes.  ARKitDetected wins when ARKit
-   *  finds the correct fixture face. */
-  planeSource: 'Disabled' | 'ARKitDetected' | 'Virtual';
-
-  /** V15.0d — depth (metres) at which the synthetic plane is placed
-   *  in front of the camera when `planeSource = Virtual`.  Set to
-   *  the user's typical scan distance.  Range 0.3 – 5.0 m.  Default
-   *  1.5 m. */
-  virtualPlaneDepthMeters: number;
-
-  /** V15.0d — minimum dot product between an ARKit-detected plane's
-   *  surface normal and the camera's facing direction for the plane
-   *  to be accepted (when `planeSource = ARKitDetected`).  1.0 =
-   *  plane perfectly facing camera; 0.0 = plane edge-on; negative
-   *  = facing away.  Range 0.0 – 1.0.  Default 0.6 (≈53° max angle
-   *  off-camera). */
-  arkitPlaneAlignmentThreshold: number;
-
-  /** V15.0g — how the plane-projection helper renders each frame onto
-   *  the canvas.  Affects ARKitDetected and Virtual modes; ignored
-   *  when planeSource = Disabled.
-   *
-   *  - 'Trapezoidal' (V15.0b legacy): geometrically-correct 3D
-   *    raycast.  Each camera pixel maps to its plane intersection.
-   *    Result is a trapezoid that grows distorted with tilt
-   *    (cooler-bottom-2.3×-wider-than-top problem).
-   *  - 'Rectified' (V15.0g default): camera frame pasted as a clean
-   *    rectangle around its plane-projected anchor.  Eliminates the
-   *    tilt-induced trapezoidal distortion at the cost of strict 3D-
-   *    correctness — the camera's per-pixel perspective stays inside
-   *    the rectangle but doesn't reconcile across tilts. */
-  planeProjectionStyle: 'Trapezoidal' | 'Rectified';
-
-  /** V15.0d — 2D NCC search half-window in pixels.  Was hardcoded
-   *  ±12 in V15.0c.4.  Smaller = less wandering on repetitive
-   *  textures (peg holes, slatted panels), but easier to miss the
-   *  true overlap when pose noise is high.  Range 4 – 30.  Default
-   *  12. */
-  nccSearchMargin2d: number;
-
-  /** V15.0d — 2D NCC confidence threshold below which the correction
-   *  is rejected.  Was hardcoded 0.75 in V15.0c.4.  Higher = stricter,
-   *  fewer false matches on repetitive textures, but more frames
-   *  where NCC silently doesn't fire.  Range 0.30 – 0.99.  Default
-   *  0.75. */
-  nccConfidenceThreshold2d: number;
-
-  /** V15.0d (1B) — exponential-moving-average smoothing on 2D NCC
-   *  corrections.  When enabled, the applied correction is
-   *  `α × current + (1−α) × prev` instead of just `current`.  Damps
-   *  single-frame snaps to spurious peaks.  Default false. */
-  enableNcc2dEmaSmoothing: boolean;
-
-  /** V15.0d — EMA weight on the CURRENT-frame NCC correction
-   *  (1 − α weight on the previous correction).  Range 0.05 – 0.95.
-   *  Default 0.4 (60% prev / 40% current — heavy damping). */
-  ncc2dEmaAlpha: number;
-
-  /** V15.0d (1C) — pan-axis-aware 2D NCC.  When enabled, the cross-
-   *  axis (perpendicular to pan) NCC correction is clamped tighter
-   *  than the pan-axis (since 1D NCC + pose already handle cross-
-   *  axis wobble).  Default false. */
-  enableNcc2dPanAxisLock: boolean;
-
-  /** V15.0d — cross-axis clamp (pixels) for the pan-axis-aware mode.
-   *  Range 0 – 30.  Default 5. */
-  ncc2dCrossAxisLockPx: number;
-
   // Frame selection (V16)
 
   /** V16 — how the engine decides which ARFrames to ingest.

package/src/stitching/stitchVideo.ts

@@ -76,32 +76,6 @@ export interface StitchVideoOptions {
    *     Right choice on low-RAM devices or with `feather`.
    */
   seamFinderType?: 'graphcut' | 'skip';
-  /**
-   * Phase 5: pose-driven stitching.  When present and non-empty,
-   * the native stitcher skips features → matching → BundleAdjuster
-   * and builds cv::detail::CameraParams directly from each pose's
-   * intrinsics + quaternion.  Each entry has the shape returned
-   * by `NativeModules.RNSARSession.snapshotPoseLog()`:
-   *
-   *   { tx, ty, tz, qx, qy, qz, qw,
-   *     fx, fy, cx, cy,
-   *     imageWidth, imageHeight,
-   *     timestampMs, trackingState }
-   *
-   * Frames whose closest pose is beyond a 100 ms tolerance are
-   * dropped before stitching; if fewer than 2 remain the call
-   * rejects with `opencv-failed-1032` so the host can fall back
-   * to the feature-matched path (re-call `stitchVideo` without
-   * `poses`).
-   */
-  poses?: Array<{
-    tx: number; ty: number; tz: number;
-    qx: number; qy: number; qz: number; qw: number;
-    fx: number; fy: number; cx: number; cy: number;
-    imageWidth: number; imageHeight: number;
-    timestampMs: number;
-    trackingState: number;
-  }>;
 }
 
 

package/src/types.ts

@@ -56,101 +56,6 @@ export interface DeviceMetadata {
 // `Camera.tsx` adapts this into the public `CameraCaptureResult` (a
 // discriminated union of photo + panorama) before emitting `onCapture`.
 
-/**
- * v0.9.0 Layer 3 — one sampled frame delivered by `useFrameStream`
- * to the JS-thread handler.
- *
- * The JPEG file at `jpegPath` is the stream's own copy.  Hosts that
- * need long-term retention MUST copy the file synchronously inside
- * the handler — the same path may be overwritten by a subsequent
- * sample (slot reuse — see the hook's docstring for the rotation
- * policy).
- */
-export interface SampledFrame {
-  /** Absolute filesystem path to the JPEG.  No `file://` prefix. */
-  jpegPath: string;
-
-  /**
-   * Pose at sample time.  `translation` is `undefined` in non-AR
-   * mode (gyro provides rotation only; no spatial anchor).
-   */
-  pose: {
-    rotation: [number, number, number, number];
-    translation?: [number, number, number];
-  };
-
-  /** Frame timestamp (ms; per the v0.8.0 StitcherFrame contract). */
-  timestamp: number;
-
-  /** JPEG width / height in pixels. */
-  width: number;
-  height: number;
-}
-
-/**
- * v0.9.0 Layer 3 — options for `useFrameStream`.
- *
- * For worklet-native processing without JPEG roundtrip (OCR via
- * Vision/ML Kit, TFLite ML, LiDAR depth), use
- * `useThrottledFrameProcessor` (Layer 2) instead.
- */
-export interface FrameStreamOptions {
-  /**
-   * Target sampling rate in Hertz.  Clamped to `[0.5, 10]`.  The
-   * Layer 2 throttle gate enforces the rate inside the worklet;
-   * ticks too close together are dropped silently.
-   *
-   * Clamp upper bound (10 Hz) is intentionally lower than Layer 2's
-   * (30 Hz) — beyond 10 Hz the per-frame JPEG encode + JS-bridge
-   * cost dominates the wall-clock budget.  Hosts that need higher
-   * rates should be on Layer 2 with their own JPEG encoder call
-   * (or no JPEG at all).
-   */
-  sampleHz: number;
-
-  /**
-   * JPEG quality (0-100).  Default 75.  Clamped silently to
-   * `[1, 100]` by the underlying `save_frame_as_jpeg` native plugin.
-   */
-  quality?: number;
-
-  /**
-   * Directory to write JPEG files into.  Defaults to a per-app
-   * `<cache>/rnis-frame-stream/` subdirectory.  The directory is
-   * `mkdir -p`'d on first use; hosts that supply an existing
-   * absolute path are responsible for its lifecycle.
-   */
-  outputDir?: string;
-}
-
-/**
- * v0.9.0 Layer 2 — options for `useThrottledFrameProcessor`.
- *
- * Wraps v0.8.0's `useFrameProcessor` with a monotonic-time throttle
- * gate so the supplied worklet fires at most `sampleHz` times per
- * second.  Use for sub-frame-rate worklet-native processing — native
- * OCR (Vision.framework / ML Kit), TFLite ML detection, LiDAR depth
- * processing — where the bbox / depth payloads are small enough to
- * bridge to JS via `runOnJS`.
- *
- * For JS-thread JPEG consumers (file-path OCR libraries, cloud
- * upload, thumbnail UI), use `useFrameStream` (Layer 3) instead.
- */
-export interface ThrottledFrameProcessorOptions {
-  /**
-   * Target sampling rate in Hertz.  Clamped to `[0.5, 30]`.  Inside
-   * the worklet a monotonic-time gate enforces the rate; ticks too
-   * close together are silently dropped.
-   *
-   * The clamp upper bound (30 Hz) sits at typical AR rates on
-   * mid-range Android devices — beyond that, the host should just
-   * use `useFrameProcessor` directly (no throttle).  The clamp
-   * lower bound (0.5 Hz) prevents accidentally-zero-divide values
-   * + matches `useFrameStream`'s convention.
-   */
-  sampleHz: number;
-}
-
 export interface CaptureResult {
   /** Unique device-generated UUID */
   deviceUuid: string;

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

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