react-native-image-stitcher 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -14,6 +14,36 @@ 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.19.0] — 2026-06-19
+
+### Added — Native AR frame-processor plugins
+
+AR-mode `<Camera>` can now run **native per-frame plugins** with zero-copy
+access to the AR frame — the foundation for on-device CV (OCR, object
+detection, reconstruction feeds) **without** baking that domain code into the
+SDK. The SDK ships only the generic framework; plugins live in your app.
+
+- **Plugin interface:** implement `RNISARFramePlugin` (iOS) / `ARFramePlugin`
+  (Android) — `name()` + `process(context)`.
+- **`ARFrameContext`** hands the plugin the frame **zero-copy**: the camera
+  buffer, `pose`, `intrinsics`, tracking state, timestamp, and — when the
+  matching `enable*` prop is on — `depth` + `anchors`. The buffer is valid
+  **only during `process()`**; copy it before offloading to another thread.
+- **Register at startup:** `RNISARPluginRegistry.shared.register(…)` (iOS) /
+  `RNSARPluginRegistry.register(…)` (Android). The SDK invokes registered
+  plugins per AR frame, gated on a **non-empty registry** — zero-plugin apps
+  pay nothing.
+- **Two result channels:** light **synchronous** `process()` returns fold into
+  `onArFrame`'s `ARFrameMeta.plugins` (keyed by plugin name); heavy / **async**
+  results are pushed via `registry.emit(name, result)` → the new
+  **`onArPluginResult`** callback prop (delivered off the AR thread — for slow
+  work like OCR that must not block frame capture).
+- The example ships a sample `FrameBrightnessPlugin` (both platforms),
+  surfaced live in the AR overlay.
+
+Device-verified on iPhone 16 Pro. The SDK stays dependency-light — no OCR / ML
+runtimes are added to core.
+
 ## [0.18.0] — 2026-06-18
 
 ### ⚠️ Breaking — `StitcherFrame` → `CameraFrame`

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

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+package io.imagestitcher.rn
+
+/**
+ * 0.19.0 — zero-copy native view of one ARCore frame, handed to every
+ * registered [ARFramePlugin.process] (iOS twin: `RNISARFrameContext`).
+ *
+ * The SDK builds ONE of these per AR frame — only when [RNSARPluginRegistry]
+ * is non-empty — from the SAME `ARCore Frame` + pose the `onArFrame` meta
+ * path uses, then passes it to each plugin in turn.  Zero-plugin apps never
+ * pay for the build.
+ *
+ * ## Camera image
+ *
+ * ARCore hands the SDK a `YUV_420_888` camera image which is already packed
+ * into a contiguous JVM-side NV21 byte array ([nv21]) before the ARCore
+ * `Image` is closed (the SDK does this once per frame for its own stitch /
+ * worklet paths — we reuse it here, no extra acquire).  Layout:
+ *   - bytes `[0 .. width*height)`              = Y plane (luminance), dense,
+ *                                                row stride = [width]
+ *   - bytes `[width*height .. width*height*3/2)` = interleaved V-U chroma
+ * [yPlane] is a convenience read-only window onto just the Y plane.
+ *
+ * ## Lifetime — COPY BEFORE OFFLOADING
+ *
+ * [nv21] / [yPlane] / [depthBytes] are the SDK's own arrays, reused on the
+ * next frame.  They are valid ONLY for the duration of the synchronous
+ * [ARFramePlugin.process] call.  A plugin that hands bytes to another
+ * thread (async OCR, network upload, etc.) **MUST copy** them first
+ * (`bytes.copyOf()`), or it will read torn/overwritten data on the next AR
+ * frame.
+ *
+ * @property nv21            Full NV21 camera image (Y plane then interleaved VU).
+ * @property width           Camera image width (px).
+ * @property height          Camera image height (px).
+ * @property timestampNs      ARCore frame timestamp (nanoseconds).
+ * @property fx              Focal length x (px, at capture resolution).
+ * @property fy              Focal length y (px).
+ * @property cx              Principal point x (px).
+ * @property cy              Principal point y (px).
+ * @property imageWidth      Intrinsics reference image width (px).
+ * @property imageHeight     Intrinsics reference image height (px).
+ * @property poseRotation    Camera pose rotation quaternion `[x, y, z, w]`.
+ * @property poseTranslation Camera pose translation `[x, y, z]` (metres, world).
+ * @property trackingState   Contract enum string: "normal" | "limited" | "notAvailable".
+ * @property depthBytes      Row-packed DEPTH16 (uint16/px, w*h*2 bytes) or null
+ *                           (null unless `enableDepth` AND depth available this frame).
+ * @property depthWidth      Depth map width (px), 0 when [depthBytes] is null.
+ * @property depthHeight     Depth map height (px), 0 when [depthBytes] is null.
+ * @property anchors         Anchor descriptor maps already collected for the
+ *                           `onArFrame` event (empty unless `enableAnchors`).
+ *                           Each map: { id, type, transform[16 row-major],
+ *                           alignment?, extent? } — same shape the JS
+ *                           `ARAnchor` contract uses.
+ */
+class ARFrameContext(
+    @JvmField val nv21: ByteArray,
+    @JvmField val width: Int,
+    @JvmField val height: Int,
+    @JvmField val timestampNs: Double,
+    @JvmField val fx: Double,
+    @JvmField val fy: Double,
+    @JvmField val cx: Double,
+    @JvmField val cy: Double,
+    @JvmField val imageWidth: Int,
+    @JvmField val imageHeight: Int,
+    @JvmField val poseRotation: DoubleArray,
+    @JvmField val poseTranslation: DoubleArray,
+    @JvmField val trackingState: String,
+    @JvmField val depthBytes: ByteArray? = null,
+    @JvmField val depthWidth: Int = 0,
+    @JvmField val depthHeight: Int = 0,
+    @JvmField val anchors: List<Map<String, Any?>> = emptyList(),
+) {
+    /**
+     * Read-only window onto JUST the Y (luminance) plane of [nv21] — the
+     * first `width * height` bytes.  Cheap (no copy): a sliced, read-only
+     * [java.nio.ByteBuffer] over the same backing array.  Convenient for
+     * plugins that only need luma (brightness, simple CV gates).
+     *
+     * Like [nv21], valid only during [ARFramePlugin.process]; copy before
+     * offloading.
+     */
+    val yPlane: java.nio.ByteBuffer
+        get() = java.nio.ByteBuffer
+            .wrap(nv21, 0, width * height)
+            .slice()
+            .asReadOnlyBuffer()
+}

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

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: Apache-2.0
+package io.imagestitcher.rn
+
+import com.facebook.react.bridge.WritableMap
+
+/**
+ * 0.19.0 — Android AR frame-processor plugin SPI (Swift twin:
+ * `ios/Sources/RNImageStitcher/RNISARFramePlugin.swift`).
+ *
+ * Mirrors vision-camera's `FrameProcessorPlugin` registration ergonomics:
+ * the *host app* implements this interface, registers an instance with
+ * [RNSARPluginRegistry] at startup, and the SDK invokes [process] for every
+ * ARCore frame while the registry is non-empty.  The SDK ships ONLY this
+ * generic framework — no OCR or any other concrete plugin (the host writes
+ * those against this contract).
+ *
+ * ## Threading & lifetime
+ *
+ * [process] runs on the **AR (GL render) thread**, synchronously, once per
+ * ARCore frame.  The [ARFrameContext] handed in is a zero-copy view onto
+ * the live frame — its byte buffers (`yPlane` / `nv21` / depth `bytes`) are
+ * the SDK's own arrays and are reused on subsequent frames.  A plugin that
+ * offloads heavy work to another thread **MUST copy** any bytes it needs
+ * before returning from [process] (see [ARFrameContext]).
+ *
+ * ## Sync vs async results
+ *
+ *  - Return a non-null [WritableMap] for a *light, synchronous* result.  The
+ *    SDK folds it into the throttled `onArFrame` `ARFrameMeta` event under
+ *    `plugins[name]`, so it rides the existing channel for free.
+ *  - Return `null` and call [RNSARPluginRegistry.emit] later (from the
+ *    plugin's own queue) to deliver an *async* result over the dedicated
+ *    `RNImageStitcherARPluginResult` device event.
+ *
+ * Plugins are responsible for their own throttling / work-offloading — the
+ * SDK calls [process] on EVERY AR frame while the registry is non-empty.
+ */
+interface ARFramePlugin {
+    /**
+     * Stable, unique name for this plugin.  Used as the key under
+     * `ARFrameMeta.plugins` for sync results and as the `plugin` field of
+     * the `RNImageStitcherARPluginResult` event for async results.  The JS
+     * side keys off this string, so keep it stable across app launches.
+     */
+    fun name(): String
+
+    /**
+     * Process one ARCore frame.  Return a light synchronous result map
+     * (folded into the `onArFrame` event) or `null` (no sync result — emit
+     * later via [RNSARPluginRegistry.emit] if needed).
+     *
+     * Runs on the AR thread.  Do NOT block: self-throttle and offload heavy
+     * work.  Copy any [ARFrameContext] byte buffers you retain past the
+     * call.
+     */
+    fun process(context: ARFrameContext): WritableMap?
+}

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

