react-native-image-stitcher 0.17.0 → 0.19.0

package/src/camera/ARCameraView.tsx

@@ -32,6 +32,7 @@
 
 import React, { forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
 import {
+  NativeEventEmitter,
   NativeModules,
   Platform,
   StyleSheet,
@@ -42,7 +43,8 @@ import {
 } from 'react-native';
 
 import { ensureStitcherProxyInstalled } from '../stitching/ensureStitcherProxyInstalled';
-import type { StitcherFrameProcessor } from '../stitching/StitcherFrame';
+import type { CameraFrameProcessor } from '../stitching/CameraFrame';
+import type { ARFrameMeta, ARPluginResult } from '../stitching/ARFrameMeta';
 
 
 // React Native looks up the component by its NATIVE name.
@@ -69,7 +71,7 @@ export interface ARCameraViewProps {
   /**
    * Optional host worklet invoked once per AR frame, ALONGSIDE the
    * lib's first-party stitching (composition, not replacement).  The
-   * worklet receives a `StitcherFrame` enriched with AR metadata —
+   * worklet receives a `CameraFrame` enriched with AR metadata —
    * `source: 'ar'`, world-space `pose` (rotation + translation),
    * `arTrackingState`, and (when supported) `arDepth` / `arAnchors`.
    *
@@ -84,7 +86,87 @@ export interface ARCameraViewProps {
    * different runtimes with different frame shapes, hence the separate
    * prop.
    */
-  arFrameProcessor?: StitcherFrameProcessor;
+  arFrameProcessor?: CameraFrameProcessor;
+  /**
+   * Opt in to per-frame AR depth extraction (`CameraFrame.arDepth`).
+   * Default `false` — depth is the costliest field (a per-frame buffer
+   * copy), so it stays off until a worklet needs it.
+   */
+  enableDepth?: boolean;
+  /**
+   * Opt in to per-frame AR anchor extraction (`CameraFrame.arAnchors` —
+   * detected planes / augmented images).  Default `false`.
+   */
+  enableAnchors?: boolean;
+  /**
+   * Opt in to scene-reconstruction mesh anchors (`type: 'mesh'` entries
+   * in `arAnchors`, carrying `meshGeometry`).  Default `false`.  iOS
+   * enables ARKit `sceneReconstruction` (LiDAR devices); Android
+   * reconstructs a rough mesh from the depth map.  Expensive — only on
+   * when needed.  Implies depth on Android.
+   */
+  enableMesh?: boolean;
+  /**
+   * Which plane orientations to surface in `arAnchors` (requires
+   * `enableAnchors`).  Default `'vertical'` — the orientation the
+   * plane-projected stitch path has always used, so existing callers
+   * see no change.
+   *
+   *   - `'vertical'`   — walls / doors / fixtures (the default)
+   *   - `'horizontal'` — floors / tables / seats
+   *   - `'both'`       — surface every detected plane
+   *
+   * Platform notes: iOS changes ARKit `planeDetection` to match (a
+   * live session reconfigure).  Android always detects both planes
+   * (ARCore needs horizontal planes to bootstrap tracking) and simply
+   * FILTERS which orientations reach `arAnchors`, so the JS-observable
+   * set is identical on both platforms.
+   */
+  planeDetection?: 'vertical' | 'horizontal' | 'both';
+
+  /**
+   * v0.18.0 — LIGHT per-frame AR metadata callback, invoked on the JS
+   * MAIN thread (NOT a worklet).  When provided, the native AR session
+   * builds an {@link ARFrameMeta} per frame and emits it as a device
+   * event; this component subscribes and calls the handler.  Worklet-free
+   * — this is the recommended way to read AR pose / tracking / anchor /
+   * intrinsics / depth-dims / mesh-counts data (the `arFrameProcessor`
+   * worklet can only safely surface a shared value; see `ARFrameMeta`).
+   *
+   * Costly fields are gated: `depth` only when `enableDepth`, `mesh` only
+   * when `enableMesh`, `anchors` only when `enableAnchors`;
+   * `intrinsics` / `pose` / `trackingState` are always present.  Emission
+   * is throttled to {@link arFrameMetaInterval} ms.
+   */
+  onArFrame?: (meta: ARFrameMeta) => void;
+
+  /**
+   * v0.18.0 — throttle interval (ms) for {@link onArFrame}.  Default `100`
+   * (≈ 10 Hz).  No effect unless `onArFrame` is provided.
+   */
+  arFrameMetaInterval?: number;
+
+  /**
+   * v0.19.0 — ASYNCHRONOUS AR-plugin result callback, invoked on the JS MAIN
+   * thread (NOT a worklet).  Part of the AR plugin framework: host-registered
+   * native plugins (see `RNISARPluginRegistry` / `RNSARPluginRegistry`) can
+   * offload heavy per-frame work to their own queue and later push a result
+   * via `registry.emit(name, result)`.  The SDK routes that to JS as a
+   * `RNImageStitcherARPluginResult` device event; when this prop is provided,
+   * this component subscribes and invokes the handler with
+   * `{ plugin, result }`.
+   *
+   * SYNCHRONOUS plugin results (computed inline on the AR thread) instead ride
+   * the throttled {@link onArFrame} event on {@link ARFrameMeta.plugins} —
+   * read them there.  This callback is ONLY for the out-of-band async channel.
+   *
+   * The subscription is independent of {@link onArFrame}: a host can read
+   * sync results via `onArFrame` and async results via `onArPluginResult`,
+   * either, or both.  Wiring mirrors `onArFrame` exactly (latest handler held
+   * in a ref so the subscription effect depends only on whether a handler is
+   * present; cleanup on unmount / when the handler is removed).
+   */
+  onArPluginResult?: (e: ARPluginResult) => void;
 }
 
 
@@ -167,7 +249,18 @@ type RecordingCallbacks = {
 
 export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
   function ARCameraView(
-    { style, guidance, arFrameProcessor },
+    {
+      style,
+      guidance,
+      arFrameProcessor,
+      enableDepth,
+      enableAnchors,
+      enableMesh,
+      planeDetection,
+      onArFrame,
+      arFrameMetaInterval,
+      onArPluginResult,
+    },
     ref,
   ): React.JSX.Element {
     // Held across the start→stop lifecycle so stopRecording's
@@ -189,7 +282,7 @@ export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
       }
       const proxy = (globalThis as {
         __stitcherProxy?: {
-          install(fn: StitcherFrameProcessor): string;
+          install(fn: CameraFrameProcessor): string;
           uninstall(id: string): void;
         };
       }).__stitcherProxy;
@@ -202,6 +295,138 @@ export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
       };
     }, [arFrameProcessor]);
 
