react-native-image-stitcher 0.18.0 → 0.19.0

package/dist/camera/Camera.d.ts

@@ -42,7 +42,7 @@ 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 CaptureHeaderProps } from './CaptureHeader';
 import { type CapturePreviewAction } from './CapturePreview';
 import { type CaptureThumbnailItem } from './CaptureThumbnailStrip';
@@ -656,6 +656,25 @@ 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;
     /**
      * Which device holds the non-AR panorama capture accepts.
      *

package/dist/camera/Camera.js

@@ -310,7 +310,7 @@ function extractPanoramaOverrides(props) {
  * The public `<Camera>` component.
  */
 function Camera(props) {
-    const { defaultCaptureSource = 'non-ar', defaultLens = '1x', captureSources = 'both', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, onLensChange, onFramesDropped, onError, onCaptureAbandoned, flash: controlledFlash, onFlashChange, showFlashButton = true, headerTitle, onHeaderBack, headerBackLabel, headerGuidance, headerColors, thumbnails, thumbnailsMin, thumbnailsMax, onThumbnailPress, capturePreview, capturePreviewActions, onCapturePreviewClose, frameProcessor: hostFrameProcessor, arFrameProcessor, enableDepth, enableAnchors, enableMesh, planeDetection, onArFrame, arFrameMetaInterval, engine = 'batch-keyframe', 
+    const { defaultCaptureSource = 'non-ar', defaultLens = '1x', captureSources = 'both', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, onLensChange, onFramesDropped, onError, onCaptureAbandoned, flash: controlledFlash, onFlashChange, showFlashButton = true, headerTitle, onHeaderBack, headerBackLabel, headerGuidance, headerColors, thumbnails, thumbnailsMin, thumbnailsMax, onThumbnailPress, capturePreview, capturePreviewActions, onCapturePreviewClose, frameProcessor: hostFrameProcessor, arFrameProcessor, enableDepth, enableAnchors, enableMesh, planeDetection, onArFrame, arFrameMetaInterval, onArPluginResult, engine = 'batch-keyframe', 
     // ── Panorama GUIDANCE (feature/pano-ux-guidance) ──────────────
     panMode = 'vertical', panGuidance = true, maxPanDurationMs = 0, panTooFastThreshold, lateralBudgetCm = 4, rectCrop = false, showPreview = false, guidanceCopy, } = props;
     // Derived guidance state.  The landscape-only gate decision itself is
@@ -1425,7 +1425,7 @@ function Camera(props) {
         // (V12.14.8 OOM fix).  The CaptureStatusOverlay renders the
         // "Stitching…" state on top, so no placeholder label is needed
         // in that case — only for the camera-switch transition.
-        react_1.default.createElement(react_native_1.View, { style: [react_native_1.StyleSheet.absoluteFill, styles.transitionPlaceholder] }, statusPhase === 'stitching' ? null : (react_1.default.createElement(react_native_1.Text, { style: styles.transitionLabel }, "Switching camera\u2026")))) : isAR ? (react_1.default.createElement(ARCameraView_1.ARCameraView, { ref: arViewRef, style: react_native_1.StyleSheet.absoluteFill, arFrameProcessor: arFrameProcessor, enableDepth: enableDepth, enableAnchors: enableAnchors, enableMesh: enableMesh, planeDetection: planeDetection, onArFrame: onArFrame, arFrameMetaInterval: arFrameMetaInterval })) : (react_1.default.createElement(CameraView_1.CameraView, { ref: visionCameraRef, device: capture.device, isActive: true, 
+        react_1.default.createElement(react_native_1.View, { style: [react_native_1.StyleSheet.absoluteFill, styles.transitionPlaceholder] }, statusPhase === 'stitching' ? null : (react_1.default.createElement(react_native_1.Text, { style: styles.transitionLabel }, "Switching camera\u2026")))) : isAR ? (react_1.default.createElement(ARCameraView_1.ARCameraView, { ref: arViewRef, style: react_native_1.StyleSheet.absoluteFill, arFrameProcessor: arFrameProcessor, enableDepth: enableDepth, enableAnchors: enableAnchors, enableMesh: enableMesh, planeDetection: planeDetection, onArFrame: onArFrame, arFrameMetaInterval: arFrameMetaInterval, onArPluginResult: onArPluginResult })) : (react_1.default.createElement(CameraView_1.CameraView, { ref: visionCameraRef, device: capture.device, isActive: true, 
             // `video={true}` is REQUIRED for takeSnapshot to work on iOS.
             // vision-camera v4's iOS implementation of takeSnapshot waits
             // for a frame on the video pipeline; with video disabled, the

package/dist/index.d.ts

@@ -93,6 +93,7 @@ export { useIncrementalStitcher } from './stitching/useIncrementalStitcher';
 export { useKeyframeStream } from './stitching/useKeyframeStream';
 export type { CameraFrame, CameraFrameProcessor, ARAnchor, } from './stitching/CameraFrame';
 export type { ARFrameMeta } from './stitching/ARFrameMeta';
+export type { ARPluginResult } from './stitching/ARFrameMeta';
 export { useFrameProcessorDriver } from './stitching/useFrameProcessorDriver';
 export type { UseFrameProcessorDriverOptions, FrameProcessorDriverHandle, } from './stitching/useFrameProcessorDriver';
 export { useStitcherWorklet } from './stitching/useStitcherWorklet';

package/dist/stitching/ARFrameMeta.d.ts

@@ -96,5 +96,54 @@ export interface ARFrameMeta {
         vertexCount: number;
         faceCount: number;
     } | null;
+    /**
+     * v0.19.0 — SYNCHRONOUS results from host-registered AR frame plugins
+     * (the AR plugin framework).  Keyed by each plugin's `name()`; the value
+     * is the light JSON result the plugin's `process(ctx)` returned on the AR
+     * thread (`nil`/`null`-returning plugins are omitted).  Only present when
+     * the native plugin registry is non-empty AND at least one plugin returned
+     * a sync result for this frame; otherwise omitted entirely (zero-plugin
+     * apps pay nothing — native skips building the context).
+     *
+     * The SDK ships ONLY the generic framework — there are no built-in
+     * plugins.  Hosts register native plugins via `RNISARPluginRegistry`
+     * (iOS) / `RNSARPluginRegistry` (Android) at startup; each plugin is
+     * called once per AR frame while the registry is non-empty.  Result
+     * values are `unknown` because each plugin defines its own shape — cast
+     * after reading the entry you care about (e.g.
+     * `meta.plugins?.brightness as number`).
+     *
+     * ## Sync vs async results
+     *
+     * This field carries only the LIGHT, in-band SYNC results (computed fast
+     * enough to ride the throttled `onArFrame` event).  Plugins that offload
+     * heavy work to their own queue deliver results out-of-band via
+     * `registry.emit(name, result)`, which surfaces through the separate
+     * `onArPluginResult` callback (the `RNImageStitcherARPluginResult`
+     * event) — NOT here.
+     */
+    plugins?: {
+        [name: string]: unknown;
+    };
+}
+/**
+ * v0.19.0 — an ASYNCHRONOUS result from a host-registered AR frame plugin,
+ * delivered via the `onArPluginResult` callback.
+ *
+ * Unlike the in-band SYNC results carried on {@link ARFrameMeta.plugins}
+ * (which ride the throttled `onArFrame` event), a plugin produces an async
+ * result by offloading heavy work to its own queue and later calling
+ * `registry.emit(name, result)` on the native side.  The SDK routes that to
+ * JS as a `RNImageStitcherARPluginResult` device event; `<ARCameraView>`
+ * subscribes and invokes `onArPluginResult` on the JS MAIN thread.
+ *
+ * `result` is `unknown` because each plugin defines its own result shape —
+ * branch on `plugin` (the emitting plugin's `name()`) and cast accordingly.
+ */
+export interface ARPluginResult {
+    /** The `name()` of the plugin that emitted this result. */
+    plugin: string;
+    /** The plugin-defined result payload (cast after branching on `plugin`). */
+    result: unknown;
 }
 //# sourceMappingURL=ARFrameMeta.d.ts.map

package/ios/Sources/RNImageStitcher/ARSessionBridge.swift

@@ -38,6 +38,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 +58,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 +87,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 +116,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

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,247 @@
+// 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,
+            ]
+        )
+    }
+}