react-native-image-stitcher 0.16.2 → 0.17.0

package/ios/Sources/RNImageStitcher/StitcherFrameHostObject.h

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// StitcherFrameHostObject.h — Obj-C facade for the v0.8.0
+// `StitcherFrame` JSI host object.  Header is intentionally
+// Obj-C-only (no `<jsi/jsi.h>` import) so this can land in the
+// public CocoaPods umbrella without breaking `use_frameworks!` hosts
+// (same rationale as `KeyframeGateBridge.h`).
+//
+// The C++ JSI host object class lives in the .mm; this facade
+// exposes only what cross-module callers need:
+//
+//   - Factory `+ fromARFrame:pose:` that the AR worklet runtime
+//     calls per ARFrame to construct a host object backed by the
+//     current AR session's frame.
+//   - Opaque accessor `- (void *)jsiHostObjectPtr` returning the
+//     `std::shared_ptr<facebook::jsi::HostObject> *` (boxed) that
+//     the worklet runtime hands to `jsi::Object::createFromHostObject`.
+//
+// Lifetime: the Obj-C wrapper holds the C++ shared_ptr; ARC frees
+// the wrapper when nothing references it.  Worklet runtime
+// invalidates the underlying ARFrame retain when the dispatch
+// returns; after invalidation, JSI access throws.
+
+#pragma once
+
+#import <Foundation/Foundation.h>
+#import <ARKit/ARKit.h>
+
+@class RNSARFramePose;
+
+NS_ASSUME_NONNULL_BEGIN
+
+NS_SWIFT_NAME(StitcherFrameHostObject)
+@interface StitcherFrameHostObject : NSObject
+
+/// Construct a host object backed by the supplied ARFrame + pose.
+/// Retains the ARFrame for the host object's lifetime — caller can
+/// safely release their reference.
+///
+/// Thread: safe to call from the ARSession delegate queue; the
+/// resulting host object's JSI access must happen on the worklet
+/// runtime's thread (separate queue).
++ (instancetype)fromARFrame:(ARFrame *)arFrame pose:(RNSARFramePose *)pose;
+
+/// Mark the host object's underlying ARFrame as no longer accessible.
+/// Subsequent JSI property reads return `undefined` or throw,
+/// depending on the property.  Idempotent.
+- (void)invalidate;
+
+/// Opaque pointer to a `std::shared_ptr<facebook::jsi::HostObject>`.
+/// The worklet runtime (Obj-C++ context with JSI available) casts
+/// this back via `*reinterpret_cast<std::shared_ptr<facebook::jsi::HostObject>*>(ptr)`
+/// to hand to `jsi::Object::createFromHostObject`.
+///
+/// Returns `NULL` if the host object has been invalidated.
+- (nullable void *)jsiHostObjectPtr;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Sources/RNImageStitcher/StitcherFrameHostObject.mm