@@ -398,28 +398,46 @@ class RNSARCameraView @JvmOverloads constructor(
         // contract was already in place for Phase 4.
         appendPose(camera, frame.timestamp)
 
-        // onArFrame (v0.18.0) — LIGHT AR-metadata event channel.  Built
-        // + emitted INDEPENDENTLY of the stitcher ingest / host-worklet
-        // fan-out below: a host that only wants per-frame AR metadata
-        // (no capture, no worklet) still gets it.  Gated + throttled
-        // internally; near-free (one volatile read + one nanoTime
-        // compare) when disabled or inside the throttle window.
-        maybeEmitArFrameMeta(frame, camera)
-
         // 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
+        // observes the live AR stream), OR when a native AR plugin is
+        // registered (0.19.0 — `forwardToIncremental` builds the
+        // ARFrameContext + runs the plugins; their SYNC results are stashed
+        // for the onArFrame meta below).  `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()) {
+        // `ingestActive`; the host-worklet dispatch is gated on the native
+        // worklet registry count; the plugin invocation on the plugin
+        // registry.  All three checks are cheap atomic reads so the common
+        // idle preview path (no capture, no worklet, no plugin) stays
+        // near-free.
+        //
+        // ORDER (0.19.0): run forwardToIncremental BEFORE maybeEmitArFrameMeta
+        // so the native-plugin SYNC results computed in the former are
+        // available to fold into the onArFrame `plugins` field built in the
+        // latter (same render frame).
+        if (ingestActive ||
+            StitcherWorkletRuntime.hasHostWorklets() ||
+            !RNSARPluginRegistry.isEmpty()
+        ) {
             forwardToIncremental(frame, camera)
+        } else {
+            // No consumer this frame — make sure last frame's stashed plugin
+            // sync results don't leak into a later onArFrame meta.
+            lastPluginSyncResults = null
         }
 
+        // onArFrame (v0.18.0) — LIGHT AR-metadata event channel.  Built
+        // + emitted INDEPENDENTLY of the stitcher ingest / host-worklet
+        // fan-out above: a host that only wants per-frame AR metadata
+        // (no capture, no worklet) still gets it.  Gated + throttled
+        // internally; near-free (one volatile read + one nanoTime
+        // compare) when disabled or inside the throttle window.  Native-
+        // plugin SYNC results (0.19.0) stashed by forwardToIncremental
+        // above ride along under the meta's `plugins` field.
+        maybeEmitArFrameMeta(frame, camera)
+
         // takePhoto consumer — runs on EVERY render tick (not just
         // when ingest is active), since the host calls takePhoto in
         // photo mode where ingest is off.  No-op when no request is
@@ -813,6 +831,132 @@ class RNSARCameraView @JvmOverloads constructor(
             anchorAlignments = anchorAlignments,
             anchorExtents = anchorExtents,
         )
+
+        // ── 0.19.0 — native AR-plugin per-frame invocation ───────────────
+        //
+        // Mirror of iOS' RNSARSession.session(_:didUpdate:) plugin loop.
+        // Only build the ARFrameContext + call plugins when the registry is
+        // NON-EMPTY (the onDrawFrame gate already let us in via that check,
+        // but a worklet-only frame can reach here with an empty plugin
+        // registry — re-check so those frames pay nothing).  Runs on the AR
+        // (GL render) thread, synchronously.  Reuses the already-packed
+        // `packed.nv21`, the depth/anchors collected above, and the pose +
+        // intrinsics already read — no extra Image acquire, no second pack.
+        // Depth is passed ONLY when the host opted into enableDepth (a
+        // mesh-only host acquired depth for its mesh, but the contract says
+        // the context's depth is null unless enableDepth).
+        runArPlugins(
+            packed, qarr, tArr, arTracking, frame, intrinsics, anchors,
+            depth = if (flags.depth) depth else null,
+        )
+    }
+
+    /// 0.19.0 — last frame's native-plugin SYNC results, keyed by plugin
+    /// name.  Written by [runArPlugins] on the GL render thread, read by
+    /// [maybeEmitArFrameMeta] on the same thread one step later in the same
+    /// onDrawFrame tick.  Null = no plugins ran / no sync results this
+    /// frame.  Single-threaded handoff (both on the GL thread) so no
+    /// synchronisation is needed, but @Volatile is cheap insurance against
+    /// any future cross-thread read.
+    @Volatile
+    private var lastPluginSyncResults: Map<String, Any?>? = null
+
+    /**
+     * 0.19.0 — build one [ARFrameContext] from the current frame and invoke
+     * every registered [ARFramePlugin].
+     *
+     *  - Non-null SYNC results are collected into a `{ name -> result }` map
+     *    and stashed in [lastPluginSyncResults] for [maybeEmitArFrameMeta]
+     *    to fold into the onArFrame `plugins` field this same tick.
+     *  - A plugin returning `null` defers to the ASYNC channel
+     *    ([RNSARPluginRegistry.emit] → `RNImageStitcherARPluginResult`).
+     *
+     * A throwing plugin is isolated (logged, skipped) so one bad plugin
+     * can't take down the AR render loop.
+     *
+     * Reuses caller-collected data (no extra Image work):
+     * @param packed     the already-packed NV21 camera image.
+     * @param qarr       pose rotation quaternion [x,y,z,w].
+     * @param tArr       pose translation [x,y,z] (world metres).
+     * @param tracking   contract tracking string ("normal"|"limited"|"notAvailable").
+     * @param frame      the ARCore frame (for the timestamp).
+     * @param intrinsics camera intrinsics (fx,fy,cx,cy + image dims).
+     * @param anchors    anchor descriptors already collected for onArFrame
+     *                   (enableAnchors-gated; empty otherwise).
+     * @param depth      row-packed DEPTH16 or null (enableDepth-gated).
+     */
+    private fun runArPlugins(
+        packed: YuvImageConverter.PackedYuv,
+        qarr: FloatArray,
+        tArr: FloatArray,
+        tracking: String,
+        frame: com.google.ar.core.Frame,
+        intrinsics: com.google.ar.core.CameraIntrinsics,
+        anchors: List<ArAnchorData>,
+        depth: ArDepthData?,
+    ) {
+        val plugins = RNSARPluginRegistry.plugins()
+        if (plugins.isEmpty()) {
+            lastPluginSyncResults = null
+            return
+        }
+
+        // Flatten the already-collected anchor descriptors into plain maps
+        // (id/type/transform + optional alignment/extent) so plugins get the
+        // same shape as the JS `ARAnchor` contract without a JSI dependency.
+        val anchorMaps: List<Map<String, Any?>> =
+            if (anchors.isEmpty()) emptyList()
+            else anchors.map { a ->
+                val m = HashMap<String, Any?>(5)
+                m["id"] = a.id
+                m["type"] = a.type
+                m["transform"] = a.transform
+                if (a.alignment.isNotEmpty()) m["alignment"] = a.alignment
+                a.extent?.let { m["extent"] = it }
+                m
+            }
+
+        val ctx = ARFrameContext(
+            nv21 = packed.nv21,
+            width = packed.width,
+            height = packed.height,
+            timestampNs = frame.timestamp.toDouble(),
+            fx = intrinsics.focalLength[0].toDouble(),
+            fy = intrinsics.focalLength[1].toDouble(),
+            cx = intrinsics.principalPoint[0].toDouble(),
+            cy = intrinsics.principalPoint[1].toDouble(),
+            imageWidth = intrinsics.imageDimensions[0],
+            imageHeight = intrinsics.imageDimensions[1],
+            poseRotation = doubleArrayOf(
+                qarr[0].toDouble(), qarr[1].toDouble(),
+                qarr[2].toDouble(), qarr[3].toDouble(),
+            ),
+            poseTranslation = doubleArrayOf(
+                tArr[0].toDouble(), tArr[1].toDouble(), tArr[2].toDouble(),
+            ),
+            trackingState = tracking,
+            depthBytes = depth?.bytes,
+            depthWidth = depth?.width ?: 0,
+            depthHeight = depth?.height ?: 0,
+            anchors = anchorMaps,
+        )
+
+        var sync: HashMap<String, Any?>? = null
+        for (plugin in plugins) {
+            val result = try {
+                plugin.process(ctx)
+            } catch (t: Throwable) {
+                if (forwardLogTick % 30 == 1) {
+                    Log.w(TAG, "AR plugin '${plugin.name()}' threw in process(): ${t.message}")
+                }
+                null
+            }
+            if (result != null) {
+                if (sync == null) sync = HashMap()
+                sync[plugin.name()] = result
+            }
+        }
+        lastPluginSyncResults = sync
     }
 
     /// Packed DEPTH16 result: dense (no row padding) uint16-per-pixel
