react-native-image-stitcher 0.18.0 → 0.20.0

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

@@ -0,0 +1,177 @@
+// 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
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * 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>()
+
+    // ── 0.20.0 — native-plugin overlay path ──────────────────────────────
+    //
+    // A native plugin can place AR overlays DIRECTLY (native→native, zero JS
+    // latency) via [setOverlays] / [addOverlay] / [removeOverlay] /
+    // [clearOverlays].  These write the **plugin namespace** of the bound
+    // view's [AROverlayStore]; the renderer draws the UNION of plugin + JS
+    // overlays, so a JS `setOverlays` never clobbers plugin overlays (and
+    // vice-versa).
+    //
+    // We CACHE the latest plugin overlay set here so a view that binds AFTER
+    // a plugin placed overlays (e.g. plugin registered + overlays set in
+    // MainApplication.onCreate, before any ARCameraView mounts) still picks
+    // them up — [RNSARCameraView] replays the cache into its store when it
+    // binds (see [currentPluginOverlays]).
+    private val pluginOverlays = AtomicReference<List<AROverlayData>>(emptyList())
+
+    /**
+     * Replace the ENTIRE native-plugin overlay set.  Merges with (does NOT
+     * clobber) JS-set overlays — the renderer draws the union.  Safe from
+     * any thread (a plugin's own work queue, typically).
+     *
+     * @param overlays the plugin overlays to render (an empty list clears
+     *                 the plugin namespace; JS overlays untouched).
+     */
+    @JvmStatic
+    fun setOverlays(overlays: List<AROverlayData>) {
+        pluginOverlays.set(overlays.toList())
+        boundStore()?.setPluginOverlays(overlays)
+    }
+
+    /** Add or replace one plugin overlay by id. */
+    @JvmStatic
+    fun addOverlay(overlay: AROverlayData) {
+        pluginOverlays.updateAndGet { cur ->
+            val idx = cur.indexOfFirst { it.id == overlay.id }
+            if (idx < 0) cur + overlay else cur.toMutableList().also { it[idx] = overlay }
+        }
+        boundStore()?.addPluginOverlay(overlay)
+    }
+
+    /** Remove one plugin overlay by id (no-op if unknown). */
+    @JvmStatic
+    fun removeOverlay(id: String) {
+        pluginOverlays.updateAndGet { cur -> cur.filterNot { it.id == id } }
+        boundStore()?.removePluginOverlay(id)
+    }
+
+    /** Clear ALL plugin overlays (JS overlays untouched). */
+    @JvmStatic
+    fun clearOverlays() {
+        pluginOverlays.set(emptyList())
+        boundStore()?.clearPluginOverlays()
+    }
+
+    /**
+     * The cached plugin overlay set — replayed into a freshly-bound view's
+     * store so plugins that placed overlays before any view mounted still
+     * render.  Called by [RNSARCameraView.onAttachedToWindow].
+     */
+    @JvmStatic
+    internal fun currentPluginOverlays(): List<AROverlayData> = pluginOverlays.get()
+
+    /// The bound AR camera view's overlay store, or null when no view is
+    /// mounted yet (overlays land in the cache until one binds).
+    private fun boundStore(): AROverlayStore? =
+        RNSARSession.instance?.boundOverlayStore()
+
+    /**
+     * 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

@@ -186,6 +186,91 @@ class RNSARSession(reactContext: ReactApplicationContext)
         arFrameMetaLastEmitNs = 0L
     }
 
+    // ── 0.20.0 — AR overlay/annotation imperative API ────────────────────
+    //
+    // JS-facing methods backing the `<Camera>` / `<ARCameraView>` ref's
+    // overlay API (setOverlays / addOverlay / updateOverlay / removeOverlay /
+    // clearOverlays) AND the declarative `overlays` prop (which TS funnels
+    // through `setOverlays`).  Each forwards to the bound AR camera view's
+    // [AROverlayStore] JS namespace; the renderer draws the UNION of these
+    // and any native-plugin overlays.  Fire-and-forget (no Promise) — mirrors
+    // the other config-prop setters (setPlaneDetection, lockPortrait).
+    //
+    // No-op (logged) when no AR camera view is bound — the host called an
+    // overlay method before mounting <ARCameraView>; the next mount will NOT
+    // auto-replay JS overlays (unlike plugin overlays), so the host should
+    // set overlays after mount (the declarative `overlays` prop does this
+    // naturally via its mount effect).
+
+    @ReactMethod
+    fun setOverlays(overlays: com.facebook.react.bridge.ReadableArray?) {
+        val view = attachedView ?: run {
+            Log.d(TAG, "setOverlays: no AR camera view bound — ignoring")
+            return
+        }
+        view.setOverlaysFromJs(AROverlayData.fromReadableArray(overlays))
+    }
+
+    @ReactMethod
+    fun addOverlay(overlay: com.facebook.react.bridge.ReadableMap?) {
+        val view = attachedView ?: run {
+            Log.d(TAG, "addOverlay: no AR camera view bound — ignoring")
+            return
+        }
+        val parsed = AROverlayData.fromReadableMap(overlay) ?: run {
+            Log.w(TAG, "addOverlay: malformed overlay (no id / no anchor) — ignoring")
+            return
+        }
+        view.addOverlayFromJs(parsed)
+    }
+
+    @ReactMethod
+    fun updateOverlay(id: String?, patch: com.facebook.react.bridge.ReadableMap?) {
+        if (id.isNullOrEmpty() || patch == null) {
+            Log.w(TAG, "updateOverlay: missing id or patch — ignoring")
+            return
+        }
+        val view = attachedView ?: run {
+            Log.d(TAG, "updateOverlay: no AR camera view bound — ignoring")
+            return
+        }
+        view.updateOverlayFromJs(id, patch)
+    }
+
+    @ReactMethod
+    fun removeOverlay(id: String?) {
+        if (id.isNullOrEmpty()) return
+        val view = attachedView ?: run {
+            Log.d(TAG, "removeOverlay: no AR camera view bound — ignoring")
+            return
+        }
+        view.removeOverlayFromJs(id)
+    }
+
+    @ReactMethod
+    fun clearOverlays() {
+        val view = attachedView ?: run {
+            Log.d(TAG, "clearOverlays: no AR camera view bound — ignoring")
+            return
+        }
+        view.clearOverlaysFromJs()
+    }
+
+    // v0.20.0 — raycast from the screen-centre crosshair to the nearest real
+    // surface; resolves `{ worldPosition: [x,y,z] }` or null.  The hitTest
+    // needs the live ARCore frame on the GL thread, so the view fulfils it on
+    // the next render tick.  Resolves null (not reject) when no view is bound
+    // so the JS controller falls back to its fixed 1 m-ahead placement.
+    @ReactMethod
+    fun raycast(promise: Promise) {
+        val view = attachedView ?: run {
+            Log.d(TAG, "raycast: no AR camera view bound — resolving null")
+            promise.resolve(null)
+            return
+        }
+        view.requestRaycast(promise)
+    }
+
     @ReactMethod
     fun isSupported(promise: Promise) {
         // `checkAvailability` can return UNKNOWN_CHECKING if the
@@ -892,12 +977,26 @@ class RNSARSession(reactContext: ReactApplicationContext)
 
     internal fun bindCameraView(view: RNSARCameraView) {
         attachedView = view
+        // 0.20.0 — replay any plugin overlays placed BEFORE this view
+        // mounted (e.g. from MainApplication.onCreate) so they render
+        // immediately.  Plugin overlays live in the plugin namespace; JS
+        // overlays (set via the imperative API) survive across remounts on
+        // the view's own store, so we don't touch them here.
+        val cached = RNSARPluginRegistry.currentPluginOverlays()
+        if (cached.isNotEmpty()) {
+            view.overlayStore.setPluginOverlays(cached)
+        }
     }
 
     internal fun unbindCameraView(view: RNSARCameraView) {
         if (attachedView === view) attachedView = null
     }
 
+    /// 0.20.0 — the bound AR camera view's overlay store, or null when no
+    /// view is mounted.  Used by [RNSARPluginRegistry] to push native-plugin
+    /// overlays into the live renderer.
+    internal fun boundOverlayStore(): AROverlayStore? = attachedView?.overlayStore
+
     /**
      * Emit a pre-built [ARFrameMeta] WritableMap to JS over the shared
      * `RNImageStitcherARFrame` device event.  Called from
@@ -928,6 +1027,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 +1192,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,9 @@
 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';
+import type { AROverlay } from '../stitching/AROverlay';
+import { type AROverlayMethods } from './arOverlayController';
 export interface ARCameraViewProps {
     /** Layout style, typically `StyleSheet.absoluteFill` or `flex: 1`. */
     style?: ViewStyle;