@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// StitcherFrameHostObject.mm — iOS-specific wrapper for the shared
+// `retailens::StitcherFrameJsiHostObject` (defined in
+// `cpp/stitcher_frame_jsi.{hpp,cpp}`).
+//
+// Owns:
+//   - The Obj-C facade callable from Swift / other Obj-C / .mm files.
+//   - The iOS-specific `PixelBufferReader` impl (wraps a
+//     `CVPixelBufferRef` from `ARFrame.capturedImage`; lock / memcpy
+//     / unlock pattern).
+//   - The Obj-C → C++ extraction logic that builds a
+//     `retailens::StitcherFrameData` from an `ARFrame` + the lib's
+//     `RNSARFramePose`.
+//
+// Does NOT own:
+//   - The JSI `get` / `getPropertyNames` dispatch.  That lives in
+//     `cpp/stitcher_frame_jsi.cpp` and is identical to the Android
+//     implementation (DRY across platforms).
+
+#import "StitcherFrameHostObject.h"
+
+#import <Foundation/Foundation.h>
+#import <CoreVideo/CVPixelBuffer.h>
+#import <CoreMedia/CoreMedia.h>
+#import <os/log.h>
+
+#include <jsi/jsi.h>
+
+#include <algorithm>
+#include <cstring>
+#include <memory>
+#include <string>
+#include <utility>
+
+#include "stitcher_frame_data.hpp"
+#include "stitcher_frame_jsi.hpp"
+
+using namespace facebook;
+
+// Forward-declare the Swift `RNSARFramePose` Obj-C surface we need.
+// This matches the pattern in `KeyframeGateFrameProcessor.mm`
+// (forward-declaring `IncrementalStitcher`) — avoids depending on
+// the autogenerated `RNImageStitcher-Swift.h`, which is created at
+// build time and not always available to .mm files in this pod.
+//
+// MUST stay in sync with `RNSARSession.swift::RNSARFramePose` —
+// adding a new field there means adding it here too.
+@class RNSARFramePose;
+@interface RNSARFramePose : NSObject
+@property (nonatomic, readonly) double tx;
+@property (nonatomic, readonly) double ty;
+@property (nonatomic, readonly) double tz;
+@property (nonatomic, readonly) double qx;
+@property (nonatomic, readonly) double qy;
+@property (nonatomic, readonly) double qz;
+@property (nonatomic, readonly) double qw;
+@property (nonatomic, readonly) NSInteger imageWidth;
+@property (nonatomic, readonly) NSInteger imageHeight;
+@property (nonatomic, readonly) double timestampMs;
+@end
+
+#pragma mark - iOS PixelBufferReader
+
+namespace {
+
+/// iOS-specific `retailens::PixelBufferReader` impl.  See the base
+/// class docstring for the general contract (thread-affinity,
+/// invalidation semantics, Y-plane-only constraint).  This subclass
+/// adds:
+///   - `CVPixelBuffer` lock/memcpy/unlock per copyTo
+///   - `CFBridgingRetain` of the parent `ARFrame` so ARKit's
+///     pool can't reclaim the underlying buffer mid-read
+class IOSPixelBufferReader : public retailens::PixelBufferReader {
+ public:
+  explicit IOSPixelBufferReader(ARFrame* arFrame) {
+    // Retain the ARFrame for our lifetime.  CFBridgingRetain hands
+    // ARC ownership to our void*.  Released in destructor.
+    _retainedFrame = (void*)CFBridgingRetain(arFrame);
+    CVPixelBufferRef pixelBuffer = arFrame.capturedImage;
+    if (pixelBuffer != NULL) {
+      _bytesPerRow = CVPixelBufferGetBytesPerRow(pixelBuffer);
+      _height = CVPixelBufferGetHeight(pixelBuffer);
+    }
+  }
+
+  ~IOSPixelBufferReader() override {
+    // Transfer ownership back to ARC, which then releases.
+    if (_retainedFrame != nullptr) {
+      ARFrame* frame = CFBridgingRelease(_retainedFrame);
+      (void)frame;
+      _retainedFrame = nullptr;
+    }
+  }
+
+  std::size_t byteSize() const override {
+    return _bytesPerRow * _height;
+  }
+
+  std::size_t copyTo(uint8_t* dst, std::size_t maxBytes) override {
+    if (_retainedFrame == nullptr) return 0;
+    ARFrame* frame = (__bridge ARFrame*)_retainedFrame;
+    CVPixelBufferRef pixelBuffer = frame.capturedImage;
+    if (pixelBuffer == NULL) return 0;
+
+    CVPixelBufferLockBaseAddress(pixelBuffer, kCVPixelBufferLock_ReadOnly);
+    const uint8_t* src = (const uint8_t*)CVPixelBufferGetBaseAddress(pixelBuffer);
+    std::size_t toCopy = std::min<std::size_t>(byteSize(), maxBytes);
+    if (src != nullptr && toCopy > 0) {
+      std::memcpy(dst, src, toCopy);
+    } else {
+      toCopy = 0;
+    }
+    CVPixelBufferUnlockBaseAddress(pixelBuffer, kCVPixelBufferLock_ReadOnly);
+    return toCopy;
+  }
+
+ private:
+  void* _retainedFrame = nullptr;   // CFBridgingRetain'd ARFrame
+  std::size_t _bytesPerRow = 0;
+  std::size_t _height = 0;
+};
+
+}  // anonymous namespace
+
+#pragma mark - Obj-C facade
+
+@implementation StitcherFrameHostObject {
+  std::shared_ptr<retailens::StitcherFrameJsiHostObject> _hostObject;
+}
+
++ (instancetype)fromARFrame:(ARFrame*)arFrame pose:(RNSARFramePose*)pose {
+  StitcherFrameHostObject* obj = [[self alloc] init];
+
+  retailens::StitcherFrameData data;
+  data.source = "ar";
+  data.width = static_cast<int32_t>(pose.imageWidth);
+  data.height = static_cast<int32_t>(pose.imageHeight);
+  // ARKit's `kCVPixelFormatType_420YpCbCr8BiPlanarFullRange` (NV12)
+  // is reported as "yuv".  Other formats (rare in ARKit; possible if
+  // ARWorldTrackingConfiguration.videoFormat is overridden to BGRA)
+  // → "unknown" + os_log warning so worklets that gate on
+  // `pixelFormat === 'yuv'` can be debugged without a screen recording.
+  OSType pf = CVPixelBufferGetPixelFormatType(arFrame.capturedImage);
+  if (pf == kCVPixelFormatType_420YpCbCr8BiPlanarFullRange ||
+      pf == kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange) {
+    data.pixelFormat = "yuv";
+  } else {
+    data.pixelFormat = "unknown";
+    os_log_error(OS_LOG_DEFAULT,
+        "[StitcherFrame] unexpected ARKit pixel format 0x%x; "
+        "worklet receives pixelFormat='unknown' and toArrayBuffer() "
+        "bytes are first-plane only (layout undefined for unknown "
+        "formats).  See StitcherFrame.ts docstring.", (unsigned int)pf);
+  }
+  // ARKit doesn't have a `Frame.orientation` per se; pose carries
+  // the imageWidth >= imageHeight discriminator the lib uses
+  // elsewhere (`isLandscape`).  v0.8.0 ships a coarse mapping;
+  // worklets that need exact UI orientation can read it from
+  // device-orientation sensors.
+  data.orientation =
+      (pose.imageWidth >= pose.imageHeight) ? "landscape-right" : "portrait";
+  // `ARFrame.timestamp` is CFAbsoluteTime (seconds since epoch).
+  // Convert to ns to match vc Frame.timestamp.
+  data.timestampNs = arFrame.timestamp * 1e9;
+
+  data.qx = pose.qx;
+  data.qy = pose.qy;
+  data.qz = pose.qz;
+  data.qw = pose.qw;
+  data.tx = pose.tx;
+  data.ty = pose.ty;
+  data.tz = pose.tz;
+  data.hasTranslation = true;   // AR mode always has translation
+
+  switch (arFrame.camera.trackingState) {
+    case ARTrackingStateNotAvailable:
+      data.arTrackingState = "notAvailable";
+      break;
+    case ARTrackingStateLimited:
+      data.arTrackingState = "limited";
+      break;
+    case ARTrackingStateNormal:
+      data.arTrackingState = "normal";
+      break;
+  }
+
+  data.pixelReader = std::make_shared<IOSPixelBufferReader>(arFrame);
+
+  // Use the static factory (private ctor enforces shared_ptr
+  // ownership — required for `shared_from_this()` inside the JSI
+  // `toArrayBuffer` lambda).
+  obj->_hostObject =
+      retailens::StitcherFrameJsiHostObject::create(std::move(data));
+  return obj;
+}
+
+- (void)invalidate {
+  if (_hostObject) {
+    _hostObject->invalidate();
+  }
+}
+
+- (void*)jsiHostObjectPtr {
+  if (!_hostObject) return NULL;
+  // Box a heap-allocated copy of the shared_ptr to the abstract
+  // `jsi::HostObject` base.  Caller (worklet runtime) does:
+  //   auto sp = static_cast<std::shared_ptr<jsi::HostObject>*>(ptr);
+  //   auto jsObj = jsi::Object::createFromHostObject(rt, *sp);
+  //   delete sp;
+  return new std::shared_ptr<jsi::HostObject>(_hostObject);
+}
+
+@end