@@ -1186,6 +1330,31 @@ class RNSARCameraView @JvmOverloads constructor(
             meta.putNull("mesh")
         }
 
+        // ── plugins (0.19.0) — native-plugin SYNC results, if any ────────
+        //    `lastPluginSyncResults` was stashed by `runArPlugins` earlier
+        //    in THIS same onDrawFrame tick (forwardToIncremental runs before
+        //    maybeEmitArFrameMeta).  Each value is the WritableMap a plugin
+        //    returned from `process()`; we re-key it under `plugins[name]`.
+        //    Omitted entirely when no plugin produced a sync result (JS sees
+        //    `meta.plugins === undefined`), matching the optional `plugins?`
+        //    field in the ARFrameMeta contract.
+        val pluginResults = lastPluginSyncResults
+        if (!pluginResults.isNullOrEmpty()) {
+            val pluginsMap = com.facebook.react.bridge.Arguments.createMap()
+            for ((name, value) in pluginResults) {
+                when (value) {
+                    is com.facebook.react.bridge.WritableMap ->
+                        pluginsMap.putMap(name, value)
+                    null -> pluginsMap.putNull(name)
+                    // Defensive: a plugin should only ever return a
+                    // WritableMap, but never let an unexpected type crash the
+                    // emit — drop it.
+                    else -> { /* skip unsupported result type */ }
+                }
+            }
+            meta.putMap("plugins", pluginsMap)
+        }
+
         session.emitArFrameMeta(meta)
     }
 

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

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: Apache-2.0
+package io.imagestitcher.rn
+
+import android.util.Log
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import java.util.concurrent.CopyOnWriteArrayList
+
+/**
+ * 0.19.0 — process-wide registry of [ARFramePlugin]s (iOS twin:
+ * `RNISARPluginRegistry`).
+ *
+ * The host app registers native plugins HERE at startup (typically from its
+ * `MainApplication.onCreate`); the SDK's AR per-frame path
+ * ([RNSARCameraView.forwardToIncremental]) reads [plugins] each frame and,
+ * when the list is non-empty, builds one [ARFrameContext] and calls every
+ * plugin's [ARFramePlugin.process].
+ *
+ * Doubles as the **async result channel**: a plugin that returned `null`
+ * from `process` (deferring heavy work to its own queue) calls [emit] later
+ * to deliver its result to JS over the `RNImageStitcherARPluginResult`
+ * device event.
+ *
+ * ## Threading
+ *
+ * Backed by a [CopyOnWriteArrayList], so [register] / [unregister] (usually
+ * on the main thread at startup) never race the AR thread's [plugins] read.
+ * [emit] is safe from any thread — it routes through the singleton
+ * [RNSARSession]'s React context, which guards a torn-down Catalyst
+ * instance internally.
+ */
+object RNSARPluginRegistry {
+
+    private const val TAG = "RNSARPluginRegistry"
+
+    /// Event name carrying an ASYNC plugin result to JS.  MUST match the
+    /// iOS `supportedEvents` entry + the TS `NativeEventEmitter`
+    /// subscription string exactly.
+    const val AR_PLUGIN_RESULT_EVENT = "RNImageStitcherARPluginResult"
+
+    private val registered = CopyOnWriteArrayList<ARFramePlugin>()
+
+    /**
+     * Register a plugin.  Idempotent by [ARFramePlugin.name]: registering a
+     * plugin whose name matches an existing one REPLACES the old instance
+     * (so a host re-registering on a JS reload doesn't accumulate
+     * duplicates).  Safe to call from any thread.
+     */
+    @JvmStatic
+    fun register(plugin: ARFramePlugin) {
+        val name = plugin.name()
+        // Drop any prior plugin with the same name, then add the new one.
+        registered.removeAll { it.name() == name }
+        registered.add(plugin)
+        Log.i(TAG, "register: '$name' (now ${registered.size} plugin(s))")
+    }
+
+    /**
+     * Unregister the plugin with the given [name] (no-op if none match).
+     * Safe to call from any thread.
+     */
+    @JvmStatic
+    fun unregister(name: String) {
+        val removed = registered.removeAll { it.name() == name }
+        if (removed) Log.i(TAG, "unregister: '$name' (now ${registered.size} plugin(s))")
+    }
+
+    /**
+     * Snapshot of the currently-registered plugins.  Read once per AR frame
+     * by the SDK; the [CopyOnWriteArrayList] makes iteration race-free
+     * against concurrent [register] / [unregister].
+     */
+    @JvmStatic
+    fun plugins(): List<ARFramePlugin> = registered
+
+    /** Cheap fast-path read for the AR thread: "do we have any plugins?". */
+    @JvmStatic
+    fun isEmpty(): Boolean = registered.isEmpty()
+
+    /**
+     * Emit an ASYNC plugin result to JS over the
+     * `RNImageStitcherARPluginResult` device event.
+     *
+     * Event body: `{ plugin: <pluginName>, result: <result> }` — the same
+     * shape the TS `onArPluginResult` prop consumes.  Routes through the
+     * singleton [RNSARSession]'s `DeviceEventManagerModule` emitter (the
+     * SAME channel `onArFrame` uses), so RN drops the event when no JS
+     * listener is attached and a torn-down Catalyst instance is swallowed
+     * silently.
+     *
+     * Safe from any thread (the plugin's own work queue, typically).
+     *
+     * @param pluginName the emitting plugin's [ARFramePlugin.name].
+     * @param result     the plugin's result map (consumed by JS verbatim).
+     */
+    @JvmStatic
+    fun emit(pluginName: String, result: WritableMap) {
+        val session = RNSARSession.instance
+        if (session == null) {
+            Log.d(TAG, "emit('$pluginName'): no RNSARSession instance yet — dropping")
+            return
+        }
+        val body: WritableMap = Arguments.createMap().apply {
+            putString("plugin", pluginName)
+            putMap("result", result)
+        }
+        session.emitArPluginResult(body)
+    }
+}

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

