react-native-image-stitcher 0.19.0 → 0.20.1

package/ios/Sources/RNImageStitcher/RNSARCameraView.swift

@@ -31,17 +31,37 @@
 
 import Foundation
 import ARKit
+import SceneKit
 import UIKit
+import simd
 
 
 @objc(RNSARCameraView)
-public final class RNSARCameraView: UIView {
+public final class RNSARCameraView: UIView, ARSCNViewDelegate {
 
     /// The ARSCNView that does the actual rendering.  Bound to the
     /// singleton's ARSession so all preview surfaces share the same
     /// session (and the same pose log that the stitcher consumes).
     private var arSCNView: ARSCNView!
 
+    /// v0.20.0 — world-anchored overlays backed by REAL `ARAnchor`s.  Each
+    /// overlay becomes an `ARAnchor` added to the session; ARSCNView creates a
+    /// node per anchor (via `renderer(_:nodeFor:)`) and keeps its transform
+    /// synced to the anchor every frame — and crucially ARKit *refines* the
+    /// anchor as its world understanding improves (drift / re-localization),
+    /// so the marker stays glued to the real-world spot across a long session,
+    /// not just a short one (which a fixed world coordinate would not survive).
+    /// Diffed against the overlay store each render pass (`RNISAROverlay` is
+    /// `Equatable`): add new ids, rebuild changed ones, remove gone ones.
+    ///
+    /// Two maps, guarded by `anchorLock` because `nodeFor` may run on a
+    /// different (render) thread than the `updateAtTime` diff:
+    ///   - `overlayAnchors`: overlay id → (its anchor, the overlay it came from)
+    ///   - `anchorOverlays`: anchor UUID → overlay (so `nodeFor` can build it)
+    private var overlayAnchors: [String: (anchor: ARAnchor, overlay: RNISAROverlay)] = [:]
+    private var anchorOverlays: [UUID: RNISAROverlay] = [:]
+    private let anchorLock = NSLock()
+
     public override init(frame: CGRect) {
         super.init(frame: frame)
         setupView()
@@ -68,6 +88,14 @@ public final class RNSARCameraView: UIView {
         //     a renderer.
         arSCNView.session = RNSARSession.shared.arSession
 
+        // v0.20.0 — become the ARSCNView's render delegate so
+        // `renderer(_:updateAtTime:)` fires once per render pass (display
+        // rate) on the MAIN thread.  This is our per-frame overlay redraw
+        // hook: cheap (a handful of overlays), already on the main thread,
+        // and gives us smooth display-rate tracking without touching the
+        // ARSession delegate (which `RNSARSession` owns for pose logging).
+        arSCNView.delegate = self
+
         // We don't draw any 3D content in Phase 4.4.  Disable
         // SceneKit's automatic statistics overlay and lighting model
         // — we just want the camera feed.
@@ -78,6 +106,39 @@ public final class RNSARCameraView: UIView {
         // this view outside ARSCNView's letterboxed sub-rect).
         backgroundColor = .black
         addSubview(arSCNView)
+
+        // v0.20.0 — overlays render as world-anchored SceneKit nodes inside
+        // `arSCNView.scene` (see `syncOverlayNodes`), so there is no separate
+        // 2D overlay UIView to add here.
+    }
+
+    // MARK: - v0.20.0 — declarative `overlays` prop (KVC from RN)
+
+    /// Declarative `overlays` prop.  RN sets this via KVC
+    /// (`RCT_EXPORT_VIEW_PROPERTY(overlays, NSArray)`) whenever the prop
+    /// changes; we replace the JS overlay namespace wholesale (declarative
+    /// = the full set each render).  Forwarded to the global store rather
+    /// than held per-view because the overlay world is global to the single
+    /// AR session.  `@objc` + `NSArray` so KVC can set it.
+    @objc public var overlays: NSArray = [] {
+        didSet {
+            Self.applyJSSetOverlays(overlays)
+        }
+    }
+
+    /// Parse a JS overlay-dictionary array and replace the JS overlay
+    /// namespace in the shared store.  Shared by the declarative prop
+    /// setter (above) and the imperative `setOverlays` view command (in
+    /// `RNSARCameraViewManager`).
+    static func applyJSSetOverlays(_ overlays: NSArray) {
+        var parsed: [RNISAROverlay] = []
+        parsed.reserveCapacity(overlays.count)
+        for item in overlays {
+            guard let dict = item as? [String: Any],
+                  let o = RNISAROverlay.from(dictionary: dict) else { continue }
+            parsed.append(o)
+        }
+        RNISAROverlayStore.shared.setJSOverlays(parsed)
     }
 
     public override func layoutSubviews() {
@@ -96,7 +157,12 @@ public final class RNSARCameraView: UIView {
         // ARSCNView fills a same-AR sub-rect, there is nothing to crop
         // and the user sees the full captured scene.  The parent view's
         // black background fills the remainder.
-        arSCNView.frame = letterboxedFrame()
+        let lb = letterboxedFrame()
+        arSCNView.frame = lb
+        // Overlay nodes live in `arSCNView.scene` and are rendered by the
+        // same (letterboxed) ARSCNView against the live AR camera, so they
+        // need no separate framing — they align with the camera feed
+        // automatically.
     }
 
     /// Returns the largest `CGRect` inside `bounds` that matches the
@@ -184,6 +250,238 @@ public final class RNSARCameraView: UIView {
             }
         }
     }
-}
 
+    // MARK: - ARSCNViewDelegate (v0.20.0 overlay redraw hook)
+
+    /// Called once per ARSCNView render pass.  Keeps the set of overlay
+    /// ARAnchors in sync with the overlay store (add / rebuild / remove).
+    /// ARKit then tracks each anchor and ARSCNView positions its node — we do
+    /// NOT project or position anything by hand.  Cheap: an `==` diff over a
+    /// handful of overlays.
+    ///
+    /// We deliberately do NOT touch `RNSARSession`'s pose log / plugin /
+    /// onArFrame paths — those ride the ARSession delegate which the singleton
+    /// owns.  This delegate is purely the overlay-sync hook.
+    public func renderer(
+        _ renderer: SCNSceneRenderer,
+        updateAtTime time: TimeInterval
+    ) {
+        syncOverlayAnchors()
+    }
+
+    /// ARSCNViewDelegate: vend the node for one of our overlay anchors.  May
+    /// run on the render thread; ARSCNView keeps the returned node's transform
+    /// synced to the (ARKit-refined) anchor.  We build the visual RELATIVE to
+    /// the anchor origin — the anchor carries the world position.
+    public func renderer(
+        _ renderer: SCNSceneRenderer,
+        nodeFor anchor: ARAnchor
+    ) -> SCNNode? {
+        anchorLock.lock()
+        let overlay = anchorOverlays[anchor.identifier]
+        anchorLock.unlock()
+        guard let overlay = overlay else { return nil }
+
+        if let quad = overlay.worldQuad, quad.count >= 3 {
+            // Anchor sits at the centroid; draw the loop relative to it.
+            var c = simd_float3(0, 0, 0)
+            for v in quad { c += v }
+            c /= Float(quad.count)
+            return Self.makeQuadOutlineNode(
+                relCorners: quad.map { $0 - c },
+                color: overlay.color, label: overlay.label)
+        }
+        return Self.makeBillboardNode(
+            sizeMeters: overlay.sizeMeters, color: overlay.color,
+            label: overlay.label)
+    }
+
+    /// Diff the overlay store against the live anchors: add an ARAnchor for
+    /// each new/changed overlay, remove anchors whose overlay is gone.
+    private func syncOverlayAnchors() {
+        let session = arSCNView.session
+        let overlays = RNISAROverlayStore.shared.snapshot()
+        var liveIDs = Set<String>()
+        liveIDs.reserveCapacity(overlays.count)
+
+        for overlay in overlays {
+            liveIDs.insert(overlay.id)
+            anchorLock.lock()
+            let existing = overlayAnchors[overlay.id]
+            anchorLock.unlock()
+            if let existing = existing, existing.overlay == overlay { continue }
+
+            // New or changed → drop the old anchor, add a fresh one.
+            if let existing = existing {
+                session.remove(anchor: existing.anchor)
+                anchorLock.lock()
+                anchorOverlays[existing.anchor.identifier] = nil
+                overlayAnchors[overlay.id] = nil
+                anchorLock.unlock()
+            }
+            guard let pose = Self.anchorPose(for: overlay) else { continue }
+            let anchor = ARAnchor(transform: pose)
+            anchorLock.lock()
+            anchorOverlays[anchor.identifier] = overlay
+            overlayAnchors[overlay.id] = (anchor, overlay)
+            anchorLock.unlock()
+            session.add(anchor: anchor)
+        }
+
+        // Remove anchors whose overlay id is gone (snapshot under the lock,
+        // call session.remove outside it).
+        anchorLock.lock()
+        let goneIDs = overlayAnchors.keys.filter { !liveIDs.contains($0) }
+        let goneAnchors = goneIDs.compactMap { overlayAnchors[$0]?.anchor }
+        for id in goneIDs {
+            if let a = overlayAnchors[id]?.anchor { anchorOverlays[a.identifier] = nil }
+            overlayAnchors[id] = nil
+        }
+        anchorLock.unlock()
+        for a in goneAnchors { session.remove(anchor: a) }
+    }
+
+    // MARK: - v0.20.0 overlay node builders (RELATIVE to the anchor origin)
+
+    /// World transform for an overlay's anchor: a translation-only pose at the
+    /// `worldPosition`, or at the centroid of `worldQuad`.  nil if no geometry.
+    private static func anchorPose(for overlay: RNISAROverlay) -> simd_float4x4? {
+        let p: simd_float3
+        if let quad = overlay.worldQuad, quad.count >= 3 {
+            var c = simd_float3(0, 0, 0)
+            for v in quad { c += v }
+            p = c / Float(quad.count)
+        } else if let center = overlay.worldPosition {
+            p = center
+        } else {
+            return nil
+        }
+        var m = matrix_identity_float4x4
+        m.columns.3 = simd_float4(p.x, p.y, p.z, 1)
+        return m
+    }
+
+    /// A camera-facing billboard plane (at the anchor origin), sized in metres,
+    /// textured with a stroked outline + optional centred label.  Always drawn
+    /// on top (depth read/write off) so an annotation is never hidden.
+    private static func makeBillboardNode(
+        sizeMeters: CGSize?,
+        color: UIColor,
+        label: String?
+    ) -> SCNNode {
+        let w = sizeMeters?.width ?? RNISAROverlay.defaultMarkerExtent
+        let h = sizeMeters?.height ?? RNISAROverlay.defaultMarkerExtent
+        let plane = SCNPlane(width: w, height: h)
+        let mat = SCNMaterial()
+        mat.diffuse.contents = overlayImage(color: color, label: label)
+        mat.isDoubleSided = true
+        mat.lightingModel = .constant      // unlit — show the texture as-is
+        mat.writesToDepthBuffer = false
+        mat.readsFromDepthBuffer = false   // never occluded by the scene
+        plane.firstMaterial = mat
+
+        let node = SCNNode(geometry: plane)
+        node.renderingOrder = 1000         // draw after the camera background
+        let billboard = SCNBillboardConstraint()
+        billboard.freeAxes = .all          // always face the camera, flat
+        node.constraints = [billboard]
+        return node
+    }
+
+    /// A THICK 3D outline through corners expressed RELATIVE to the anchor
+    /// origin (anchor at the quad centroid).  Each edge is a thin cylinder —
+    /// SceneKit `.line` primitives are always 1px and unscalable, so a visible
+    /// outline must be real geometry.  Optional camera-facing label at centre.
+    private static func makeQuadOutlineNode(
+        relCorners: [simd_float3],
+        color: UIColor,
+        label: String?
+    ) -> SCNNode {
+        let node = SCNNode()
+        node.renderingOrder = 1000
+        let n = relCorners.count
+        for i in 0..<n {
+            if let edge = edgeCylinder(
+                from: relCorners[i], to: relCorners[(i + 1) % n], color: color) {
+                node.addChildNode(edge)
+            }
+        }
+        if let label = label, !label.isEmpty {
+            // Label at the centroid (≈ local origin in relative space).
+            let labelNode = makeBillboardNode(
+                sizeMeters: CGSize(width: 0.12, height: 0.12),
+                color: color, label: label)
+            node.addChildNode(labelNode)
+        }
+        return node
+    }
+
+    /// A thin cylinder (≈4 mm) spanning two points — one edge of a quad
+    /// outline.  SCNCylinder's axis is +Y, so we centre it at the midpoint and
+    /// rotate +Y onto the edge direction.
+    private static func edgeCylinder(
+        from a: simd_float3, to b: simd_float3, color: UIColor
+    ) -> SCNNode? {
+        let d = b - a
+        let len = simd_length(d)
+        guard len > 1e-5 else { return nil }
+        let cyl = SCNCylinder(radius: 0.004, height: CGFloat(len))
+        let mat = SCNMaterial()
+        mat.diffuse.contents = color
+        mat.lightingModel = .constant
+        mat.writesToDepthBuffer = false
+        mat.readsFromDepthBuffer = false
+        cyl.firstMaterial = mat
+        let node = SCNNode(geometry: cyl)
+        node.renderingOrder = 1000
+        node.simdPosition = (a + b) * 0.5
+        let yAxis = simd_float3(0, 1, 0)
+        let dir = d / len
+        let dot = simd_dot(yAxis, dir)
+        if dot < -0.9999 {
+            node.simdOrientation = simd_quatf(angle: .pi, axis: simd_float3(1, 0, 0))
+        } else if dot < 0.9999 {
+            let axis = simd_normalize(simd_cross(yAxis, dir))
+            node.simdOrientation = simd_quatf(angle: acos(dot), axis: axis)
+        }
+        return node
+    }
+
+    /// Render a stroked rounded-rect outline + optional centred label chip to
+    /// a square image, used as the billboard plane's texture.  Transparent
+    /// background so only the outline + chip show over the camera feed.
+    private static func overlayImage(color: UIColor, label: String?) -> UIImage {
+        let px: CGFloat = 512
+        let renderer = UIGraphicsImageRenderer(size: CGSize(width: px, height: px))
+        return renderer.image { ctx in
+            let cg = ctx.cgContext
+            let inset = px * 0.07
+            let rect = CGRect(x: inset, y: inset,
+                              width: px - 2 * inset, height: px - 2 * inset)
+            let path = UIBezierPath(roundedRect: rect, cornerRadius: px * 0.05)
+            cg.setStrokeColor(color.cgColor)
+            cg.setLineWidth(px * 0.03)
+            path.stroke()
+
+            guard let label = label, !label.isEmpty else { return }
+            let fontSize = px * 0.13
+            let font = UIFont.systemFont(ofSize: fontSize, weight: .bold)
+            let attrs: [NSAttributedString.Key: Any] = [
+                .font: font, .foregroundColor: UIColor.white,
+            ]
+            let ts = (label as NSString).size(withAttributes: attrs)
+            let pad = fontSize * 0.35
+            let chip = CGRect(x: (px - ts.width) / 2 - pad,
+                              y: (px - ts.height) / 2 - pad,
+                              width: ts.width + 2 * pad,
+                              height: ts.height + 2 * pad)
+            color.withAlphaComponent(0.9).setFill()
+            UIBezierPath(roundedRect: chip, cornerRadius: pad).fill()
+            (label as NSString).draw(
+                at: CGPoint(x: (px - ts.width) / 2, y: (px - ts.height) / 2),
+                withAttributes: attrs)
+        }
+    }
+
+}
 

package/ios/Sources/RNImageStitcher/RNSARSession.swift

@@ -1103,54 +1103,67 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         } else {
             resolvedPath = rawPath
         }
