react-native-image-stitcher 0.16.2 → 0.17.0

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, 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, 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 })) : (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 })) : (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/camera/CaptureMemoryPill.d.ts

@@ -16,9 +16,10 @@
  * (false comfort exactly where OOM happens).  Falls back to 1500/2200 if the
  * RAM read is unavailable.
  *
- * Backed by the `getMemoryFootprintMB()` native module (iOS: `task_info`
- * `phys_footprint`; Android: `/proc/self/statm` RSS — the SAME number the C++
- * `[memstat]` logs report).  Returns -1 if the native call fails.
+ * Backed by the `getMemoryFootprintMB()` native module (iOS:
+ * `task_info(TASK_VM_INFO)` `phys_footprint`; Android: `/proc/self/statm` RSS
+ * — resident pages, unthrottled — the SAME number the C++ `[memstat]` logs
+ * report).  Returns -1 if the native call fails.
  *
  * Mount this pill inside a `settings.debug`-gated branch — it
  * polls native every 500 ms and is unwanted in production builds.

package/dist/camera/CaptureMemoryPill.js

@@ -18,9 +18,10 @@
  * (false comfort exactly where OOM happens).  Falls back to 1500/2200 if the
  * RAM read is unavailable.
  *
- * Backed by the `getMemoryFootprintMB()` native module (iOS: `task_info`
- * `phys_footprint`; Android: `/proc/self/statm` RSS — the SAME number the C++
- * `[memstat]` logs report).  Returns -1 if the native call fails.
+ * Backed by the `getMemoryFootprintMB()` native module (iOS:
+ * `task_info(TASK_VM_INFO)` `phys_footprint`; Android: `/proc/self/statm` RSS
+ * — resident pages, unthrottled — the SAME number the C++ `[memstat]` logs
+ * report).  Returns -1 if the native call fails.
  *
  * Mount this pill inside a `settings.debug`-gated branch — it
  * polls native every 500 ms and is unwanted in production builds.

package/dist/stitching/ensureStitcherProxyInstalled.d.ts

@@ -0,0 +1,8 @@
+export declare function ensureStitcherProxyInstalled(): boolean;
+/**
+ * Test-only — reset module-internal state.  Used by jest to allow
+ * multiple test cases to re-trigger the install path independently.
+ * NOT exported from `src/index.ts`.
+ */
+export declare function _resetStitcherProxyInstallStateForTests(): void;
+//# sourceMappingURL=ensureStitcherProxyInstalled.d.ts.map

package/dist/stitching/ensureStitcherProxyInstalled.js

@@ -0,0 +1,81 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureStitcherProxyInstalled = ensureStitcherProxyInstalled;
+exports._resetStitcherProxyInstallStateForTests = _resetStitcherProxyInstallStateForTests;
+const react_native_1 = require("react-native");
+/**
+ * `__DEV__` is RN's global dev-flag.  Guard the read with `typeof`
+ * so the helper works in any environment that imports it without
+ * defining __DEV__ (jest, SSR, custom tooling).  Same pattern RN's
+ * own debug code uses.
+ */
+function isDev() {
+    return typeof __DEV__ !== 'undefined' && __DEV__;
+}
+let installed = false;
+function ensureStitcherProxyInstalled() {
+    if (installed)
+        return true;
+    // Already installed by an earlier hook mount.  Cheap fast-path.
+    if (typeof globalThis.__stitcherProxy !== 'undefined') {
+        installed = true;
+        return true;
+    }
+    const mod = react_native_1.NativeModules
+        .StitcherJsiInstaller;
+    if (mod == null || typeof mod.install !== 'function') {
+        // Module not present — Android until Phase 4b.ii lands, or
+        // an old iOS build.  Surface this once at debug-info level so
+        // the host can see "your worklets are JS-registered only" in
+        // logcat / Console.app without a noisy per-frame warning.
+        if (isDev() && !warnedAboutMissingModule) {
+            warnedAboutMissingModule = true;
+            console.info('[react-native-image-stitcher] StitcherJsiInstaller native ' +
+                'module not found; host worklets registered in JS-side ' +
+                'registry only.  AR-mode dispatch requires the native install ' +
+                '(iOS Phase 4b.i — included in v0.8.0; Android Phase 4b.ii ' +
+                '— follow-up release).');
+        }
+        return false;
+    }
+    try {
+        const ok = mod.install();
+        if (!ok) {
+            // Native module ran but couldn't install (JSI runtime
+            // unreachable).  Same fallback as the missing-module case.
+            if (isDev() && !warnedAboutFailedInstall) {
+                warnedAboutFailedInstall = true;
+                console.info('[react-native-image-stitcher] StitcherJsiInstaller.install() ' +
+                    'returned false (JSI runtime unreachable — remote debug ' +
+                    'mode?).  Falling back to JS-side host worklet registry.');
+            }
+            return false;
+        }
+        installed = true;
+        return true;
+    }
+    catch (err) {
+        if (isDev() && !warnedAboutFailedInstall) {
+            warnedAboutFailedInstall = true;
+            console.info('[react-native-image-stitcher] StitcherJsiInstaller.install() ' +
+                'threw: ' +
+                String(err) +
+                '.  Falling back to JS-side host worklet registry.');
+        }
+        return false;
+    }
+}
+let warnedAboutMissingModule = false;
+let warnedAboutFailedInstall = false;
+/**
+ * Test-only — reset module-internal state.  Used by jest to allow
+ * multiple test cases to re-trigger the install path independently.
+ * NOT exported from `src/index.ts`.
+ */
+function _resetStitcherProxyInstallStateForTests() {
+    installed = false;
+    warnedAboutMissingModule = false;
+    warnedAboutFailedInstall = false;
+}
+//# sourceMappingURL=ensureStitcherProxyInstalled.js.map

package/ios/Sources/RNImageStitcher/RNSARSession.swift

@@ -501,10 +501,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 +537,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.
@@ -596,8 +626,16 @@ 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)
 
         // If recording is in flight, append this frame to the
         // asset writer DIRECTLY — no queue hop.

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}` + `StitcherFrameHostObject.{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 `StitcherFrameHostObject` 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

package/ios/Sources/RNImageStitcher/RNSARWorkletRuntime.mm

@@ -0,0 +1,313 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// RNSARWorkletRuntime.mm — Obj-C++ implementation.  See the header
+// for the API contract.  This file owns:
+//
+//   - The dispatch queue the worklet runtime is pinned to
+//   - The `std::shared_ptr<RNWorklet::JsiWorkletContext>` itself
+//   - The registry of host worklets (Phase 4 wiring will populate
+//     this via a JSI plugin entry point)
+//
+// Phase 3b scope: construct the context + expose the API.  No
+// dispatch logic yet — `dispatchFrame:pose:` is a stub.  Phase 3c
+// fills in (a) the host-object construction + worklet invocation,
+// (b) the first-party stitching callback, (c) the migration in
+// `RNSARSession.delegate`.
+//
+// ## Singleton lifetime note (for Leaks-tool readers)
+//
+// `+ shared` uses `dispatch_once`, so the singleton lives for the
+// process lifetime — same pattern as most Obj-C singletons.  This
+// means the dispatch queue (created in `init`) + the JsiWorkletContext
+// (constructed lazily in `installIfNeeded`) + the `workletCallInvoker`
+// lambda that captures the queue are ALL retained until process
+// termination.  Xcode Instruments → Leaks will flag this as "leaked
+// allocation rooted at the singleton" — that's noise, not a real leak
+// (process termination reclaims it).  Phase 3c will keep this shape.
+
+#import "RNSARWorkletRuntime.h"
+#import "StitcherFrameHostObject.h"
+
+#import <Foundation/Foundation.h>
+#import <os/log.h>
+
+#include <jsi/jsi.h>
+// worklets-core headers — use quotes-include since the pod
+// publishes them via HEADER_SEARCH_PATHS, not as a framework
+// module map.  Same pattern KeyframeGateFrameProcessor.mm uses
+// for vision-camera headers (which are reachable via <angle>
+// only because vc's podspec sets `define_module` differently).
+#include "WKTJsiWorkletContext.h"
+#include "WKTJsiWorklet.h"
+
+#include "stitcher_worklet_registry.hpp"
+
+#include <exception>
+#include <memory>
+#include <utility>
+#include <vector>
+
+// Forward-declare `RNSARFramePose` — same pattern as
+// StitcherFrameHostObject.mm.  We don't read its fields here in
+// Phase 3b (the stub doesn't unpack the pose), but Phase 3c will.
+@class RNSARFramePose;
+
+@implementation RNSARWorkletRuntime {
+    /// Dispatch queue the worklet runtime's `workletCallInvoker`
+    /// posts onto.  Serial; `DISPATCH_QUEUE_SERIAL` matches the
+    /// existing `IncrementalStitcher::workQueue` cost envelope
+    /// (one-at-a-time frame ingest).
+    ///
+    /// Phase 3c will configure `ARSession.delegateQueue` to point
+    /// at the same queue so the delegate fires on the worklet
+    /// thread — eliminates a thread hop per frame + makes the
+    /// "first-party first, host worklets after" ordering trivial
+    /// to enforce (all on one queue).
+    dispatch_queue_t _dispatchQueue;
+
+    /// The wrapped worklet-runtime context.  Constructed lazily on
+    /// `-installIfNeeded`; held for the singleton's lifetime
+    /// (process-wide).
+    std::shared_ptr<RNWorklet::JsiWorkletContext> _ctx;
+
+    /// Single-flight install guard.  `BOOL` is sufficient because
+    /// `-installIfNeeded` synchronises on `_installLock` below.
+    BOOL _installed;
+
+    /// Lock for `_installed` + `_ctx`.  Construction may race with
+    /// concurrent first-mount calls from multiple `<Camera>`
+    /// instances; serialise to ensure exactly-once init.
+    NSLock *_installLock;
+
+    // Phase 4 will add the host-worklet registry here.  Storage
+    // shape (NSMutableArray of boxed shared_ptrs vs C++ vector
+    // ivar) is intentionally NOT pre-committed in Phase 3b — let
+    // the JSI plugin's actual register/unregister implementation
+    // pick the natural shape.
+
+    /// Phase 3c — first-party callback installed by RNSARSession.
+    /// Invoked synchronously on the caller thread per AR frame.
+    /// Cleared on RNSARSession.stop() to avoid retain cycles.
+    ///
+    /// Atomic property protects against the delegate firing
+    /// concurrently with a setFirstPartyCallback: call on a
+    /// different thread (rare but possible: setter on main thread
+    /// from RNSARSession.start while a delayed delegate frame
+    /// arrives).
+    RNSARFirstPartyCallback _firstPartyCallback;
+
+    /// Lock for `_firstPartyCallback` reads + writes.  The
+    /// `_installLock` above is dispatch-queue-scoped (install);
+    /// callback rotation is a separate concern.
+    NSLock *_callbackLock;
+}
+
++ (instancetype)shared {
+    static RNSARWorkletRuntime *sInstance;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{ sInstance = [[self alloc] init]; });
+    return sInstance;
+}
+
+- (instancetype)init {
+    if ((self = [super init])) {
+        _dispatchQueue = dispatch_queue_create(
+            "io.imagestitcher.ar-worklet-runtime", DISPATCH_QUEUE_SERIAL);
+        _installed = NO;
+        _installLock = [[NSLock alloc] init];
+        _callbackLock = [[NSLock alloc] init];
+        _firstPartyCallback = nil;
+    }
+    return self;
+}
+
+- (void)setFirstPartyCallback:(RNSARFirstPartyCallback)callback {
+    [_callbackLock lock];
+    // Copy the block to move it from stack to heap (ARC handles
+    // the copy semantics for blocks assigned to strong ivars).
+    _firstPartyCallback = [callback copy];
+    [_callbackLock unlock];
+}
+
+- (void)installIfNeeded {
+    [_installLock lock];
+    if (_installed) {
+        [_installLock unlock];
+        return;
+    }
+
+    // Build the `workletCallInvoker`.  `RNWorklet::JsiWorkletContext`
+    // accepts a `std::function<void(std::function<void()>&&)>` that
+    // posts a task onto whatever thread the runtime should execute
+    // on.  We post onto `_dispatchQueue` (a serial GCD queue).
+    //
+    // The captured `fp` is moved into a `std::shared_ptr` so the
+    // dispatch_async block (which can only capture copyable types)
+    // can hold + invoke it.  Without the shared_ptr indirection
+    // we'd hit `std::function` copy-construction on the
+    // non-copyable forward closure.
+    dispatch_queue_t queue = _dispatchQueue;
+    auto invoker = [queue](std::function<void()>&& fp) {
+        auto fpHolder = std::make_shared<std::function<void()>>(std::move(fp));
+        dispatch_async(queue, ^{ (*fpHolder)(); });
+    };
+
+    _ctx = std::make_shared<RNWorklet::JsiWorkletContext>(
+        "stitcher.ar", std::move(invoker));
+    _installed = YES;
+    [_installLock unlock];
+}
+
+- (BOOL)isInstalled {
+    [_installLock lock];
+    BOOL result = _installed;
+    [_installLock unlock];
+    return result;
+}
+
+- (void)dispatchFrame:(ARFrame *)arFrame pose:(RNSARFramePose *)pose {
+    // ── Phase 3c — first-party (synchronous on caller thread) ────
+    //
+    // The callback (installed by RNSARSession.start) wraps the
+    // existing `incrementalConsumer.consumeFrame(...)` call path,
+    // so net behavior is byte-identical to the v0.7.x direct call.
+    //
+    // **Why first-party runs on the CALLER thread (not the worklet
+    // thread):** ARKit's pool reuse contract requires the pixel
+    // buffer to be consumed before this method returns.  The Swift
+    // consumer does that synchronously inside `consumeFrame(...)`
+    // (converts NV12 → cv::Mat synchronously, then defers heavier
+    // work to its own queue).  If we posted the callback onto
+    // `_dispatchQueue`, the delegate would return before
+    // `consumeFrame` ran, ARKit could reclaim the buffer, and we'd
+    // get torn frames.
+    //
+    // Pull the callback under the lock so a concurrent
+    // `setFirstPartyCallback:` doesn't race with our invocation.
+    [_callbackLock lock];
+    RNSARFirstPartyCallback cb = _firstPartyCallback;
+    [_callbackLock unlock];
+    if (cb != nil) {
+        cb(arFrame, pose);
+    }
+
+    // ── Phase 4b — host-worklet fan-out (async on worklet thread) ──
+    //
+    // Snapshot the native registry.  Fast-path early-exit when no
+    // host worklets are registered — saves the host-object alloc
+    // + dispatch_async hop on every frame (the common case in
+    // first-party-only deployments).
+    auto invokers = retailens::StitcherWorkletRegistry::shared().snapshot();
+    if (invokers.empty()) {
+        return;
+    }
+
+    // Construction must happen on the caller thread.  The
+    // `IOSPixelBufferReader` ctor takes a `CFBridgingRetain(arFrame)`
+    // so the underlying CVPixelBuffer stays alive until the host
+    // object's `invalidate` runs.  ARKit's pool will throttle the
+    // *next* frame's delegate call while we hold this retain
+    // (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];
+
+    // Hand the host object's jsi::HostObject shared_ptr (boxed as
+    // void*) into the lambda.  The lambda will:
+    //   1. Cast back to `std::shared_ptr<jsi::HostObject>*`
+    //   2. Construct the JS-side `jsi::Object` from the host object
+    //   3. Invoke each registered WorkletInvoker with the JS-side
+    //      object as its single argument
+    //   4. Delete the boxed shared_ptr
+    //   5. Invalidate the host object on caller-side retained ref
+    //
+    // The dispatch is via worklets-core's `JsiWorkletContext::
+    // invokeOnWorkletThread` — internally posts onto our serial
+    // `_dispatchQueue` via the `workletCallInvoker` we set up in
+    // `installIfNeeded`.
+    //
+    // `hostObj` (the Obj-C facade) is captured by the block; ARC
+    // retains it for the block's lifetime, so the host object
+    // outlives the dispatch.  We invalidate AFTER all worklets
+    // return.
+    void *hostObjPtr = [hostObj jsiHostObjectPtr];
+    if (hostObjPtr == NULL) {
+        // Host object construction failed (e.g., ARFrame was nil).
+        // Skip fan-out.
+        os_log_error(OS_LOG_DEFAULT,
+            "[RNSARWorkletRuntime] host object jsiHostObjectPtr was NULL; "
+            "skipping host-worklet fan-out for this frame.");
+        return;
+    }
+
+    if (_ctx == nullptr) {
+        // installIfNeeded wasn't called.  This shouldn't happen
+        // because RNSARSession.start calls installIfNeeded before
+        // any frames arrive, but guard defensively.
+        os_log_error(OS_LOG_DEFAULT,
+            "[RNSARWorkletRuntime] _ctx is nullptr in dispatchFrame; "
+            "did installIfNeeded run?  Skipping host-worklet fan-out.");
+        // Leaked: hostObjPtr (boxed shared_ptr).  Reclaim it here so
+        // we don't leak even on the defensive path.
+        delete static_cast<std::shared_ptr<facebook::jsi::HostObject>*>(hostObjPtr);
+        return;
+    }
+
+    _ctx->invokeOnWorkletThread(
+        [invokers, hostObjPtr, hostObj](
+            RNWorklet::JsiWorkletContext* /*ctx*/,
+            facebook::jsi::Runtime& rt) {
+            // Reclaim the boxed shared_ptr.  After this scope the
+            // unique_ptr automatically deletes the heap allocation
+            // even if the JSI call below throws.
+            std::unique_ptr<std::shared_ptr<facebook::jsi::HostObject>> spBox(
+                static_cast<std::shared_ptr<facebook::jsi::HostObject>*>(
+                    hostObjPtr));
+
+            facebook::jsi::Object frameJsi =
+                facebook::jsi::Object::createFromHostObject(rt, *spBox);
+            // Pass the host object as a single argument.  The
+            // worklet's signature is `(frame: StitcherFrame) =>
+            // void` — matches.
+            //
+            // Construct the argument value as a copy of the
+            // Object (jsi::Value(rt, obj) makes a fresh Value
+            // wrapping the same host object — refcounted by JSI).
+            facebook::jsi::Value frameVal(rt, frameJsi);
+
+            for (const auto& entry : invokers) {
+                if (!entry.invoker) continue;
+                try {
+                    entry.invoker->call(rt, facebook::jsi::Value::undefined(),
+                                         &frameVal, 1);
+                } catch (const facebook::jsi::JSError& jsErr) {
+                    // Per-worklet failure isolation: one host
+                    // worklet throwing must NOT stop the lib's own
+                    // path or other host worklets.  Log + continue.
+                    os_log_error(OS_LOG_DEFAULT,
+                        "[RNSARWorkletRuntime] host worklet '%{public}s' "
+                        "threw JS error: %{public}s",
+                        entry.id.c_str(), jsErr.what());
+                } catch (const std::exception& e) {
+                    os_log_error(OS_LOG_DEFAULT,
+                        "[RNSARWorkletRuntime] host worklet '%{public}s' "
+                        "threw native exception: %{public}s",
+                        entry.id.c_str(), e.what());
+                } catch (...) {
+                    os_log_error(OS_LOG_DEFAULT,
+                        "[RNSARWorkletRuntime] host worklet '%{public}s' "
+                        "threw unknown exception", entry.id.c_str());
+                }
+            }
+
+            // Drop the JSI references BEFORE invalidating the host
+            // object — `frameJsi` / `frameVal` go out of scope at
+            // end of lambda anyway, but be explicit.  Then
+            // invalidate the Obj-C facade which releases the
+            // CFBridgingRetain'd ARFrame so ARKit's pool can recycle.
+            [hostObj invalidate];
+        });
+}
+
+@end