@@ -116,6 +118,52 @@ 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;
+    /**
+     * v0.20.0 — AR OVERLAY / ANNOTATION renderer.  A declarative array of 2D
+     * shapes the native overlay layer draws ON TOP of the AR camera preview,
+     * each anchored to WORLD positions and REPROJECTED to screen on every AR
+     * frame from the current camera pose + intrinsics (smooth, display-rate
+     * tracking; no 3D engine).
+     *
+     * State-driven: pass a React-state array and update it as your world points
+     * change.  The set is diffed against the current overlays BY `id` (add /
+     * update / remove), so re-passing the same ids is cheap.  Each render pushes
+     * the resolved array to native via `RNSARSession.setOverlays`.
+     *
+     * For zero-render-latency / fire-and-forget mutations use the imperative ref
+     * methods instead ({@link ARCameraViewHandle.setOverlays} etc.) — both paths
+     * funnel through the same native channel and stay consistent.  JS-set
+     * overlays are merged on the native side with any overlays a registered AR
+     * plugin placed directly (`RNISARPluginRegistry.setOverlays` /
+     * `RNSARPluginRegistry.setOverlays`); the two sets are namespaced so neither
+     * clobbers the other.
+     *
+     * See {@link AROverlay} for the shape (single world point + size, or explicit
+     * world quad; `outline` / `box`; optional label + colour; `mode:'3d'` is a
+     * documented scaffold this release and renders as `'2d'`).
+     */
+    overlays?: AROverlay[];
 }
 /**
  * Imperative handle exposed via the ref — shape mirrors the subset
@@ -127,8 +175,13 @@ export interface ARCameraViewProps {
  * Note we do NOT exhaustively mirror vision-camera's API surface —
  * only the methods the panorama capture flow uses today.  As the
  * SDK grows AR-aware features, methods are added here.
+ *
+ * v0.20.0 — also exposes the imperative AR-overlay methods
+ * ({@link AROverlayMethods}: `setOverlays` / `addOverlay` / `updateOverlay` /
+ * `removeOverlay` / `clearOverlays`) so a host can drive overlays without a
+ * render (the declarative `overlays` prop is the React-state alternative).
  */
