react-native-image-stitcher 0.17.0 → 0.19.0

package/ios/Sources/RNImageStitcher/RNSARSession.swift

@@ -29,6 +29,7 @@ import AVFoundation
 import simd
 import UIKit
 import os.log
+import QuartzCore  // CACurrentMediaTime (monotonic clock for onArFrame throttle)
 
 // V15.0c.4 — FAULT-level os_log on the same subsystem/category the
 // slit-scan engine uses, so Console.app's filter for `category =
@@ -41,6 +42,19 @@ fileprivate let arSessionDiagLog = OSLog(
 )
 
 
+// v0.18.0 — `onArFrame` LIGHT-metadata channel.  The AR session posts
+// this notification (carrying the `ARFrameMeta`-shaped dictionary) per
+// throttled frame; `RNSARSessionBridge` (an RCTEventEmitter) observes it
+// and re-emits as the JS `RNImageStitcherARFrame` device event.  We go
+// via NotificationCenter — rather than the bridge holding a reference to
+// the session singleton — so the framework-free engine pattern (used by
+// IncrementalStitcher) is preserved.
+public extension Notification.Name {
+    static let retailensARFrameMeta =
+        Notification.Name("RNImageStitcherARFrame")
+}
+
+
 /// Track state mirrors `ARCamera.TrackingState`.  We mirror it
 /// rather than re-export the ARKit enum so the JS bridge sees a
 /// stable shape that doesn't drift with iOS SDK updates.
@@ -165,6 +179,39 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
     /// Whether the session is currently running.
     @objc public private(set) var isRunning: Bool = false
 
+    // ──────────────────────────────────────────────────────────────
+    // Scene reconstruction (ARKit mesh) — opt-in
+    // ──────────────────────────────────────────────────────────────
+    /// Whether ARKit scene reconstruction (the LiDAR mesh,
+    /// `ARMeshAnchor`s) should be enabled.  Off by default — meshing
+    /// is costly (extra LiDAR processing + per-frame ARMeshAnchor
+    /// churn) and only the StitcherFrame `meshGeometry` consumer wants
+    /// it.  Driven from JS via
+    /// `NativeModules.RNSARSession.setSceneReconstructionEnabled(bool)`
+    /// (the <Camera> `enableMesh` prop).  When toggled while a session
+    /// is live, the session is reconfigured + re-run in place.
+    ///
+    /// Honored both at session creation (`start()`) and on live toggle
+    /// (`setSceneReconstructionEnabled`).  Independent of the depth
+    /// `frameSemantics`/planeDetection config — those are left
+    /// untouched.  No-ops on devices without
+    /// `supportsSceneReconstruction` (the flag is stored but produces
+    /// no mesh).
+    @objc public private(set) var isSceneReconstructionEnabled: Bool = false
+
+    // ──────────────────────────────────────────────────────────────
+    // v0.18.0 — configurable plane detection (planeDetection prop)
+    // ──────────────────────────────────────────────────────────────
+    /// Which plane orientations ARKit should detect, driven from JS via
+    /// `NativeModules.RNSARSession.setPlaneDetection(mode)` (the
+    /// `<Camera>` `planeDetection` prop).  Default `[.vertical]` preserves
+    /// the plane-projected stitch path's long-standing behaviour.  Stored
+    /// as the raw ARKit OptionSet so `start()` and the live-reconfigure
+    /// paths (`setSceneReconstructionEnabled` / `setPlaneDetection`) read
+    /// one source of truth.
+    private var planeDetectionOptions:
+        ARWorldTrackingConfiguration.PlaneDetection = [.vertical]
+
     // ──────────────────────────────────────────────────────────────
     // V15.0b — vertical plane detection
     // ──────────────────────────────────────────────────────────────
@@ -423,6 +470,46 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
     /// been torn down.
     @objc public weak var incrementalConsumer: ARFrameConsumer?
 