package/ios/Sources/RNImageStitcher/StitcherJsiInstaller.h

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// StitcherJsiInstaller.h — RN module that installs the
+// `globalThis.__stitcherProxy` JSI host object on the main JS
+// runtime.  Called once at lib boot from the TS layer
+// (`src/index.ts` or the `useFrameProcessor` hook) via a
+// synchronous JS bridge call.
+//
+// The proxy exposes two host functions:
+//
+//   __stitcherProxy.install(workletFn)  →  string ID
+//   __stitcherProxy.uninstall(id)       →  undefined
+//
+// `install` wraps the worklet function into a
+// `RNWorklet::WorkletInvoker` and stores it in the C++
+// `retailens::StitcherWorkletRegistry` singleton (in
+// `cpp/stitcher_worklet_registry.{hpp,cpp}`).  The AR worklet
+// runtime's per-frame dispatch reads from that registry to fan
+// out invocations.
+//
+// Why a RN module (not a vanilla NSObject installable):
+//   - Hosts can't reliably reach into the JSI runtime from JS
+//     without a native sync method to broker the install.
+//   - `RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD` is the documented
+//     pattern for "JS calls a native method synchronously to
+//     install JSI bindings on the main runtime".  vision-camera
+//     uses the same pattern (`VisionCameraInstaller.mm`).
+//   - In RN's bridgeless mode the legacy `RCTCxxBridge.runtime`
+//     accessor still works (vc has a comment to migrate but it
+//     hasn't been needed yet — same applies to us).
+
+#pragma once
+
+#import <Foundation/Foundation.h>
+#import <React/RCTBridgeModule.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface StitcherJsiInstaller : NSObject <RCTBridgeModule>
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Sources/RNImageStitcher/StitcherJsiInstaller.mm

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// StitcherJsiInstaller.mm — implementation.  Installs
+// `globalThis.__stitcherProxy` on the main JS runtime.
+//
+// ## Why a host object rather than two globalThis functions
+//
+// We could install `__stitcherProxy_install` + `__stitcherProxy_uninstall`
+// directly on `globalThis`.  Wrapping them in a host object is
+// slightly more code but:
+//   - Namespaces the proxy under a single global property
+//     (easier to feature-detect; one `if (globalThis.__stitcherProxy)`
+//     instead of two).
+//   - Matches vc's pattern (`global.VisionCameraProxy`), so future
+//     readers recognise the shape.
+//   - Keeps room to grow (e.g., add `__stitcherProxy.snapshot()` for
+//     diagnostics) without polluting globalThis further.
+
+#import "StitcherJsiInstaller.h"
+
+#import <Foundation/Foundation.h>
+#import <React/RCTBridge.h>
+#import <React/RCTBridge+Private.h>
+#import <React/RCTUtils.h>
+#import <ReactCommon/CallInvoker.h>
+// `RCTCxxBridge` (and its bridgeless-mode `RCTBridgeProxy` forwarder)
+// exposes `-jsCallInvoker` returning `std::shared_ptr<CallInvoker>`,
+// but the property declaration lives in `<ReactCommon/RCTTurboModule.h>`
+// which isn't on our pod's HEADER_SEARCH_PATHS (worklets-core gets it
+// via its own ReactCommon dep).  Rather than enlarging our pod's
+// dependency surface, forward-declare the property in an anonymous
+// category — the runtime dispatches to RN's actual implementation.
+// Pattern matches `WKTJsiWorkletContext.cpp`'s approach to keep the
+// pod self-contained.
+@interface RCTCxxBridge ()
+@property (nonatomic, readonly) std::shared_ptr<facebook::react::CallInvoker> jsCallInvoker;
+@end
+#import <os/log.h>
+
+#include <jsi/jsi.h>
+
+#include "stitcher_proxy_jsi.hpp"
+// v0.11.1 — worklets-core JsiWorkletContext.  We initialize the
+// SINGLETON default instance here so that other contexts in this
+// library that use the 2-arg `JsiWorkletContext(name, workletInvoker)`
+// constructor inherit a working `_jsCallInvoker` (and thus their
+// `runOnJS` / `Worklets.createRunOnJS` callbacks actually route back
+// to the main JS thread).  Specifically: `RNSARWorkletRuntime`'s AR-
+// side worklet context (see `RNSARWorkletRuntime.mm:155`) uses the
+// 2-arg ctor; pre-v0.11.1 that left its inherited `_jsCallInvoker`
+// nullptr, and `invokeOnJsThread` silently no-op'd (see
+// `WKTJsiWorkletContext.cpp:124-131`).  Test 2 of the v0.11.0
+// manual-verification checklist surfaced this as "AR-mode host
+// worklets register but their runOnJS callbacks never fire."
+#include "WKTJsiWorkletContext.h"
+
+using namespace facebook;
+
+// The host object class + install logic moved to shared C++ in
+// `cpp/stitcher_proxy_jsi.{hpp,cpp}` (v0.8.0 Phase 4b.ii).  The
+// Android JNI installer reuses the same `install` / `uninstall` /
+// `count` host functions verbatim — the JSI dispatch is identical
+// across platforms (matches the StitcherFrame host object's design).
+
+#pragma mark - RN module
+
+@implementation StitcherJsiInstaller
+
+// RN injects `_bridge` at module init (legacy bridge → RCTBridge*;
+// bridgeless / new arch → RCTBridgeProxy*, which forwards `runtime`
+// access via NSProxy `forwardInvocation:`).  Using the injected
+// `_bridge` instead of `[RCTBridge currentBridge]` is the
+// bridgeless-compatible idiom — `currentBridge` is nil under new
+// arch.  Pattern lifted from `react-native-worklets-core/ios/Worklets.mm`.
+@synthesize bridge = _bridge;
+
+RCT_EXPORT_MODULE()
+
++ (BOOL)requiresMainQueueSetup {
+  return YES;
+}
+
+- (void)setBridge:(RCTBridge*)bridge {
+  _bridge = bridge;
+}
+
+// Synchronous install method.  JS calls this once at lib bootstrap
+// to install the global proxy on the main JS runtime.  Returns
+// `@YES` on success or `@NO` if the JSI runtime wasn't reachable
+// (remote debug mode pre-Hermes; bridge not yet ready; etc.).
+//
+// `RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD` is the documented
+// pattern for "run native code synchronously on the JS thread to
+// install JSI bindings."  Same pattern worklets-core + vision-camera
+// use for their installs.
+//
+// **Bridgeless mode:** `_bridge` is an `RCTBridgeProxy` (NSProxy
+// subclass) that forwards `-runtime` / `-jsCallInvoker` invocations
+// to the underlying RCTHost-backed runtime.  The `(RCTCxxBridge*)`
+// cast is a no-op at runtime (NSProxy ignores static type) but
+// keeps the Obj-C compiler happy about property access.
+RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(install) {
+  if (_bridge == nil) {
+    os_log_error(OS_LOG_DEFAULT,
+        "[StitcherJsiInstaller] _bridge is nil; the module was "
+        "instantiated without bridge injection.  Cannot install "
+        "__stitcherProxy.");
+    return @NO;
+  }
+
+  RCTCxxBridge* cxxBridge = (RCTCxxBridge*)_bridge;
+  if (cxxBridge.runtime == nullptr) {
+    os_log_error(OS_LOG_DEFAULT,
+        "[StitcherJsiInstaller] _bridge.runtime is nullptr; the JS "
+        "runtime hasn't been initialized yet OR remote debugger is "
+        "attached.  Cannot install __stitcherProxy.");
+    return @NO;
+  }
+
+  jsi::Runtime& runtime = *(jsi::Runtime*)cxxBridge.runtime;
+  retailens::installStitcherProxy(runtime);
+
+  // v0.11.1 — initialize the singleton default JsiWorkletContext so
+  // that downstream 2-arg ctors (RNSARWorkletRuntime) inherit a
+  // working `_jsCallInvoker`.  Without this, AR-mode host worklets'
+  // `runOnJS` / `Worklets.createRunOnJS` callbacks silently no-op
+  // (`WKTJsiWorkletContext.cpp:124-131` early-returns when
+  // `_jsCallInvoker == nullptr`).  See file-top comment for the full
+  // diagnosis (Test 2 of v0.11.0 manual-verification checklist).
+  //
+  // Idempotent at the worklets-core level: re-initialization is
+  // tolerated; the default instance is a process-scope singleton
+  // and we're called once per JS-runtime bootstrap.  In bridgeless
+  // mode `cxxBridge.jsCallInvoker` is forwarded via RCTBridgeProxy
+  // to the underlying RCTHost's `CallInvoker` (same forwarding
+  // pattern as `cxxBridge.runtime` above).
+  auto jsCallInvoker = cxxBridge.jsCallInvoker;
+  if (jsCallInvoker == nullptr) {
+    os_log_error(OS_LOG_DEFAULT,
+        "[StitcherJsiInstaller] cxxBridge.jsCallInvoker is nullptr; "
+        "AR-mode host worklets' runOnJS will not fire.  Proxy installed "
+        "but worklet-bridging is impaired.");
+    // Proxy is still installed; only the runOnJS path is impaired.
+    // Return @YES so JS callers don't fall back to the JS-side registry.
+    return @YES;
+  }
+  auto jsInvokerAdapter =
+      [jsCallInvoker](std::function<void()>&& fp) {
+        jsCallInvoker->invokeAsync(std::move(fp));
+      };
+  RNWorklet::JsiWorkletContext::getDefaultInstance()->initialize(
+      "stitcher.default", &runtime, jsInvokerAdapter);
+
+  os_log_info(OS_LOG_DEFAULT,
+      "[StitcherJsiInstaller] installed globalThis.__stitcherProxy "
+      "AND initialized default JsiWorkletContext on main JS runtime.");
+  return @YES;
+}
+
+@end

