react-native-image-stitcher 0.19.0 → 0.20.0

package/dist/camera/ARCameraView.js

@@ -68,6 +68,7 @@ exports.ARCameraView = void 0;
 const react_1 = __importStar(require("react"));
 const react_native_1 = require("react-native");
 const ensureStitcherProxyInstalled_1 = require("../stitching/ensureStitcherProxyInstalled");
+const arOverlayController_1 = require("./arOverlayController");
 // React Native looks up the component by its NATIVE name.
 //   iOS: comes from `ARCameraViewManager.m`'s
 //        `RCT_EXTERN_MODULE(RNSARCameraViewManager, RCTViewManager)`.
@@ -77,11 +78,21 @@ const ensureStitcherProxyInstalled_1 = require("../stitching/ensureStitcherProxy
 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, arFrameProcessor, enableDepth, enableAnchors, enableMesh, planeDetection, onArFrame, arFrameMetaInterval, onArPluginResult, }, ref) {
+exports.ARCameraView = (0, react_1.forwardRef)(function ARCameraView({ style, guidance, arFrameProcessor, enableDepth, enableAnchors, enableMesh, planeDetection, onArFrame, arFrameMetaInterval, onArPluginResult, overlays, }, 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);
+    // 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 = (0, react_1.useRef)(null);
+    if (overlayControllerRef.current == null) {
+        overlayControllerRef.current = (0, arOverlayController_1.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
@@ -205,7 +216,27 @@ exports.ARCameraView = (0, react_1.forwardRef)(function ARCameraView({ style, gu
             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.
+    (0, react_1.useEffect)(() => {
+        if (overlays == null) {
+            return;
+        }
+        overlayController.setOverlays(overlays);
+    }, [overlays, overlayController]);
     (0, react_1.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 = react_native_1.NativeModules.RNSARSession;
             if (!native?.takePhoto) {
@@ -249,7 +280,7 @@ exports.ARCameraView = (0, react_1.forwardRef)(function ARCameraView({ style, gu
                 callbacks.onRecordingError?.(err);
             }
         },
-    }), []);
+    }), [overlayController]);
     if (!NativeARCameraView
         || (react_native_1.Platform.OS !== 'ios' && react_native_1.Platform.OS !== 'android')) {
         // Web / unsupported platforms get a clear "not available here"

package/dist/camera/Camera.d.ts

@@ -43,6 +43,8 @@ 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, ARPluginResult } from '../stitching/ARFrameMeta';
+import type { AROverlay } from '../stitching/AROverlay';
+import type { AROverlayMethods } from './arOverlayController';
 import { type CaptureHeaderProps } from './CaptureHeader';
 import { type CapturePreviewAction } from './CapturePreview';
 import { type CaptureThumbnailItem } from './CaptureThumbnailStrip';
@@ -675,6 +677,25 @@ export interface CameraProps {
      * 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[];
     /**
      * Which device holds the non-AR panorama capture accepts.
      *
@@ -753,10 +774,33 @@ export interface CameraProps {
      */
     guidanceCopy?: Partial<GuidanceCopy>;
 }
+/**
+ * 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 {
+}
 /**
  * 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 declare function Camera(props: CameraProps): React.JSX.Element;
+export declare const Camera: React.ForwardRefExoticComponent<CameraProps & React.RefAttributes<CameraHandle>>;
 /**
  * v0.12.0 — JS edge corresponding to the physical home-indicator
  * side of the device.  This is where the shutter + controls anchor

package/dist/camera/Camera.js

@@ -74,8 +74,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports._cameraShouldUnmountForTests = exports._isSideEdgeForTests = exports._homeIndicatorEdgeForTests = exports.CameraError = void 0;
-exports.Camera = Camera;
+exports._cameraShouldUnmountForTests = exports._isSideEdgeForTests = exports._homeIndicatorEdgeForTests = exports.Camera = exports.CameraError = void 0;
 const react_1 = __importStar(require("react"));
 const react_native_1 = require("react-native");
 const react_native_safe_area_context_1 = require("react-native-safe-area-context");
@@ -308,9 +307,13 @@ function extractPanoramaOverrides(props) {
 // `<Image>` requires the scheme; iOS is lenient).
 /**
  * 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).
  */
-function Camera(props) {
-    const { defaultCaptureSource = 'non-ar', defaultLens = '1x', captureSources = 'both', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, onLensChange, onFramesDropped, onError, onCaptureAbandoned, flash: controlledFlash, onFlashChange, showFlashButton = true, headerTitle, onHeaderBack, headerBackLabel, headerGuidance, headerColors, thumbnails, thumbnailsMin, thumbnailsMax, onThumbnailPress, capturePreview, capturePreviewActions, onCapturePreviewClose, frameProcessor: hostFrameProcessor, arFrameProcessor, enableDepth, enableAnchors, enableMesh, planeDetection, onArFrame, arFrameMetaInterval, onArPluginResult, engine = 'batch-keyframe', 
+exports.Camera = (0, react_1.forwardRef)(function Camera(props, ref) {
+    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, onArPluginResult, overlays, 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
@@ -513,6 +516,21 @@ function Camera(props) {
     const incremental = (0, useIncrementalStitcher_1.useIncrementalStitcher)();
     const visionCameraRef = (0, react_1.useRef)(null);
     const arViewRef = (0, react_1.useRef)(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.
+    (0, react_1.useImperativeHandle)(ref, () => ({
+        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
@@ -1425,7 +1443,7 @@ function Camera(props) {
         // (V12.14.8 OOM fix).  The CaptureStatusOverlay renders the
         // "Stitching…" state on top, so no placeholder label is needed
         // in that case — only for the camera-switch transition.
-        react_1.default.createElement(react_native_1.View, { style: [react_native_1.StyleSheet.absoluteFill, styles.transitionPlaceholder] }, statusPhase === 'stitching' ? null : (react_1.default.createElement(react_native_1.Text, { style: styles.transitionLabel }, "Switching camera\u2026")))) : isAR ? (react_1.default.createElement(ARCameraView_1.ARCameraView, { ref: arViewRef, style: react_native_1.StyleSheet.absoluteFill, arFrameProcessor: arFrameProcessor, enableDepth: enableDepth, enableAnchors: enableAnchors, enableMesh: enableMesh, planeDetection: planeDetection, onArFrame: onArFrame, arFrameMetaInterval: arFrameMetaInterval, onArPluginResult: onArPluginResult })) : (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, onArPluginResult: onArPluginResult, overlays: overlays })) : (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
@@ -1590,7 +1608,7 @@ function Camera(props) {
                     setCropPending(null);
                 }
             } })));
-}
+});
 function noop() {
     /* no-op handler used when panorama mode is disabled */
 }

package/dist/camera/arOverlayController.d.ts

@@ -0,0 +1,52 @@
+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>;
+}
+/** The `RNSARSession` native-module method name overlays dispatch through. */
+export declare const AR_OVERLAY_SET_METHOD: "setOverlays";
+/**
+ * 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 declare const AR_OVERLAY_VIEW_COMMAND: "RNSARCameraViewOverlays";
+/**
+ * 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 declare function createAROverlayController(): AROverlayMethods & {
+    /** Current JS-set overlays in insertion order (used by tests / diffing). */
+    getOverlays: () => AROverlay[];
+};
+//# sourceMappingURL=arOverlayController.d.ts.map

package/dist/camera/arOverlayController.js

@@ -0,0 +1,132 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AR_OVERLAY_VIEW_COMMAND = exports.AR_OVERLAY_SET_METHOD = void 0;
+exports.createAROverlayController = createAROverlayController;
+/**
+ * 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`.
+ */
+const react_native_1 = require("react-native");
+/** The `RNSARSession` native-module method name overlays dispatch through. */
+exports.AR_OVERLAY_SET_METHOD = 'setOverlays';
+/**
+ * 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.
+ */
+exports.AR_OVERLAY_VIEW_COMMAND = 'RNSARCameraViewOverlays';
+/**
+ * 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).
+ */
+function createAROverlayController() {
+    // Insertion-ordered map: preserves the order overlays were added so the
+    // native render order is stable + predictable.
+    const overlaysById = new Map();
+    const flush = () => {
+        const native = react_native_1.NativeModules
+            .RNSARSession;
+        // 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?.catch?.(() => undefined);
+    };
+    return {
+        getOverlays: () => Array.from(overlaysById.values()),
+        setOverlays: (overlays) => {
+            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) => {
+            // 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, patch) => {
+            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) => {
+            if (overlaysById.delete(id)) {
+                flush();
+            }
+        },
+        clearOverlays: () => {
+            if (overlaysById.size > 0) {
+                overlaysById.clear();
+                flush();
+            }
+        },
+        raycast: async () => {
+            const native = react_native_1.NativeModules
+                .RNSARSession;
+            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;
+            }
+        },
+    };
+}
+//# sourceMappingURL=arOverlayController.js.map

package/dist/index.d.ts

@@ -20,7 +20,7 @@
  * adds RetaiLens-specific features on top.
  */
 export { Camera, CameraError } from './camera/Camera';
-export type { CameraProps, CameraCaptureResult, PanoramaCaptureResult, CameraErrorCode, CaptureSource, CaptureSourcesMode, CameraLens, StitchMode, Blender, SeamFinder, Warper, FramesDroppedInfo, } from './camera/Camera';
+export type { CameraProps, CameraHandle, CameraCaptureResult, PanoramaCaptureResult, CameraErrorCode, CaptureSource, CaptureSourcesMode, CameraLens, StitchMode, Blender, SeamFinder, Warper, FramesDroppedInfo, } from './camera/Camera';
 export type { CaptureWarning, CaptureWarningCode, CaptureWarningCopy, } from './camera/captureWarnings';
 export { DEFAULT_CAPTURE_WARNING_COPY } from './camera/captureWarnings';
 export { userFacingStitchError, RECOVERABLE_STITCH_GUIDANCE, RECOVERABLE_STITCH_CODES, } from './camera/cameraErrorMessages';
@@ -94,6 +94,9 @@ export { useKeyframeStream } from './stitching/useKeyframeStream';
 export type { CameraFrame, CameraFrameProcessor, ARAnchor, } from './stitching/CameraFrame';
 export type { ARFrameMeta } from './stitching/ARFrameMeta';
 export type { ARPluginResult } from './stitching/ARFrameMeta';
+export type { AROverlay } from './stitching/AROverlay';
+export type { AROverlayMethods } from './camera/arOverlayController';
+export { AR_OVERLAY_SET_METHOD, AR_OVERLAY_VIEW_COMMAND, } from './camera/arOverlayController';
 export { useFrameProcessorDriver } from './stitching/useFrameProcessorDriver';
 export type { UseFrameProcessorDriverOptions, FrameProcessorDriverHandle, } from './stitching/useFrameProcessorDriver';
 export { useStitcherWorklet } from './stitching/useStitcherWorklet';

package/dist/index.js

@@ -22,8 +22,8 @@
  * adds RetaiLens-specific features on top.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useFrameProcessorDriver = exports.useKeyframeStream = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = exports.cropQuad = exports.RectCropPreview = exports.LateralMotionModal = exports.CaptureFrameCounterOverlay = exports.CaptureCountdownOverlay = exports.PanHowToOverlay = exports.RotateToLandscapePrompt = exports.usePanMotion = exports.DEFAULT_GUIDANCE_COPY = exports.OrientationDriftModal = exports.useOrientationDrift = exports.useDeviceOrientation = exports.useVideoCapture = exports.useCapture = exports.ViewportCropOverlay = exports.panoramaSettingsToNativeConfig = exports.DEFAULT_FLOW_GATE_SETTINGS = exports.DEFAULT_PANORAMA_SETTINGS = exports.PanoramaSettingsModal = exports.PanoramaBandOverlay = exports.CaptureThumbnailStrip = exports.useStitchStatsToast = exports.CaptureStitchStatsToast = exports.CaptureOrientationPill = exports.CaptureKeyframePill = exports.CaptureMemoryPill = exports.CaptureDebugOverlay = exports.CaptureStatusOverlay = exports.CapturePreview = exports.CaptureControlsBar = exports.CaptureHeader = exports.CameraView = exports.ARCameraView = exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.RECOVERABLE_STITCH_CODES = exports.RECOVERABLE_STITCH_GUIDANCE = exports.userFacingStitchError = exports.DEFAULT_CAPTURE_WARNING_COPY = exports.CameraError = exports.Camera = void 0;
-exports.stitchVideo = exports.useStitcherWorklet = void 0;
+exports.AR_OVERLAY_SET_METHOD = exports.useKeyframeStream = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = exports.cropQuad = exports.RectCropPreview = exports.LateralMotionModal = exports.CaptureFrameCounterOverlay = exports.CaptureCountdownOverlay = exports.PanHowToOverlay = exports.RotateToLandscapePrompt = exports.usePanMotion = exports.DEFAULT_GUIDANCE_COPY = exports.OrientationDriftModal = exports.useOrientationDrift = exports.useDeviceOrientation = exports.useVideoCapture = exports.useCapture = exports.ViewportCropOverlay = exports.panoramaSettingsToNativeConfig = exports.DEFAULT_FLOW_GATE_SETTINGS = exports.DEFAULT_PANORAMA_SETTINGS = exports.PanoramaSettingsModal = exports.PanoramaBandOverlay = exports.CaptureThumbnailStrip = exports.useStitchStatsToast = exports.CaptureStitchStatsToast = exports.CaptureOrientationPill = exports.CaptureKeyframePill = exports.CaptureMemoryPill = exports.CaptureDebugOverlay = exports.CaptureStatusOverlay = exports.CapturePreview = exports.CaptureControlsBar = exports.CaptureHeader = exports.CameraView = exports.ARCameraView = exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.RECOVERABLE_STITCH_CODES = exports.RECOVERABLE_STITCH_GUIDANCE = exports.userFacingStitchError = exports.DEFAULT_CAPTURE_WARNING_COPY = exports.CameraError = exports.Camera = void 0;
+exports.stitchVideo = exports.useStitcherWorklet = exports.useFrameProcessorDriver = exports.AR_OVERLAY_VIEW_COMMAND = void 0;
 // ─────────────────────────────────────────────────────────────────────
 // Layer 1 — the high-level <Camera> component
 // ─────────────────────────────────────────────────────────────────────
@@ -189,6 +189,9 @@ Object.defineProperty(exports, "useIncrementalStitcher", { enumerable: true, get
 // keyframe, packet detection, server-side analysis, etc.).
 var useKeyframeStream_1 = require("./stitching/useKeyframeStream");
 Object.defineProperty(exports, "useKeyframeStream", { enumerable: true, get: function () { return useKeyframeStream_1.useKeyframeStream; } });
+var arOverlayController_1 = require("./camera/arOverlayController");
+Object.defineProperty(exports, "AR_OVERLAY_SET_METHOD", { enumerable: true, get: function () { return arOverlayController_1.AR_OVERLAY_SET_METHOD; } });
+Object.defineProperty(exports, "AR_OVERLAY_VIEW_COMMAND", { enumerable: true, get: function () { return arOverlayController_1.AR_OVERLAY_VIEW_COMMAND; } });
 // 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/dist/stitching/AROverlay.d.ts

@@ -0,0 +1,97 @@
+/**
+ * v0.20.0 — the AR OVERLAY / ANNOTATION renderer's data model.
+ *
+ * An {@link AROverlay} describes a 2D shape (a billboard marker/box or a
+ * world-anchored quad) that the native overlay layer draws ON TOP of the AR
+ * camera preview (`RNSARCameraView`).  Each overlay is anchored to WORLD
+ * positions and REPROJECTED to screen on EVERY AR frame from the current
+ * camera pose + intrinsics — so it tracks the scene at display rate with no
+ * 3D-engine dependency.
+ *
+ * ## Two ways to anchor an overlay
+ *
+ *   1. **A single world point** (`worldPosition`) — drawn as a billboard
+ *      marker/box facing the camera, sized by `sizeMeters` (default a small
+ *      marker).  Use this for a pin on a detected plane anchor, a label on a
+ *      point of interest, etc.
+ *   2. **Explicit world corners** (`worldQuad`, 3–4 points) — drawn as the
+ *      outline/box connecting the projected corners.  Use this for a detected
+ *      quad (a shelf face, a packet, a door) whose real-world shape you
+ *      already know.
+ *
+ * Provide ONE of the two anchor forms.  If both are present `worldQuad` wins
+ * (it's the more specific description); the native renderers read `worldQuad`
+ * first and fall back to `worldPosition` + `sizeMeters`.
+ *
+ * ## Rendering / reprojection (native)
+ *
+ * The native side reprojects each overlay's world point(s) to screen with the
+ * AR framework's BUILT-IN, correct projection — iOS
+ * `ARFrame.camera.projectPoint(_:orientation:viewportSize:)`, Android
+ * `viewMatrix · projectionMatrix` → clip → NDC → screen.  Points behind the
+ * camera or off-screen are hidden.  The layer redraws every frame so the
+ * outline/box + label stay pinned to the world as the camera moves.
+ *
+ * ## Where overlays come from
+ *
+ * Overlays reach the native renderer through two INDEPENDENT, merged sets:
+ *
+ *   - **JS-set** — the declarative `overlays` prop or the imperative ref
+ *     methods (`setOverlays` / `addOverlay` / `updateOverlay` / `removeOverlay`
+ *     / `clearOverlays`) on `<Camera>` and `<ARCameraView>`.
+ *   - **Native-plugin-set** — a registered AR plugin places overlays directly
+ *     via the 0.19 registry (`RNISARPluginRegistry.setOverlays(...)` on iOS /
+ *     `RNSARPluginRegistry.setOverlays(...)` on Android), with zero JS latency.
+ *
+ * The native renderer draws the UNION of both sets; the plugin set is
+ * namespaced so a JS `setOverlays(...)` never clobbers plugin overlays.
+ */
+export interface AROverlay {
+    /**
+     * Stable identifier.  The declarative `overlays` prop diffs the incoming
+     * array against the current set BY `id` (add / update / remove); the
+     * imperative `updateOverlay` / `removeOverlay` methods key off it too.  Must
+     * be unique within a set.
+     */
+    id: string;
+    /**
+     * Anchor form 1 — a single world point in METRES (world space `[x, y, z]`).
+     * Drawn as a billboard marker/box of `sizeMeters` extent facing the camera.
+     * Ignored when `worldQuad` is provided.
+     */
+    worldPosition?: [number, number, number];
+    /**
+     * Box extent in METRES `[width, height]` at `worldPosition`.  Only meaningful
+     * with `worldPosition`.  Defaults to a small marker on the native side when
+     * omitted.
+     */
+    sizeMeters?: [number, number];
+    /**
+     * Anchor form 2 — 3 or 4 explicit world corners in METRES (e.g. a detected
+     * quad).  Each corner is `[x, y, z]` in world space.  Drawn as the
+     * outline/box connecting the projected corners.  Takes precedence over
+     * `worldPosition` + `sizeMeters` when both are present.
+     */
+    worldQuad?: Array<[number, number, number]>;
+    /**
+     * Draw style.  Default `'outline'` (stroked edges).  `'box'` is a filled /
+     * boxed marker.  Both render in 2D this release.
+     */
+    shape?: 'box' | 'outline';
+    /** Optional text label drawn at the overlay's anchor point. */
+    label?: string;
+    /**
+     * Stroke / fill colour as a hex string (e.g. `'#00E5FF'`).  Defaults to a
+     * theme colour on the native side when omitted.
+     */
+    color?: string;
+    /**
+     * Render mode.  Default `'2d'` — a flat shape reprojected to screen.
+     * `'3d'` is SCAFFOLD ONLY this release: the data-model field exists and the
+     * native renderers leave a marked hook for a future SceneKit (iOS) / Android
+     * 3D renderer, but v1 treats `'3d'` as `'2d'` (with a one-time native log
+     * warning).  Document-only forward compatibility.
+     */
+    mode?: '2d' | '3d';
+}
+//# sourceMappingURL=AROverlay.d.ts.map

package/dist/stitching/AROverlay.js

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

package/ios/Sources/RNImageStitcher/ARCameraViewManager.m

@@ -21,13 +21,20 @@
 
 @interface RCT_EXTERN_MODULE(RNSARCameraViewManager, RCTViewManager)
 
-// No exposed view props for Phase 4.4 — the view's behaviour is
-// fully driven by mount/unmount lifecycle (the AR session
-// starts/stops automatically when the view enters/leaves the
-// window hierarchy).  Future phases may add props for:
-//   - tracking-state HUD visibility
-//   - exposure / focus controls
-//   - debug overlay (feature points, planes)
-// Each of these will land here as RCT_EXPORT_VIEW_PROPERTY lines.
+// v0.20.0 — declarative AR overlay set.  React-state-driven array of
+// overlay dictionaries (the JS `AROverlay[]` shape).  RN sets this via KVC
+// on the VIEW (`RNSARCameraView.overlays`); the view's `@objc` setter
+// forwards the array to the JS namespace of `RNISAROverlayStore.shared`,
+// which the per-frame draw view reprojects + strokes.  (We forward through
+// the view rather than store per-view state because the overlay set is
+// global to the single AR session.)
+//
+// The IMPERATIVE overlay API (setOverlays / addOverlay / updateOverlay /
+// removeOverlay / clearOverlays on the ref) is NOT a view command — per
+// the shared contract (src/camera/arOverlayController.ts) it dispatches
+// through the `RNSARSession.setOverlays(_:)` native MODULE method (see
+// ARSessionBridge.{swift,m}), matching every other AR setting.  Only the
+// declarative prop lives on the view manager.
+RCT_EXPORT_VIEW_PROPERTY(overlays, NSArray)
 
 @end

package/ios/Sources/RNImageStitcher/ARCameraViewManager.swift

@@ -36,5 +36,27 @@ public final class RNSARCameraViewManager: RCTViewManager {
     public override class func requiresMainQueueSetup() -> Bool {
         return true
     }
+
+    // MARK: - v0.20.0 — AR overlays
+    //
+    // OVERLAY WIRE PATH (shared cross-platform contract, see
+    // `src/camera/arOverlayController.ts`): the JS imperative methods
+    // (setOverlays / addOverlay / updateOverlay / removeOverlay /
+    // clearOverlays) AND the declarative `overlays` prop both resolve, in
+    // JS, to the FULL current overlay array and dispatch it through the
+    // `RNSARSession.setOverlays(_:)` native MODULE method (see
+    // `ARSessionBridge.swift`).  Native replaces its JS-overlay namespace
+    // in `RNISAROverlayStore` wholesale and merges with the SEPARATE
+    // plugin-overlay namespace (`RNISARPluginRegistry.setOverlays`) — the
+    // draw view renders the UNION every ARFrame.
+    //
+    // The module method is the chosen mechanism (matching every other AR
+    // setting: setPlaneDetection / setArFrameMetaEnabled /
+    // setSceneReconstructionEnabled) because there is exactly ONE
+    // `RNSARCameraView` mounted (ARKit can't share the camera), so there's
+    // nothing to key by view tag.  We ALSO honor the declarative
+    // `overlays` view prop here on the view (`RNSARCameraView.overlays`
+    // KVC setter) so a host can drive overlays purely declaratively
+    // without the module — both land in the same store namespace.
 }
 #endif

package/ios/Sources/RNImageStitcher/ARSessionBridge.m

@@ -56,6 +56,20 @@ RCT_EXTERN_METHOD(setArFrameMetaEnabled:(nonnull NSNumber *)enabled
                   resolver:(RCTPromiseResolveBlock)resolver
                   rejecter:(RCTPromiseRejectBlock)rejecter)
 
+// v0.20.0 — AR overlay renderer.  Replace the entire JS-set overlay
+// collection (the shared arOverlayController sends the full array every
+// mutation).  Native merges with the namespaced plugin-overlay set + the
+// RNSARCameraView draw view reprojects them each ARFrame.
+RCT_EXTERN_METHOD(setOverlays:(nonnull NSArray *)overlays
+                  resolver:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
+// v0.20.0 — raycast from the crosshair (screen centre) to the first real
+// surface hit → { worldPosition: [x,y,z] } or null.  Used to place an
+// overlay ON the aimed surface (then anchor it), vs a guessed distance ahead.
+RCT_EXTERN_METHOD(raycast:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
 RCT_EXTERN_METHOD(snapshotPoseLog:(RCTPromiseResolveBlock)resolver
                   rejecter:(RCTPromiseRejectBlock)rejecter)