+    // ──────────────────────────────────────────────────────────────
+    // v0.18.0 — `onArFrame` LIGHT-metadata channel
+    // ──────────────────────────────────────────────────────────────
+    //
+    // When a host supplies the `<Camera onArFrame={...}>` prop, the TS
+    // layer calls `setArFrameMetaEnabled(true, intervalMs)`; on
+    // unmount / prop-removal it calls `(false, _)`.  While enabled, each
+    // ARFrame's per-frame path builds the LIGHT `ARFrameMeta` dictionary
+    // (no pixel / vertex / face bytes — see
+    // `CameraFrameHostObject.lightArFrameMetaFromARFrame:pose:`) and
+    // posts it on `.retailensARFrameMeta` for the bridge to re-emit.
+    //
+    // Throttle: emit at most one meta per `arFrameMetaIntervalSec`
+    // (default 0.1s ≈ 10Hz) using `CACurrentMediaTime()` (monotonic,
+    // unaffected by wall-clock changes).  Both flags are touched only on
+    // the ARSession delegate thread (the per-frame path) + the bridge
+    // thread (the setter); guarded by `arFrameMetaLock`.
+    private var arFrameMetaEnabled: Bool = false
+    private var arFrameMetaIntervalSec: TimeInterval = 0.1
+    private var lastArFrameMetaEmit: TimeInterval = 0
+    private let arFrameMetaLock = NSLock()
+
+    // ──────────────────────────────────────────────────────────────
+    // v0.19.0 — native AR plugin framework (RNISARPluginRegistry)
+    // ──────────────────────────────────────────────────────────────
+    //
+    // While the plugin registry is NON-EMPTY, the per-frame path builds a
+    // `RNISARFrameContext` once and calls each registered plugin's
+    // `process(_:)` on the AR (delegate) thread (see `invokeArPlugins`).
+    // Non-nil SYNC results are cached here so the throttled `onArFrame`
+    // meta build can fold them in under `plugins: { [name]: result }`
+    // without re-running plugins.  Zero-plugin apps skip the whole path
+    // (the registry's `isEmpty` gate), so they pay nothing.
+    //
+    // Written on the AR thread (per-frame) and read on the same thread
+    // (the meta build runs inline in `session(_:didUpdate:)`), but guarded
+    // anyway for defensiveness against any future off-thread reader.
+    private var latestPluginSyncResults: [String: Any] = [:]
+    private let pluginSyncResultsLock = NSLock()
+
     private override init() {
         super.init()
         arSession.delegate = self
@@ -454,40 +541,12 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
                    "[V15.0f-ar-start] start() called while already running — ignored to preserve plane detection state")
             return
         }
-        let config = ARWorldTrackingConfiguration()
-        // sceneDepth gives us per-pixel depth on LiDAR-equipped
-        // devices; gracefully no-ops on non-LiDAR devices.  Used by
-        // Phase 6 measurement.
-        if ARWorldTrackingConfiguration.supportsFrameSemantics(.smoothedSceneDepth) {
-            config.frameSemantics = .smoothedSceneDepth
-        }
-        // V15.0b — enable VERTICAL plane detection for the
-        // plane-projected stitch mode.  ARKit incrementally builds a
-        // model of any vertical surface in view (typical retail
-        // fixture wall).  The first-detected vertical plane's
-        // transform is latched at capture-start and used as the
-        // canvas reference frame: each accepted camera frame is
-        // warped onto the plane via a 3×3 homography rather than
-        // onto a virtual cylinder/plane at first-frame anchor.
-        // CPU cost is negligible (<2 ms/frame).  Detection time:
-        // 2–5 s on non-LiDAR devices, sub-second on LiDAR.
-        config.planeDetection = [.vertical]
-        // Auto-focus on for better feature tracking on shelves with
-        // small text and packaging detail.
-        config.isAutoFocusEnabled = true
-
-        // Option B — prefer the 4:3 videoFormat for full sensor FOV; the
-        // keyframe is downscaled to arKeyframeMaxLongEdge below so memory
-        // stays consistent across devices regardless of the format res.
-        if let fmt = ARWorldTrackingConfiguration.supportedVideoFormats.min(by: { a, b in
-            let da = abs(a.imageResolution.width / a.imageResolution.height - 4.0 / 3.0)
-            let db = abs(b.imageResolution.width / b.imageResolution.height - 4.0 / 3.0)
-            if abs(da - db) > 0.001 { return da < db }
-            return a.imageResolution.width * a.imageResolution.height
-                 < b.imageResolution.width * b.imageResolution.height
-        }) {
-            config.videoFormat = fmt
-        }
+        // Build the shared base config (depth semantics + plane detection
+        // + autofocus + scene reconstruction + 4:3 video format).  See
+        // `makeBaseConfiguration()` — centralised so `start()` and the
+        // live-reconfigure paths can't drift.  `start()` is the only path
+        // that resets tracking + removes existing anchors.
+        let config = makeBaseConfiguration()
         arSession.run(config, options: [.resetTracking, .removeExistingAnchors])
         // V16-diag — log the chosen video format so we can correlate
         // batch-keyframe memory with ARFrame resolution.  iPhone Pro