-        guard let frame = arSession.currentFrame else {
-            completion(nil, NSError(
-                domain: "RNImageStitcherARCapture",
-                code: 2001,
-                userInfo: [NSLocalizedDescriptionKey:
-                    "AR session has no current frame — start the session first."]
-            ))
-            return
+        // Capture a HIGH-RESOLUTION still.  ARKit's live `capturedImage` is the
+        // small AR video format (and the SDK picks the SMALLEST 4:3 format), far
+        // too low-res for document OCR / detail capture.
+        // `captureHighResolutionFrame` (iOS 16+) grabs a full-resolution photo
+        // WITHOUT leaving the AR session.  Fall back to the live frame on older
+        // OS or if the high-res grab fails.
+        let encode: (CVPixelBuffer) -> Void = { [weak self] pixelBuffer in
+            self?.encodeArPhoto(
+                pixelBuffer: pixelBuffer,
+                toPath: resolvedPath,
+                quality: quality,
+                orientation: orientation,
+                completion: completion
+            )
         }
-        let pixelBuffer = frame.capturedImage
+        if #available(iOS 16.0, *) {
+            arSession.captureHighResolutionFrame { [weak self] hiResFrame, error in
+                if let hiResFrame = hiResFrame {
+                    encode(hiResFrame.capturedImage)
+                } else if let live = self?.arSession.currentFrame {
+                    encode(live.capturedImage)
+                } else {
+                    completion(nil, NSError(
+                        domain: "RNImageStitcherARCapture",
+                        code: 2001,
+                        userInfo: [NSLocalizedDescriptionKey:
+                            "AR high-res capture failed: \(error?.localizedDescription ?? "no current frame")."]
+                    ))
+                }
+            }
+        } else {
+            guard let frame = arSession.currentFrame else {
+                completion(nil, NSError(
+                    domain: "RNImageStitcherARCapture",
+                    code: 2001,
+                    userInfo: [NSLocalizedDescriptionKey:
+                        "AR session has no current frame — start the session first."]
+                ))
+                return
+            }
+            encode(frame.capturedImage)
+        }
+    }
 
