react-native-image-stitcher 0.16.2 → 0.18.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,28 @@ 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()
+
     private override init() {
         super.init()
         arSession.delegate = self
@@ -454,40 +523,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
@@ -501,10 +542,34 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         isRunning = true
         currentTrackingState = .initialising
 
-        // Per-frame ingest calls `incrementalConsumer.consumeFrame`
-        // directly from `session(_:didUpdate:)` below. (The v0.8
-        // worklet-runtime indirection that used to live here was archived
-        // in the batch-keyframe cleanup — see archive/.)
+        // v0.8.0 Phase 3c/4b — wire the AR worklet runtime.  The
+        // per-frame ingest is routed through `RNSARWorkletRuntime`
+        // (see `session(_:didUpdate:)` below) instead of calling the
+        // incremental consumer directly.  Two steps here:
+        //
+        //   1. `installIfNeeded()` lazily constructs the worklet
+        //      runtime's `JsiWorkletContext` + its serial dispatch
+        //      queue (idempotent; safe across redundant start() calls
+        //      and multiple <Camera> mounts).
+        //   2. `setFirstPartyCallback:` installs the EXISTING first-
+        //      party stitching behaviour as a closure.  The runtime
+        //      invokes this synchronously on the delegate (caller)
+        //      thread per frame — byte-identical to the old direct
+        //      `consumeFrame(...)` call — and then fans the frame out
+        //      to any host-registered worklets asynchronously on its
+        //      own queue.
+        //
+        // The callback captures `self` weakly so the runtime singleton
+        // (process-lifetime) never keeps this session alive.  It reads
+        // `incrementalConsumer` (itself weak) at call time, so a torn-
+        // down consumer simply no-ops — same semantics as the prior
+        // `incrementalConsumer?.consumeFrame(...)` optional-chain.
+        let workletRuntime = RNSARWorkletRuntime.shared()
+        workletRuntime.installIfNeeded()
+        workletRuntime.setFirstPartyCallback { [weak self] arFrame, pose in
+            self?.incrementalConsumer?.consumeFrame(
+                pixelBuffer: arFrame.capturedImage, pose: pose)
+        }
     }
 
     @objc public func stop() {
@@ -513,6 +578,12 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         isRunning = false
         currentTrackingState = .notAvailable
         clearPoseLog()
+        // v0.8.0 Phase 3c — clear the worklet runtime's first-party
+        // callback so the (process-lifetime) runtime singleton doesn't
+        // hold the closure (and transitively the consumer reference)
+        // between captures.  `start()` reinstalls it on the next run.
+        // Idempotent; safe even if start() never ran the install path.
+        RNSARWorkletRuntime.shared().setFirstPartyCallback(nil)
         // V15.0b — clear latched plane so the next capture detects
         // afresh.  Plane geometry is per-capture: a different
         // fixture in a different orientation needs a new lock.
@@ -525,6 +596,174 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         planeLatchLock.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
     /// panorama starts fresh.
     @objc public func clearPoseLog() {
@@ -596,8 +835,22 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         // cv::Mat sync conversion synchronously on the delegate thread
         // before returning, so the captured pixel buffer is safe for
         // ARKit to recycle after this call.
-        incrementalConsumer?.consumeFrame(pixelBuffer: frame.capturedImage,
-                                          pose: pose)
+        //
+        // `dispatchFrame(_:pose:)` runs the first-party callback
+        // (installed in `start()`, which wraps the same
+        // `incrementalConsumer.consumeFrame(...)` path) SYNCHRONOUSLY on
+        // this delegate thread — preserving the pool-reuse contract —
+        // and THEN fans the frame out to any host-registered worklets
+        // ASYNCHRONOUSLY on the runtime's own queue.  Do NOT also call
+        // `consumeFrame` here: dispatchFrame already drives it, and
+        // double-consuming would ingest each frame twice.
+        RNSARWorkletRuntime.shared().dispatchFrame(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.
@@ -1144,6 +1397,49 @@ 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)
+        NotificationCenter.default.post(
+            name: .retailensARFrameMeta,
+            object: nil,
+            userInfo: meta
+        )
+    }
+
     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

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// RNSARWorkletRuntime.h — Obj-C facade for the v0.8.0 AR-mode
+// worklet runtime.  Wraps `react-native-worklets-core`'s
+// `RNWorklet::JsiWorkletContext` (the same primitive vision-camera
+// uses for its Frame Processor runtime) so the lib can dispatch
+// per-ARFrame worklets on a thread we own — rather than ARKit's
+// delegate queue, where doing significant work would block the
+// AR session's update loop.
+//
+// ## Phase 3b scope (this commit)
+//
+// Owns:
+//   - The dispatch queue the worklet runtime pins to.
+//   - The underlying `JsiWorkletContext` (constructed lazily on
+//     `installIfNeeded`, lives for the singleton's lifetime).
+//
+// Exposes:
+//   - `+ shared` singleton accessor.
+//   - `- installIfNeeded` (idempotent runtime construction).
+//   - `- isInstalled` for diagnostics + tests.
+//   - `- dispatchFrame:pose:` — currently a no-op stub; Phase 3c
+//     fills in the actual host-object construction + worklet
+//     invocation + first-party stitching dispatch.
+//
+// Host-worklet registry is intentionally NOT in Phase 3b — Phase 4
+// lands the JSI plugin + TS-side hook that defines the storage
+// shape (NSMutableArray of boxed shared_ptrs vs a C++ vector ivar
+// vs something else).  Pre-committing the storage type here would
+// risk rework.  See
+// `docs/plans/handoff/2026-05-26-v0.8.0-phases-2-5-implementation-guide.md`
+// Phase 4 section for the planned API.
+//
+// ## Why Obj-C facade with `.mm` implementation
+//
+// 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}` + `CameraFrameHostObject.{h,mm}`:
+// keep the header umbrella-safe (no JSI imports), put the C++ glue in
+// the .mm.
+//
+// ## Header umbrella safety
+//
+// This .h imports only Foundation + ARKit (both system frameworks).
+// Worklets-core types are confined to the .mm.
+
+#pragma once
+
+#import <Foundation/Foundation.h>
+#import <ARKit/ARKit.h>
+
+@class RNSARFramePose;
+
+NS_ASSUME_NONNULL_BEGIN
+
+NS_SWIFT_NAME(RNSARWorkletRuntime)
+@interface RNSARWorkletRuntime : NSObject
+
+/// Singleton accessor.  One AR worklet runtime per process; multiple
+/// `<Camera>` mounts share it.  Construction is cheap (just an Obj-C
+/// alloc + an `NSMutableArray`); the heavy JSI work happens in
+/// `-installIfNeeded`.
++ (instancetype)shared;
+
+/// Construct the underlying `JsiWorkletContext` if not yet
+/// installed.  Idempotent — repeated calls are no-ops.  Called from
+/// `RNSARSession` at AR-mode start time (Phase 3c will wire this
+/// up; Phase 3b ships the method but no one calls it yet).
+///
+/// Threading: safe to call from any thread; internally serialised.
+/// The runtime's own dispatch queue starts running once installed.
+- (void)installIfNeeded;
+
+/// Diagnostics + tests.  Returns `YES` after a successful
+/// `-installIfNeeded`.
+- (BOOL)isInstalled;
+
+/// Phase 3c — type of the first-party stitching callback.  Invoked
+/// synchronously on the caller thread (`ARSession.delegateQueue` —
+/// typically main queue today) per AR frame.  Block must consume
+/// the pixel buffer before returning (ARKit pool reuse contract).
+typedef void (^RNSARFirstPartyCallback)(ARFrame *arFrame,
+                                         RNSARFramePose *pose);
+
+/// Phase 3c — install the closure that takes ownership of the
+/// per-frame first-party stitching dispatch.  Called from
+/// `RNSARSession.start()` after the incremental consumer is set;
+/// the block then routes `dispatchFrame:pose:` calls through to
+/// the existing `incrementalConsumer.consumeFrame(...)` path.
+///
+/// Pre-Phase-3c the delegate called the consumer directly.  After
+/// Phase 3c the delegate calls `dispatchFrame:pose:` (this class)
+/// which invokes the callback.  Net behavior is byte-identical;
+/// the indirection sets up the seam where Phase 4 will fan out to
+/// host worklets without changing the first-party path.
+///
+/// Pass `nil` to clear (e.g. on `RNSARSession.stop()`).  Idempotent.
+- (void)setFirstPartyCallback:(nullable RNSARFirstPartyCallback)callback;
+
+/// Dispatch one AR frame through the registered worklets.  Called
+/// per `ARFrame` by `RNSARSession.delegate` once Phase 3c lands the
+/// migration (Phase 3b ships this method as a no-op stub so the
+/// runtime can be built + linked + the API surface fixed).
+///
+/// The Phase 3c implementation will:
+///   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).
+///   3. If any host worklets are registered, dispatch the host
+///      object onto the worklet runtime's thread + invoke each
+///      worklet via `RNWorklet::WorkletInvoker::call`.
+///   4. Invalidate the host object after all worklets return.
+///
+/// Phase 3c gate: install/idempotence tests + this method's
+/// integration test required before merge.  See
+/// `docs/plans/handoff/2026-05-26-v0.8.0-phases-2-5-implementation-guide.md`
+/// Phase 3c gate criteria.
+///
+/// Threading: typically called from `ARSession.delegateQueue` (main
+/// queue by default; Phase 3c will pin it explicitly to a
+/// dedicated queue).
+- (void)dispatchFrame:(ARFrame *)arFrame pose:(RNSARFramePose *)pose
+    NS_SWIFT_NAME(dispatchFrame(_:pose:));
+
+@end
+
+NS_ASSUME_NONNULL_END