react-native-image-stitcher 0.18.0 → 0.20.0

package/src/camera/ARCameraView.tsx

@@ -44,7 +44,12 @@ import {
 
 import { ensureStitcherProxyInstalled } from '../stitching/ensureStitcherProxyInstalled';
 import type { CameraFrameProcessor } from '../stitching/CameraFrame';
-import type { ARFrameMeta } from '../stitching/ARFrameMeta';
+import type { ARFrameMeta, ARPluginResult } from '../stitching/ARFrameMeta';
+import type { AROverlay } from '../stitching/AROverlay';
+import {
+  createAROverlayController,
+  type AROverlayMethods,
+} from './arOverlayController';
 
 
 // React Native looks up the component by its NATIVE name.
@@ -145,6 +150,54 @@ export interface ARCameraViewProps {
    * (≈ 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;
+
+  /**
+   * v0.20.0 — AR OVERLAY / ANNOTATION renderer.  A declarative array of 2D
+   * shapes the native overlay layer draws ON TOP of the AR camera preview,
+   * each anchored to WORLD positions and REPROJECTED to screen on every AR
+   * frame from the current camera pose + intrinsics (smooth, display-rate
+   * tracking; no 3D engine).
+   *
+   * State-driven: pass a React-state array and update it as your world points
+   * change.  The set is diffed against the current overlays BY `id` (add /
+   * update / remove), so re-passing the same ids is cheap.  Each render pushes
+   * the resolved array to native via `RNSARSession.setOverlays`.
+   *
+   * For zero-render-latency / fire-and-forget mutations use the imperative ref
+   * methods instead ({@link ARCameraViewHandle.setOverlays} etc.) — both paths
+   * funnel through the same native channel and stay consistent.  JS-set
+   * overlays are merged on the native side with any overlays a registered AR
+   * plugin placed directly (`RNISARPluginRegistry.setOverlays` /
+   * `RNSARPluginRegistry.setOverlays`); the two sets are namespaced so neither
+   * clobbers the other.
+   *
+   * See {@link AROverlay} for the shape (single world point + size, or explicit
+   * world quad; `outline` / `box`; optional label + colour; `mode:'3d'` is a
+   * documented scaffold this release and renders as `'2d'`).
+   */
+  overlays?: AROverlay[];
 }
 
 
@@ -158,8 +211,13 @@ export interface ARCameraViewProps {
  * Note we do NOT exhaustively mirror vision-camera's API surface —
  * only the methods the panorama capture flow uses today.  As the
  * SDK grows AR-aware features, methods are added here.
+ *
+ * v0.20.0 — also exposes the imperative AR-overlay methods
+ * ({@link AROverlayMethods}: `setOverlays` / `addOverlay` / `updateOverlay` /
+ * `removeOverlay` / `clearOverlays`) so a host can drive overlays without a
+ * render (the declarative `overlays` prop is the React-state alternative).
  */
-export interface ARCameraViewHandle {
+export interface ARCameraViewHandle extends AROverlayMethods {
   /**
    * Capture the latest ARFrame as a JPEG.  Resolves with a
    * vision-camera-compatible PhotoFile (`{ path, width, height,
@@ -237,6 +295,8 @@ export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
       planeDetection,
       onArFrame,
       arFrameMetaInterval,
+      onArPluginResult,
+      overlays,
     },
     ref,
   ): React.JSX.Element {
@@ -245,6 +305,19 @@ export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
     // pair vision-camera uses.
     const recordingCallbacksRef = useRef<RecordingCallbacks | null>(null);
 
+    // v0.20.0 — AR overlay controller (shared logic with <Camera>).  One
+    // instance per mount holds the JS-set overlay collection (keyed by id) and
+    // pushes the full array to native on every mutation.  Both the declarative
+    // `overlays` prop (effect below) and the imperative ref methods drive it,
+    // so the two APIs can never diverge.
+    const overlayControllerRef = useRef<
+      ReturnType<typeof createAROverlayController> | null
+    >(null);
+    if (overlayControllerRef.current == null) {
+      overlayControllerRef.current = createAROverlayController();
+    }
+    const overlayController = overlayControllerRef.current;
+
     // 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
@@ -362,7 +435,70 @@ export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
       };
     }, [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]);
+
+    // v0.20.0 — declarative `overlays` prop → native.  Each render pushes the
+    // resolved array through the controller (which replaces the JS-set
+    // collection wholesale and dispatches to `RNSARSession.setOverlays`).  The
+    // controller dedups identical native dispatches at the wire level is NOT
+    // attempted here — React only re-runs this when `overlays` identity
+    // changes, and native overlay set is cheap (a handful of shapes).  When the
+    // prop is omitted we DON'T touch the controller, so a host driving overlays
+    // purely imperatively (via the ref) isn't clobbered by an undefined prop.
+    useEffect(() => {
+      if (overlays == null) {
+        return;
+      }
+      overlayController.setOverlays(overlays);
+    }, [overlays, overlayController]);
+
     useImperativeHandle(ref, () => ({
+      setOverlays: overlayController.setOverlays,
+      addOverlay: overlayController.addOverlay,
+      updateOverlay: overlayController.updateOverlay,
+      removeOverlay: overlayController.removeOverlay,
+      clearOverlays: overlayController.clearOverlays,
+      raycast: overlayController.raycast,
       takePhoto: async (options = {}) => {
         const native: any =
           (NativeModules as Record<string, unknown>).RNSARSession;
@@ -414,7 +550,7 @@ export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
           callbacks.onRecordingError?.(err as Error);
         }
       },
-    }), []);
+    }), [overlayController]);
 
     if (!NativeARCameraView
         || (Platform.OS !== 'ios' && Platform.OS !== 'android')) {

package/src/camera/Camera.tsx

@@ -41,8 +41,10 @@
  */
 
 import React, {
+  forwardRef,
   useCallback,
   useEffect,
+  useImperativeHandle,
   useMemo,
   useRef,
   useState,
@@ -67,7 +69,9 @@ import type {
 
 import { useARSession } from '../ar/useARSession';
 import type { CameraFrameProcessor } from '../stitching/CameraFrame';
-import type { ARFrameMeta } from '../stitching/ARFrameMeta';
+import type { ARFrameMeta, ARPluginResult } from '../stitching/ARFrameMeta';
+import type { AROverlay } from '../stitching/AROverlay';
+import type { AROverlayMethods } from './arOverlayController';
 import { ARCameraView, type ARCameraViewHandle } from './ARCameraView';
 import { CameraShutter } from './CameraShutter';
 import { CameraView } from './CameraView';
@@ -814,6 +818,46 @@ export interface CameraProps {
    */
   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;
+
+  /**
+   * v0.20.0 — AR OVERLAY / ANNOTATION renderer.  A declarative array of 2D
+   * shapes drawn ON TOP of the AR camera preview, each anchored to WORLD
+   * positions and REPROJECTED to screen on every AR frame from the current
+   * camera pose + intrinsics (smooth display-rate tracking, no 3D engine).
+   * Only meaningful in AR capture (`captureSource === 'ar'`); `<Camera>`
+   * threads this straight through to the underlying `<ARCameraView>`.
+   *
+   * State-driven: pass a React-state array and update it as your world points
+   * change (e.g. from {@link CameraProps.onArFrame} plane anchors).  The set is
+   * diffed against the current overlays BY `id`.  For zero-render-latency
+   * mutations use the imperative ref methods on the `<Camera>` handle instead
+   * ({@link CameraHandle}: `setOverlays` / `addOverlay` / `updateOverlay` /
+   * `removeOverlay` / `clearOverlays`) — both paths funnel through the same
+   * native channel.  JS-set overlays merge on the native side with overlays a
+   * registered AR plugin placed directly (namespaced so neither clobbers the
+   * other).  See {@link AROverlay} for the shape.
+   */
+  overlays?: AROverlay[];
+
   // ── Panorama GUIDANCE (feature/pano-ux-guidance) ──────────────────
   /**
    * Which device holds the non-AR panorama capture accepts.
@@ -902,6 +946,26 @@ export interface CameraProps {
 }
 
 
+/**
+ * v0.20.0 — imperative handle exposed via the `<Camera>` ref.
+ *
+ * Currently scoped to the AR-overlay methods ({@link AROverlayMethods}:
+ * `setOverlays` / `addOverlay` / `updateOverlay` / `removeOverlay` /
+ * `clearOverlays`), which forward to the underlying `<ARCameraView>`'s overlay
+ * channel when AR mode is mounted.  They are no-ops while the camera is in
+ * non-AR mode (no `<ARCameraView>` is mounted, and overlays only render over
+ * the AR preview) — use the declarative {@link CameraProps.overlays} prop for
+ * a set that survives AR↔non-AR transitions, since it re-applies automatically
+ * whenever `<ARCameraView>` (re)mounts.
+ *
+ * The shape is identical to {@link ARCameraViewHandle}'s overlay subset so a
+ * host can use either component with the same overlay code.  Photo / panorama
+ * capture remain driven by the built-in shutter (no imperative capture methods
+ * on this handle — see the component docstring's scope note).
+ */
+export interface CameraHandle extends AROverlayMethods {}
+
+
 // ─── Sub-components ─────────────────────────────────────────────────
 
 /**
@@ -1187,8 +1251,15 @@ function extractPanoramaOverrides(props: CameraProps): PanoramaPropOverrides {
 
 /**
  * The public `<Camera>` component.
+ *
+ * v0.20.0 — now a `forwardRef`.  The ref exposes {@link CameraHandle} (the AR
+ * overlay methods); existing callers that don't pass a ref are unaffected
+ * (`forwardRef` makes the ref optional).
  */
-export function Camera(props: CameraProps): React.JSX.Element {
+export const Camera = forwardRef<CameraHandle, CameraProps>(function Camera(
+  props: CameraProps,
+  ref,
+): React.JSX.Element {
   const {
     defaultCaptureSource = 'non-ar',
     defaultLens = '1x',
@@ -1227,6 +1298,8 @@ export function Camera(props: CameraProps): React.JSX.Element {
     planeDetection,
     onArFrame,
     arFrameMetaInterval,
+    onArPluginResult,
+    overlays,
     engine = 'batch-keyframe',
     // ── Panorama GUIDANCE (feature/pano-ux-guidance) ──────────────
     panMode = 'vertical',
@@ -1490,6 +1563,22 @@ export function Camera(props: CameraProps): React.JSX.Element {
   const visionCameraRef = useRef<VisionCamera | null>(null);
   const arViewRef = useRef<ARCameraViewHandle | null>(null);
 
+  // v0.20.0 — AR overlay imperative handle.  `<Camera>` itself renders no
+  // overlay layer; the overlay methods forward to the mounted
+  // `<ARCameraView>`'s handle (which owns the controller + native dispatch).
+  // No-op when AR mode isn't mounted (`arViewRef.current === null`), matching
+  // the CameraHandle docstring — the declarative `overlays` prop is the path
+  // that survives AR↔non-AR transitions.  The `overlays` prop is also threaded
+  // straight to `<ARCameraView>` below, so a host can use either API.
+  useImperativeHandle(ref, (): CameraHandle => ({
+    setOverlays: (o) => arViewRef.current?.setOverlays(o),
+    addOverlay: (o) => arViewRef.current?.addOverlay(o),
+    updateOverlay: (id, patch) => arViewRef.current?.updateOverlay(id, patch),
+    removeOverlay: (id) => arViewRef.current?.removeOverlay(id),
+    clearOverlays: () => arViewRef.current?.clearOverlays(),
+    raycast: () => arViewRef.current?.raycast() ?? Promise.resolve(null),
+  }), []);
+
   // Effect that does the async transition work whenever the settled
   // refs disagree with the current isAR/lens.  Order matters:
   //   1. Set the cameraTransitioning state so the gate stays closed
@@ -2497,6 +2586,8 @@ export function Camera(props: CameraProps): React.JSX.Element {
           planeDetection={planeDetection}
           onArFrame={onArFrame}
           arFrameMetaInterval={arFrameMetaInterval}
+          onArPluginResult={onArPluginResult}
+          overlays={overlays}
         />
       ) : (
         <CameraView
@@ -2993,7 +3084,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
       />
     </View>
   );
-}
+});
 
 
 function noop(): void {

package/src/camera/arOverlayController.ts

@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * v0.20.0 — shared JS→native plumbing for the AR overlay renderer.
+ *
+ * `<ARCameraView>` and `<Camera>` expose an IDENTICAL imperative overlay API
+ * (`setOverlays` / `addOverlay` / `updateOverlay` / `removeOverlay` /
+ * `clearOverlays`) plus a declarative `overlays` prop.  Rather than duplicate
+ * the diff + native-dispatch logic in each component, both build their handle
+ * from {@link createAROverlayController} — DRY, single source of truth for the
+ * wire format and the merge-by-id semantics.
+ *
+ * ## Native mechanism (agreed cross-platform contract)
+ *
+ * Every AR-session setting in this SDK already flows through the
+ * `RNSARSession` native-module singleton (`setPlaneDetection`,
+ * `setArFrameMetaEnabled`, `setSceneReconstructionEnabled`) because
+ * `RNSARSession.shared` drives the single mounted `RNSARCameraView`.  Overlays
+ * follow the same pattern: a single `setOverlays(overlays)` method on
+ * `RNSARSession` carries the FULL current JS-set overlay array each time it
+ * changes.  Native replaces its JS-set overlay collection wholesale (the merge
+ * with the namespaced native-plugin set happens on the native side) and the
+ * overlay layer redraws every AR frame.
+ *
+ * The declarative `overlays` prop and the imperative methods both ultimately
+ * call this same `setOverlays` with the resolved array, so the two APIs are
+ * interchangeable and can't diverge.
+ *
+ * Why a module method (not a UIManager view command)?  It matches every other
+ * AR setting in this codebase and there is only ever ONE `RNSARCameraView`
+ * mounted (ARKit/ARCore can't share the camera), so there's nothing to key by
+ * view tag.  The equivalent UIManager view-command name, for native sides that
+ * prefer per-view dispatch, is documented as `RNSARCameraViewOverlays`.
+ */
+
+import { NativeModules } from 'react-native';
+
+import type { AROverlay } from '../stitching/AROverlay';
+
+/**
+ * The imperative overlay methods exposed on both `<ARCameraView>` and
+ * `<Camera>` refs.  Identical shape on both so a host can swap components
+ * without rewriting overlay code.
+ */
+export interface AROverlayMethods {
+  /** Replace the entire JS-set overlay collection. */
+  setOverlays: (overlays: AROverlay[]) => void;
+  /** Add one overlay (replaces any existing overlay with the same `id`). */
+  addOverlay: (overlay: AROverlay) => void;
+  /**
+   * Shallow-merge a patch into the overlay with `id`.  No-op if no overlay
+   * with that `id` is currently set.
+   */
+  updateOverlay: (id: string, patch: Partial<AROverlay>) => void;
+  /** Remove the overlay with `id` (no-op if absent). */
+  removeOverlay: (id: string) => void;
+  /** Remove all JS-set overlays. */
+  clearOverlays: () => void;
+  /**
+   * Raycast from the screen centre (the crosshair) to the first real-world
+   * surface and resolve its world position `[x, y, z]` in metres (ARKit/ARCore
+   * world frame), or `null` when nothing is hit (e.g. a featureless wall before
+   * any plane is detected).  Use it to place an overlay ON the aimed surface at
+   * the real distance — pass the result as a `worldPosition` to
+   * {@link setOverlays} / {@link addOverlay} — instead of guessing a distance.
+   * Resolves `null` (never throws) when the native module / method is absent.
+   */
+  raycast: () => Promise<[number, number, number] | null>;
+}
+
+interface RNSARSessionOverlayModule {
+  // On iOS the native `setOverlays` is a Promise method (resolver/rejecter
+  // RN-injected); on Android it's `void`.  We call it fire-and-forget but
+  // type it as possibly-thenable so the defensive `.catch` below compiles.
+  setOverlays?: (overlays: AROverlay[]) => void | Promise<unknown>;
+  // Raycast resolves `{ worldPosition: [x,y,z] }` on a hit, or `null`.
+  raycast?: () => Promise<{ worldPosition?: number[] } | null>;
+}
+
+/** The `RNSARSession` native-module method name overlays dispatch through. */
+export const AR_OVERLAY_SET_METHOD = 'setOverlays' as const;
+
+/**
+ * The agreed UIManager view-command name for native sides that drive overlays
+ * via per-view command dispatch instead of the module method.  The JS layer
+ * dispatches through the module method (there's only one AR view), but the
+ * name is pinned here so the native side can match if it chooses commands.
+ */
+export const AR_OVERLAY_VIEW_COMMAND = 'RNSARCameraViewOverlays' as const;
+
+/**
+ * Build an overlay controller backed by an in-memory ordered set keyed by
+ * `id`.  Every mutating call resolves the new full array and pushes it to
+ * native via `RNSARSession.setOverlays`.  The controller is the single source
+ * of truth for BOTH the imperative ref methods and the declarative `overlays`
+ * prop (the prop's effect calls `setOverlays` with the prop value).
+ */
+export function createAROverlayController(): AROverlayMethods & {
+  /** Current JS-set overlays in insertion order (used by tests / diffing). */
+  getOverlays: () => AROverlay[];
+} {
+  // Insertion-ordered map: preserves the order overlays were added so the
+  // native render order is stable + predictable.
+  const overlaysById = new Map<string, AROverlay>();
+
+  const flush = (): void => {
+    const native = (NativeModules as Record<string, unknown>)
+      .RNSARSession as RNSARSessionOverlayModule | undefined;
+    // Native module / method unavailable (web, or a native build predating the
+    // overlay channel): no-op, no crash — mirrors the other AR setters.
+    const ret = native?.setOverlays?.(Array.from(overlaysById.values()));
+    // iOS returns a Promise (the native method is Promise-typed); swallow any
+    // rejection so a transient native error never surfaces as an unhandled
+    // rejection.  Android returns void — the optional chain skips the catch.
+    (ret as Promise<unknown> | undefined)?.catch?.(() => undefined);
+  };
+
+  return {
+    getOverlays: () => Array.from(overlaysById.values()),
+
+    setOverlays: (overlays: AROverlay[]) => {
+      overlaysById.clear();
+      for (const o of overlays) {
+        // Last-writer-wins on duplicate ids in the incoming array.
+        overlaysById.set(o.id, o);
+      }
+      flush();
+    },
+
+    addOverlay: (overlay: AROverlay) => {
+      // Re-set to move an existing id to the end? No — preserve original slot
+      // by deleting first only when absent.  Map#set keeps the existing slot
+      // when the key already exists, so a plain set is the right "replace in
+      // place" behaviour.
+      overlaysById.set(overlay.id, overlay);
+      flush();
+    },
+
+    updateOverlay: (id: string, patch: Partial<AROverlay>) => {
+      const existing = overlaysById.get(id);
+      if (existing == null) {
+        return;
+      }
+      // Shallow-merge; `id` is preserved from the existing overlay regardless
+      // of what the patch carries (the map key must stay consistent).
+      overlaysById.set(id, { ...existing, ...patch, id });
+      flush();
+    },
+
+    removeOverlay: (id: string) => {
+      if (overlaysById.delete(id)) {
+        flush();
+      }
+    },
+
+    clearOverlays: () => {
+      if (overlaysById.size > 0) {
+        overlaysById.clear();
+        flush();
+      }
+    },
+
+    raycast: async (): Promise<[number, number, number] | null> => {
+      const native = (NativeModules as Record<string, unknown>)
+        .RNSARSession as RNSARSessionOverlayModule | undefined;
+      const fn = native?.raycast;
+      // Native module / method unavailable (web, or a native build predating
+      // the raycast channel): resolve null — the caller falls back.
+      if (typeof fn !== 'function') {
+        return null;
+      }
+      try {
+        const res = await fn();
+        const wp = res?.worldPosition;
+        if (Array.isArray(wp) && wp.length >= 3) {
+          return [Number(wp[0]), Number(wp[1]), Number(wp[2])];
+        }
+        return null;
+      } catch {
+        return null;
+      }
+    },
+  };
+}

package/src/index.ts

@@ -27,6 +27,7 @@
 export { Camera, CameraError } from './camera/Camera';
 export type {
   CameraProps,
+  CameraHandle,
   CameraCaptureResult,
   PanoramaCaptureResult,
   CameraErrorCode,
@@ -265,8 +266,27 @@ export type {
 } 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.
+// 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';
+// v0.20.0 — AR OVERLAY / ANNOTATION renderer data model.  A 2D shape anchored
+// to a world point (or world quad) and reprojected to screen every AR frame.
+// Drive it via the declarative `overlays` prop or the imperative ref methods
+// (`setOverlays` / `addOverlay` / `updateOverlay` / `removeOverlay` /
+// `clearOverlays`) on both `<Camera>` and `<ARCameraView>`.
+export type { AROverlay } from './stitching/AROverlay';
+// The shared imperative-overlay method signatures (the `<Camera>` /
+// `<ARCameraView>` ref handles extend this).  Plus the agreed native channel
+// names, for hosts / native plugins matching the wire contract.
+export type { AROverlayMethods } from './camera/arOverlayController';
+export {
+  AR_OVERLAY_SET_METHOD,
+  AR_OVERLAY_VIEW_COMMAND,
+} from './camera/arOverlayController';
 // 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

@@ -104,4 +104,54 @@ export interface ARFrameMeta {
     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;
 }