react-native-image-stitcher 0.19.0 → 0.20.0

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

@@ -11,7 +11,9 @@ import android.util.Log
 import android.view.Surface
 import android.view.WindowManager
 import android.widget.FrameLayout
+import com.google.ar.core.Anchor
 import com.google.ar.core.Camera
+import com.google.ar.core.Pose
 import com.google.ar.core.Session
 import com.google.ar.core.TrackingState
 import com.google.ar.core.exceptions.CameraNotAvailableException
@@ -78,6 +80,38 @@ class RNSARCameraView @JvmOverloads constructor(
     private val backgroundRenderer = BackgroundRenderer()
     private val sessionRef = AtomicReference<Session?>(null)
     private var sessionTextureBound = false
+
+    // ── 0.20.0 — AR overlay/annotation renderer ─────────────────────────
+    //
+    // [overlayStore] is the single source of truth for the overlays to
+    // draw (UNION of JS-set + native-plugin-set; see [AROverlayStore]);
+    // [overlayRenderer] is the transparent Canvas View stacked ABOVE the
+    // GLSurfaceView in this FrameLayout.  Per frame, [onDrawFrame] snapshots
+    // the camera view/projection matrices + the letterbox box and pushes
+    // them into the renderer (which reprojects + redraws on the UI thread).
+    //
+    // The store is exposed (via [overlayStore] internal) so the native
+    // plugin path ([RNSARPluginRegistry.setOverlays] etc.) and the JS
+    // imperative path ([RNSARSession] @ReactMethods → bound view) both write
+    // to it; the JS imperative path uses the JS namespace, plugins the
+    // plugin namespace.
+    val overlayStore = AROverlayStore()
+    private val overlayRenderer = AROverlayRenderer(context, overlayStore)
+
+    // v0.20.0 — one ARCore Anchor per world-anchored overlay (parity with
+    // iOS' ARAnchor) so ARCore refines the pose against drift / re-localization
+    // instead of trusting a frozen world coordinate.  GL-thread only (created /
+    // read / detached inside [reconcileOverlayAnchors] from onDrawFrame).
+    private val overlayAnchors = HashMap<String, Anchor>()
+    // The source world point each anchor was created at — used to detect when
+    // an overlay's position changed (JS re-set it) and recreate the anchor.
+    private val overlayAnchorSrc = HashMap<String, FloatArray>()
+
+    // Scratch matrices for the per-frame overlay camera snapshot — reused
+    // each frame so the GL thread does no per-frame allocation when overlays
+    // are active.  ARCore returns COLUMN-MAJOR (OpenGL) matrices.
+    private val overlayViewMatrix = FloatArray(16)
+    private val overlayProjMatrix = FloatArray(16)
     /// Last known display rotation; consulted on each setDisplayGeometry
     /// call so we can recompute when the user rotates the device.
     private var lastDisplayRotation: Int = -1
@@ -131,6 +165,21 @@ class RNSARCameraView @JvmOverloads constructor(
         glView.requestRender()
     }
 
+    /// Pending crosshair raycast (v0.20.0).  Fulfilled on the next render
+    /// tick with the live ARCore frame — `Frame.hitTest` must run on the GL
+    /// thread, so a JS `raycast()` call can't resolve synchronously.
+    private val pendingRaycast =
+        AtomicReference<com.facebook.react.bridge.Promise?>(null)
+
+    /// Called from the bridge (RNSARSession.raycast @ReactMethod).  Stores a
+    /// promise fulfilled on the next render tick by hitTest from the screen
+    /// centre.  Supersedes any queued raycast.
+    internal fun requestRaycast(promise: com.facebook.react.bridge.Promise) {
+        val previous = pendingRaycast.getAndSet(promise)
+        previous?.resolve(null) // superseded → null (caller falls back)
+        glView.requestRender()
+    }
+
     init {
         // Black background avoids a flash before the GL surface starts
         // clearing itself black each frame (the GL-level letterbox draws
@@ -140,6 +189,14 @@ class RNSARCameraView @JvmOverloads constructor(
             glView,
             LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT),
         )
+        // 0.20.0 — overlay renderer stacked ABOVE the GLSurfaceView (added
+        // after glView so it draws on top).  Full-screen + transparent; it
+        // reprojects world overlays into the same letterbox box the camera
+        // feed fills, so its coordinate space matches the preview.
+        addView(
+            overlayRenderer,
+            LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT),
+        )
     }
 
     override fun onAttachedToWindow() {
@@ -215,6 +272,11 @@ class RNSARCameraView @JvmOverloads constructor(
         // Pause the GL thread so we stop drawing frames.
         glView.onPause()
         sessionTextureBound = false
+        // 0.20.0 — stop drawing overlays; we drop the camera snapshot so a
+        // stale pose isn't reused if the view re-attaches.  The overlay SET
+        // itself is left intact (the host may keep the same overlays across
+        // a remount); only the per-frame camera state is cleared.
+        overlayRenderer.clear()
         IncrementalStitcher.bridgeInstance?.unbindArCameraView(this)
         RNSARSession.instance?.unbindCameraView(this)
         // iOS parity (didMoveToWindow else-branch): stop the session
@@ -398,6 +460,18 @@ class RNSARCameraView @JvmOverloads constructor(
         // contract was already in place for Phase 4.
         appendPose(camera, frame.timestamp)
 
+        // ── 0.20.0 — feed the overlay renderer this frame's camera ───────
+        //
+        // Only when overlays exist (cheap AtomicReference emptiness check),
+        // snapshot the view + projection matrices and the letterbox box so
+        // the overlay View can reproject world points → screen and redraw.
+        // Runs every render frame so overlays track at display rate.
+        //
+        // First reconcile ARCore anchors + publish their drift-corrected poses
+        // so the renderer projects the refined positions, not frozen coords.
+        reconcileOverlayAnchors(session)
+        maybeUpdateOverlayCamera(camera, box)
+
         // 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
@@ -445,6 +519,65 @@ class RNSARCameraView @JvmOverloads constructor(
         pendingTakePhoto.getAndSet(null)?.let { req ->
             fulfilTakePhoto(frame, req)
         }
+
+        // raycast consumer (v0.20.0) — same pattern: a JS raycast() request
+        // is fulfilled here with the live frame's hitTest from the crosshair.
+        pendingRaycast.getAndSet(null)?.let { promise ->
+            fulfilRaycast(frame, camera, promise)
+        }
+    }
+
+    /// Raycast from the screen-centre crosshair to the nearest real-world
+    /// surface; resolve `{ worldPosition: [x,y,z] }` (or null when nothing is
+    /// hit / not tracking).  Runs on the GL render thread from onDrawFrame.
+    /// hitTest coordinates are in the `setDisplayGeometry` space — which we
+    /// feed the LETTERBOX BOX — so the crosshair is the box centre.  Mirrors
+    /// iOS `RNSARSession.raycast`; the JS controller falls back to a fixed
+    /// 1 m-ahead point when this resolves null.
+    private fun fulfilRaycast(
+        frame: com.google.ar.core.Frame,
+        camera: Camera,
+        promise: com.facebook.react.bridge.Promise,
+    ) {
+        try {
+            if (camera.trackingState != TrackingState.TRACKING) {
+                promise.resolve(null)
+                return
+            }
+            val box = letterboxBox()
+            val cx = box[2] / 2f // box width  / 2
+            val cy = box[3] / 2f // box height / 2
+            val hits = frame.hitTest(cx, cy)
+            // hits are sorted near→far.  Prefer a plane hit inside the
+            // detected polygon, then a depth / feature point, then any hit.
+            val hit = hits.firstOrNull { h ->
+                when (val t = h.trackable) {
+                    is com.google.ar.core.Plane ->
+                        t.trackingState == TrackingState.TRACKING &&
+                            t.isPoseInPolygon(h.hitPose)
+                    is com.google.ar.core.DepthPoint -> true
+                    is com.google.ar.core.Point -> true
+                    else -> false
+                }
+            } ?: hits.firstOrNull()
+            if (hit == null) {
+                promise.resolve(null)
+                return
+            }
+            val p = hit.hitPose
+            val wp = com.facebook.react.bridge.Arguments.createArray().apply {
+                pushDouble(p.tx().toDouble())
+                pushDouble(p.ty().toDouble())
+                pushDouble(p.tz().toDouble())
+            }
+            val result = com.facebook.react.bridge.Arguments.createMap().apply {
+                putArray("worldPosition", wp)
+            }
+            promise.resolve(result)
+        } catch (t: Throwable) {
+            Log.w(TAG, "raycast failed: ${t.message}")
+            promise.resolve(null)
+        }
     }
 
     /// Capture the current ARCore frame to JPEG and resolve / reject
@@ -547,6 +680,163 @@ class RNSARCameraView @JvmOverloads constructor(
         RNSARSession.instance?.updateTrackingState(camera.trackingState)
     }
 
+    /// v0.20.0 — keep one ARCore Anchor per world-anchored overlay so ARCore
+    /// refines its pose against drift / re-localization (parity with iOS'
+    /// ARAnchor).  Runs on the GL thread each frame: create anchors for new
+    /// overlays, recreate when an overlay's source pose changes, detach removed
+    /// ones, then publish the live anchor positions to the renderer (which uses
+    /// them instead of the frozen world coordinates).  Cheap no-op when there
+    /// are neither overlays nor lingering anchors.
+    private fun reconcileOverlayAnchors(session: Session) {
+        if (overlayStore.isEmpty() && overlayAnchors.isEmpty()) return
+
+        val overlays = overlayStore.snapshot()
+        val live = HashSet<String>(overlays.size)
+        val positions = HashMap<String, FloatArray>(overlays.size)
+
+        for (o in overlays) {
+            val target = anchorTarget(o) ?: continue
+            live.add(o.id)
+            val prev = overlayAnchorSrc[o.id]
+            if (prev == null || !prev.contentEquals(target)) {
+                // New overlay, or its position changed → (re)create the anchor.
+                overlayAnchors.remove(o.id)?.detach()
+                val anchor = try {
+                    session.createAnchor(
+                        Pose(target, floatArrayOf(0f, 0f, 0f, 1f)),
+                    )
+                } catch (t: Throwable) {
+                    Log.w(TAG, "createAnchor failed for '${o.id}': ${t.message}")
+                    null
+                }
+                if (anchor != null) {
+                    overlayAnchors[o.id] = anchor
+                    overlayAnchorSrc[o.id] = target.copyOf()
+                } else {
+                    overlayAnchorSrc.remove(o.id)
+                }
+            }
+            // Publish the live (tracking) anchor pose, else the source pose.
+            val a = overlayAnchors[o.id]
+            positions[o.id] = if (a != null && a.trackingState == TrackingState.TRACKING) {
+                val p = a.pose
+                floatArrayOf(p.tx(), p.ty(), p.tz())
+            } else {
+                overlayAnchorSrc[o.id] ?: target
+            }
+        }
+
+        // Detach anchors for overlays that no longer exist.
+        if (overlayAnchors.keys.any { it !in live }) {
+            for (id in overlayAnchors.keys.filter { it !in live }) {
+                overlayAnchors.remove(id)?.detach()
+                overlayAnchorSrc.remove(id)
+            }
+        }
+
+        overlayRenderer.setAnchorPositions(positions)
+    }
+
+    /// The world point to anchor an overlay at: its `worldPosition`, or the
+    /// centroid of its `worldQuad`.  null when it has no world geometry.
+    private fun anchorTarget(o: AROverlayData): FloatArray? {
+        o.worldPosition?.let { return it }
+        val q = o.worldQuad ?: return null
+        if (q.isEmpty()) return null
+        var cx = 0f; var cy = 0f; var cz = 0f
+        for (v in q) { cx += v[0]; cy += v[1]; cz += v[2] }
+        val n = q.size.toFloat()
+        return floatArrayOf(cx / n, cy / n, cz / n)
+    }
+
+    // ── 0.20.0 — per-frame overlay camera snapshot + JS imperative API ──
+
+    /**
+     * Snapshot this frame's camera view + projection matrices and the
+     * letterbox box into the [overlayRenderer], then trigger a redraw.
+     *
+     * Cheap no-op when no overlays are set (single AtomicReference
+     * emptiness check) so the common no-overlay preview path pays almost
+     * nothing.  ARCore's `getViewMatrix` / `getProjectionMatrix` are
+     * COLUMN-MAJOR (OpenGL) — exactly what `android.opengl.Matrix` and the
+     * renderer expect.  The near/far planes (0.05 m / 100 m) bound depth
+     * precision; they don't affect XY projection.
+     *
+     * @param camera the ARCore camera for this frame (pose + intrinsics).
+     * @param glBox  the letterbox box [x, y, w, h] in GL pixel space
+     *               (origin BOTTOM-left, as used by `glViewport`).  We flip
+     *               Y to the overlay View's TOP-left origin here.
+     */
+    private fun maybeUpdateOverlayCamera(camera: Camera, glBox: IntArray) {
+        if (overlayStore.isEmpty()) return
+
+        // ARCore projection matrix: near=0.05 m, far=100 m (matches the
+        // BackgroundRenderer's typical range; depth bounds only).
+        try {
+            camera.getViewMatrix(overlayViewMatrix, 0)
+            camera.getProjectionMatrix(overlayProjMatrix, 0, 0.05f, 100f)
+        } catch (t: Throwable) {
+            // Camera not ready (early frames) — skip this frame's overlay
+            // update; the feed keeps drawing and we retry next frame.
+            return
+        }
+
+        // GL viewport box → overlay View box.  GL origin is bottom-left;
+        // the View is top-left.  Both share surfaceWidth × surfaceHeight.
+        val boxX = glBox[0].toFloat()
+        val boxW = glBox[2].toFloat()
+        val boxH = glBox[3].toFloat()
+        val boxYTop = (surfaceHeight - (glBox[1] + glBox[3])).toFloat()
+
+        val tracking = camera.trackingState == TrackingState.TRACKING
+
+        overlayRenderer.updateCamera(
+            viewMatrix = overlayViewMatrix,
+            projectionMatrix = overlayProjMatrix,
+            boxX = boxX,
+            boxY = boxYTop,
+            boxW = boxW,
+            boxH = boxH,
+            tracking = tracking,
+        )
+    }
+
+    // ── JS imperative overlay API (forwarded from RNSARSession) ──────────
+    //
+    // The JS `ARCameraViewHandle` / `<Camera>` ref methods (setOverlays /
+    // addOverlay / updateOverlay / removeOverlay / clearOverlays) route
+    // through the singleton `RNSARSession` native module — the SAME idiom
+    // takePhoto uses — which forwards to the bound view's [overlayStore]
+    // (JS namespace).  These run on the bridge thread; the store's
+    // AtomicReferences make that safe against the GL thread's per-frame
+    // read.  An overlay set change triggers an immediate redraw so the
+    // overlay appears without waiting for the next AR frame's snapshot.
+
+    internal fun setOverlaysFromJs(overlays: List<AROverlayData>) {
+        overlayStore.setJsOverlays(overlays)
+        overlayRenderer.postInvalidateOnAnimation()
+    }
+
+    internal fun addOverlayFromJs(overlay: AROverlayData) {
+        overlayStore.addJsOverlay(overlay)
+        overlayRenderer.postInvalidateOnAnimation()
+    }
+
+    internal fun updateOverlayFromJs(id: String, patch: com.facebook.react.bridge.ReadableMap) {
+        overlayStore.updateJsOverlay(id, patch)
+        overlayRenderer.postInvalidateOnAnimation()
+    }
+
+    internal fun removeOverlayFromJs(id: String) {
+        overlayStore.removeJsOverlay(id)
+        overlayRenderer.postInvalidateOnAnimation()
+    }
+
+    internal fun clearOverlaysFromJs() {
+        overlayStore.clearJsOverlays()
+        overlayRenderer.postInvalidateOnAnimation()
+    }
+
     /// P3-G diagnostic — rate-limit the per-frame log so we can see
     /// at-a-glance whether forwardToIncremental is even running, vs
     /// being short-circuited at the `if (ingestActive)` guard in

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

@@ -1,8 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
 package io.imagestitcher.rn
 
+import com.facebook.react.bridge.ReadableArray
 import com.facebook.react.uimanager.SimpleViewManager
 import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.annotations.ReactProp
 
 /**
  * RN ViewManager for `RNSARCameraView`.
@@ -16,11 +18,19 @@ import com.facebook.react.uimanager.ThemedReactContext
  * in `src/camera/ARCameraView.tsx` which auto-selects the native
  * component for iOS vs Android.
  *
- * The view itself is config-free for now (no JS-side props beyond
- * `style`) since lifecycle is driven by mount/unmount + the
- * incremental stitcher's start/finalize methods.  Future phases may
- * add props like `enabled` to allow JS-controlled pause/resume of
- * the GL render loop.
+ * Props:
+ *   - `overlays` (0.20.0) — declarative `AROverlay[]` drawn on the AR
+ *     overlay layer above the camera preview (see [AROverlayStore] /
+ *     [AROverlayRenderer]).  React state-driven: when the array changes,
+ *     RN re-sends it and we REPLACE the view's JS overlay namespace.  The
+ *     imperative ref API (setOverlays / addOverlay / updateOverlay /
+ *     removeOverlay / clearOverlays) routes through the `RNSARSession`
+ *     native module instead (the same idiom takePhoto uses); both write the
+ *     SAME JS namespace, and the renderer draws the union of JS + native-
+ *     plugin overlays.
+ *
+ * Lifecycle remains driven by mount/unmount + the incremental stitcher's
+ * start/finalize methods.
  */
 class RNSARCameraViewManager : SimpleViewManager<RNSARCameraView>() {
 
@@ -29,6 +39,21 @@ class RNSARCameraViewManager : SimpleViewManager<RNSARCameraView>() {
     override fun createViewInstance(reactContext: ThemedReactContext): RNSARCameraView =
         RNSARCameraView(reactContext)
 
+    /**
+     * 0.20.0 — declarative `overlays` prop.  Parses the `AROverlay[]` array
+     * (the shared TS contract shape) and REPLACES the view's JS overlay
+     * namespace.  A null / empty array clears the JS overlays (native-plugin
+     * overlays are untouched).  Malformed entries are dropped (see
+     * [AROverlayData.fromReadableArray]).
+     *
+     * React diffs the prop by value before re-sending, so we don't diff
+     * here — a fresh array means "this is the new full JS overlay set".
+     */
+    @ReactProp(name = "overlays")
+    fun setOverlays(view: RNSARCameraView, overlays: ReadableArray?) {
+        view.setOverlaysFromJs(AROverlayData.fromReadableArray(overlays))
+    }
+
     companion object {
         const val REACT_CLASS = "RNSARCameraView"
     }

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

@@ -5,6 +5,7 @@ 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:
@@ -40,6 +41,73 @@ object RNSARPluginRegistry {
 
     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

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

package/dist/camera/ARCameraView.d.ts

@@ -32,6 +32,8 @@ import React from 'react';
 import { type ViewStyle } from 'react-native';
 import type { CameraFrameProcessor } from '../stitching/CameraFrame';
 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;
@@ -137,6 +139,31 @@ export interface ARCameraViewProps {
      * 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
@@ -148,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,