react-native-image-stitcher 0.17.0 → 0.18.0

package/dist/camera/Camera.d.ts

@@ -41,7 +41,8 @@
 import React from 'react';
 import { type StyleProp, type ViewStyle } from 'react-native';
 import type { DrawableFrameProcessor, ReadonlyFrameProcessor } from 'react-native-vision-camera';
-import type { StitcherFrameProcessor } from '../stitching/StitcherFrame';
+import type { CameraFrameProcessor } from '../stitching/CameraFrame';
+import type { ARFrameMeta } from '../stitching/ARFrameMeta';
 import { type CaptureHeaderProps } from './CaptureHeader';
 import { type CapturePreviewAction } from './CapturePreview';
 import { type CaptureThumbnailItem } from './CaptureThumbnailStrip';
@@ -527,11 +528,11 @@ export interface CameraProps {
      *     worklet to fire on vc's Frame Processor runtime.
      *
      * ```tsx
-     * import { Camera, useFrameProcessor, type StitcherFrame }
+     * import { Camera, useFrameProcessor, type CameraFrame }
      *   from 'react-native-image-stitcher';
      *
      * function MyScreen() {
-     *   const fp = useFrameProcessor((frame: StitcherFrame) => {
+     *   const fp = useFrameProcessor((frame: CameraFrame) => {
      *     'worklet';
      *     // ...
      *   }, []);
@@ -552,12 +553,12 @@ export interface CameraProps {
      * ```tsx
      * import {
      *   Camera, useFrameProcessor, useStitcherWorklet,
-     *   type StitcherFrame,
+     *   type CameraFrame,
      * } from 'react-native-image-stitcher';
      *
      * function MyScreen() {
      *   const stitcher = useStitcherWorklet();
-     *   const fp = useFrameProcessor((frame: StitcherFrame) => {
+     *   const fp = useFrameProcessor((frame: CameraFrame) => {
      *     'worklet';
      *     hostPreLogic(frame);
      *     stitcher.call(frame);   // ← first-party stitching
@@ -601,14 +602,60 @@ export interface CameraProps {
     /**
      * 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'`
+     * replacement).  Receives a `CameraFrame` 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;
+    arFrameProcessor?: CameraFrameProcessor;
+    /**
+     * Opt in to per-frame AR depth on the `arFrameProcessor` frame
+     * (`CameraFrame.arDepth`).  Default `false` — depth is the costliest
+     * field (a per-frame buffer copy), so it's off until you need it.
+     */
+    enableDepth?: boolean;
+    /**
+     * Opt in to per-frame AR anchors (`CameraFrame.arAnchors` — detected
+     * planes / images).  Default `false`.
+     */
+    enableAnchors?: boolean;
+    /**
+     * Opt in to scene-reconstruction mesh anchors (`type: 'mesh'` in
+     * `arAnchors`, with `meshGeometry`).  Default `false`.  iOS enables
+     * ARKit `sceneReconstruction` (LiDAR); Android reconstructs a rough
+     * mesh from the depth map.  Expensive — only on when needed.
+     */
+    enableMesh?: boolean;
+    /**
+     * Which plane orientations to surface in `CameraFrame.arAnchors`
+     * (requires `enableAnchors`; AR capture only).  Default `'vertical'`
+     * — the orientation the plane-projected stitch path has always used.
+     * `'horizontal'` surfaces floors / tables; `'both'` surfaces every
+     * detected plane.  See `ARCameraView` for the per-platform details.
+     */
+    planeDetection?: 'vertical' | 'horizontal' | 'both';
+    /**
+     * v0.18.0 — LIGHT per-frame AR metadata callback, invoked on the JS
+     * MAIN thread (NOT a worklet).  Only fires in AR capture
+     * (`captureSource === 'ar'`).  Receives an {@link ARFrameMeta} carrying
+     * pose, tracking state, intrinsics, and (when the matching `enable*`
+     * prop is on) depth dimensions, anchors, and mesh counts.
+     *
+     * This is the recommended way to read AR metadata: it sidesteps the
+     * worklet path entirely (the `arFrameProcessor` worklet can only safely
+     * surface a worklets-core shared value, because capturing a host
+     * callback crashes the worklet closure-wrap).  Native builds the meta
+     * and emits a device event; `<Camera>` threads the handler through to
+     * `<ARCameraView>`, which subscribes and invokes it on the main thread.
+     */
+    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;
     /**
      * Which device holds the non-AR panorama capture accepts.
      *

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, arFrameProcessor, 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, enableDepth, enableAnchors, enableMesh, planeDetection, onArFrame, arFrameMetaInterval, 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, arFrameProcessor: arFrameProcessor })) : (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, enableDepth: enableDepth, enableAnchors: enableAnchors, enableMesh: enableMesh, planeDetection: planeDetection, onArFrame: onArFrame, arFrameMetaInterval: arFrameMetaInterval })) : (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/index.d.ts

@@ -91,7 +91,8 @@ export { IncrementalOutcome, incrementalStitcherIsAvailable, subscribeIncrementa
 export type { IncrementalState, AcceptedKeyframe } from './stitching/incremental';
 export { useIncrementalStitcher } from './stitching/useIncrementalStitcher';
 export { useKeyframeStream } from './stitching/useKeyframeStream';
-export type { StitcherFrame, StitcherFrameProcessor, ARAnchor, } from './stitching/StitcherFrame';
+export type { CameraFrame, CameraFrameProcessor, ARAnchor, } from './stitching/CameraFrame';
+export type { ARFrameMeta } from './stitching/ARFrameMeta';
 export { useFrameProcessorDriver } from './stitching/useFrameProcessorDriver';
 export type { UseFrameProcessorDriverOptions, FrameProcessorDriverHandle, } from './stitching/useFrameProcessorDriver';
 export { useStitcherWorklet } from './stitching/useStitcherWorklet';

package/dist/stitching/ARFrameMeta.d.ts

@@ -0,0 +1,100 @@
+/**
+ * v0.18.0 — LIGHT per-frame AR metadata delivered to JS on the MAIN
+ * thread via a normal callback (`onArFrame`), bypassing worklets entirely.
+ *
+ * ## Why a callback, NOT a worklet
+ *
+ * The AR worklet path (`arFrameProcessor` + the `__stitcherProxy` JSI
+ * registry) deep-copies the worklet's whole closure into the AR worklet
+ * runtime via react-native-worklets-core's `WorkletInvoker`.  When the
+ * worklet captures a host object (e.g. a `createRunOnJS` callback) that
+ * closure-wrap recurses without termination → stack overflow → SIGBUS the
+ * instant AR mode mounts (verified on device).  Worklets can therefore
+ * only safely capture a worklets-core *shared value* — an awkward,
+ * poll-from-JS pattern for getting structured data back.
+ *
+ * `onArFrame` sidesteps the whole problem: native builds the metadata and
+ * emits it as a plain `RNImageStitcherARFrame` device event carrying a
+ * JSON object; the JS side subscribes via `NativeEventEmitter` and invokes
+ * the host callback on the main thread.  No worklet, no closure-wrap, no
+ * shared-value polling.  This is the recommended way to read AR metadata.
+ *
+ * ## Cost / gating
+ *
+ * The metadata is intentionally LIGHT — no pixel / vertex / face byte
+ * marshaling.  `depth` reports only the depth map's dimensions + whether a
+ * confidence channel exists (no buffer copy); `mesh` reports only anchor /
+ * vertex / face *counts*.  Native gates each costly field on the matching
+ * extraction flag (`depth` ⇐ `enableDepth`, `mesh` ⇐ `enableMesh`,
+ * `anchors` ⇐ `enableAnchors`); `intrinsics` / `pose` / `trackingState` are
+ * always present.  Emission is gated on a TS-set enabled flag (only true
+ * when `onArFrame` is provided) and throttled to `arFrameMetaInterval` ms
+ * (default 100 ≈ 10 Hz) on the native side.
+ */
+export interface ARFrameMeta {
+    /** Frame-capture timestamp in NANOSECONDS (AR-framework monotonic clock). */
+    timestamp: number;
+    /** AR tracking quality at this frame. */
+    trackingState: 'notAvailable' | 'limited' | 'normal';
+    /**
+     * Camera pose in world coordinates at frame-capture time.
+     *
+     *   - `rotation` — quaternion `(x, y, z, w)`, matching the convention
+     *     used throughout the engine + the `CameraFrame.pose` field.
+     *   - `translation` — metres in world space `[x, y, z]`.
+     */
+    pose: {
+        rotation: [number, number, number, number];
+        translation: [number, number, number];
+    };
+    /**
+     * Camera intrinsics for this frame — focal lengths (`fx`, `fy`) and
+     * principal point (`cx`, `cy`) in PIXELS at the `imageWidth × imageHeight`
+     * capture resolution.  Always attempted (not gated); `null` only when the
+     * AR framework didn't provide them for this frame.
+     */
+    intrinsics: {
+        fx: number;
+        fy: number;
+        cx: number;
+        cy: number;
+        imageWidth: number;
+        imageHeight: number;
+    } | null;
+    /**
+     * Depth-map summary — dimensions + whether a per-pixel confidence channel
+     * is available.  NO pixel buffer is copied (that's the costly part).
+     * Present only when the `enableDepth` prop is on AND the device produced a
+     * depth map this frame; `null` otherwise.
+     */
+    depth: {
+        width: number;
+        height: number;
+        hasConfidence: boolean;
+    } | null;
+    /**
+     * Tracked AR anchors visible in this frame (planes / images / points /
+     * mesh).  Empty array when `enableAnchors` is on but nothing is tracked;
+     * effectively empty when `enableAnchors` is off.  `transform` is a 4×4
+     * row-major anchor→world matrix (16 numbers).
+     */
+    anchors: Array<{
+        id: string;
+        type: 'plane' | 'image' | 'point' | 'mesh';
+        alignment?: 'horizontal' | 'vertical';
+        extent?: [number, number];
+        classification?: string;
+        transform: number[];
+    }>;
+    /**
+     * Scene-reconstruction mesh summary — anchor / vertex / face COUNTS only
+     * (no vertex / face byte marshaling).  Present only when `enableMesh` is
+     * on; `null` otherwise.
+     */
+    mesh: {
+        anchorCount: number;
+        vertexCount: number;
+        faceCount: number;
+    } | null;
+}
+//# sourceMappingURL=ARFrameMeta.d.ts.map

package/dist/stitching/{StitcherFrame.js → ARFrameMeta.js}

@@ -1,4 +1,4 @@
 "use strict";
 // SPDX-License-Identifier: Apache-2.0
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=StitcherFrame.js.map
+//# sourceMappingURL=ARFrameMeta.js.map

package/dist/stitching/{StitcherFrame.d.ts → CameraFrame.d.ts}

@@ -2,7 +2,7 @@
  * v0.8.0 — unified frame contract for the lib's worklet processor.
  *
  * Worklets registered via the v0.8.0 `useFrameProcessor` hook (also in
- * this directory) receive a `StitcherFrame` regardless of capture mode.
+ * this directory) receive a `CameraFrame` regardless of capture mode.
  * The lib-owned worklet runtime guarantees the same JS-visible shape
  * whether the underlying source is a vision-camera `Frame` (non-AR
  * mode, sourced from the FP plugin) or an ARKit `ARFrame` / ARCore
@@ -16,10 +16,10 @@
  * (Phase-0 audit confirmed the iOS path).  But vision-camera's
  * **Android** `Frame` is `androidx.camera.core.ImageProxy`-coupled —
  * ARCore does NOT produce `ImageProxy` instances.  Forcing
- * `StitcherFrame extends Frame` would either (a) require reverse-
+ * `CameraFrame extends Frame` would either (a) require reverse-
  * engineering ImageProxy on Android (intractable + fragile), or
  * (b) make the type asymmetric per platform.  Both are worse than
- * making `StitcherFrame` a structural sibling type that vc Frames
+ * making `CameraFrame` a structural sibling type that vc Frames
  * happen to satisfy (because vc Frames carry the same width / height /
  * orientation / pixelFormat / timestamp / toArrayBuffer surface).
  *
@@ -36,7 +36,7 @@
  * a JPEG-encode frame-processor plugin).  Returning a reference and
  * reading it later will read into freed memory.
  */
-export interface StitcherFrame {
+export interface CameraFrame {
     /** Pixel width of the camera image. */
     width: number;
     /** Pixel height of the camera image. */
@@ -141,6 +141,27 @@ export interface StitcherFrame {
      * tracking is degraded check this.  Undefined in non-AR mode.
      */
     arTrackingState?: 'notAvailable' | 'limited' | 'normal';
+    /**
+     * Camera intrinsics for THIS frame — focal lengths (`fx`,`fy`) and
+     * principal point (`cx`,`cy`) in PIXELS at the `imageWidth × imageHeight`
+     * capture resolution.  Needed to lift 2D image-space coordinates to 3D
+     * via pose + intrinsics (e.g. object-level reconstruction).
+     *
+     * Populated on **AR frames** (`source: 'ar'`) from ARKit
+     * `ARCamera.intrinsics` / ARCore `Camera` intrinsics.  **Undefined for
+     * non-AR (vision-camera) frames** — they are raw vc `Frame`s without an
+     * intrinsics surface; read vc's own APIs there if needed.  (The spec
+     * called this required; it's optional here because the non-AR frame
+     * shape genuinely can't carry it.)
+     */
+    intrinsics?: {
+        fx: number;
+        fy: number;
+        cx: number;
+        cy: number;
+        imageWidth: number;
+        imageHeight: number;
+    };
 }
 /**
  * v0.8.0 — public AR anchor type.  Subset of ARKit/ARCore anchor info
@@ -150,21 +171,59 @@ export interface StitcherFrame {
 export interface ARAnchor {
     /** Stable per-session anchor identifier. */
     id: string;
-    /** Anchor kind.  `'point'` is Android (ARCore) only. */
-    type: 'plane' | 'image' | 'point';
     /**
-     * 4×4 row-major transform from anchor space to world space.
-     * 16 numbers.
+     * Anchor kind.  `'point'` is Android (ARCore) only; `'mesh'` is a
+     * scene-reconstruction mesh anchor, present only when the `enableMesh`
+     * `<Camera>` prop is on (and the device supports reconstruction).
+     */
+    type: 'plane' | 'image' | 'point' | 'mesh';
+    /**
+     * 4×4 row-major transform from anchor space to world space (16
+     * numbers).  For `'mesh'` anchors, the `meshGeometry.vertices` are in
+     * this anchor's LOCAL space — multiply by `transform` for world coords.
      */
     transform: number[];
+    /**
+     * Plane orientation — `'horizontal'` (floor / table / seat) vs
+     * `'vertical'` (wall / door / window).  Present on `'plane'` anchors;
+     * undefined for other anchor kinds.  Lets a host distinguish a shelf
+     * surface from the wall behind it.
+     */
+    alignment?: 'horizontal' | 'vertical';
+    /**
+     * Plane size in metres along its local x / z axes (`[x, z]`).  Present
+     * on `'plane'` anchors only.
+     */
+    extent?: [number, number];
+    /**
+     * ARKit semantic classification of the plane's surface, when the
+     * framework provides it (iOS; mostly horizontal planes).  Undefined
+     * when unknown / unsupported (incl. Android, which has no equivalent).
+     */
+    classification?: 'wall' | 'floor' | 'ceiling' | 'table' | 'seat' | 'door' | 'window' | 'none';
+    /**
+     * Scene-reconstruction geometry — present only on `type: 'mesh'`
+     * anchors.  Buffers (wrap in the noted typed-array view):
+     *   - `vertices`  → `Float32Array`, xyz triplets in anchor-local space.
+     *   - `faces`     → `Uint32Array`, triangle indices into `vertices`.
+     *   - `classifications` → optional `Uint8Array`, one ARKit mesh class
+     *     per face (0=none, 1=wall, 2=floor, 3=ceiling, …).  **iOS only**
+     *     (from `ARMeshAnchor`); absent on Android, where the mesh is
+     *     reconstructed from the depth map and carries no semantics.
+     */
+    meshGeometry?: {
+        vertices: ArrayBuffer;
+        faces: ArrayBuffer;
+        classifications?: ArrayBuffer;
+    };
 }
 /**
  * v0.8.0 — worklet function signature for the unified frame processor.
  *
  * Must be a `'worklet'`-prefixed function (so it can run on the
- * worklet runtime).  Receives a `StitcherFrame` per camera frame; the
+ * worklet runtime).  Receives a `CameraFrame` per camera frame; the
  * return value is ignored (use `runOnJS` / shared values to surface
  * results back to the JS thread).
  */
-export type StitcherFrameProcessor = (frame: StitcherFrame) => void;
-//# sourceMappingURL=StitcherFrame.d.ts.map
+export type CameraFrameProcessor = (frame: CameraFrame) => void;
+//# sourceMappingURL=CameraFrame.d.ts.map

package/dist/stitching/CameraFrame.js

@@ -0,0 +1,4 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=CameraFrame.js.map

package/dist/stitching/useStitcherWorklet.d.ts

@@ -106,17 +106,17 @@
  *   their own worklet via this hook must do the wiring themselves.
  */
 import type { Frame } from 'react-native-vision-camera';
-import type { StitcherFrame } from './StitcherFrame';
+import type { CameraFrame } from './CameraFrame';
 /**
  * Frames the lib's stitching worklet accepts.  Accepting either a
  * vc `Frame` (what the host's `useFrameProcessor` body sees) or the
- * lib's `StitcherFrame` (what the lib's `useFrameProcessor` body
+ * lib's `CameraFrame` (what the lib's `useFrameProcessor` body
  * sees) keeps the same `useStitcherWorklet` usable from both kinds
  * of host worklet bodies without a cast on the call site.  The
  * worklet only reads `width` / `height`; the rest of the frame
  * object is forwarded verbatim to the native plugin.
  */
-export type StitcherWorkletInput = Frame | StitcherFrame;
+export type StitcherWorkletInput = Frame | CameraFrame;
 export interface UseStitcherWorkletOptions {
     /**
      * Gyro sample interval in ms (~30 Hz default).  Drives the JS-
@@ -145,7 +145,7 @@ export interface UseStitcherWorkletOptions {
 }
 export interface StitcherWorkletHandle {
     /**
-     * Worklet function: pass a `StitcherFrame` to perform one frame of
+     * Worklet function: pass a `CameraFrame` to perform one frame of
      * the lib's first-party stitching (throttle + pose synthesis +
      * native plugin call).  Safe to call from inside another
      * `'worklet'`-prefixed function (this is the canonical

package/dist/stitching/useStitcherWorklet.js

@@ -228,7 +228,7 @@ function useStitcherWorklet(options = {}) {
         // party callback installed in `RNSARWorkletRuntime`).  Calling
         // the vc Frame Processor plugin here would throw
         // `getPropertyAsObject: property '__frame' is undefined`
-        // because AR frames are `StitcherFrameHostObject` instances
+        // because AR frames are `CameraFrameHostObject` instances
         // and don't carry the vc `Frame` proxy's JSI marker.  The
         // throw is caught silently by the per-worklet error handler
         // (`RNSARWorkletRuntime.mm:284-301`) and bubbles up only to
@@ -240,12 +240,12 @@ function useStitcherWorklet(options = {}) {
         // hook (the AR-side stitching path runs natively, independent
         // of the composed worklet body).
         //
-        // The `(frame as StitcherFrame).source` cast is safe: vc
+        // The `(frame as CameraFrame).source` cast is safe: vc
         // `Frame` doesn't carry a `source` property so the check
         // returns `undefined !== 'ar'` → `true`, and the worklet
         // proceeds normally.  Only frames that explicitly tag
         // themselves as AR-source (which our native AR dispatcher
-        // does — see `StitcherFrameHostObject.mm`) get short-circuited.
+        // does — see `CameraFrameHostObject.mm`) get short-circuited.
         if (frame.source === 'ar')
             return;
         // Throttle (verbatim from useFrameProcessorDriver).
@@ -273,7 +273,7 @@ function useStitcherWorklet(options = {}) {
         const fx = w * sharedFxNumerator.value;
         const fy = h * sharedFyNumerator.value;
         // vc's `plugin.call` is typed against vc's `Frame`.  The worklet
-        // accepts the union (`Frame | StitcherFrame`); cast through
+        // accepts the union (`Frame | CameraFrame`); cast through
         // `unknown` because the union doesn't satisfy vc's interface
         // even though structurally both members do.
         plugin.call(frame, {

package/ios/Sources/RNImageStitcher/ARSessionBridge.m

@@ -5,6 +5,7 @@
 // imports as `NativeModules.RNSARSession`.
 
 #import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>
 
 // REMAP form, NOT EXTERN_MODULE.  The Swift singleton in
 // RNSARSession.swift takes the @objc name "RNSARSession"
@@ -20,7 +21,14 @@
 // `RNSARSessionBridge` and dispatch methods against THAT
 // class — where takePhoto / startRecording / stopRecording etc.
 // actually live.
-@interface RCT_EXTERN_REMAP_MODULE(RNSARSession, RNSARSessionBridge, NSObject)
+//
+// v0.18.0 — base class is now `RCTEventEmitter` (was `NSObject`) so the
+// "RNSARSession" module can emit the `RNImageStitcherARFrame` device
+// event for the `onArFrame` channel.  RN auto-provides the
+// `addListener:` / `removeListeners:` emitter selectors for a module
+// whose remap base is RCTEventEmitter; the Swift class supplies
+// `supportedEvents` / `startObserving` / `stopObserving`.
+@interface RCT_EXTERN_REMAP_MODULE(RNSARSession, RNSARSessionBridge, RCTEventEmitter)
 
 RCT_EXTERN_METHOD(isSupported:(RCTPromiseResolveBlock)resolver
                   rejecter:(RCTPromiseRejectBlock)rejecter)
@@ -34,6 +42,20 @@ RCT_EXTERN_METHOD(stop:(RCTPromiseResolveBlock)resolver
 RCT_EXTERN_METHOD(getState:(RCTPromiseResolveBlock)resolver
                   rejecter:(RCTPromiseRejectBlock)rejecter)
 
+RCT_EXTERN_METHOD(setSceneReconstructionEnabled:(nonnull NSNumber *)enabled
+                  resolver:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
+RCT_EXTERN_METHOD(setPlaneDetection:(nonnull NSString *)mode
+                  resolver:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
+// v0.18.0 — toggle the onArFrame LIGHT-metadata channel + its throttle.
+RCT_EXTERN_METHOD(setArFrameMetaEnabled:(nonnull NSNumber *)enabled
+                  intervalMs:(nonnull NSNumber *)intervalMs
+                  resolver:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
 RCT_EXTERN_METHOD(snapshotPoseLog:(RCTPromiseResolveBlock)resolver
                   rejecter:(RCTPromiseRejectBlock)rejecter)
 

package/ios/Sources/RNImageStitcher/ARSessionBridge.swift

@@ -17,15 +17,109 @@
 import Foundation
 import React
 
+// v0.18.0 — `RNSARSessionBridge` is now an `RCTEventEmitter` (was a
+// plain `NSObject`) so it can deliver the `onArFrame` LIGHT-metadata
+// channel as the JS `RNImageStitcherARFrame` device event.  The JS side
+// subscribes via `new NativeEventEmitter(NativeModules.RNSARSession)` —
+// the same module name this bridge is remapped to (see ARSessionBridge.m).
+//
+// Pattern mirrors `IncrementalStitcherBridge`: observe a NotificationCenter
+// post from the framework-free `RNSARSession` engine, then re-emit on the
+// main queue via `bridge.enqueueJSCall("RCTDeviceEventEmitter", "emit", …)`
+// rather than `RCTEventEmitter.sendEvent(…)`, because under RN bridgeless
+// interop `sendEvent` silently no-ops for some event-body shapes (see the
+// IncrementalStitcherBridge.handleStateUpdate docstring).
 @objc(RNSARSessionBridge)
-public final class RNSARSessionBridge: NSObject {
+public final class RNSARSessionBridge: RCTEventEmitter {
+
+    /// Whether at least one JS listener is attached to the AR-frame event.
+    /// RN's EventEmitter contract: don't emit when no listeners are
+    /// registered.  Toggled by `startObserving` / `stopObserving`.
+    private var hasListeners: Bool = false
+
+    private static let arFrameEvent = "RNImageStitcherARFrame"
+
+    public override init() {
+        super.init()
+        // Defensively de-dupe the observer: under RN bridgeless interop a
+        // bridge's init() can run twice on the same instance.  Remove any
+        // prior registration for this notification before adding, so the
+        // observer fires at most once per post regardless.
+        NotificationCenter.default.removeObserver(
+            self,
+            name: .retailensARFrameMeta,
+            object: nil
+        )
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(handleArFrameMeta(_:)),
+            name: .retailensARFrameMeta,
+            object: nil
+        )
+    }
 
-    @objc public static func requiresMainQueueSetup() -> Bool {
+    deinit {
+        NotificationCenter.default.removeObserver(self)
+    }
+
+    // MARK: - RCTEventEmitter protocol
+
+    public override static func requiresMainQueueSetup() -> Bool {
         // ARSession.start() must be called on the main thread —
         // ARKit needs to attach to the active CVDisplayLink.
         return true
     }
 
+    public override func supportedEvents() -> [String]! {
+        return [Self.arFrameEvent]
+    }
+
+    public override func startObserving() {
+        hasListeners = true
+    }
+
+    public override func stopObserving() {
+        hasListeners = false
+    }
+
+    /// Forward a posted `ARFrameMeta` dictionary to JS as the
+    /// `RNImageStitcherARFrame` device event.  Dropped when no JS listener
+    /// is attached.  Emits via `enqueueJSCall` on the main queue (see the
+    /// class docstring for why not `sendEvent`).
+    @objc private func handleArFrameMeta(_ notification: Notification) {
+        guard hasListeners else { return }
+        guard let userInfo = notification.userInfo else { return }
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self, let bridge = self.bridge else { return }
+            bridge.enqueueJSCall(
+                "RCTDeviceEventEmitter",
+                method: "emit",
+                args: [Self.arFrameEvent, userInfo],
+                completion: nil
+            )
+        }
+    }
+
+    // MARK: - Module methods
+
+    /// v0.18.0 — toggle the `onArFrame` LIGHT-metadata channel.  Called
+    /// from JS with `true` + the throttle interval (ms) when a host
+    /// supplies `<Camera onArFrame={...}>`, and `false` on
+    /// unmount / prop-removal.  Resolves with no value.
+    @objc(setArFrameMetaEnabled:intervalMs:resolver:rejecter:)
+    public func setArFrameMetaEnabled(
+        enabled: NSNumber,
+        intervalMs: NSNumber,
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        RNSARSession.shared.setArFrameMetaEnabled(
+            enabled.boolValue,
+            intervalMs: intervalMs.doubleValue
+        )
+        resolver(nil)
+    }
+
     @objc(isSupported:rejecter:)
     public func isSupported(
         resolver: @escaping RCTPromiseResolveBlock,
@@ -68,6 +162,47 @@ public final class RNSARSessionBridge: NSObject {
         ])
     }
 
+    /// Toggle ARKit scene reconstruction (LiDAR mesh / `ARMeshAnchor`s).
+    /// Driven by the <Camera> `enableMesh` prop; gates the
+    /// StitcherFrame `meshGeometry` extraction at the SESSION level
+    /// (the per-frame `__stitcherProxy.setExtractionConfig(...mesh)`
+    /// gates the marshaling — both must be on for a host to receive
+    /// mesh).  Resolves with no value.
+    ///
+    /// Hops to the main queue: `setSceneReconstructionEnabled` may call
+    /// `arSession.run(config)` to reconfigure a live session, and
+    /// ARKit session lifecycle must run on the main thread (same
+    /// constraint as `start`).
+    @objc(setSceneReconstructionEnabled:resolver:rejecter:)
+    public func setSceneReconstructionEnabled(
+        enabled: NSNumber,
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        let on = enabled.boolValue
+        DispatchQueue.main.async {
+            RNSARSession.shared.setSceneReconstructionEnabled(on)
+            resolver(nil)
+        }
+    }
+
+    /// Hops to the main queue: `setPlaneDetection` may call
+    /// `arSession.run(config)` to reconfigure a live session, and ARKit
+    /// session lifecycle must run on the main thread (same constraint as
+    /// `start` / `setSceneReconstructionEnabled`).
+    @objc(setPlaneDetection:resolver:rejecter:)
+    public func setPlaneDetection(
+        mode: NSString,
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        let m = mode as String
+        DispatchQueue.main.async {
+            RNSARSession.shared.setPlaneDetection(m)
+            resolver(nil)
+        }
+    }
+
     @objc(snapshotPoseLog:rejecter:)
     public func snapshotPoseLog(
         resolver: @escaping RCTPromiseResolveBlock,