react-native-image-stitcher 0.17.0 → 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
@@ -555,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() {
@@ -637,6 +846,12 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         // 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.
         //
@@ -1182,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

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

package/ios/Sources/RNImageStitcher/RNSARWorkletRuntime.mm

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

package/package.json

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

@@ -32,6 +32,7 @@
 
 import React, { forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
 import {
+  NativeEventEmitter,
   NativeModules,
   Platform,
   StyleSheet,
@@ -42,7 +43,8 @@ import {
 } from 'react-native';
 
 import { ensureStitcherProxyInstalled } from '../stitching/ensureStitcherProxyInstalled';
-import type { StitcherFrameProcessor } from '../stitching/StitcherFrame';
+import type { CameraFrameProcessor } from '../stitching/CameraFrame';
+import type { ARFrameMeta } from '../stitching/ARFrameMeta';
 
 
 // React Native looks up the component by its NATIVE name.
@@ -69,7 +71,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`.
    *
@@ -84,7 +86,65 @@ 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;
 }
 
 
@@ -167,7 +227,17 @@ type RecordingCallbacks = {
 
 export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
   function ARCameraView(
-    { style, guidance, arFrameProcessor },
+    {
+      style,
+      guidance,
+      arFrameProcessor,
+      enableDepth,
+      enableAnchors,
+      enableMesh,
+      planeDetection,
+      onArFrame,
+      arFrameMetaInterval,
+    },
     ref,
   ): React.JSX.Element {
     // Held across the start→stop lifecycle so stopRecording's
@@ -189,7 +259,7 @@ export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
       }
       const proxy = (globalThis as {
         __stitcherProxy?: {
-          install(fn: StitcherFrameProcessor): string;
+          install(fn: CameraFrameProcessor): string;
           uninstall(id: string): void;
         };
       }).__stitcherProxy;
@@ -202,6 +272,96 @@ export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
       };
     }, [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.
+    useEffect(() => {
+      const depth = enableDepth === true;
+      const anchors = enableAnchors === true;
+      const mesh = enableMesh === true;
+      if (ensureStitcherProxyInstalled()) {
+        (globalThis as {
+          __stitcherProxy?: {
+            setExtractionConfig?(d: boolean, a: boolean, m: boolean): void;
+          };
+        }).__stitcherProxy?.setExtractionConfig?.(depth, anchors, mesh);
+      }
+      if (Platform.OS === 'ios') {
+        const session = (NativeModules as Record<string, unknown>)
+          .RNSARSession as
+          | { setSceneReconstructionEnabled?(on: boolean): void }
+          | undefined;
+        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.
+    useEffect(() => {
+      const mode = planeDetection ?? 'vertical';
+      const session = (NativeModules as Record<string, unknown>)
+        .RNSARSession as
+        | { setPlaneDetection?(mode: string): void }
+        | undefined;
+      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 = useRef<((meta: ARFrameMeta) => void) | undefined>(
+      onArFrame,
+    );
+    useEffect(() => {
+      onArFrameRef.current = onArFrame;
+    }, [onArFrame]);
+
+    const arFrameEnabled = onArFrame != null;
+    useEffect(() => {
+      if (!arFrameEnabled) {
+        return undefined;
+      }
+      const session = (NativeModules as Record<string, unknown>)
+        .RNSARSession as
+        | {
+            setArFrameMetaEnabled?(enabled: boolean, intervalMs: number): void;
+          }
+        | undefined;
+      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 NativeEventEmitter(
+        NativeModules.RNSARSession as never,
+      );
+      const sub = emitter.addListener(
+        'RNImageStitcherARFrame',
+        (meta: ARFrameMeta) => {
+          onArFrameRef.current?.(meta);
+        },
+      );
+      return () => {
+        sub.remove();
+        session.setArFrameMetaEnabled?.(false, intervalMs);
+      };
+    }, [arFrameEnabled, arFrameMetaInterval]);
+
     useImperativeHandle(ref, () => ({
       takePhoto: async (options = {}) => {
         const native: any =