-        // v0.12.0 — Pre-v0.12 this method hardcoded `.right` (90° CW)
-        // to rotate-to-portrait, assuming the user always held the
-        // phone in portrait.  Under R2-lite the device can be in
-        // any orientation, so we pick the CIImage orientation per
-        // the JS-supplied `orientation` arg (from
-        // `useDeviceOrientation()`).
-        //
-        // Empirical mapping (on-device test 2026-05-28):
-        //   portrait              → .right  (90° CW — preserved from pre-v0.12)
-        //   landscape-left        → .up     (sensor matches device tilt; no rotation)
-        //   landscape-right       → .down   (180° — sensor opposite of device tilt)
-        //   portrait-upside-down  → .left   (90° CCW)
-        //
-        // The landscape mapping (landscape-left → .up) was determined
-        // empirically and is the opposite of what Apple's ARKit
-        // pixel-buffer-orientation docs would imply.  Likely because
-        // `useDeviceOrientation()` reports `landscape-left` via the
-        // `UIDeviceOrientation` convention (home indicator on user-
-        // right) while iOS's sensor-native orientation matches that
-        // tilt direction directly.  Without this fix, AR-mode single
-        // photos in landscape come out upside-down.
-        // v0.12.0 — Pre-v0.12 this method hardcoded `.right` (90° CW)
-        // to rotate-to-portrait, assuming the user always held the
-        // phone in portrait.  Under R2-lite the device can be in
-        // any orientation, so we pick the CIImage orientation per
-        // the JS-supplied `orientation` arg (from
-        // `useDeviceOrientation()`).
-        //
-        // Empirical mapping (on-device test 2026-05-28):
-        //   portrait              → .right  (90° CW — preserved from pre-v0.12)
-        //   landscape-left        → .up     (sensor matches device tilt; no rotation)
-        //   landscape-right       → .down   (180° — sensor opposite of device tilt)
-        //   portrait-upside-down  → .left   (90° CCW)
-        //
-        // The landscape mapping (landscape-left → .up) was determined
-        // empirically; the user reported AR landscape photos came out
-        // upside-down with .down and correctly upright with .up.
+    /// Encode an AR pixel buffer → an oriented, FULL-RESOLUTION JPEG at `path`.
+    /// Unlike stitch keyframes, a user / document photo is NOT downscaled — OCR
+    /// and detail capture need the full resolution that
+    /// `captureHighResolutionFrame` provides.
+    ///
+    /// Orientation maps the JS `useDeviceOrientation()` value → CIImage
+    /// orientation (empirical, on-device 2026-05-28): portrait → .right,
+    /// landscape-left → .up, landscape-right → .down,
+    /// portrait-upside-down → .left.  Without this, AR-mode landscape photos
+    /// come out upside-down.
+    private func encodeArPhoto(
+        pixelBuffer: CVPixelBuffer,
+        toPath resolvedPath: String,
+        quality: Int,
+        orientation: String,
+        completion: @escaping ([String: Any]?, NSError?) -> Void
+    ) {
         let exifOrientation: CGImagePropertyOrientation
         switch orientation {
         case "landscape-left":        exifOrientation = .up
@@ -1158,21 +1171,9 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         case "portrait-upside-down":  exifOrientation = .left
         default:                       exifOrientation = .right  // portrait + unknown
         }
-        var ciImage = CIImage(cvPixelBuffer: pixelBuffer)
-            .oriented(exifOrientation)
-        // AR keyframe downscale guard — normalise long edge to the budget so
-        // every device produces a ~0.3 MP keyframe (cross-device-consistent
-        // stitch memory).  Mirrors Android's downscale in YuvImageConverter.
-        let kfLongEdge = max(ciImage.extent.width, ciImage.extent.height)
-        if kfLongEdge > Self.arKeyframeMaxLongEdge {
-            let kfScale = Self.arKeyframeMaxLongEdge / kfLongEdge
-            ciImage = ciImage.transformed(by: CGAffineTransform(scaleX: kfScale, y: kfScale))
-        }
+        let ciImage = CIImage(cvPixelBuffer: pixelBuffer).oriented(exifOrientation)
         let context = CIContext(options: nil)
-        guard let cgImage = context.createCGImage(
-            ciImage,
-            from: ciImage.extent
-        ) else {
+        guard let cgImage = context.createCGImage(ciImage, from: ciImage.extent) else {
             completion(nil, NSError(
                 domain: "RNImageStitcherARCapture",
                 code: 2002,
@@ -1194,7 +1195,6 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
             ))
             return
         }
-
         let cleanedPath = Self.normalisePath(resolvedPath)
         let url = URL(fileURLWithPath: cleanedPath)
         // Best-effort delete an existing file at the same path —
@@ -1574,8 +1574,13 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         // simd_quatf from a 4x4 matrix uses the rotational part.
         let q = simd_quatf(t)
 
-        // Camera intrinsics.  Apple gives us a 3x3 matrix where
-        // [0][0] = fx, [1][1] = fy, [0][2] = cx, [1][2] = cy.
+        // Camera intrinsics.  `simd_float3x3` subscripts as k[column][row]
+        // (COLUMN-MAJOR).  ARKit's K is:
+        //   column 0 = (fx, 0, 0), column 1 = (0, fy, 0), column 2 = (cx, cy, 1)
+        // so fx = k[0][0], fy = k[1][1], cx = k[2][0], cy = k[2][1].
+        // (Pre-0.20.1 bug: read cx/cy as k[0][2]/k[1][2] = 0 — fx/fy survived
+        // because they're on the diagonal, so the principal point came through
+        // as 0,0 and broke any pixel↔world unprojection.)
         let k = frame.camera.intrinsics
         let imageRes = frame.camera.imageResolution
 
@@ -1596,8 +1601,8 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
             qw: Double(q.real),
             fx: Double(k[0][0]),
             fy: Double(k[1][1]),
-            cx: Double(k[0][2]),
-            cy: Double(k[1][2]),
+            cx: Double(k[2][0]),
+            cy: Double(k[2][1]),
             imageWidth: Int(imageRes.width),
             imageHeight: Int(imageRes.height),
             timestampMs: frame.timestamp * 1000.0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "Pose-aware panorama capture + stitching for React Native. One <Camera> component, both tap-to-photo and hold-to-pan modes, both AR-backed and IMU-fallback capture paths.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/camera/ARCameraView.tsx

@@ -45,6 +45,11 @@ import {
 import { ensureStitcherProxyInstalled } from '../stitching/ensureStitcherProxyInstalled';
 import type { CameraFrameProcessor } from '../stitching/CameraFrame';
 import type { ARFrameMeta, ARPluginResult } from '../stitching/ARFrameMeta';
+import type { AROverlay } from '../stitching/AROverlay';
+import {
+  createAROverlayController,
+  type AROverlayMethods,
+} from './arOverlayController';
 
 
 // React Native looks up the component by its NATIVE name.
@@ -167,6 +172,32 @@ 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[];
 }
 
 
@@ -180,8 +211,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,
@@ -260,6 +296,7 @@ export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
       onArFrame,
       arFrameMetaInterval,
       onArPluginResult,
+      overlays,
     },
     ref,
   ): React.JSX.Element {
@@ -268,6 +305,19 @@ export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
     // pair vision-camera uses.
     const recordingCallbacksRef = useRef<RecordingCallbacks | null>(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 = useRef<
+      ReturnType<typeof createAROverlayController> | null
+    >(null);
+    if (overlayControllerRef.current == null) {
+      overlayControllerRef.current = 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
@@ -427,7 +477,28 @@ export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
       };
     }, [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.
+    useEffect(() => {
+      if (overlays == null) {
+        return;
+      }
+      overlayController.setOverlays(overlays);
+    }, [overlays, overlayController]);
+
     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: any =
           (NativeModules as Record<string, unknown>).RNSARSession;
@@ -479,7 +550,7 @@ export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
           callbacks.onRecordingError?.(err as Error);
         }
       },
-    }), []);
+    }), [overlayController]);
 
     if (!NativeARCameraView
         || (Platform.OS !== 'ios' && Platform.OS !== 'android')) {