react-native-image-stitcher 0.17.0 → 0.19.0

package/cpp/{stitcher_frame_jsi.cpp → camera_frame_jsi.cpp}

@@ -1,12 +1,14 @@
 // SPDX-License-Identifier: Apache-2.0
 //
-// stitcher_frame_jsi.cpp — implementation of the shared C++ JSI
-// host object.  See stitcher_frame_jsi.hpp for class docs.
+// camera_frame_jsi.cpp — implementation of the shared C++ JSI
+// host object.  See camera_frame_jsi.hpp for class docs.
 
-#include "stitcher_frame_jsi.hpp"
+#include "camera_frame_jsi.hpp"
 
+#include <cstring>
 #include <string>
 #include <utility>
+#include <vector>
 
 namespace retailens {
 
@@ -20,10 +22,10 @@ using facebook::jsi::Runtime;
 using facebook::jsi::String;
 using facebook::jsi::Value;
 
-StitcherFrameJsiHostObject::StitcherFrameJsiHostObject(StitcherFrameData data)
+CameraFrameJsiHostObject::CameraFrameJsiHostObject(CameraFrameData data)
     : _data(std::move(data)), _isValid(true) {}
 
-void StitcherFrameJsiHostObject::invalidate() {
+void CameraFrameJsiHostObject::invalidate() {
   _isValid = false;
   // Release the pixel reader immediately so the underlying camera
   // buffer can be reclaimed.  ARKit's ARFrame uses a pooled
@@ -33,7 +35,7 @@ void StitcherFrameJsiHostObject::invalidate() {
   _data.pixelReader.reset();
 }
 
-std::vector<PropNameID> StitcherFrameJsiHostObject::getPropertyNames(
+std::vector<PropNameID> CameraFrameJsiHostObject::getPropertyNames(
     Runtime& rt) {
   std::vector<PropNameID> names;
   names.push_back(PropNameID::forUtf8(rt, "isValid"));
@@ -50,10 +52,21 @@ std::vector<PropNameID> StitcherFrameJsiHostObject::getPropertyNames(
   if (!_data.arTrackingState.empty()) {
     names.push_back(PropNameID::forUtf8(rt, "arTrackingState"));
   }
+  if (_data.arDepth.has_value()) {
+    names.push_back(PropNameID::forUtf8(rt, "arDepth"));
+  }
+  // AR frames expose `arAnchors` (possibly an empty array); non-AR
+  // frames omit it (JS sees `undefined`).
+  if (_data.source == "ar") {
+    names.push_back(PropNameID::forUtf8(rt, "arAnchors"));
+  }
+  if (_data.hasIntrinsics) {
+    names.push_back(PropNameID::forUtf8(rt, "intrinsics"));
+  }
   return names;
 }
 
-Value StitcherFrameJsiHostObject::get(Runtime& rt,
+Value CameraFrameJsiHostObject::get(Runtime& rt,
                                        const PropNameID& propName) {
   const std::string name = propName.utf8(rt);
 
@@ -106,7 +119,7 @@ Value StitcherFrameJsiHostObject::get(Runtime& rt,
     // object's lifetime beyond what the runtime intended.  When the
     // runtime releases its shared_ptr (after dispatch), the weak
     // ref expires and toArrayBuffer() throws on next call.
-    auto weakSelf = std::weak_ptr<StitcherFrameJsiHostObject>(shared_from_this());
+    auto weakSelf = std::weak_ptr<CameraFrameJsiHostObject>(shared_from_this());
     HostFunctionType fn = [weakSelf](Runtime& runtime,
                                        const Value& thisVal,
                                        const Value* args,
@@ -205,9 +218,139 @@ Value StitcherFrameJsiHostObject::get(Runtime& rt,
         PropNameID::forUtf8(rt, "toArrayBuffer"), 0, fn);
   }
 
-  // Unknown property — return undefined (matches JS object
-  // semantics).  Worklets accessing arDepth / arAnchors hit this
-  // path in v0.8.0 (stubbed to undefined; populated in v0.8.1+).
+  if (name == "arDepth") {
+    // Normalise both platforms to ONE JS shape:
+    //   { width, height, depthMap: Float32 metres, confidenceMap?: Uint8 0..2 }
+    if (!_data.arDepth.has_value()) return Value::undefined();
+    const ArDepth& d = *_data.arDepth;
+    const std::size_t px =
+        static_cast<std::size_t>(d.width) * static_cast<std::size_t>(d.height);
+    if (px == 0) return Value::undefined();
+
+    Object depth(rt);
+    depth.setProperty(rt, "width", Value(static_cast<double>(d.width)));
+    depth.setProperty(rt, "height", Value(static_cast<double>(d.height)));
+
+    // depthMap — always emitted as Float32 metres (px * 4 bytes).
+    auto depthBuf = std::make_shared<OwningPixelBuffer>(px * sizeof(float));
+    auto* out = reinterpret_cast<float*>(depthBuf->bytes());
+    std::vector<uint8_t> conf;  // Uint8 0..2 (empty => no confidenceMap)
+
+    if (d.format == "f32m") {
+      // iOS ARKit: depthBytes already Float32 metres; confidence is a
+      // separate Uint8 (ARConfidenceLevel 0..2) — pass both through.
+      if (d.depthBytes.size() >= px * sizeof(float)) {
+        std::memcpy(out, d.depthBytes.data(), px * sizeof(float));
+      }
+      if (d.confidenceBytes.size() >= px) {
+        conf.assign(d.confidenceBytes.begin(), d.confidenceBytes.begin() + px);
+      }
+    } else if (d.format == "u16packed") {
+      // Android ARCore DEPTH16: low 13 bits = millimetres, high 3 bits
+      // = confidence 0..7.  Convert mm->metres and map confidence 0..7
+      // -> 0..2 so JS sees the same scale as iOS.
+      const auto* src = reinterpret_cast<const uint16_t*>(d.depthBytes.data());
+      const std::size_t srcCount = d.depthBytes.size() / sizeof(uint16_t);
+      conf.resize(px, 0);
+      for (std::size_t i = 0; i < px; ++i) {
+        const uint16_t raw = (i < srcCount) ? src[i] : 0;
+        out[i] = static_cast<float>(raw & 0x1FFF) / 1000.0f;
+        const uint8_t c7 = static_cast<uint8_t>((raw >> 13) & 0x7);
+        conf[i] = (c7 <= 2) ? 0 : (c7 <= 5 ? 1 : 2);
+      }
+    } else {
+      return Value::undefined();
+    }
+
+    depth.setProperty(rt, "depthMap", facebook::jsi::ArrayBuffer(rt, depthBuf));
+    if (!conf.empty()) {
+      auto confBuf = std::make_shared<OwningPixelBuffer>(px);
+      std::memcpy(confBuf->bytes(), conf.data(), px);
+      depth.setProperty(rt, "confidenceMap",
+                        facebook::jsi::ArrayBuffer(rt, confBuf));
+    }
+    return depth;
+  }
+
+  if (name == "arAnchors") {
+    // AR frames return an array (possibly empty); non-AR returns
+    // undefined (matches the JS `arAnchors?: ARAnchor[]` contract).
+    if (_data.source != "ar") return Value::undefined();
+    Array anchors(rt, _data.arAnchors.size());
+    for (std::size_t i = 0; i < _data.arAnchors.size(); ++i) {
+      const ArAnchor& a = _data.arAnchors[i];
+      Object obj(rt);
+      obj.setProperty(rt, "id", String::createFromUtf8(rt, a.id));
+      obj.setProperty(rt, "type", String::createFromUtf8(rt, a.type));
+      Array transform(rt, 16);
+      for (std::size_t j = 0; j < 16; ++j) {
+        transform.setValueAtIndex(rt, j, Value(a.transform[j]));
+      }
+      obj.setProperty(rt, "transform", transform);
+      if (!a.alignment.empty()) {
+        obj.setProperty(rt, "alignment",
+                        String::createFromUtf8(rt, a.alignment));
+      }
+      if (a.hasExtent) {
+        Array extent(rt, 2);
+        extent.setValueAtIndex(rt, 0, Value(a.extentX));
+        extent.setValueAtIndex(rt, 1, Value(a.extentZ));
+        obj.setProperty(rt, "extent", extent);
+      }
+      if (!a.classification.empty()) {
+        obj.setProperty(rt, "classification",
+                        String::createFromUtf8(rt, a.classification));
+      }
+      if (a.hasMesh) {
+        // Scene-reconstruction geometry — bytes emitted verbatim as
+        // ArrayBuffers (vertices=Float32, faces=Uint32, classifications=Uint8).
+        Object mesh(rt);
+        auto vbuf = std::make_shared<OwningPixelBuffer>(a.meshVertices.size());
+        if (!a.meshVertices.empty()) {
+          std::memcpy(vbuf->bytes(), a.meshVertices.data(), a.meshVertices.size());
+        }
+        mesh.setProperty(rt, "vertices", facebook::jsi::ArrayBuffer(rt, vbuf));
+        auto fbuf = std::make_shared<OwningPixelBuffer>(a.meshFaces.size());
+        if (!a.meshFaces.empty()) {
+          std::memcpy(fbuf->bytes(), a.meshFaces.data(), a.meshFaces.size());
+        }
+        mesh.setProperty(rt, "faces", facebook::jsi::ArrayBuffer(rt, fbuf));
+        if (!a.meshClassifications.empty()) {
+          auto cbuf =
+              std::make_shared<OwningPixelBuffer>(a.meshClassifications.size());
+          std::memcpy(cbuf->bytes(), a.meshClassifications.data(),
+                      a.meshClassifications.size());
+          mesh.setProperty(rt, "classifications",
+                           facebook::jsi::ArrayBuffer(rt, cbuf));
+        }
+        obj.setProperty(rt, "meshGeometry", mesh);
+      }
+      anchors.setValueAtIndex(rt, i, obj);
+    }
+    return anchors;
+  }
+
+  // Per-frame camera intrinsics (AR frames only).  `intrinsics ===
+  // undefined` when not populated (non-AR frames).  Shape mirrors the
+  // JS `CameraFrame.intrinsics`: fx/fy/cx/cy in pixels + the capture
+  // resolution they're expressed at.
+  if (name == "intrinsics") {
+    if (!_data.hasIntrinsics) return Value::undefined();
+    Object intrinsics(rt);
+    intrinsics.setProperty(rt, "fx", Value(_data.fx));
+    intrinsics.setProperty(rt, "fy", Value(_data.fy));
+    intrinsics.setProperty(rt, "cx", Value(_data.cx));
+    intrinsics.setProperty(rt, "cy", Value(_data.cy));
+    intrinsics.setProperty(
+        rt, "imageWidth",
+        Value(static_cast<double>(_data.intrinsicsImageWidth)));
+    intrinsics.setProperty(
+        rt, "imageHeight",
+        Value(static_cast<double>(_data.intrinsicsImageHeight)));
+    return intrinsics;
+  }
+
+  // Unknown property — return undefined (matches JS object semantics).
   return Value::undefined();
 }
 

package/cpp/{stitcher_frame_jsi.hpp → camera_frame_jsi.hpp}

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 //
-// stitcher_frame_jsi.hpp — shared C++ JSI host object for the v0.8.0
+// camera_frame_jsi.hpp — shared C++ JSI host object for the v0.8.0
 // `StitcherFrame` contract.  Compiles on both iOS and Android; each
 // platform provides only the PixelBufferReader implementation and
 // the construction call site (Obj-C++ on iOS; JNI on Android).
@@ -18,7 +18,7 @@
 #include <memory>
 #include <vector>
 
-#include "stitcher_frame_data.hpp"
+#include "camera_frame_data.hpp"
 
 namespace retailens {
 
@@ -59,26 +59,26 @@ class OwningPixelBuffer : public facebook::jsi::MutableBuffer {
 /// worklet, then invalidate (typically immediately after dispatch
 /// returns — the underlying pixel buffer's lifetime is bound to
 /// the calling AR-session callback scope).
-class StitcherFrameJsiHostObject
+class CameraFrameJsiHostObject
     : public facebook::jsi::HostObject,
-      public std::enable_shared_from_this<StitcherFrameJsiHostObject> {
+      public std::enable_shared_from_this<CameraFrameJsiHostObject> {
  public:
   /// Factory.  ALWAYS use this — `shared_from_this()` (called inside
   /// `get` for `toArrayBuffer`) requires the instance to be owned
   /// by a `shared_ptr` from the moment of construction.  A raw
-  /// `new StitcherFrameJsiHostObject(...)` would throw
+  /// `new CameraFrameJsiHostObject(...)` would throw
   /// `std::bad_weak_ptr` on the first `toArrayBuffer()` JSI call.
   ///
   /// Private constructor + public factory enforces this at the
   /// language level; callers can't accidentally construct without
   /// `std::make_shared`.
-  static std::shared_ptr<StitcherFrameJsiHostObject> create(
-      StitcherFrameData data) {
+  static std::shared_ptr<CameraFrameJsiHostObject> create(
+      CameraFrameData data) {
     // `std::make_shared` would require a public ctor; route through
     // a tagged-dispatch private constructor instead.
-    struct EnableMakeShared : StitcherFrameJsiHostObject {
-      explicit EnableMakeShared(StitcherFrameData d)
-          : StitcherFrameJsiHostObject(std::move(d)) {}
+    struct EnableMakeShared : CameraFrameJsiHostObject {
+      explicit EnableMakeShared(CameraFrameData d)
+          : CameraFrameJsiHostObject(std::move(d)) {}
     };
     return std::make_shared<EnableMakeShared>(std::move(data));
   }
@@ -99,9 +99,9 @@ class StitcherFrameJsiHostObject
   bool isValid() const { return _isValid; }
 
  private:
-  explicit StitcherFrameJsiHostObject(StitcherFrameData data);
+  explicit CameraFrameJsiHostObject(CameraFrameData data);
 
-  StitcherFrameData _data;
+  CameraFrameData _data;
   bool _isValid;
 };
 

package/cpp/stitcher_proxy_jsi.cpp

@@ -8,6 +8,7 @@
 
 #include "stitcher_worklet_registry.hpp"
 
+#include <atomic>
 #include <memory>
 #include <string>
 #include <vector>
@@ -16,6 +17,13 @@ namespace retailens {
 
 namespace {
 
+// AR-metadata extraction toggles (see header).  Atomic: written on the
+// JS thread via __stitcherProxy.setExtractionConfig, read on the AR
+// delegate / GL thread by the platform extraction.  Default all false.
+std::atomic<bool> g_extractDepth{false};
+std::atomic<bool> g_extractAnchors{false};
+std::atomic<bool> g_extractMesh{false};
+
 class StitcherProxyHostObject : public facebook::jsi::HostObject {
  public:
   facebook::jsi::Value get(facebook::jsi::Runtime& rt,
@@ -84,6 +92,21 @@ class StitcherProxyHostObject : public facebook::jsi::HostObject {
           rt, PropNameID::forUtf8(rt, "count"), 0, std::move(fn));
     }
 
+    if (name == "setExtractionConfig") {
+      // setExtractionConfig(depth, anchors, mesh) — three booleans gating
+      // the platform AR extraction.  Missing/non-bool args default false.
+      auto fn = [](facebook::jsi::Runtime& runtime, const Value& /*thisVal*/,
+                   const Value* args, size_t count) -> Value {
+        g_extractDepth.store(count > 0 && args[0].isBool() && args[0].getBool());
+        g_extractAnchors.store(count > 1 && args[1].isBool() &&
+                               args[1].getBool());
+        g_extractMesh.store(count > 2 && args[2].isBool() && args[2].getBool());
+        return Value::undefined();
+      };
+      return Function::createFromHostFunction(
+          rt, PropNameID::forUtf8(rt, "setExtractionConfig"), 3, std::move(fn));
+    }
+
     return Value::undefined();
   }
 
@@ -93,6 +116,8 @@ class StitcherProxyHostObject : public facebook::jsi::HostObject {
     names.push_back(facebook::jsi::PropNameID::forUtf8(rt, "install"));
     names.push_back(facebook::jsi::PropNameID::forUtf8(rt, "uninstall"));
     names.push_back(facebook::jsi::PropNameID::forUtf8(rt, "count"));
+    names.push_back(
+        facebook::jsi::PropNameID::forUtf8(rt, "setExtractionConfig"));
     return names;
   }
 };
@@ -106,4 +131,10 @@ void installStitcherProxy(facebook::jsi::Runtime& runtime) {
       facebook::jsi::Object::createFromHostObject(runtime, proxy));
 }
 
+ExtractionConfig getExtractionConfig() {
+  return ExtractionConfig{g_extractDepth.load(std::memory_order_relaxed),
+                          g_extractAnchors.load(std::memory_order_relaxed),
+                          g_extractMesh.load(std::memory_order_relaxed)};
+}
+
 }  // namespace retailens

package/cpp/stitcher_proxy_jsi.hpp

@@ -43,4 +43,20 @@ namespace retailens {
 /// Android: `@ReactMethod(isBlockingSynchronousMethod = true)`).
 void installStitcherProxy(facebook::jsi::Runtime& runtime);
 
+/// Per-frame AR-metadata extraction toggles.  Set from JS via
+/// `__stitcherProxy.setExtractionConfig(depth, anchors, mesh)` (driven by
+/// the `<Camera>` enableDepth/enableAnchors/enableMesh props); read by the
+/// platform AR extraction to skip costly work when off.  Defaults: all
+/// false — zero arDepth/arAnchors/mesh cost until a host opts in (the
+/// always-cheap pose/tracking/pixels are unaffected).
+struct ExtractionConfig {
+  bool depth = false;
+  bool anchors = false;
+  bool mesh = false;
+};
+
+/// Thread-safe snapshot of the current extraction config.  Written on the
+/// JS thread (via the proxy), read on the AR delegate / GL thread.
+ExtractionConfig getExtractionConfig();
+
 }  // namespace retailens

package/cpp/stitcher_worklet_dispatch.cpp

@@ -5,7 +5,7 @@
 
 #include "stitcher_worklet_dispatch.hpp"
 
-#include "stitcher_frame_jsi.hpp"
+#include "camera_frame_jsi.hpp"
 #include "stitcher_worklet_registry.hpp"
 
 #include <react-native-worklets-core/WKTJsiWorklet.h>
@@ -31,7 +31,7 @@
 namespace retailens {
 
 void dispatchToHostWorklets(RNWorklet::JsiWorkletContext* context,
-                             StitcherFrameData data) {
+                             CameraFrameData data) {
   // Fast-path early-exit when no host worklets are registered.
   // The Android caller (`StitcherWorkletRuntime.dispatchToHostWorklets`)
   // already runs in a hot per-frame loop; saving the host-object
@@ -51,18 +51,18 @@ void dispatchToHostWorklets(RNWorklet::JsiWorkletContext* context,
 
   // Build the JSI host object on the worklet thread (inside the
   // lambda) so JSI access happens on the target runtime.
-  // `StitcherFrameJsiHostObject::create` uses the `make_shared`-via-
+  // `CameraFrameJsiHostObject::create` uses the `make_shared`-via-
   // factory pattern (required by `shared_from_this()` inside the
   // `toArrayBuffer` lambda); see its header.
   //
-  // Capture `data` by-move so the StitcherFrameData (including the
+  // Capture `data` by-move so the CameraFrameData (including the
   // pixel reader's shared_ptr) lives until the lambda runs.
   // Capture `invokers` by-move as well.
   context->invokeOnWorkletThread(
       [invokers = std::move(invokers), data = std::move(data)](
           RNWorklet::JsiWorkletContext* /*ctx*/,
           facebook::jsi::Runtime& rt) mutable {
-        auto hostObj = StitcherFrameJsiHostObject::create(std::move(data));
+        auto hostObj = CameraFrameJsiHostObject::create(std::move(data));
         facebook::jsi::Object frameJsi =
             facebook::jsi::Object::createFromHostObject(rt, hostObj);
         facebook::jsi::Value frameVal(rt, frameJsi);

package/cpp/stitcher_worklet_dispatch.hpp

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 // stitcher_worklet_dispatch.hpp — shared C++ helper that fans out a
-// `StitcherFrameData` to every host worklet registered in the
+// `CameraFrameData` to every host worklet registered in the
 // process-scope `retailens::StitcherWorkletRegistry`.
 //
 // v0.8.0 Phase 4b.iii — used by Android's per-frame fan-out path
@@ -26,7 +26,7 @@
 
 #pragma once
 
-#include "stitcher_frame_data.hpp"
+#include "camera_frame_data.hpp"
 
 #include <jsi/jsi.h>
 
@@ -36,7 +36,7 @@ class JsiWorkletContext;
 
 namespace retailens {
 
-/// Fan out a `StitcherFrameData` to every registered host worklet.
+/// Fan out a `CameraFrameData` to every registered host worklet.
 ///
 /// Behaviour:
 ///
@@ -44,7 +44,7 @@ namespace retailens {
 ///      is empty.  No host object is constructed; the caller's
 ///      thread returns immediately.
 ///   2. Otherwise, the function snapshots the registry, constructs
-///      a `StitcherFrameJsiHostObject` (deferred until inside the
+///      a `CameraFrameJsiHostObject` (deferred until inside the
 ///      worklet-thread lambda so JSI access happens on the
 ///      target runtime), and dispatches via
 ///      `context->invokeOnWorkletThread(...)`.
@@ -66,6 +66,6 @@ namespace retailens {
 /// @param data     Frame data + pixel reader.  Moved into the
 ///                 worklet-thread lambda.
 void dispatchToHostWorklets(RNWorklet::JsiWorkletContext* context,
-                             StitcherFrameData data);
+                             CameraFrameData data);
 
 }  // namespace retailens

package/dist/camera/ARCameraView.d.ts

@@ -30,7 +30,8 @@
  */
 import React from 'react';
 import { type ViewStyle } from 'react-native';
-import type { StitcherFrameProcessor } from '../stitching/StitcherFrame';
+import type { CameraFrameProcessor } from '../stitching/CameraFrame';
+import type { ARFrameMeta, ARPluginResult } from '../stitching/ARFrameMeta';
 export interface ARCameraViewProps {
     /** Layout style, typically `StyleSheet.absoluteFill` or `flex: 1`. */
     style?: ViewStyle;
@@ -43,7 +44,7 @@ export interface ARCameraViewProps {
     /**
      * 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 —
+     * worklet receives a `CameraFrame` enriched with AR metadata —
      * `source: 'ar'`, world-space `pose` (rotation + translation),
      * `arTrackingState`, and (when supported) `arDepth` / `arAnchors`.
      *
@@ -58,7 +59,84 @@ export interface ARCameraViewProps {
      * different runtimes with different frame shapes, hence the separate
      * prop.
      */
-    arFrameProcessor?: StitcherFrameProcessor;
+    arFrameProcessor?: CameraFrameProcessor;
+    /**
+     * Opt in to per-frame AR depth extraction (`CameraFrame.arDepth`).
+     * Default `false` — depth is the costliest field (a per-frame buffer
+     * copy), so it stays off until a worklet needs it.
+     */
+    enableDepth?: boolean;
+    /**
+     * Opt in to per-frame AR anchor extraction (`CameraFrame.arAnchors` —
+     * detected planes / augmented images).  Default `false`.
+     */
+    enableAnchors?: boolean;
+    /**
+     * Opt in to scene-reconstruction mesh anchors (`type: 'mesh'` entries
+     * in `arAnchors`, carrying `meshGeometry`).  Default `false`.  iOS
+     * enables ARKit `sceneReconstruction` (LiDAR devices); Android
+     * reconstructs a rough mesh from the depth map.  Expensive — only on
+     * when needed.  Implies depth on Android.
+     */
+    enableMesh?: boolean;
+    /**
+     * Which plane orientations to surface in `arAnchors` (requires
+     * `enableAnchors`).  Default `'vertical'` — the orientation the
+     * plane-projected stitch path has always used, so existing callers
+     * see no change.
+     *
+     *   - `'vertical'`   — walls / doors / fixtures (the default)
+     *   - `'horizontal'` — floors / tables / seats
+     *   - `'both'`       — surface every detected plane
+     *
+     * Platform notes: iOS changes ARKit `planeDetection` to match (a
+     * live session reconfigure).  Android always detects both planes
+     * (ARCore needs horizontal planes to bootstrap tracking) and simply
+     * FILTERS which orientations reach `arAnchors`, so the JS-observable
+     * set is identical on both platforms.
+     */
+    planeDetection?: 'vertical' | 'horizontal' | 'both';
+    /**
+     * v0.18.0 — LIGHT per-frame AR metadata callback, invoked on the JS
+     * MAIN thread (NOT a worklet).  When provided, the native AR session
+     * builds an {@link ARFrameMeta} per frame and emits it as a device
+     * event; this component subscribes and calls the handler.  Worklet-free
+     * — this is the recommended way to read AR pose / tracking / anchor /
+     * intrinsics / depth-dims / mesh-counts data (the `arFrameProcessor`
+     * worklet can only safely surface a shared value; see `ARFrameMeta`).
+     *
+     * Costly fields are gated: `depth` only when `enableDepth`, `mesh` only
+     * when `enableMesh`, `anchors` only when `enableAnchors`;
+     * `intrinsics` / `pose` / `trackingState` are always present.  Emission
+     * is throttled to {@link arFrameMetaInterval} ms.
+     */
+    onArFrame?: (meta: ARFrameMeta) => void;
+    /**
+     * v0.18.0 — throttle interval (ms) for {@link onArFrame}.  Default `100`
+     * (≈ 10 Hz).  No effect unless `onArFrame` is provided.
+     */
+    arFrameMetaInterval?: number;
+    /**
+     * v0.19.0 — ASYNCHRONOUS AR-plugin result callback, invoked on the JS MAIN
+     * thread (NOT a worklet).  Part of the AR plugin framework: host-registered
+     * native plugins (see `RNISARPluginRegistry` / `RNSARPluginRegistry`) can
+     * offload heavy per-frame work to their own queue and later push a result
+     * via `registry.emit(name, result)`.  The SDK routes that to JS as a
+     * `RNImageStitcherARPluginResult` device event; when this prop is provided,
+     * this component subscribes and invokes the handler with
+     * `{ plugin, result }`.
+     *
+     * SYNCHRONOUS plugin results (computed inline on the AR thread) instead ride
+     * the throttled {@link onArFrame} event on {@link ARFrameMeta.plugins} —
+     * read them there.  This callback is ONLY for the out-of-band async channel.
+     *
+     * The subscription is independent of {@link onArFrame}: a host can read
+     * sync results via `onArFrame` and async results via `onArPluginResult`,
+     * either, or both.  Wiring mirrors `onArFrame` exactly (latest handler held
+     * in a ref so the subscription effect depends only on whether a handler is
+     * present; cleanup on unmount / when the handler is removed).
+     */
+    onArPluginResult?: (e: ARPluginResult) => void;
 }
 /**
  * Imperative handle exposed via the ref — shape mirrors the subset

package/dist/camera/ARCameraView.js

@@ -77,7 +77,7 @@ const ensureStitcherProxyInstalled_1 = require("../stitching/ensureStitcherProxy
 const NativeARCameraView = react_native_1.Platform.OS === 'ios' || react_native_1.Platform.OS === 'android'
     ? (0, react_native_1.requireNativeComponent)('RNSARCameraView')
     : null;
-exports.ARCameraView = (0, react_1.forwardRef)(function ARCameraView({ style, guidance, arFrameProcessor }, ref) {
+exports.ARCameraView = (0, react_1.forwardRef)(function ARCameraView({ style, guidance, arFrameProcessor, enableDepth, enableAnchors, enableMesh, planeDetection, onArFrame, arFrameMetaInterval, onArPluginResult, }, ref) {
     // Held across the start→stop lifecycle so stopRecording's
     // resolved VideoFile can be delivered via the same callback
     // pair vision-camera uses.
@@ -103,6 +103,108 @@ exports.ARCameraView = (0, react_1.forwardRef)(function ARCameraView({ style, gu
             proxy.uninstall(id);
         };
     }, [arFrameProcessor]);
+    // Push the AR-metadata extraction config to native — gates the
+    // costly per-frame depth / anchor / mesh work (all off by default).
+    // Routed through `__stitcherProxy.setExtractionConfig`, read by the
+    // platform AR extraction.  iOS ADDITIONALLY toggles ARKit
+    // `sceneReconstruction` for mesh (a session-config change, not a
+    // per-frame gate); Android reconstructs mesh from the depth map and
+    // needs no session change.
+    (0, react_1.useEffect)(() => {
+        const depth = enableDepth === true;
+        const anchors = enableAnchors === true;
+        const mesh = enableMesh === true;
+        if ((0, ensureStitcherProxyInstalled_1.ensureStitcherProxyInstalled)()) {
+            globalThis.__stitcherProxy?.setExtractionConfig?.(depth, anchors, mesh);
+        }
+        if (react_native_1.Platform.OS === 'ios') {
+            const session = react_native_1.NativeModules
+                .RNSARSession;
+            session?.setSceneReconstructionEnabled?.(mesh);
+        }
+    }, [enableDepth, enableAnchors, enableMesh]);
+    // Push the plane-detection mode to native.  Unlike the extraction
+    // config above this is a SESSION setting, so it routes through the
+    // RNSARSession native module on BOTH platforms (iOS reconfigures
+    // ARKit `planeDetection`; Android stores an emission filter — see
+    // the prop docs).  Defaults to `'vertical'` to preserve the
+    // plane-projected stitch path's long-standing behaviour.
+    (0, react_1.useEffect)(() => {
+        const mode = planeDetection ?? 'vertical';
+        const session = react_native_1.NativeModules
+            .RNSARSession;
+        session?.setPlaneDetection?.(mode);
+    }, [planeDetection]);
+    // v0.18.0 — onArFrame device-event wiring (worklet-free, main thread).
+    //
+    // The latest `onArFrame` is held in a ref so the subscription effect
+    // depends only on whether a handler is present + the interval — NOT on
+    // the handler's identity (which typically changes every render).  This
+    // avoids tearing down + re-establishing the native event subscription
+    // (and the costly `setArFrameMetaEnabled(true)` extraction toggle) on
+    // every parent re-render.
+    const onArFrameRef = (0, react_1.useRef)(onArFrame);
+    (0, react_1.useEffect)(() => {
+        onArFrameRef.current = onArFrame;
+    }, [onArFrame]);
+    const arFrameEnabled = onArFrame != null;
+    (0, react_1.useEffect)(() => {
+        if (!arFrameEnabled) {
+            return undefined;
+        }
+        const session = react_native_1.NativeModules
+            .RNSARSession;
+        if (session?.setArFrameMetaEnabled == null) {
+            // Native module / method unavailable (e.g. web, or a native build
+            // predating the event channel): no-op, no crash.
+            return undefined;
+        }
+        const intervalMs = arFrameMetaInterval ?? 100;
+        session.setArFrameMetaEnabled(true, intervalMs);
+        const emitter = new react_native_1.NativeEventEmitter(react_native_1.NativeModules.RNSARSession);
+        const sub = emitter.addListener('RNImageStitcherARFrame', (meta) => {
+            onArFrameRef.current?.(meta);
+        });
+        return () => {
+            sub.remove();
+            session.setArFrameMetaEnabled?.(false, intervalMs);
+        };
+    }, [arFrameEnabled, arFrameMetaInterval]);
+    // v0.19.0 — onArPluginResult device-event wiring (worklet-free, main
+    // thread).  Mirrors the onArFrame subscription above: the latest handler
+    // is held in a ref so the subscription effect depends only on WHETHER a
+    // handler is present, not its (per-render-changing) identity — so the
+    // native event subscription isn't torn down + re-established every render.
+    //
+    // This is a PURELY-JS subscription: unlike onArFrame there's no native
+    // "enable" toggle to flip.  Native emits `RNImageStitcherARPluginResult`
+    // whenever a registered plugin calls `registry.emit(...)`; the registry is
+    // empty unless the host registered plugins, so an app with no plugins
+    // never sees an event even if this prop is wired.
+    const onArPluginResultRef = (0, react_1.useRef)(onArPluginResult);
+    (0, react_1.useEffect)(() => {
+        onArPluginResultRef.current = onArPluginResult;
+    }, [onArPluginResult]);
+    const arPluginResultEnabled = onArPluginResult != null;
+    (0, react_1.useEffect)(() => {
+        if (!arPluginResultEnabled) {
+            return undefined;
+        }
+        const native = react_native_1.NativeModules
+            .RNSARSession;
+        if (native == null) {
+            // Native module unavailable (e.g. web, or a native build predating
+            // the plugin event channel): no-op, no crash.
+            return undefined;
+        }
+        const emitter = new react_native_1.NativeEventEmitter(native);
+        const sub = emitter.addListener('RNImageStitcherARPluginResult', (e) => {
+            onArPluginResultRef.current?.(e);
+        });
+        return () => {
+            sub.remove();
+        };
+    }, [arPluginResultEnabled]);
     (0, react_1.useImperativeHandle)(ref, () => ({
         takePhoto: async (options = {}) => {
             const native = react_native_1.NativeModules.RNSARSession;