+    // Push the AR-metadata extraction config to native — gates the
+    // costly per-frame depth / anchor / mesh work (all off by default).
+    // Routed through `__stitcherProxy.setExtractionConfig`, read by the
+    // platform AR extraction.  iOS ADDITIONALLY toggles ARKit
+    // `sceneReconstruction` for mesh (a session-config change, not a
+    // per-frame gate); Android reconstructs mesh from the depth map and
+    // needs no session change.
+    useEffect(() => {
+      const depth = enableDepth === true;
+      const anchors = enableAnchors === true;
+      const mesh = enableMesh === true;
+      if (ensureStitcherProxyInstalled()) {
+        (globalThis as {
+          __stitcherProxy?: {
+            setExtractionConfig?(d: boolean, a: boolean, m: boolean): void;
+          };
+        }).__stitcherProxy?.setExtractionConfig?.(depth, anchors, mesh);
+      }
+      if (Platform.OS === 'ios') {
+        const session = (NativeModules as Record<string, unknown>)
+          .RNSARSession as
+          | { setSceneReconstructionEnabled?(on: boolean): void }
+          | undefined;
+        session?.setSceneReconstructionEnabled?.(mesh);
+      }
+    }, [enableDepth, enableAnchors, enableMesh]);
+
+    // Push the plane-detection mode to native.  Unlike the extraction
+    // config above this is a SESSION setting, so it routes through the
+    // RNSARSession native module on BOTH platforms (iOS reconfigures
+    // ARKit `planeDetection`; Android stores an emission filter — see
+    // the prop docs).  Defaults to `'vertical'` to preserve the
+    // plane-projected stitch path's long-standing behaviour.
+    useEffect(() => {
+      const mode = planeDetection ?? 'vertical';
+      const session = (NativeModules as Record<string, unknown>)
+        .RNSARSession as
+        | { setPlaneDetection?(mode: string): void }
+        | undefined;
+      session?.setPlaneDetection?.(mode);
+    }, [planeDetection]);
+
+    // v0.18.0 — onArFrame device-event wiring (worklet-free, main thread).
+    //
+    // The latest `onArFrame` is held in a ref so the subscription effect
+    // depends only on whether a handler is present + the interval — NOT on
+    // the handler's identity (which typically changes every render).  This
+    // avoids tearing down + re-establishing the native event subscription
+    // (and the costly `setArFrameMetaEnabled(true)` extraction toggle) on
+    // every parent re-render.
+    const onArFrameRef = useRef<((meta: ARFrameMeta) => void) | undefined>(
+      onArFrame,
+    );
+    useEffect(() => {
+      onArFrameRef.current = onArFrame;
+    }, [onArFrame]);
+
+    const arFrameEnabled = onArFrame != null;
+    useEffect(() => {
+      if (!arFrameEnabled) {
+        return undefined;
+      }
+      const session = (NativeModules as Record<string, unknown>)
+        .RNSARSession as
+        | {
+            setArFrameMetaEnabled?(enabled: boolean, intervalMs: number): void;
+          }
+        | undefined;
+      if (session?.setArFrameMetaEnabled == null) {
+        // Native module / method unavailable (e.g. web, or a native build
+        // predating the event channel): no-op, no crash.
+        return undefined;
+      }
+      const intervalMs = arFrameMetaInterval ?? 100;
+      session.setArFrameMetaEnabled(true, intervalMs);
+      const emitter = new NativeEventEmitter(
+        NativeModules.RNSARSession as never,
+      );
+      const sub = emitter.addListener(
+        'RNImageStitcherARFrame',
+        (meta: ARFrameMeta) => {
+          onArFrameRef.current?.(meta);
+        },
+      );
+      return () => {
+        sub.remove();
+        session.setArFrameMetaEnabled?.(false, intervalMs);
+      };
+    }, [arFrameEnabled, arFrameMetaInterval]);
+
+    // v0.19.0 — onArPluginResult device-event wiring (worklet-free, main
+    // thread).  Mirrors the onArFrame subscription above: the latest handler
+    // is held in a ref so the subscription effect depends only on WHETHER a
+    // handler is present, not its (per-render-changing) identity — so the
+    // native event subscription isn't torn down + re-established every render.
+    //
+    // This is a PURELY-JS subscription: unlike onArFrame there's no native
+    // "enable" toggle to flip.  Native emits `RNImageStitcherARPluginResult`
+    // whenever a registered plugin calls `registry.emit(...)`; the registry is
+    // empty unless the host registered plugins, so an app with no plugins
+    // never sees an event even if this prop is wired.
+    const onArPluginResultRef = useRef<
+      ((e: ARPluginResult) => void) | undefined
+    >(onArPluginResult);
+    useEffect(() => {
+      onArPluginResultRef.current = onArPluginResult;
+    }, [onArPluginResult]);
+
+    const arPluginResultEnabled = onArPluginResult != null;
+    useEffect(() => {
+      if (!arPluginResultEnabled) {
+        return undefined;
+      }
+      const native = (NativeModules as Record<string, unknown>)
+        .RNSARSession;
+      if (native == null) {
+        // Native module unavailable (e.g. web, or a native build predating
+        // the plugin event channel): no-op, no crash.
+        return undefined;
+      }
+      const emitter = new NativeEventEmitter(native as never);
+      const sub = emitter.addListener(
+        'RNImageStitcherARPluginResult',
+        (e: ARPluginResult) => {
+          onArPluginResultRef.current?.(e);
+        },
+      );
+      return () => {
+        sub.remove();
+      };
+    }, [arPluginResultEnabled]);
+
     useImperativeHandle(ref, () => ({
       takePhoto: async (options = {}) => {
         const native: any =

package/src/camera/Camera.tsx

@@ -66,7 +66,8 @@ import type {
 } from 'react-native-vision-camera';
 
 import { useARSession } from '../ar/useARSession';
-import type { StitcherFrameProcessor } from '../stitching/StitcherFrame';
+import type { CameraFrameProcessor } from '../stitching/CameraFrame';
+import type { ARFrameMeta, ARPluginResult } from '../stitching/ARFrameMeta';
 import { ARCameraView, type ARCameraViewHandle } from './ARCameraView';
 import { CameraShutter } from './CameraShutter';
 import { CameraView } from './CameraView';
@@ -680,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';
    *     // ...
    *   }, []);
@@ -705,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
@@ -755,14 +756,83 @@ 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;
+
+  /**
+   * v0.19.0 — ASYNCHRONOUS AR-plugin result callback (the AR plugin
+   * framework), invoked on the JS MAIN thread (NOT a worklet).  Only fires in
+   * AR capture (`captureSource === 'ar'`).  Host-registered native plugins
+   * (see `RNISARPluginRegistry` / `RNSARPluginRegistry`) that offload heavy
+   * per-frame work to their own queue push results via
+   * `registry.emit(name, result)`; `<Camera>` threads this handler to
+   * `<ARCameraView>`, which subscribes to the `RNImageStitcherARPluginResult`
+   * device event and invokes it with `{ plugin, result }`.
+   *
+   * SYNCHRONOUS plugin results (computed inline on the AR thread) instead ride
+   * the throttled {@link onArFrame} event on {@link ARFrameMeta.plugins}.
+   * Use `onArFrame` for the in-band sync channel and `onArPluginResult` for
+   * the out-of-band async channel — a host can wire either or both.
+   *
+   * The SDK ships ONLY the generic plugin framework; there are no built-in
+   * plugins, so this never fires unless the host registers native plugins.
+   */
+  onArPluginResult?: (e: ARPluginResult) => void;
 
   // ── Panorama GUIDANCE (feature/pano-ux-guidance) ──────────────────
   /**
@@ -1171,6 +1241,13 @@ export function Camera(props: CameraProps): React.JSX.Element {
     onCapturePreviewClose,
     frameProcessor: hostFrameProcessor,
     arFrameProcessor,
+    enableDepth,
+    enableAnchors,
+    enableMesh,
+    planeDetection,
+    onArFrame,
+    arFrameMetaInterval,
+    onArPluginResult,
     engine = 'batch-keyframe',
     // ── Panorama GUIDANCE (feature/pano-ux-guidance) ──────────────
     panMode = 'vertical',
@@ -2435,6 +2512,13 @@ export function Camera(props: CameraProps): React.JSX.Element {
           ref={arViewRef}
           style={StyleSheet.absoluteFill}
           arFrameProcessor={arFrameProcessor}
+          enableDepth={enableDepth}
+          enableAnchors={enableAnchors}
+          enableMesh={enableMesh}
+          planeDetection={planeDetection}
+          onArFrame={onArFrame}
+          arFrameMetaInterval={arFrameMetaInterval}
+          onArPluginResult={onArPluginResult}
         />
       ) : (
         <CameraView

package/src/index.ts

@@ -259,10 +259,19 @@ 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.  v0.19.0 adds `plugins` (sync results from
+// host-registered AR plugins ride this same throttled event).
+export type { ARFrameMeta } from './stitching/ARFrameMeta';
+// v0.19.0 — the AR plugin framework's ASYNC result type, delivered via the
+// `onArPluginResult` callback (a plugin's out-of-band `registry.emit(...)`
+// result).  The SDK ships only the generic framework — no built-in plugins.
+export type { ARPluginResult } 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,157 @@
+// 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;
+
+  /**
+   * v0.19.0 — SYNCHRONOUS results from host-registered AR frame plugins
+   * (the AR plugin framework).  Keyed by each plugin's `name()`; the value
+   * is the light JSON result the plugin's `process(ctx)` returned on the AR
+   * thread (`nil`/`null`-returning plugins are omitted).  Only present when
+   * the native plugin registry is non-empty AND at least one plugin returned
+   * a sync result for this frame; otherwise omitted entirely (zero-plugin
+   * apps pay nothing — native skips building the context).
+   *
+   * The SDK ships ONLY the generic framework — there are no built-in
+   * plugins.  Hosts register native plugins via `RNISARPluginRegistry`
+   * (iOS) / `RNSARPluginRegistry` (Android) at startup; each plugin is
+   * called once per AR frame while the registry is non-empty.  Result
+   * values are `unknown` because each plugin defines its own shape — cast
+   * after reading the entry you care about (e.g.
+   * `meta.plugins?.brightness as number`).
+   *
+   * ## Sync vs async results
+   *
+   * This field carries only the LIGHT, in-band SYNC results (computed fast
+   * enough to ride the throttled `onArFrame` event).  Plugins that offload
+   * heavy work to their own queue deliver results out-of-band via
+   * `registry.emit(name, result)`, which surfaces through the separate
+   * `onArPluginResult` callback (the `RNImageStitcherARPluginResult`
+   * event) — NOT here.
+   */
+  plugins?: { [name: string]: unknown };
+}
+
+
+/**
+ * v0.19.0 — an ASYNCHRONOUS result from a host-registered AR frame plugin,
+ * delivered via the `onArPluginResult` callback.
+ *
+ * Unlike the in-band SYNC results carried on {@link ARFrameMeta.plugins}
+ * (which ride the throttled `onArFrame` event), a plugin produces an async
+ * result by offloading heavy work to its own queue and later calling
+ * `registry.emit(name, result)` on the native side.  The SDK routes that to
+ * JS as a `RNImageStitcherARPluginResult` device event; `<ARCameraView>`
+ * subscribes and invokes `onArPluginResult` on the JS MAIN thread.
+ *
+ * `result` is `unknown` because each plugin defines its own result shape —
+ * branch on `plugin` (the emitting plugin's `name()`) and cast accordingly.
+ */
+export interface ARPluginResult {
+  /** The `name()` of the plugin that emitted this result. */
+  plugin: string;
+  /** The plugin-defined result payload (cast after branching on `plugin`). */
+  result: unknown;
+}