@@ -553,6 +612,180 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         detectedPlaneTransformInternal = nil
         bestRejectedAlignment = -1.0
         planeLatchLock.unlock()
+        // v0.19.0 — drop any cached SYNC plugin results so the next
+        // capture's `onArFrame` meta doesn't surface stale plugin output
+        // before the first frame of the new session runs the plugins.
+        pluginSyncResultsLock.lock()
+        latestPluginSyncResults = [:]
+        pluginSyncResultsLock.unlock()
+    }
+
+    /// Build the `ARWorldTrackingConfiguration` shared by `start()` and
+    /// the live-reconfigure paths (`setSceneReconstructionEnabled`,
+    /// `setPlaneDetection`).  Single source of truth so the call sites
+    /// can't drift — every reconfigure preserves the SAME depth
+    /// frameSemantics, current plane-detection mode, autofocus, scene
+    /// reconstruction, and 4:3 video-format preference.  Only the `run`
+    /// OPTIONS differ at the call site (`start()` resets tracking; the
+    /// live toggles do not).
+    ///
+    /// - sceneDepth + smoothedSceneDepth: enable both when supported so
+    ///   `ARFrame.sceneDepth` populates the StitcherFrame `arDepth` field;
+    ///   each is gated by `supportsFrameSemantics` so this no-ops on
+    ///   non-LiDAR devices instead of throwing at `run()`.
+    /// - planeDetection: from `planeDetectionOptions` (default `[.vertical]`
+    ///   for the plane-projected stitch path; set via `setPlaneDetection`).
+    /// - autofocus: on, for feature tracking on shelves with small text.
+    /// - sceneReconstruction: from the stored `isSceneReconstructionEnabled`
+    ///   flag (no-ops on non-LiDAR devices).
+    /// - videoFormat: prefer 4:3 for full sensor FOV (keyframe is
+    ///   downscaled to `arKeyframeMaxLongEdge` later for memory parity).
+    private func makeBaseConfiguration() -> ARWorldTrackingConfiguration {
+        let config = ARWorldTrackingConfiguration()
+        var depthSemantics: ARConfiguration.FrameSemantics = []
+        if ARWorldTrackingConfiguration.supportsFrameSemantics(.sceneDepth) {
+            depthSemantics.insert(.sceneDepth)
+        }
+        if ARWorldTrackingConfiguration.supportsFrameSemantics(.smoothedSceneDepth) {
+            depthSemantics.insert(.smoothedSceneDepth)
+        }
+        config.frameSemantics = depthSemantics
+        config.planeDetection = planeDetectionOptions
+        config.isAutoFocusEnabled = true
+        Self.applySceneReconstruction(to: config,
+                                      enabled: isSceneReconstructionEnabled)
+        if let fmt = ARWorldTrackingConfiguration.supportedVideoFormats.min(by: { a, b in
+            let da = abs(a.imageResolution.width / a.imageResolution.height - 4.0 / 3.0)
+            let db = abs(b.imageResolution.width / b.imageResolution.height - 4.0 / 3.0)
+            if abs(da - db) > 0.001 { return da < db }
+            return a.imageResolution.width * a.imageResolution.height
+                 < b.imageResolution.width * b.imageResolution.height
+        }) {
+            config.videoFormat = fmt
+        }
+        return config
+    }
+
+    /// Set the ARWorldTrackingConfiguration's `sceneReconstruction`
+    /// from a desired-enabled flag, gated on device support.  Prefers
+    /// `.meshWithClassification` (per-face semantic labels — what the
+    /// StitcherFrame `meshGeometry.classifications` consumer wants),
+    /// falling back to plain `.mesh`, and `.none` when disabled or
+    /// unsupported.  Centralised so `start()` and the live-toggle path
+    /// stay consistent.
+    private static func applySceneReconstruction(
+        to config: ARWorldTrackingConfiguration,
+        enabled: Bool
+    ) {
+        guard enabled else {
+            // `ARWorldTrackingConfiguration.SceneReconstruction` is an
+            // OptionSet — the empty set `[]` means "no meshing"
+            // (`.none` is unavailable on OptionSets).
+            config.sceneReconstruction = []
+            return
+        }
+        if ARWorldTrackingConfiguration.supportsSceneReconstruction(
+            .meshWithClassification) {
+            config.sceneReconstruction = .meshWithClassification
+        } else if ARWorldTrackingConfiguration.supportsSceneReconstruction(
+            .mesh) {
+            config.sceneReconstruction = .mesh
+        } else {
+            // No LiDAR / unsupported — leave meshing off (empty set).
+            config.sceneReconstruction = []
+        }
+    }
+
+    /// Toggle ARKit scene reconstruction (LiDAR mesh / `ARMeshAnchor`s).
+    /// Stores the flag so it's honored by the next `start()`, and — if a
+    /// session is ALREADY running — reconfigures + re-runs the live
+    /// session in place so the toggle takes effect immediately.
+    ///
+    /// Reconfiguration rebuilds the SAME config `start()` builds (depth
+    /// frameSemantics + vertical planeDetection + autofocus + 4:3 video
+    /// format) so we don't accidentally drop those when flipping the
+    /// mesh flag.  We re-run WITHOUT `[.resetTracking,
+    /// .removeExistingAnchors]` so the existing world map, pose log, and
+    /// any latched plane survive the toggle (only the mesh option
+    /// changes).
+    ///
+    /// No-op on devices without scene-reconstruction support: the flag
+    /// is still stored (cheap, harmless) but `applySceneReconstruction`
+    /// leaves the config `.none`.
+    @objc public func setSceneReconstructionEnabled(_ enabled: Bool) {
+        isSceneReconstructionEnabled = enabled
+        os_log(.fault, log: arSessionDiagLog,
+               "[scene-mesh] setSceneReconstructionEnabled(%{public}@) running=%{public}@ supported=%{public}@",
+               enabled ? "true" : "false",
+               isRunning ? "true" : "false",
+               ARWorldTrackingConfiguration.supportsSceneReconstruction(.mesh)
+                   ? "true" : "false")
+
+        guard isRunning else { return }
+
+        // Rebuild the live config from the shared builder — picks up the
+        // new mesh flag (just stored) along with the current depth
+        // semantics + plane-detection mode, so a mesh toggle never
+        // silently drops those.  Re-run in place — NO reset/removeAnchors
+        // so existing tracking, pose log, and latched plane survive.
+        let config = makeBaseConfiguration()
+        arSession.run(config)
+    }
+
+    /// Set which plane orientations ARKit detects — the JS `<Camera>`
+    /// `planeDetection` prop, routed via
+    /// `NativeModules.RNSARSession.setPlaneDetection(mode)`.  Stores the
+    /// mode (honored by the next `start()`) and, if a session is live,
+    /// reconfigures + re-runs in place (no reset — tracking / pose log /
+    /// latched plane survive).
+    ///
+    /// `mode`: `"vertical"` (default), `"horizontal"`, or `"both"`.
+    /// Anything else falls back to `"vertical"`.
+    ///
+    /// NOTE on the legacy vertical-plane latch: the V15 plane-projected
+    /// stitch latches the first camera-facing VERTICAL plane.  Choosing
+    /// `"horizontal"` drops vertical detection, so that latch won't fire
+    /// — an explicit opt-out (the caller asked for horizontal-only).
+    /// `"vertical"` and `"both"` keep it working.
+    @objc public func setPlaneDetection(_ mode: String) {
+        switch mode {
+        case "horizontal": planeDetectionOptions = [.horizontal]
+        case "both":       planeDetectionOptions = [.horizontal, .vertical]
+        default:           planeDetectionOptions = [.vertical]  // "vertical" + fallback
+        }
+        os_log(.fault, log: arSessionDiagLog,
+               "[plane-detect] setPlaneDetection(%{public}@) running=%{public}@",
+               mode, isRunning ? "true" : "false")
+        guard isRunning else { return }
+        // Reconfigure in place — NO reset/removeAnchors so existing
+        // tracking + pose log survive the plane-mode change.
+        let config = makeBaseConfiguration()
+        arSession.run(config)
+    }
+
+    /// v0.18.0 — toggle the `onArFrame` LIGHT-metadata channel.  Called
+    /// from JS (via the bridge) with `true` + the throttle interval when a
+    /// host supplies `<Camera onArFrame={...}>`, and `false` on
+    /// unmount / prop-removal.  Idempotent.
+    ///
+    /// `intervalMs` clamps to a 16ms floor (≈60Hz, ARKit's max delivery
+    /// rate) — a smaller value can't produce more frames, and 0 would
+    /// disable throttling entirely (one emit per ARFrame).  Resetting the
+    /// `lastArFrameMetaEmit` clock on enable means the first frame after
+    /// `onArFrame` mounts emits immediately rather than waiting out a
+    /// stale interval from a previous session.
+    @objc public func setArFrameMetaEnabled(_ enabled: Bool, intervalMs: Double) {
+        arFrameMetaLock.lock()
+        arFrameMetaEnabled = enabled
+        arFrameMetaIntervalSec = max(0.016, intervalMs / 1000.0)
+        if enabled {
+            // Emit the next frame immediately (don't carry a stale clock).
+            lastArFrameMetaEmit = 0
+        }
+        arFrameMetaLock.unlock()
+        os_log(.fault, log: arSessionDiagLog,
+               "[onArFrame] setArFrameMetaEnabled(%{public}@) interval=%.0fms",
+               enabled ? "true" : "false", intervalMs)
     }
 
     /// Empty the pose log — call between captures so the next
