react-native-image-stitcher 0.16.2 → 0.18.0

package/src/camera/ARCameraView.tsx

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

package/src/camera/Camera.tsx

@@ -66,6 +66,8 @@ import type {
 } from 'react-native-vision-camera';
 
 import { useARSession } from '../ar/useARSession';
+import type { CameraFrameProcessor } from '../stitching/CameraFrame';
+import type { ARFrameMeta } from '../stitching/ARFrameMeta';
 import { ARCameraView, type ARCameraViewHandle } from './ARCameraView';
 import { CameraShutter } from './CameraShutter';
 import { CameraView } from './CameraView';
@@ -679,11 +681,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';
    *     // ...
    *   }, []);
@@ -704,12 +706,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
@@ -751,6 +753,67 @@ export interface CameraProps {
    */
   frameProcessor?: ReadonlyFrameProcessor | DrawableFrameProcessor;
 
+  /**
+   * AR-mode host worklet, invoked once per ARKit / ARCore frame
+   * ALONGSIDE the lib's first-party stitching (composition, not
+   * replacement).  Receives a `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?: 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;
+
   // ── Panorama GUIDANCE (feature/pano-ux-guidance) ──────────────────
   /**
    * Which device holds the non-AR panorama capture accepts.
@@ -1157,6 +1220,13 @@ export function Camera(props: CameraProps): React.JSX.Element {
     capturePreviewActions,
     onCapturePreviewClose,
     frameProcessor: hostFrameProcessor,
+    arFrameProcessor,
+    enableDepth,
+    enableAnchors,
+    enableMesh,
+    planeDetection,
+    onArFrame,
+    arFrameMetaInterval,
     engine = 'batch-keyframe',
     // ── Panorama GUIDANCE (feature/pano-ux-guidance) ──────────────
     panMode = 'vertical',
@@ -2420,6 +2490,13 @@ export function Camera(props: CameraProps): React.JSX.Element {
         <ARCameraView
           ref={arViewRef}
           style={StyleSheet.absoluteFill}
+          arFrameProcessor={arFrameProcessor}
+          enableDepth={enableDepth}
+          enableAnchors={enableAnchors}
+          enableMesh={enableMesh}
+          planeDetection={planeDetection}
+          onArFrame={onArFrame}
+          arFrameMetaInterval={arFrameMetaInterval}
         />
       ) : (
         <CameraView

package/src/camera/CaptureMemoryPill.tsx

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

package/src/index.ts

@@ -259,10 +259,14 @@ export { useKeyframeStream } from './stitching/useKeyframeStream';
 // v0.8.0 — unified frame contract for the worklet processor.  Same
 // JS-visible shape regardless of capture mode (AR vs non-AR).
 export type {
-  StitcherFrame,
-  StitcherFrameProcessor,
+  CameraFrame,
+  CameraFrameProcessor,
   ARAnchor,
-} from './stitching/StitcherFrame';
+} from './stitching/CameraFrame';
+// v0.18.0 — LIGHT per-frame AR metadata delivered via the `onArFrame`
+// callback (main-thread, worklet-free).  See the type's docstring for why
+// it bypasses the worklet path.
+export type { ARFrameMeta } from './stitching/ARFrameMeta';
 // NOTE: the host-worklet / frame-stream hooks `useFrameProcessor`,
 // `useThrottledFrameProcessor` and `useFrameStream` (v0.8–v0.9) were
 // archived in the batch-keyframe cleanup — they drove the third-party

package/src/stitching/ARFrameMeta.ts

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * 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;
+}

package/src/stitching/{StitcherFrame.ts → CameraFrame.ts}

@@ -4,7 +4,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
@@ -18,10 +18,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).
  *
@@ -38,10 +38,10 @@
  * a JPEG-encode frame-processor plugin).  Returning a reference and
  * reading it later will read into freed memory.
  */
-export interface StitcherFrame {
+export interface CameraFrame {
   // ── vision-camera-shaped fields (structural compat) ─────────────
   // Worklets written against a vc `Frame` work unchanged against a
-  // `StitcherFrame` (the fields below are a strict subset of vc
+  // `CameraFrame` (the fields below are a strict subset of vc
   // Frame's JS-visible surface).
 
   /** Pixel width of the camera image. */
@@ -167,6 +167,28 @@ 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;
+  };
 }
 
 /**
@@ -177,21 +199,67 @@ 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;
+export type CameraFrameProcessor = (frame: CameraFrame) => void;