react-native-image-stitcher 0.18.0 → 0.20.0

package/ios/Sources/RNImageStitcher/ARSessionBridge.swift

@@ -16,6 +16,8 @@
 
 import Foundation
 import React
+import ARKit
+import simd
 
 // v0.18.0 — `RNSARSessionBridge` is now an `RCTEventEmitter` (was a
 // plain `NSObject`) so it can deliver the `onArFrame` LIGHT-metadata
@@ -38,6 +40,8 @@ public final class RNSARSessionBridge: RCTEventEmitter {
     private var hasListeners: Bool = false
 
     private static let arFrameEvent = "RNImageStitcherARFrame"
+    // v0.19.0 — async AR-plugin result channel (RNISARPluginRegistry.emit).
+    private static let arPluginResultEvent = "RNImageStitcherARPluginResult"
 
     public override init() {
         super.init()
@@ -56,6 +60,20 @@ public final class RNSARSessionBridge: RCTEventEmitter {
             name: .retailensARFrameMeta,
             object: nil
         )
+        // v0.19.0 — observe the async AR-plugin result channel (posted by
+        // `RNISARPluginRegistry.emit`) and re-emit as a JS device event.
+        // Same de-dupe rationale as the onArFrame observer above.
+        NotificationCenter.default.removeObserver(
+            self,
+            name: .retailensARPluginResult,
+            object: nil
+        )
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(handleArPluginResult(_:)),
+            name: .retailensARPluginResult,
+            object: nil
+        )
     }
 
     deinit {
@@ -71,7 +89,7 @@ public final class RNSARSessionBridge: RCTEventEmitter {
     }
 
     public override func supportedEvents() -> [String]! {
-        return [Self.arFrameEvent]
+        return [Self.arFrameEvent, Self.arPluginResultEvent]
     }
 
     public override func startObserving() {
@@ -100,6 +118,25 @@ public final class RNSARSessionBridge: RCTEventEmitter {
         }
     }
 
+    /// v0.19.0 — forward a posted async AR-plugin result
+    /// (`{ plugin, result }`, from `RNISARPluginRegistry.emit`) to JS as
+    /// the `RNImageStitcherARPluginResult` device event.  Dropped when no
+    /// JS listener is attached.  Emits via `enqueueJSCall` on the main
+    /// queue (same `sendEvent`-avoidance rationale as `handleArFrameMeta`).
+    @objc private func handleArPluginResult(_ notification: Notification) {
+        guard hasListeners else { return }
+        guard let userInfo = notification.userInfo else { return }
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self, let bridge = self.bridge else { return }
+            bridge.enqueueJSCall(
+                "RCTDeviceEventEmitter",
+                method: "emit",
+                args: [Self.arPluginResultEvent, userInfo],
+                completion: nil
+            )
+        }
+    }
+
     // MARK: - Module methods
 
     /// v0.18.0 — toggle the `onArFrame` LIGHT-metadata channel.  Called
@@ -203,6 +240,85 @@ public final class RNSARSessionBridge: RCTEventEmitter {
         }
     }
 