@@ -928,6 +928,28 @@ class RNSARSession(reactContext: ReactApplicationContext)
         }
     }
 
+    /**
+     * Emit a pre-built ASYNC plugin-result body to JS over the
+     * `RNImageStitcherARPluginResult` device event (0.19.0).  Called from
+     * [RNSARPluginRegistry.emit] — the body is `{ plugin, result }`.
+     *
+     * Reuses the SAME `DeviceEventManagerModule.RCTDeviceEventEmitter`
+     * channel as [emitArFrameMeta]; RN drops the event when no JS listener
+     * is attached, and a torn-down Catalyst instance is swallowed silently
+     * (plugin results are best-effort).
+     */
+    internal fun emitArPluginResult(body: com.facebook.react.bridge.WritableMap) {
+        try {
+            reactApplicationContext
+                .getJSModule(
+                    com.facebook.react.modules.core.DeviceEventManagerModule.RCTDeviceEventEmitter::class.java,
+                )
+                .emit(AR_PLUGIN_RESULT_EVENT, body)
+        } catch (t: Throwable) {
+            Log.d(TAG, "emitArPluginResult: emit failed (ignoring): ${t.message}")
+        }
+    }
+
     /// Required by RN's `NativeEventEmitter` contract — the TS
     /// `onArFrame` wiring constructs a `NativeEventEmitter` over this
     /// module, which calls `addListener`/`removeListeners` on subscribe /
