react-native-image-stitcher 0.16.2 → 0.18.0

package/dist/camera/ARCameraView.d.ts

@@ -30,6 +30,8 @@
  */
 import React from 'react';
 import { type ViewStyle } from 'react-native';
+import type { CameraFrameProcessor } from '../stitching/CameraFrame';
+import type { ARFrameMeta } from '../stitching/ARFrameMeta';
 export interface ARCameraViewProps {
     /** Layout style, typically `StyleSheet.absoluteFill` or `flex: 1`. */
     style?: ViewStyle;
@@ -39,6 +41,81 @@ 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;
 }
 /**
  * Imperative handle exposed via the ref — shape mirrors the subset

package/dist/camera/ARCameraView.js

@@ -67,6 +67,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ARCameraView = void 0;
 const react_1 = __importStar(require("react"));
 const react_native_1 = require("react-native");
+const ensureStitcherProxyInstalled_1 = require("../stitching/ensureStitcherProxyInstalled");
 // React Native looks up the component by its NATIVE name.
 //   iOS: comes from `ARCameraViewManager.m`'s
 //        `RCT_EXTERN_MODULE(RNSARCameraViewManager, RCTViewManager)`.
@@ -76,11 +77,99 @@ const react_native_1 = require("react-native");
 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 }, ref) {
+exports.ARCameraView = (0, react_1.forwardRef)(function ARCameraView({ style, guidance, arFrameProcessor, enableDepth, enableAnchors, enableMesh, planeDetection, onArFrame, arFrameMetaInterval, }, ref) {
     // Held across the start→stop lifecycle so stopRecording's
     // resolved VideoFile can be delivered via the same callback
     // pair vision-camera uses.
     const recordingCallbacksRef = (0, react_1.useRef)(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.
+    (0, react_1.useEffect)(() => {
+        if (arFrameProcessor == null) {
+            return undefined;
+        }
+        if (!(0, ensureStitcherProxyInstalled_1.ensureStitcherProxyInstalled)()) {
+            return undefined;
+        }
+        const proxy = globalThis.__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.
+    (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]);
     (0, react_1.useImperativeHandle)(ref, () => ({
         takePhoto: async (options = {}) => {
             const native = react_native_1.NativeModules.RNSARSession;

package/dist/camera/Camera.d.ts

@@ -41,6 +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 { 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';
@@ -526,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';
      *     // ...
      *   }, []);
@@ -551,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
@@ -597,6 +599,63 @@ export interface CameraProps {
      * CHANGELOG.)
      */
     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;
     /**
      * 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, 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 })) : (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/camera/CaptureMemoryPill.d.ts

@@ -16,9 +16,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/dist/camera/CaptureMemoryPill.js

@@ -18,9 +18,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/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/ensureStitcherProxyInstalled.d.ts

@@ -0,0 +1,8 @@
+export declare function ensureStitcherProxyInstalled(): boolean;
+/**
+ * Test-only — reset module-internal state.  Used by jest to allow
+ * multiple test cases to re-trigger the install path independently.
+ * NOT exported from `src/index.ts`.
+ */
+export declare function _resetStitcherProxyInstallStateForTests(): void;
+//# sourceMappingURL=ensureStitcherProxyInstalled.d.ts.map