+    // MARK: - v0.20.0 — AR overlay renderer
+
+    /// Replace the ENTIRE JS-set overlay collection.  The JS layer (the
+    /// shared `arOverlayController`) does the per-id diff and always sends
+    /// the FULL current array here on every mutation (declarative prop +
+    /// imperative ref methods both funnel through this one method).
+    ///
+    /// Native replaces its JS-overlay namespace in `RNISAROverlayStore`
+    /// wholesale; the per-frame draw view in the mounted `RNSARCameraView`
+    /// reprojects + strokes them every ARFrame.  Plugin-placed overlays
+    /// (a SEPARATE namespace, via `RNISARPluginRegistry.setOverlays`) are
+    /// untouched — the draw view renders the UNION.
+    ///
+    /// `overlays` is an array of dictionaries matching the JS `AROverlay`
+    /// shape (`id`, `worldPosition?`, `sizeMeters?`, `worldQuad?`, `shape?`,
+    /// `label?`, `color?`, `mode?`).  Entries missing an `id` or any
+    /// geometry are dropped.  Synchronous (no main-queue hop needed — it
+    /// only mutates the thread-safe store; the draw view reads it on the
+    /// next render pass).
+    @objc(setOverlays:resolver:rejecter:)
+    public func setOverlays(
+        overlays: NSArray,
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        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)
+        resolver(nil)
+    }
+
+    // MARK: - v0.20.0 — raycast (crosshair → real-world surface)
+
+    /// Raycast from the screen CENTER (the crosshair) along the camera's view
+    /// ray and resolve the first real-world surface hit as
+    /// `{ worldPosition: [x, y, z] }` (metres, ARKit world frame), or `null`
+    /// when nothing is hit (e.g. a featureless wall before any plane is
+    /// detected — the caller then falls back to a fixed distance ahead).
+    ///
+    /// Uses an `.estimatedPlane` target so it works before a plane is fully
+    /// detected.  No screen point arg is needed: the crosshair is the centre,
+    /// so the ray is exactly the camera's forward (−Z) axis from its position.
+    /// Pin the marker on THIS hit (then anchor it) and it sits on the real
+    /// surface at the real distance, instead of floating a guessed metre ahead.
+    @objc(raycast:rejecter:)
+    public func raycast(
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        DispatchQueue.main.async {
+            let session = RNSARSession.shared.arSession
+            guard let frame = session.currentFrame else {
+                resolver(nil)
+                return
+            }
+            let t = frame.camera.transform
+            let origin = simd_float3(t.columns.3.x, t.columns.3.y, t.columns.3.z)
+            // ARKit camera looks down its local −Z.
+            let forward = -simd_float3(t.columns.2.x, t.columns.2.y, t.columns.2.z)
+            let query = ARRaycastQuery(
+                origin: origin,
+                direction: simd_normalize(forward),
+                allowing: .estimatedPlane,
+                alignment: .any
+            )
+            guard let hit = session.raycast(query).first else {
+                resolver(nil)
+                return
+            }
+            let p = hit.worldTransform.columns.3
+            resolver(["worldPosition": [p.x, p.y, p.z]])
+        }
+    }
+
     @objc(snapshotPoseLog:rejecter:)
     public func snapshotPoseLog(
         resolver: @escaping RCTPromiseResolveBlock,

package/ios/Sources/RNImageStitcher/CameraFrameHostObject.h

@@ -78,6 +78,31 @@ NS_SWIFT_NAME(CameraFrameHostObject)
                                          pose:(RNSARFramePose *)pose
     NS_SWIFT_NAME(lightArFrameMeta(from:pose:));
 
+/// Build the gated anchor-dictionary array for an ARFrame — the SAME
+/// `[{ id, type, alignment?, extent?, classification?, transform }]`
+/// shape the `onArFrame` LIGHT meta surfaces (mesh anchors excluded;
+/// they're summarised under `mesh`).  Returns an EMPTY array when the
+/// JS `enableAnchors` flag is off (read from the shared C++ extraction
+/// config) — matching the TS contract's `Array<...>` (never null).
+///
+/// Extracted so BOTH the `onArFrame` light-meta path AND the v0.19.0 AR
+/// plugin context (`RNISARFrameContext.anchors`) build anchors from one
+/// source of truth (DRY).
+///
+/// Thread: safe to call from the ARSession delegate queue (reads the
+/// frame synchronously; copies nothing that outlives the call).
++ (NSArray<NSDictionary *> *)arAnchorDictsFromFrame:(ARFrame *)arFrame
+    NS_SWIFT_NAME(arAnchorDicts(from:));
+
+/// Whether the shared C++ extraction config currently has `enableDepth`
+/// on (the `<Camera enableDepth>` prop, set via JS
+/// `__stitcherProxy.setExtractionConfig`).  The v0.19.0 AR plugin
+/// context uses this to decide whether to expose the raw
+/// `ARFrame.sceneDepth` depthBuffer to plugins — gating the config read
+/// (C++) in the .mm so Swift doesn't need the C++ header.
++ (BOOL)arExtractionDepthEnabled
+    NS_SWIFT_NAME(arExtractionDepthEnabled());
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/Sources/RNImageStitcher/CameraFrameHostObject.mm

@@ -653,60 +653,15 @@ void ExtractARMesh(ARFrame* arFrame, retailens::CameraFrameData& data) {
   meta[@"depth"] = depthValue;
 
   // anchors: id / coarse type / row-major 4x4 transform, plus plane
-  // alignment + extent + (capable-device) classification.  Mirrors
-  // ExtractARAnchors above but into an NSDictionary array (no byte
-  // marshaling — that path is for the full host object).  Empty array
-  // when the prop is off (cheap + JSON-stable, matching the TS contract's
-  // `Array<...>` rather than null).  Mesh anchors are summarised under
-  // `mesh` (counts) below, NOT listed individually here unless enableMesh
-  // is off — to match Android's collectTrackingAnchors which surfaces
-  // plane/image anchors and emits mesh as a separate summary.
-  NSMutableArray *anchorsOut = [NSMutableArray array];
-  if (cfg.anchors) {
-    for (ARAnchor *a in arFrame.anchors) {
-      // ARMeshAnchors are summarised under `mesh`; skip here.
-      if ([a isKindOfClass:[ARMeshAnchor class]]) continue;
-
-      NSMutableDictionary *anchor = [NSMutableDictionary dictionary];
-      anchor[@"id"] = a.identifier.UUIDString;
-
-      if ([a isKindOfClass:[ARPlaneAnchor class]]) {
-        anchor[@"type"] = @"plane";
-        ARPlaneAnchor *plane = (ARPlaneAnchor *)a;
-        anchor[@"alignment"] =
-            (plane.alignment == ARPlaneAnchorAlignmentVertical) ? @"vertical"
-                                                                : @"horizontal";
-        // [extentX, extentZ] in plane-local metres (deprecated `extent`
-        // for iOS-15 parity, same as ExtractARAnchors).
-        anchor[@"extent"] = @[ @(plane.extent.x), @(plane.extent.z) ];
-        if (ARPlaneAnchor.isClassificationSupported &&
-            plane.classificationStatus == ARPlaneClassificationStatusKnown) {
-          std::string cls = PlaneClassificationString(plane.classification);
-          if (!cls.empty()) {
-            anchor[@"classification"] =
-                [NSString stringWithUTF8String:cls.c_str()];
-          }
-        }
-      } else if ([a isKindOfClass:[ARImageAnchor class]]) {
-        anchor[@"type"] = @"image";
-      } else {
-        anchor[@"type"] = @"point";
-      }
-
-      // Row-major anchor->world (transpose ARKit's column-major matrix),
-      // 16 NSNumbers — same transpose as ExtractARAnchors.
-      const simd_float4x4 m = a.transform;
-      NSMutableArray *transform = [NSMutableArray arrayWithCapacity:16];
-      for (int r = 0; r < 4; ++r) {
-        for (int c = 0; c < 4; ++c) {
-          [transform addObject:@((double)m.columns[c][r])];
-        }
-      }
-      anchor[@"transform"] = transform;
-      [anchorsOut addObject:anchor];
-    }
-  }
-  meta[@"anchors"] = anchorsOut;
+  // alignment + extent + (capable-device) classification.  Built by the
+  // shared `arAnchorDictsFromFrame:` helper (DRY — same source the
+  // v0.19.0 AR plugin context reuses).  Empty array when the prop is off
+  // (cheap + JSON-stable, matching the TS contract's `Array<...>` rather
+  // than null).  Mesh anchors are summarised under `mesh` (counts) below,
+  // NOT listed individually — to match Android's collectTrackingAnchors
+  // which surfaces plane/image anchors and emits mesh as a separate
+  // summary.
+  meta[@"anchors"] = [self arAnchorDictsFromFrame:arFrame];
 
   // mesh: anchor / vertex / face COUNTS only (no vertex/face byte
   // marshaling).  null when the prop is off.  Counts are read from each
@@ -741,6 +696,63 @@ void ExtractARMesh(ARFrame* arFrame, retailens::CameraFrameData& data) {
   return meta;
 }
 
++ (NSArray<NSDictionary *> *)arAnchorDictsFromFrame:(ARFrame *)arFrame {
+  // Gate on the shared C++ extraction config's `anchors` flag — when the
+  // <Camera enableAnchors> prop is off, return an empty array (JSON-
+  // stable, matches the TS `Array<...>` contract; never null).
+  NSMutableArray<NSDictionary *> *anchorsOut = [NSMutableArray array];
+  const retailens::ExtractionConfig cfg = retailens::getExtractionConfig();
+  if (!cfg.anchors || arFrame == nil) return anchorsOut;
+
+  for (ARAnchor *a in arFrame.anchors) {
+    // ARMeshAnchors are summarised under `mesh` (counts), not listed here.
+    if ([a isKindOfClass:[ARMeshAnchor class]]) continue;
+
+    NSMutableDictionary *anchor = [NSMutableDictionary dictionary];
+    anchor[@"id"] = a.identifier.UUIDString;
+
+    if ([a isKindOfClass:[ARPlaneAnchor class]]) {
+      anchor[@"type"] = @"plane";
+      ARPlaneAnchor *plane = (ARPlaneAnchor *)a;
+      anchor[@"alignment"] =
+          (plane.alignment == ARPlaneAnchorAlignmentVertical) ? @"vertical"
+                                                              : @"horizontal";
+      // [extentX, extentZ] in plane-local metres (deprecated `extent` for
+      // iOS-15 parity, same as ExtractARAnchors).
+      anchor[@"extent"] = @[ @(plane.extent.x), @(plane.extent.z) ];
+      if (ARPlaneAnchor.isClassificationSupported &&
+          plane.classificationStatus == ARPlaneClassificationStatusKnown) {
+        std::string cls = PlaneClassificationString(plane.classification);
+        if (!cls.empty()) {
+          anchor[@"classification"] =
+              [NSString stringWithUTF8String:cls.c_str()];
+        }
+      }
+    } else if ([a isKindOfClass:[ARImageAnchor class]]) {
+      anchor[@"type"] = @"image";
+    } else {
+      anchor[@"type"] = @"point";
+    }
+
+    // Row-major anchor->world (transpose ARKit's column-major matrix),
+    // 16 NSNumbers — same transpose as ExtractARAnchors.
+    const simd_float4x4 m = a.transform;
+    NSMutableArray *transform = [NSMutableArray arrayWithCapacity:16];
+    for (int r = 0; r < 4; ++r) {
+      for (int c = 0; c < 4; ++c) {
+        [transform addObject:@((double)m.columns[c][r])];
+      }
+    }
+    anchor[@"transform"] = transform;
+    [anchorsOut addObject:anchor];
+  }
+  return anchorsOut;
+}
+
++ (BOOL)arExtractionDepthEnabled {
+  return retailens::getExtractionConfig().depth ? YES : NO;
+}
+
 - (void)invalidate {
   if (_hostObject) {
     _hostObject->invalidate();

package/ios/Sources/RNImageStitcher/RNISARFramePlugin.swift

@@ -0,0 +1,284 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// RNISARFramePlugin — v0.19.0 native AR plugin framework (iOS).
+//
+// The SDK owns the ARSession and drives one per-frame callback path
+// (`RNSARSession.session(_:didUpdate:)`).  Host apps that need to run
+// heavier native per-frame analysis (OCR, barcode reading, ML
+// inference, …) register a *native* plugin against this framework — the
+// SDK ships ONLY the generic plumbing; no OCR or other concrete plugin.
+//
+// The ergonomics mirror vision-camera's FrameProcessorPlugin
+// registration: the host conforms a class to `RNISARFramePlugin`,
+// registers it once at startup via `RNISARPluginRegistry.shared`, and
+// the SDK calls `process(_:)` on the AR thread for every ARFrame while
+// the registry is non-empty.
+//
+// Two result channels:
+//   1. SYNC — `process(_:)` returns a light `[String: Any]?`.  Non-nil
+//      results are folded into the throttled `onArFrame` `ARFrameMeta`
+//      under `plugins: { [name]: result }`, riding the existing
+//      `RNImageStitcherARFrame` device event.  Use for cheap, per-frame
+//      scalars (brightness, a quick blur score, …).
+//   2. ASYNC — the plugin offloads heavy work to its own queue and later
+//      calls `RNISARPluginRegistry.shared.emit(name, result)`, which the
+//      SDK re-emits as the `RNImageStitcherARPluginResult` device event
+//      `{ plugin, result }`.  Use for OCR / ML whose latency exceeds a
+//      frame interval.
+//
+// PERFORMANCE CONTRACT: the SDK only builds the `RNISARFrameContext` and
+// calls plugins when the registry is NON-EMPTY, so a zero-plugin app
+// pays nothing on the AR hot path.  Plugins MUST self-throttle (the SDK
+// calls `process(_:)` on every ARFrame) and MUST offload anything
+// heavier than a few hundred microseconds.
+
+import Foundation
+import ARKit
+import CoreVideo
+
+// MARK: - Async result event channel
+
+/// v0.19.0 — async AR-plugin result channel.  `RNISARPluginRegistry.emit`
+/// posts this notification (carrying `{ plugin, result }`); the
+/// `RNSARSessionBridge` (an RCTEventEmitter) observes it and re-emits as
+/// the JS `RNImageStitcherARPluginResult` device event.  We route via
+/// NotificationCenter — rather than the registry holding a bridge
+/// reference — mirroring the `.retailensARFrameMeta` (`onArFrame`)
+/// channel, so the framework-free engine pattern is preserved.
+public extension Notification.Name {
+    static let retailensARPluginResult =
+        Notification.Name("RNImageStitcherARPluginResult")
+}
+
+
+// MARK: - Plugin protocol
+
+/// A native AR frame plugin.  Host apps conform a class to this and
+/// register it once via `RNISARPluginRegistry.shared.register(_:)`.
+///
+/// The SDK calls `process(_:)` once per ARFrame on the AR (ARSession
+/// delegate) thread while the registry is non-empty.  Return a light
+/// `[String: Any]?` for the SYNC channel, or `nil`; for heavy work,
+/// offload to your own queue and later call
+/// `RNISARPluginRegistry.shared.emit(name(), result)` for the ASYNC
+/// channel.
+@objc public protocol RNISARFramePlugin: AnyObject {
+    /// Stable identifier for this plugin.  Used as the key in the
+    /// `onArFrame` meta's `plugins` map AND as the `plugin` field of the
+    /// async `RNImageStitcherARPluginResult` event.  Keep it constant for
+    /// the plugin's lifetime; the registry stores plugins keyed by name
+    /// (a second `register` with the same name replaces the first).
+    func name() -> String
+
+    /// Called on the AR thread once per ARFrame while the registry is
+    /// non-empty.  Return a light JSON-safe result for the SYNC channel
+    /// (NSNumber / NSString / NSArray / NSDictionary leaves) or `nil`.
+    ///
+    /// LIFETIME: `context.pixelBuffer` (and `context.depthBuffer`) are the
+    /// live ARFrame buffers — VALID ONLY for the duration of this call.
+    /// ARKit recycles them once `process(_:)` returns.  If you offload
+    /// work to another thread/queue, you MUST copy the bytes you need
+    /// BEFORE returning.  Do NOT retain the CVPixelBuffer expecting the
+    /// pixels to survive — a CF retain does not protect against ARKit's
+    /// pool reuse.
+    func process(_ context: RNISARFrameContext) -> [String: Any]?
+}
+
+
+// MARK: - Per-frame context
+
+/// Zero-copy native view of one ARFrame, handed to each plugin's
+/// `process(_:)`.  Exposes the live capture buffer + pose + intrinsics +
+/// (opt-in) depth + (opt-in) anchors.  Nothing here is copied for the
+/// plugin's benefit; the buffers belong to ARKit and are valid only
+/// during the synchronous `process(_:)` call (see the lifetime note on
+/// `RNISARFramePlugin.process(_:)`).
+@objc(RNISARFrameContext)
+public final class RNISARFrameContext: NSObject {
+
+    /// The ARFrame's `capturedImage` (BGRA/YUV `CVPixelBuffer`).  VALID
+    /// ONLY during `process(_:)` — copy before offloading (see the
+    /// lifetime note on `RNISARFramePlugin.process(_:)`).
+    @objc public let pixelBuffer: CVPixelBuffer
+
+    /// Frame timestamp in NANOSECONDS (AR-framework monotonic clock) —
+    /// matches `CameraFrame.timestampNs` and the `ARFrameMeta.timestamp`
+    /// contract.
+    @objc public let timestampNs: Double
+
+    /// Camera intrinsics (pixels).  `imageWidth`/`imageHeight` are the
+    /// capture resolution the intrinsics are expressed against.
+    @objc public let fx: Double
+    @objc public let fy: Double
+    @objc public let cx: Double
+    @objc public let cy: Double
+    @objc public let imageWidth: Int
+    @objc public let imageHeight: Int
+
+    /// World-space camera pose: rotation as a unit quaternion
+    /// `[x, y, z, w]` and translation `[x, y, z]` in metres (ARKit's
+    /// right-handed, Y-up, -Z-forward world frame).
+    @objc public let poseRotation: [Double]
+    @objc public let poseTranslation: [Double]
+
+    /// Tracking quality: `"notAvailable"` / `"limited"` / `"normal"`.
+    @objc public let trackingState: String
+
+    /// The ARFrame's `sceneDepth` (or `smoothedSceneDepth`) depth map
+    /// `CVPixelBuffer` — `nil` unless the `<Camera enableDepth>` prop is
+    /// on AND the device produced depth this frame.  VALID ONLY during
+    /// `process(_:)`; copy before offloading.
+    @objc public let depthBuffer: CVPixelBuffer?
+
+    /// Tracking anchors as the same light dicts the `onArFrame` meta
+    /// surfaces (`{ id, type, alignment?, extent?, classification?,
+    /// transform }`; mesh anchors excluded).  EMPTY unless the
+    /// `<Camera enableAnchors>` prop is on.
+    @objc public let anchors: [[String: Any]]
+
+    @objc public init(
+        pixelBuffer: CVPixelBuffer,
+        timestampNs: Double,
+        fx: Double, fy: Double, cx: Double, cy: Double,
+        imageWidth: Int, imageHeight: Int,
+        poseRotation: [Double],
+        poseTranslation: [Double],
+        trackingState: String,
+        depthBuffer: CVPixelBuffer?,
+        anchors: [[String: Any]]
+    ) {
+        self.pixelBuffer = pixelBuffer
+        self.timestampNs = timestampNs
+        self.fx = fx; self.fy = fy; self.cx = cx; self.cy = cy
+        self.imageWidth = imageWidth
+        self.imageHeight = imageHeight
+        self.poseRotation = poseRotation
+        self.poseTranslation = poseTranslation
+        self.trackingState = trackingState
+        self.depthBuffer = depthBuffer
+        self.anchors = anchors
+    }
+}
+
+
+// MARK: - Registry
+
+/// Process-wide registry of native AR plugins + the async result router.
+///
+/// The host registers plugins at startup (e.g. in the AppDelegate); the
+/// SDK reads `plugins()` on the AR thread each frame.  Also the entry
+/// point for the ASYNC channel: a plugin calls `emit(name, result)` from
+/// its own queue and the SDK re-emits a `RNImageStitcherARPluginResult`
+/// JS event.
+///
+/// THREAD SAFETY: registration (host/startup thread) and reads (AR
+/// thread) are serialised by an internal lock.  `plugins()` returns a
+/// snapshot array so the AR thread can iterate without holding the lock.
+@objc(RNISARPluginRegistry)
+public final class RNISARPluginRegistry: NSObject {
+
+    /// Shared instance — the only way hosts register plugins.
+    @objc public static let shared = RNISARPluginRegistry()
+
+    /// Registered plugins, keyed by `name()` for O(1) replace/unregister.
+    /// Insertion order is preserved for deterministic `process(_:)`
+    /// ordering via a parallel ordered key list.
+    private var pluginsByName: [String: RNISARFramePlugin] = [:]
+    private var order: [String] = []
+    private let lock = NSLock()
+
+    private override init() { super.init() }
+
+    /// Register (or replace) a plugin.  Keyed by `plugin.name()`: a
+    /// second register with the same name replaces the first (and keeps
+    /// its position in the ordering).  Idempotent for the same instance.
+    @objc public func register(_ plugin: RNISARFramePlugin) {
+        let key = plugin.name()
+        lock.lock()
+        defer { lock.unlock() }
+        if pluginsByName[key] == nil {
+            order.append(key)
+        }
+        pluginsByName[key] = plugin
+    }
+
+    /// Remove the plugin registered under `name`.  No-op if absent.
+    @objc public func unregister(_ name: String) {
+        lock.lock()
+        defer { lock.unlock() }
+        pluginsByName.removeValue(forKey: name)
+        order.removeAll { $0 == name }
+    }
+
+    /// Snapshot of registered plugins in registration order.  Returns a
+    /// copy so the AR thread can iterate without holding the lock.
+    @objc public func plugins() -> [RNISARFramePlugin] {
+        lock.lock()
+        defer { lock.unlock() }
+        return order.compactMap { pluginsByName[$0] }
+    }
+
+    /// Whether any plugin is registered.  Cheap gate the SDK checks per
+    /// ARFrame before building the (per-frame) `RNISARFrameContext`.
+    @objc public var isEmpty: Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        return order.isEmpty
+    }
+
+    /// ASYNC channel — route a plugin's later-computed result to JS as the
+    /// `RNImageStitcherARPluginResult` device event `{ plugin, result }`.
+    /// Safe to call from any thread (the plugin's own queue); posts on
+    /// NotificationCenter, which the bridge observes + re-emits on the
+    /// main queue.
+    ///
+    /// `pluginName` should match the plugin's `name()` so JS can correlate
+    /// the result with its source.
+    @objc public func emit(_ pluginName: String, _ result: [String: Any]) {
+        NotificationCenter.default.post(
+            name: .retailensARPluginResult,
+            object: nil,
+            userInfo: [
+                "plugin": pluginName,
+                "result": result,
+            ]
+        )
+    }
+
+    // MARK: - v0.20.0 — native-plugin overlay placement
+
+    // A native plugin can place AR overlays DIRECTLY (native→native, zero
+    // JS latency) via the methods below.  Plugin overlays live in their
+    // OWN namespace in `RNISAROverlayStore`, separate from JS-set overlays
+    // — the draw view renders the UNION, so a plugin placing overlays
+    // never clobbers `<Camera overlays={...}>` / the imperative ref, and
+    // vice-versa.  Safe to call from any thread (the store is internally
+    // locked); the per-frame draw view picks the change up on its next
+    // redraw.
+
+    /// Replace the ENTIRE plugin overlay set.  Pass the same dictionary
+    /// shape the JS `AROverlay` interface uses (`id`, `worldPosition`,
+    /// `sizeMeters`, `worldQuad`, `shape`, `label`, `color`, `mode`).
+    /// Entries missing an `id` or any geometry are dropped.
+    @objc public func setOverlays(_ overlays: [[String: Any]]) {
+        let parsed = overlays.compactMap { RNISAROverlay.from(dictionary: $0) }
+        RNISAROverlayStore.shared.setPluginOverlays(parsed)
+    }
+
+    /// Add or replace a single plugin overlay (same dictionary shape as
+    /// `setOverlays`).  No-op if the dict has no `id` / no geometry.
+    @objc public func addOverlay(_ overlay: [String: Any]) {
+        guard let parsed = RNISAROverlay.from(dictionary: overlay) else { return }
+        RNISAROverlayStore.shared.addPluginOverlay(parsed)
+    }
+
+    /// Remove a single plugin overlay by id.  No-op if absent.
+    @objc public func removeOverlay(_ id: String) {
+        RNISAROverlayStore.shared.removePluginOverlay(id)
+    }
+
+    /// Clear ALL plugin overlays.  JS-set overlays are untouched.
+    @objc public func clearOverlays() {
+        RNISAROverlayStore.shared.clearPluginOverlays()
+    }
+}