@@ -1071,6 +1093,12 @@ class RNSARSession(reactContext: ReactApplicationContext)
         /// match the shared contract + the iOS `supportedEvents` entry +
         /// the TS `NativeEventEmitter` subscription string exactly.
         const val AR_FRAME_META_EVENT = "RNImageStitcherARFrame"
+
+        /// Event name carrying an ASYNC plugin result to JS (0.19.0).
+        /// MUST match [RNSARPluginRegistry.AR_PLUGIN_RESULT_EVENT], the
+        /// iOS `supportedEvents` entry, and the TS subscription string.
+        const val AR_PLUGIN_RESULT_EVENT =
+            RNSARPluginRegistry.AR_PLUGIN_RESULT_EVENT
     }
 
     init {

package/dist/camera/ARCameraView.d.ts

@@ -31,7 +31,7 @@
 import React from 'react';
 import { type ViewStyle } from 'react-native';
 import type { CameraFrameProcessor } from '../stitching/CameraFrame';
-import type { ARFrameMeta } from '../stitching/ARFrameMeta';
+import type { ARFrameMeta, ARPluginResult } from '../stitching/ARFrameMeta';
 export interface ARCameraViewProps {
     /** Layout style, typically `StyleSheet.absoluteFill` or `flex: 1`. */
     style?: ViewStyle;
@@ -116,6 +116,27 @@ export interface ARCameraViewProps {
      * (≈ 10 Hz).  No effect unless `onArFrame` is provided.
      */
     arFrameMetaInterval?: number;
+    /**
+     * v0.19.0 — ASYNCHRONOUS AR-plugin result callback, invoked on the JS MAIN
+     * thread (NOT a worklet).  Part of the AR plugin framework: host-registered
+     * native plugins (see `RNISARPluginRegistry` / `RNSARPluginRegistry`) can
+     * offload heavy per-frame work to their own queue and later push a result
+     * via `registry.emit(name, result)`.  The SDK routes that to JS as a
+     * `RNImageStitcherARPluginResult` device event; when this prop is provided,
+     * this component subscribes and invokes the handler with
+     * `{ plugin, result }`.
+     *
+     * SYNCHRONOUS plugin results (computed inline on the AR thread) instead ride
+     * the throttled {@link onArFrame} event on {@link ARFrameMeta.plugins} —
+     * read them there.  This callback is ONLY for the out-of-band async channel.
+     *
+     * The subscription is independent of {@link onArFrame}: a host can read
+     * sync results via `onArFrame` and async results via `onArPluginResult`,
+     * either, or both.  Wiring mirrors `onArFrame` exactly (latest handler held
+     * in a ref so the subscription effect depends only on whether a handler is
+     * present; cleanup on unmount / when the handler is removed).
+     */
+    onArPluginResult?: (e: ARPluginResult) => void;
 }
 /**
  * Imperative handle exposed via the ref — shape mirrors the subset

package/dist/camera/ARCameraView.js

@@ -77,7 +77,7 @@ const ensureStitcherProxyInstalled_1 = require("../stitching/ensureStitcherProxy
 const NativeARCameraView = react_native_1.Platform.OS === 'ios' || react_native_1.Platform.OS === 'android'
     ? (0, react_native_1.requireNativeComponent)('RNSARCameraView')
     : null;
-exports.ARCameraView = (0, react_1.forwardRef)(function ARCameraView({ style, guidance, arFrameProcessor, enableDepth, enableAnchors, enableMesh, planeDetection, onArFrame, arFrameMetaInterval, }, ref) {
+exports.ARCameraView = (0, react_1.forwardRef)(function ARCameraView({ style, guidance, arFrameProcessor, enableDepth, enableAnchors, enableMesh, planeDetection, onArFrame, arFrameMetaInterval, onArPluginResult, }, ref) {
     // Held across the start→stop lifecycle so stopRecording's
     // resolved VideoFile can be delivered via the same callback
     // pair vision-camera uses.
@@ -170,6 +170,41 @@ exports.ARCameraView = (0, react_1.forwardRef)(function ARCameraView({ style, gu
             session.setArFrameMetaEnabled?.(false, intervalMs);
         };
     }, [arFrameEnabled, arFrameMetaInterval]);
+    // v0.19.0 — onArPluginResult device-event wiring (worklet-free, main
+    // thread).  Mirrors the onArFrame subscription above: the latest handler
+    // is held in a ref so the subscription effect depends only on WHETHER a
+    // handler is present, not its (per-render-changing) identity — so the
+    // native event subscription isn't torn down + re-established every render.
+    //
+    // This is a PURELY-JS subscription: unlike onArFrame there's no native
+    // "enable" toggle to flip.  Native emits `RNImageStitcherARPluginResult`
+    // whenever a registered plugin calls `registry.emit(...)`; the registry is
+    // empty unless the host registered plugins, so an app with no plugins
+    // never sees an event even if this prop is wired.
+    const onArPluginResultRef = (0, react_1.useRef)(onArPluginResult);
+    (0, react_1.useEffect)(() => {
+        onArPluginResultRef.current = onArPluginResult;
+    }, [onArPluginResult]);
+    const arPluginResultEnabled = onArPluginResult != null;
+    (0, react_1.useEffect)(() => {
+        if (!arPluginResultEnabled) {
+            return undefined;
+        }
+        const native = react_native_1.NativeModules
+            .RNSARSession;
+        if (native == null) {
+            // Native module unavailable (e.g. web, or a native build predating
+            // the plugin event channel): no-op, no crash.
+            return undefined;
+        }
+        const emitter = new react_native_1.NativeEventEmitter(native);
+        const sub = emitter.addListener('RNImageStitcherARPluginResult', (e) => {
+            onArPluginResultRef.current?.(e);
+        });
+        return () => {
+            sub.remove();
+        };
+    }, [arPluginResultEnabled]);
     (0, react_1.useImperativeHandle)(ref, () => ({
         takePhoto: async (options = {}) => {
             const native = react_native_1.NativeModules.RNSARSession;