-export interface ARCameraViewHandle {
+export interface ARCameraViewHandle extends AROverlayMethods {
     /**
      * Capture the latest ARFrame as a JPEG.  Resolves with a
      * vision-camera-compatible PhotoFile (`{ path, width, height,

package/dist/camera/ARCameraView.js

@@ -68,6 +68,7 @@ exports.ARCameraView = void 0;
 const react_1 = __importStar(require("react"));
 const react_native_1 = require("react-native");
 const ensureStitcherProxyInstalled_1 = require("../stitching/ensureStitcherProxyInstalled");
+const arOverlayController_1 = require("./arOverlayController");
 // React Native looks up the component by its NATIVE name.
 //   iOS: comes from `ARCameraViewManager.m`'s
 //        `RCT_EXTERN_MODULE(RNSARCameraViewManager, RCTViewManager)`.
@@ -77,11 +78,21 @@ 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, overlays, }, ref) {
     // Held across the start→stop lifecycle so stopRecording's
     // resolved VideoFile can be delivered via the same callback
     // pair vision-camera uses.
     const recordingCallbacksRef = (0, react_1.useRef)(null);
+    // v0.20.0 — AR overlay controller (shared logic with <Camera>).  One
+    // instance per mount holds the JS-set overlay collection (keyed by id) and
+    // pushes the full array to native on every mutation.  Both the declarative
+    // `overlays` prop (effect below) and the imperative ref methods drive it,
+    // so the two APIs can never diverge.
+    const overlayControllerRef = (0, react_1.useRef)(null);
+    if (overlayControllerRef.current == null) {
+        overlayControllerRef.current = (0, arOverlayController_1.createAROverlayController)();
+    }
+    const overlayController = overlayControllerRef.current;
     // AR frame-processor registration.  Installs the native
     // `__stitcherProxy` (idempotent) and registers the host worklet so
     // the AR session's per-frame fan-out invokes it; unregisters on
@@ -170,7 +181,62 @@ 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]);
+    // v0.20.0 — declarative `overlays` prop → native.  Each render pushes the
+    // resolved array through the controller (which replaces the JS-set
+    // collection wholesale and dispatches to `RNSARSession.setOverlays`).  The
+    // controller dedups identical native dispatches at the wire level is NOT
+    // attempted here — React only re-runs this when `overlays` identity
+    // changes, and native overlay set is cheap (a handful of shapes).  When the
+    // prop is omitted we DON'T touch the controller, so a host driving overlays
+    // purely imperatively (via the ref) isn't clobbered by an undefined prop.
+    (0, react_1.useEffect)(() => {
+        if (overlays == null) {
+            return;
+        }
+        overlayController.setOverlays(overlays);
+    }, [overlays, overlayController]);
     (0, react_1.useImperativeHandle)(ref, () => ({
+        setOverlays: overlayController.setOverlays,
+        addOverlay: overlayController.addOverlay,
+        updateOverlay: overlayController.updateOverlay,
+        removeOverlay: overlayController.removeOverlay,
+        clearOverlays: overlayController.clearOverlays,
+        raycast: overlayController.raycast,
         takePhoto: async (options = {}) => {
             const native = react_native_1.NativeModules.RNSARSession;
             if (!native?.takePhoto) {
@@ -214,7 +280,7 @@ exports.ARCameraView = (0, react_1.forwardRef)(function ARCameraView({ style, gu
                 callbacks.onRecordingError?.(err);
             }
         },
-    }), []);
+    }), [overlayController]);
     if (!NativeARCameraView
         || (react_native_1.Platform.OS !== 'ios' && react_native_1.Platform.OS !== 'android')) {
         // Web / unsupported platforms get a clear "not available here"

package/dist/camera/Camera.d.ts

@@ -42,7 +42,9 @@ import React from 'react';
 import { type StyleProp, type ViewStyle } from 'react-native';
 import type { DrawableFrameProcessor, ReadonlyFrameProcessor } from 'react-native-vision-camera';
 import type { CameraFrameProcessor } from '../stitching/CameraFrame';
-import type { ARFrameMeta } from '../stitching/ARFrameMeta';
+import type { ARFrameMeta, ARPluginResult } from '../stitching/ARFrameMeta';
+import type { AROverlay } from '../stitching/AROverlay';
+import type { AROverlayMethods } from './arOverlayController';
 import { type CaptureHeaderProps } from './CaptureHeader';
 import { type CapturePreviewAction } from './CapturePreview';
 import { type CaptureThumbnailItem } from './CaptureThumbnailStrip';
@@ -656,6 +658,44 @@ export interface CameraProps {
      * (≈ 10 Hz).  No effect unless `onArFrame` is provided.
      */
     arFrameMetaInterval?: number;
+    /**
+     * v0.19.0 — ASYNCHRONOUS AR-plugin result callback (the AR plugin
+     * framework), invoked on the JS MAIN thread (NOT a worklet).  Only fires in
+     * AR capture (`captureSource === 'ar'`).  Host-registered native plugins
+     * (see `RNISARPluginRegistry` / `RNSARPluginRegistry`) that offload heavy
+     * per-frame work to their own queue push results via
+     * `registry.emit(name, result)`; `<Camera>` threads this handler to
+     * `<ARCameraView>`, which subscribes to the `RNImageStitcherARPluginResult`
+     * device event and invokes it with `{ plugin, result }`.
+     *
+     * SYNCHRONOUS plugin results (computed inline on the AR thread) instead ride
+     * the throttled {@link onArFrame} event on {@link ARFrameMeta.plugins}.
+     * Use `onArFrame` for the in-band sync channel and `onArPluginResult` for
+     * the out-of-band async channel — a host can wire either or both.
+     *
+     * The SDK ships ONLY the generic plugin framework; there are no built-in
+     * plugins, so this never fires unless the host registers native plugins.
+     */
+    onArPluginResult?: (e: ARPluginResult) => void;
+    /**
+     * v0.20.0 — AR OVERLAY / ANNOTATION renderer.  A declarative array of 2D
+     * shapes drawn ON TOP of the AR camera preview, each anchored to WORLD
+     * positions and REPROJECTED to screen on every AR frame from the current
+     * camera pose + intrinsics (smooth display-rate tracking, no 3D engine).
+     * Only meaningful in AR capture (`captureSource === 'ar'`); `<Camera>`
+     * threads this straight through to the underlying `<ARCameraView>`.
+     *
+     * State-driven: pass a React-state array and update it as your world points
+     * change (e.g. from {@link CameraProps.onArFrame} plane anchors).  The set is
+     * diffed against the current overlays BY `id`.  For zero-render-latency
+     * mutations use the imperative ref methods on the `<Camera>` handle instead
+     * ({@link CameraHandle}: `setOverlays` / `addOverlay` / `updateOverlay` /
+     * `removeOverlay` / `clearOverlays`) — both paths funnel through the same
+     * native channel.  JS-set overlays merge on the native side with overlays a
+     * registered AR plugin placed directly (namespaced so neither clobbers the
+     * other).  See {@link AROverlay} for the shape.
+     */
+    overlays?: AROverlay[];
     /**
      * Which device holds the non-AR panorama capture accepts.
      *
@@ -734,10 +774,33 @@ export interface CameraProps {
      */
     guidanceCopy?: Partial<GuidanceCopy>;
 }
+/**
+ * v0.20.0 — imperative handle exposed via the `<Camera>` ref.
+ *
+ * Currently scoped to the AR-overlay methods ({@link AROverlayMethods}:
+ * `setOverlays` / `addOverlay` / `updateOverlay` / `removeOverlay` /
+ * `clearOverlays`), which forward to the underlying `<ARCameraView>`'s overlay
+ * channel when AR mode is mounted.  They are no-ops while the camera is in
+ * non-AR mode (no `<ARCameraView>` is mounted, and overlays only render over
+ * the AR preview) — use the declarative {@link CameraProps.overlays} prop for
+ * a set that survives AR↔non-AR transitions, since it re-applies automatically
+ * whenever `<ARCameraView>` (re)mounts.
+ *
+ * The shape is identical to {@link ARCameraViewHandle}'s overlay subset so a
+ * host can use either component with the same overlay code.  Photo / panorama
+ * capture remain driven by the built-in shutter (no imperative capture methods
+ * on this handle — see the component docstring's scope note).
+ */
+export interface CameraHandle extends AROverlayMethods {
+}
 /**
  * The public `<Camera>` component.
+ *
+ * v0.20.0 — now a `forwardRef`.  The ref exposes {@link CameraHandle} (the AR
+ * overlay methods); existing callers that don't pass a ref are unaffected
+ * (`forwardRef` makes the ref optional).
  */
-export declare function Camera(props: CameraProps): React.JSX.Element;
+export declare const Camera: React.ForwardRefExoticComponent<CameraProps & React.RefAttributes<CameraHandle>>;
 /**
  * v0.12.0 — JS edge corresponding to the physical home-indicator
  * side of the device.  This is where the shutter + controls anchor