package/package.json

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

package/src/camera/ARCameraView.tsx

@@ -30,7 +30,7 @@
  * developer verification.
  */
 
-import React, { forwardRef, useImperativeHandle, useRef } from 'react';
+import React, { forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
 import {
   NativeModules,
   Platform,
@@ -41,6 +41,9 @@ import {
   type ViewStyle,
 } from 'react-native';
 
+import { ensureStitcherProxyInstalled } from '../stitching/ensureStitcherProxyInstalled';
+import type { StitcherFrameProcessor } from '../stitching/StitcherFrame';
+
 
 // React Native looks up the component by its NATIVE name.
 //   iOS: comes from `ARCameraViewManager.m`'s
@@ -63,6 +66,25 @@ export interface ARCameraViewProps {
    * components without rewriting their guidance text plumbing.
    */
   guidance?: string;
+  /**
+   * Optional host worklet invoked once per AR frame, ALONGSIDE the
+   * lib's first-party stitching (composition, not replacement).  The
+   * worklet receives a `StitcherFrame` enriched with AR metadata —
+   * `source: 'ar'`, world-space `pose` (rotation + translation),
+   * `arTrackingState`, and (when supported) `arDepth` / `arAnchors`.
+   *
+   * Must be a `'worklet'`-prefixed function.  Registration installs the
+   * native `__stitcherProxy` JSI host object on first use and fans the
+   * worklet out from the AR session's per-frame dispatch.  If the
+   * native install is unavailable (e.g. remote debugging), the worklet
+   * silently never fires — no crash.
+   *
+   * The non-AR equivalent is vision-camera's own `useFrameProcessor`
+   * passed via `<Camera frameProcessor={...}>`; the two modes run on
+   * different runtimes with different frame shapes, hence the separate
+   * prop.
+   */
+  arFrameProcessor?: StitcherFrameProcessor;
 }
 
 
@@ -145,7 +167,7 @@ type RecordingCallbacks = {
 
 export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
   function ARCameraView(
-    { style, guidance },
+    { style, guidance, arFrameProcessor },
     ref,
   ): React.JSX.Element {
     // Held across the start→stop lifecycle so stopRecording's
@@ -153,6 +175,33 @@ export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
     // pair vision-camera uses.
     const recordingCallbacksRef = useRef<RecordingCallbacks | null>(null);
 
+    // AR frame-processor registration.  Installs the native
+    // `__stitcherProxy` (idempotent) and registers the host worklet so
+    // the AR session's per-frame fan-out invokes it; unregisters on
+    // unmount or when the worklet identity changes.  No-op when no
+    // worklet is supplied or the native install is unavailable.
+    useEffect(() => {
+      if (arFrameProcessor == null) {
+        return undefined;
+      }
+      if (!ensureStitcherProxyInstalled()) {
+        return undefined;
+      }
+      const proxy = (globalThis as {
+        __stitcherProxy?: {
+          install(fn: StitcherFrameProcessor): string;
+          uninstall(id: string): void;
+        };
+      }).__stitcherProxy;
+      if (proxy == null) {
+        return undefined;
+      }
+      const id = proxy.install(arFrameProcessor);
+      return () => {
+        proxy.uninstall(id);
+      };
+    }, [arFrameProcessor]);
+
     useImperativeHandle(ref, () => ({
       takePhoto: async (options = {}) => {
         const native: any =

package/src/camera/Camera.tsx

@@ -66,6 +66,7 @@ import type {
 } from 'react-native-vision-camera';
 
 import { useARSession } from '../ar/useARSession';
+import type { StitcherFrameProcessor } from '../stitching/StitcherFrame';
 import { ARCameraView, type ARCameraViewHandle } from './ARCameraView';
 import { CameraShutter } from './CameraShutter';
 import { CameraView } from './CameraView';
@@ -751,6 +752,18 @@ export interface CameraProps {
    */
   frameProcessor?: ReadonlyFrameProcessor | DrawableFrameProcessor;
 
+  /**
+   * AR-mode host worklet, invoked once per ARKit / ARCore frame
+   * ALONGSIDE the lib's first-party stitching (composition, not
+   * replacement).  Receives a `StitcherFrame` tagged `source: 'ar'`
+   * with world-space `pose` + `arTrackingState`.  Only fires in AR
+   * capture (`captureSource === 'ar'`); the non-AR equivalent is
+   * `frameProcessor` above (the two modes use different runtimes and
+   * frame shapes).  Must be a `'worklet'`-prefixed function; if the
+   * native install is unavailable it silently never fires.
+   */
+  arFrameProcessor?: StitcherFrameProcessor;
+
   // ── Panorama GUIDANCE (feature/pano-ux-guidance) ──────────────────
   /**
    * Which device holds the non-AR panorama capture accepts.
@@ -1157,6 +1170,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
     capturePreviewActions,
     onCapturePreviewClose,
     frameProcessor: hostFrameProcessor,
+    arFrameProcessor,
     engine = 'batch-keyframe',
     // ── Panorama GUIDANCE (feature/pano-ux-guidance) ──────────────
     panMode = 'vertical',
@@ -2420,6 +2434,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
         <ARCameraView
           ref={arViewRef}
           style={StyleSheet.absoluteFill}
+          arFrameProcessor={arFrameProcessor}
         />
       ) : (
         <CameraView

package/src/camera/CaptureMemoryPill.tsx

@@ -17,9 +17,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.