@@ -637,6 +870,22 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         // double-consuming would ingest each frame twice.
         RNSARWorkletRuntime.shared().dispatchFrame(frame, pose: pose)
 
+        // v0.19.0 — native AR plugin framework.  When the registry is
+        // non-empty, build the per-frame `RNISARFrameContext` once and run
+        // every registered plugin's `process(_:)` SYNCHRONOUSLY on this AR
+        // thread (so the live pixel/depth buffers are valid for the call).
+        // Caches non-nil SYNC results for the meta build below.  Cheap
+        // no-op when no plugins are registered (the common case).  Runs
+        // BEFORE `maybeEmitArFrameMeta` so the throttled `onArFrame` meta
+        // can fold in this frame's freshest plugin results.
+        invokeArPlugins(frame, pose: pose)
+
+        // v0.18.0 — `onArFrame` LIGHT-metadata channel.  Gated +
+        // throttled; builds the ARFrameMeta dictionary and posts it for
+        // the bridge to re-emit.  Cheap no-op when disabled (the common
+        // case — most hosts don't supply `onArFrame`).
+        maybeEmitArFrameMeta(frame, pose: pose)
+
         // If recording is in flight, append this frame to the
         // asset writer DIRECTLY — no queue hop.
         //
@@ -1182,6 +1431,141 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         return path
     }
 
+    /// v0.18.0 — build + post the LIGHT `onArFrame` metadata for this
+    /// frame, gated on `arFrameMetaEnabled` and throttled to
+    /// `arFrameMetaIntervalSec`.  Runs on the ARSession delegate thread
+    /// (the per-frame `didUpdate` path).
+    ///
+    /// The gate + throttle check is taken under `arFrameMetaLock` (a
+    /// microsecond hold); the actual meta build (the slightly more
+    /// expensive part — anchor transpose, depth/mesh probes) happens
+    /// OUTSIDE the lock so the bridge's `setArFrameMetaEnabled` never
+    /// blocks behind a frame build.  Posting on NotificationCenter is
+    /// synchronous but the observer (`RNSARSessionBridge.handle…`) just
+    /// hops to the main queue for the actual JS emit, so this returns
+    /// quickly and never blocks ARKit's delegate.
+    ///
+    /// `CACurrentMediaTime()` is the monotonic media clock (same unit as
+    /// the throttle interval); immune to wall-clock adjustments.
+    private func maybeEmitArFrameMeta(_ frame: ARFrame, pose: RNSARFramePose) {
+        arFrameMetaLock.lock()
+        let enabled = arFrameMetaEnabled
+        let interval = arFrameMetaIntervalSec
+        let last = lastArFrameMetaEmit
+        let now = CACurrentMediaTime()
+        let due = enabled && (last == 0 || (now - last) >= interval)
+        if due {
+            // Reserve this slot before releasing the lock so a burst of
+            // delegate callbacks can't all pass the throttle gate.
+            lastArFrameMetaEmit = now
+        }
+        arFrameMetaLock.unlock()
+
+        guard due else { return }
+
+        // Build the LIGHT meta (no pixel/vertex/face bytes).  Reuses the
+        // Obj-C++ extraction helpers + the shared C++ extraction-config
+        // gating (depth/anchors/mesh ⇐ enableDepth/enableAnchors/enableMesh).
+        let meta = CameraFrameHostObject.lightArFrameMeta(from: frame, pose: pose)
+
+        // v0.19.0 — fold in any SYNC plugin results captured by
+        // `invokeArPlugins` for the freshest frames.  Only attach the
+        // `plugins` key when there's at least one result, so the common
+        // (no-plugin) meta shape is unchanged.  Snapshot under the lock,
+        // then bridge into a fresh dictionary copy.
+        pluginSyncResultsLock.lock()
+        let pluginResults = latestPluginSyncResults
+        pluginSyncResultsLock.unlock()
+        let userInfo: [AnyHashable: Any]
+        if pluginResults.isEmpty {
+            userInfo = meta
+        } else {
+            var withPlugins = meta
+            withPlugins["plugins"] = pluginResults
+            userInfo = withPlugins
+        }
+
+        NotificationCenter.default.post(
+            name: .retailensARFrameMeta,
+            object: nil,
+            userInfo: userInfo
+        )
+    }
+
+    /// v0.19.0 — run all registered native AR plugins for this frame.
+    /// Gated on the registry being NON-EMPTY (the cheap `isEmpty` check) so
+    /// zero-plugin apps skip the context build entirely.  When plugins are
+    /// present, builds ONE `RNISARFrameContext` (zero-copy view of the
+    /// frame's live buffers + the already-built anchor dicts) and calls
+    /// each plugin's `process(_:)` SYNCHRONOUSLY on this AR (delegate)
+    /// thread — so the live `pixelBuffer` / `depthBuffer` are valid for the
+    /// call (the plugin must copy before offloading; see the protocol
+    /// docstring).  Non-nil SYNC results are cached in
+    /// `latestPluginSyncResults` for the throttled `onArFrame` meta to fold
+    /// in; ASYNC results arrive later via `RNISARPluginRegistry.emit`.
+    private func invokeArPlugins(_ frame: ARFrame, pose: RNSARFramePose) {
+        let registry = RNISARPluginRegistry.shared
+        guard !registry.isEmpty else { return }
+        let plugins = registry.plugins()
+        guard !plugins.isEmpty else { return }
+
+        // depthBuffer: expose the live sceneDepth map ONLY when the
+        // `<Camera enableDepth>` prop is on (gating read in Obj-C++ so the
+        // C++ extraction-config header stays out of Swift).  Prefer
+        // `sceneDepth`, fall back to `smoothedSceneDepth` — same precedence
+        // as the full extraction path.
+        var depthBuffer: CVPixelBuffer? = nil
+        if CameraFrameHostObject.arExtractionDepthEnabled() {
+            if let dd = frame.sceneDepth ?? frame.smoothedSceneDepth {
+                depthBuffer = dd.depthMap
+            }
+        }
+
+        // anchors: reuse the EXACT light dicts the `onArFrame` meta builds
+        // (gated on `enableAnchors`; empty otherwise) — DRY single source.
+        let anchorDicts = CameraFrameHostObject.arAnchorDicts(from: frame)
+        let anchors = anchorDicts as? [[String: Any]] ?? []
+
+        let context = RNISARFrameContext(
+            pixelBuffer: frame.capturedImage,
+            timestampNs: frame.timestamp * 1e9,
+            fx: pose.fx, fy: pose.fy, cx: pose.cx, cy: pose.cy,
+            imageWidth: pose.imageWidth, imageHeight: pose.imageHeight,
+            poseRotation: [pose.qx, pose.qy, pose.qz, pose.qw],
+            poseTranslation: [pose.tx, pose.ty, pose.tz],
+            trackingState: Self.trackingStateString(pose.trackingState),
+            depthBuffer: depthBuffer,
+            anchors: anchors
+        )
+
+        var syncResults: [String: Any] = [:]
+        for plugin in plugins {
+            // Defensive: a plugin throwing/crashing in `process` would take
+            // down the AR thread, but Swift has no try/catch for non-Error
+            // crashes — the contract is that plugins are well-behaved.  We
+            // simply collect non-nil results keyed by the plugin's name.
+            if let result = plugin.process(context) {
+                syncResults[plugin.name()] = result
+            }
+        }
+
+        pluginSyncResultsLock.lock()
+        latestPluginSyncResults = syncResults
+        pluginSyncResultsLock.unlock()
+    }
+
+    /// Map the SDK's `RNSARTrackingState` to the same string the
+    /// `onArFrame` meta + `CameraFrame.trackingState` use, so plugins see a
+    /// consistent vocabulary.
+    private static func trackingStateString(_ s: RNSARTrackingState) -> String {
+        switch s {
+        case .tracking:     return "normal"
+        case .limited:      return "limited"
+        case .initialising: return "limited"
+        case .notAvailable: return "notAvailable"
+        }
+    }
+
     private func makePose(from frame: ARFrame) -> RNSARFramePose {
         // ARKit's transform is a 4x4 matrix; extract translation
         // (last column) and rotation (top-left 3x3 → quaternion).

package/ios/Sources/RNImageStitcher/RNSARWorkletRuntime.h

@@ -35,7 +35,7 @@
 //
 // The implementation needs to hold `std::shared_ptr<JsiWorkletContext>`
 // + run JSI value construction, which can't live in pure Swift.  Same
-// pattern as `KeyframeGateBridge.{h,mm}` + `StitcherFrameHostObject.{h,mm}`:
+// pattern as `KeyframeGateBridge.{h,mm}` + `CameraFrameHostObject.{h,mm}`:
 // keep the header umbrella-safe (no JSI imports), put the C++ glue in
 // the .mm.
 //
@@ -103,7 +103,7 @@ typedef void (^RNSARFirstPartyCallback)(ARFrame *arFrame,
 /// runtime can be built + linked + the API surface fixed).
 ///
 /// The Phase 3c implementation will:
-///   1. Build a `StitcherFrameHostObject` from `arFrame` + `pose`.
+///   1. Build a `CameraFrameHostObject` from `arFrame` + `pose`.
 ///   2. Run the first-party stitching synchronously on the caller
 ///      thread (preserves today's `ingestFromARCameraView` cost
 ///      envelope at the producer site).

package/ios/Sources/RNImageStitcher/RNSARWorkletRuntime.mm

@@ -26,7 +26,7 @@
 // (process termination reclaims it).  Phase 3c will keep this shape.
 
 #import "RNSARWorkletRuntime.h"
-#import "StitcherFrameHostObject.h"
+#import "CameraFrameHostObject.h"
 
 #import <Foundation/Foundation.h>
 #import <os/log.h>
@@ -48,7 +48,7 @@
 #include <vector>
 
 // Forward-declare `RNSARFramePose` — same pattern as
-// StitcherFrameHostObject.mm.  We don't read its fields here in
+// CameraFrameHostObject.mm.  We don't read its fields here in
 // Phase 3b (the stub doesn't unpack the pose), but Phase 3c will.
 @class RNSARFramePose;
 
@@ -210,8 +210,8 @@
     // (acceptable for Phase 4b minimum-viable; a per-frame buffer
     // copy is a known optimization for later if throughput
     // suffers).
-    StitcherFrameHostObject *hostObj =
-        [StitcherFrameHostObject fromARFrame:arFrame pose:pose];
+    CameraFrameHostObject *hostObj =
+        [CameraFrameHostObject fromARFrame:arFrame pose:pose];
 
     // Hand the host object's jsi::HostObject shared_ptr (boxed as
     // void*) into the lambda.  The lambda will:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "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",