react-native-image-stitcher 0.1.0

package/dist/stitching/useIncrementalJSDriver.js

@@ -0,0 +1,199 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * useIncrementalJSDriver — vision-camera + gyro frame driver for
+ * the incremental panorama engine, used in non-AR captures on both
+ * iOS and Android.
+ *
+ * History: previously called `useIncrementalAndroidDriver` because
+ * it was Android-only.  As of 2026-05-17 (Issue #2), the native
+ * `processFrameAtPath` entry point exists on both platforms and the
+ * hook drives non-AR on iOS too; renamed 2026-05-19 to reflect
+ * that.
+ *
+ * Why this exists
+ *   In AR captures the engine consumes frames from the ARSession
+ *   stream natively (60 Hz pose + image delivery, zero JS
+ *   involvement once started).  In NON-AR captures there is no AR
+ *   session — vision-camera owns the camera — so the engine needs
+ *   another frame source.  This hook fills the gap:
+ *
+ *     - vision-camera keeps the camera viewport
+ *     - `takeSnapshot()` runs at ~250 ms intervals during press-hold
+ *     - `react-native-sensors` gyroscope is integrated to estimate
+ *       cumulative yaw/pitch (drives the FoV-overlap gate)
+ *     - Each snapshot path + integrated pose is fed to
+ *       `IncrementalStitcher.processFrameAtPath()`
+ *
+ * Trade-off vs the AR path
+ *   Gyro integration drifts ~1–2° per minute.  Acceptable for the
+ *   typical 5–15 s shelf pan; not great for ambitious 360° captures.
+ *   Snapshot rate is ~4 Hz (vs 60 Hz in AR mode).  Pose drives
+ *   frame-selection only — the actual image alignment is feature-
+ *   matched + RANSAC-fit, so quality of the panorama itself isn't
+ *   bounded by gyro accuracy.
+ *
+ * Lifecycle
+ *   `start({ cameraRef })` enables the loop; `stop()` tears down.
+ *   Both should be called by the host's hold-start / hold-complete
+ *   handlers.  Safe to call on either platform; the hook only
+ *   activates inside the start/stop block.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useIncrementalJSDriver = useIncrementalJSDriver;
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+const react_native_sensors_1 = require("react-native-sensors");
+function getNativeIncremental() {
+    const m = react_native_1.NativeModules['IncrementalStitcher'];
+    if (!m || typeof m !== 'object')
+        return null;
+    return m;
+}
+function useIncrementalJSDriver(options = {}) {
+    const { snapshotIntervalMs = 250, gyroIntervalMs = 33, fovHorizDegrees = 65, fovVertDegrees = 50, } = options;
+    const intervalRef = (0, react_1.useRef)(null);
+    const gyroSubRef = (0, react_1.useRef)(null);
+    const cameraRef = (0, react_1.useRef)(null);
+    // Integrated pose accumulators, in radians.  Reset on each
+    // start() call.  Y-axis = horizontal pan (yaw), X-axis = vertical
+    // pan (pitch).  Sign convention matches ARKit: counter-clockwise
+    // from above is positive yaw.
+    const yawRef = (0, react_1.useRef)(0);
+    const pitchRef = (0, react_1.useRef)(0);
+    const lastGyroAtRef = (0, react_1.useRef)(null);
+    // Single in-flight guard so we don't pile up overlapping snapshot
+    // promises on slow devices — if last snapshot hasn't finished
+    // when the next interval fires, skip.
+    const snapshotInFlightRef = (0, react_1.useRef)(false);
+    // Module-level "is the driver active right now" — exposed to the
+    // host because the hook itself doesn't trigger re-renders.
+    const isRunningRef = (0, react_1.useRef)(false);
+    const stop = (0, react_1.useCallback)(() => {
+        if (intervalRef.current) {
+            clearInterval(intervalRef.current);
+            intervalRef.current = null;
+        }
+        if (gyroSubRef.current) {
+            gyroSubRef.current.unsubscribe();
+            gyroSubRef.current = null;
+        }
+        cameraRef.current = null;
+        isRunningRef.current = false;
+    }, []);
+    const start = (0, react_1.useCallback)((cameraRefArg) => {
+        // 2026-05-17 (Issue #2) — removed the Android-only platform
+        // guard.  iOS now also exposes `processFrameAtPath` (see the
+        // Swift bridge), so the same driver feeds both platforms in
+        // non-AR mode.
+        if (isRunningRef.current)
+            return;
+        const native = getNativeIncremental();
+        if (!native)
+            return;
+        cameraRef.current = cameraRefArg;
+        yawRef.current = 0;
+        pitchRef.current = 0;
+        lastGyroAtRef.current = null;
+        snapshotInFlightRef.current = false;
+        isRunningRef.current = true;
+        // Gyro integration.  Each sample carries angular velocity in
+        // rad/s; multiply by elapsed time to accumulate angular
+        // displacement.  Note: the gyro axes are device-local; we use
+        // y for yaw and x for pitch on a device held in portrait.
+        // Landscape would swap, but the FoV-overlap gate is dominant-
+        // axis based on the .mm side, so the convention matters less
+        // than consistency.
+        (0, react_native_sensors_1.setUpdateIntervalForType)(react_native_sensors_1.SensorTypes.gyroscope, gyroIntervalMs);
+        gyroSubRef.current = react_native_sensors_1.gyroscope.subscribe({
+            next: ({ x, y }) => {
+                const now = Date.now();
+                if (lastGyroAtRef.current === null) {
+                    lastGyroAtRef.current = now;
+                    return;
+                }
+                const dt = (now - lastGyroAtRef.current) / 1000.0;
+                lastGyroAtRef.current = now;
+                yawRef.current += y * dt;
+                pitchRef.current += x * dt;
+            },
+            error: (err) => {
+                // eslint-disable-next-line no-console
+                console.warn('[useIncrementalJSDriver] gyro error', err);
+            },
+        });
+        // Snapshot loop.
+        const tick = async () => {
+            if (snapshotInFlightRef.current)
+                return;
+            const cam = cameraRef.current?.current;
+            if (!cam)
+                return;
+            snapshotInFlightRef.current = true;
+            try {
+                const snap = await cam.takeSnapshot({ quality: 70 });
+                if (!snap?.path)
+                    return;
+                // Synthesise a quaternion from integrated yaw + pitch.
+                // Yaw rotates about world Y (gravity), pitch about world X
+                // (perpendicular to gravity in the device's frame).
+                // Combined as q = q_yaw · q_pitch.
+                const halfYaw = yawRef.current / 2;
+                const halfPitch = pitchRef.current / 2;
+                const cy_ = Math.cos(halfYaw);
+                const sy_ = Math.sin(halfYaw);
+                const cp = Math.cos(halfPitch);
+                const sp = Math.sin(halfPitch);
+                // q_yaw   = (0, sy, 0, cy)
+                // q_pitch = (sp, 0, 0, cp)
+                // q = q_yaw * q_pitch:
+                const qx = cy_ * sp;
+                const qy = sy_ * cp;
+                const qz = -sy_ * sp;
+                const qw = cy_ * cp;
+                // Vision-camera v4 doesn't expose camera intrinsics on
+                // Android, so we estimate fx/fy from the snapshot's pixel
+                // dimensions + assumed FoV.  cx/cy at image centre.  This
+                // is approximate; the proper Android live path is the
+                // ARCameraView, where ARCore gives us the real intrinsics.
+                const w = snap.width ?? 1920;
+                const h = snap.height ?? 1440;
+                const fx = w / (2.0 * Math.tan(((fovHorizDegrees * Math.PI) / 180) / 2));
+                const fy = h / (2.0 * Math.tan(((fovVertDegrees * Math.PI) / 180) / 2));
+                const cx = w / 2;
+                const cy = h / 2;
+                await native.processFrameAtPath({
+                    path: snap.path,
+                    yaw: yawRef.current,
+                    pitch: pitchRef.current,
+                    fovHorizDegrees,
+                    fovVertDegrees,
+                    trackingPoor: false,
+                    qx, qy, qz, qw,
+                    fx, fy, cx, cy,
+                    imageWidth: w, imageHeight: h,
+                });
+            }
+            catch (err) {
+                // Swallow per-frame errors so the loop keeps running.
+                // eslint-disable-next-line no-console
+                console.warn('[useIncrementalJSDriver] processFrame failed', err);
+            }
+            finally {
+                snapshotInFlightRef.current = false;
+            }
+        };
+        // Kick off an immediate first frame so the engine doesn't sit
+        // idle for the first interval period.
+        tick();
+        intervalRef.current = setInterval(tick, snapshotIntervalMs);
+    }, [snapshotIntervalMs, gyroIntervalMs, fovHorizDegrees, fovVertDegrees]);
+    return {
+        start,
+        stop,
+        get isRunning() {
+            return isRunningRef.current;
+        },
+    };
+}
+//# sourceMappingURL=useIncrementalJSDriver.js.map

package/dist/stitching/useIncrementalStitcher.d.ts

@@ -0,0 +1,58 @@
+/**
+ * useIncrementalStitcher — React hook driving the live panorama
+ * engine.
+ *
+ * Lifecycle:
+ *   1. Host calls `useARSession().start()` to put the AR session in
+ *      tracking mode.  (Works for AR-supported devices only — non-AR
+ *      fallback comes in a later phase.)
+ *   2. Host calls `start()` from this hook.  The native engine
+ *      registers itself as the AR session's frame consumer.
+ *   3. Native emits a state event for every ARFrame the engine
+ *      processes (~60 Hz, mostly trivially-skipped).  The hook
+ *      mirrors this into React state so a `<IncrementalStitcherView>`
+ *      or any other consumer can render the live panorama + UX hints.
+ *   4. Host calls `finalize(outputPath)` when the user releases the
+ *      shutter; resolves with the final panorama path + stats.
+ *   5. Host calls `cancel()` if the user dismisses the capture.
+ */
+import { type IncrementalState, type IncrementalStartOptions, type IncrementalFinalizeResult } from './incremental';
+export type IncrementalHint = 'slow-down' | 'scene-uniform' | 'alignment-lost' | 'tracking-poor' | null;
+export interface UseIncrementalStitcherReturn {
+    /** Whether the native engine is registered.  False = no fallback wiring. */
+    isAvailable: boolean;
+    /** True between successful `start()` and `finalize()`/`cancel()`. */
+    isRunning: boolean;
+    /** Latest state pushed by the native engine, or null pre-start. */
+    state: IncrementalState | null;
+    /**
+     * Convenience: which UX hint to show, derived from the latest
+     * state.outcome.  null when nothing should be shown (silent
+     * accepts, skips inside the overlap window).
+     */
+    hint: IncrementalHint;
+    /**
+     * Convenience: 'high' | 'medium' | null based on the last accept.
+     * Drives confidence-ring rendering in the live preview.
+     */
+    confidenceLevel: 'high' | 'medium' | null;
+    /** Begin a new capture.  Throws if the AR session isn't running. */
+    start: (options?: IncrementalStartOptions) => Promise<void>;
+    /**
+     * End the capture and write the final panorama.  When `outputPath`
+     * is omitted or empty, the native side picks a path under the
+     * app's tmp directory and returns it in the result.
+     *
+     * `captureOrientation` (optional) — pass the user's CURRENT
+     * device orientation at finalize time.  The engine prefers this
+     * value over the start-time snapshot for the bake-rotation pass,
+     * so cross-orientation captures (user opened screen in portrait,
+     * captured in landscape) bake correctly.  Omit to keep the legacy
+     * behaviour (start-time orientation).
+     */
+    finalize: (outputPath?: string, quality?: number, captureOrientation?: string) => Promise<IncrementalFinalizeResult>;
+    /** Abort the capture without producing output. */
+    cancel: () => Promise<void>;
+}
+export declare function useIncrementalStitcher(): UseIncrementalStitcherReturn;
+//# sourceMappingURL=useIncrementalStitcher.d.ts.map

package/dist/stitching/useIncrementalStitcher.js

@@ -0,0 +1,172 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * useIncrementalStitcher — React hook driving the live panorama
+ * engine.
+ *
+ * Lifecycle:
+ *   1. Host calls `useARSession().start()` to put the AR session in
+ *      tracking mode.  (Works for AR-supported devices only — non-AR
+ *      fallback comes in a later phase.)
+ *   2. Host calls `start()` from this hook.  The native engine
+ *      registers itself as the AR session's frame consumer.
+ *   3. Native emits a state event for every ARFrame the engine
+ *      processes (~60 Hz, mostly trivially-skipped).  The hook
+ *      mirrors this into React state so a `<IncrementalStitcherView>`
+ *      or any other consumer can render the live panorama + UX hints.
+ *   4. Host calls `finalize(outputPath)` when the user releases the
+ *      shutter; resolves with the final panorama path + stats.
+ *   5. Host calls `cancel()` if the user dismisses the capture.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useIncrementalStitcher = useIncrementalStitcher;
+const react_1 = require("react");
+const incremental_1 = require("./incremental");
+/**
+ * Map raw outcome → user-facing hint string.  null = no banner.
+ */
+function outcomeToHint(outcome) {
+    switch (outcome) {
+        case incremental_1.IncrementalOutcome.RejectedTooFar:
+            return 'slow-down';
+        case incremental_1.IncrementalOutcome.RejectedSceneUniform:
+            return 'scene-uniform';
+        case incremental_1.IncrementalOutcome.RejectedAlignmentLost:
+            return 'alignment-lost';
+        case incremental_1.IncrementalOutcome.SkippedTrackingPoor:
+            return 'tracking-poor';
+        case incremental_1.IncrementalOutcome.AcceptedHigh:
+        case incremental_1.IncrementalOutcome.AcceptedMedium:
+        case incremental_1.IncrementalOutcome.SkippedTooClose:
+        default:
+            return null;
+    }
+}
+function outcomeToConfidence(outcome) {
+    if (outcome === incremental_1.IncrementalOutcome.AcceptedHigh)
+        return 'high';
+    if (outcome === incremental_1.IncrementalOutcome.AcceptedMedium)
+        return 'medium';
+    return null;
+}
+function useIncrementalStitcher() {
+    const native = (0, incremental_1.getIncrementalNativeModule)();
+    const isAvailable = (0, incremental_1.incrementalStitcherIsAvailable)();
+    const [isRunning, setIsRunning] = (0, react_1.useState)(false);
+    const [state, setState] = (0, react_1.useState)(null);
+    // Keep the latest hint/confidence sticky for a few frames after a
+    // skip — otherwise the UI flickers since SkippedTooClose returns
+    // a "silent" outcome between every accept.  We collapse this by
+    // only updating hint when the new outcome is itself a hint or an
+    // accept, leaving non-hint skips alone.
+    const lastHintRef = (0, react_1.useRef)(null);
+    // Subscribe to native events on mount.  The subscription itself
+    // is cheap; the native side gates `hasListeners` so events are
+    // only emitted when JS is listening.
+    (0, react_1.useEffect)(() => {
+        if (!native)
+            return undefined;
+        const sub = (0, incremental_1.subscribeIncrementalState)((nextState) => {
+            // Sticky-snapshot merge: the native side emits a state event
+            // for EVERY ARFrame the engine processes (~60 Hz), most of
+            // which are SkippedTooClose with NO snapshot path.  A naive
+            // `setState(nextState)` would wipe the panoramaPath to null
+            // 60 times per second, blanking the live preview between
+            // accepts.  Keep the last-good snapshot fields so the PiP
+            // shows the most recent panorama continuously between accepts;
+            // other fields (outcome, confidence, hint) update normally.
+            setState((prev) => {
+                if (!nextState.panoramaPath && prev?.panoramaPath) {
+                    return {
+                        ...nextState,
+                        panoramaPath: prev.panoramaPath,
+                        width: prev.width,
+                        height: prev.height,
+                    };
+                }
+                return nextState;
+            });
+            const newHint = outcomeToHint(nextState.outcome);
+            if (newHint !== null) {
+                lastHintRef.current = newHint;
+            }
+            else if (nextState.outcome === incremental_1.IncrementalOutcome.AcceptedHigh ||
+                nextState.outcome === incremental_1.IncrementalOutcome.AcceptedMedium) {
+                // An accept clears any prior hint — operator's back on track.
+                lastHintRef.current = null;
+            }
+            // Else: SkippedTooClose etc. — leave the hint alone.
+        });
+        return () => sub?.remove();
+    }, [native]);
+    const start = (0, react_1.useCallback)(async (options = {}) => {
+        if (!native) {
+            throw new Error('useIncrementalStitcher: IncrementalStitcher native '
+                + 'module is not registered.  Ensure the SDK pod has been '
+                + 'rebuilt against the host app.');
+        }
+        await native.start(options);
+        setIsRunning(true);
+        setState(null);
+        lastHintRef.current = null;
+    }, [native]);
+    const finalize = (0, react_1.useCallback)(async (outputPath, quality = 90, captureOrientation) => {
+        if (!native) {
+            throw new Error('useIncrementalStitcher: native module unavailable');
+        }
+        const result = await native.finalize({
+            outputPath: outputPath ?? '',
+            quality,
+            // 2026-05-18 (iOS cross-orientation fix) — fresh orientation
+            // at finalize time.  Engine uses this for bake-rotation
+            // instead of the start-time snapshot.  Undefined = keep
+            // legacy start-time behaviour.
+            captureOrientation,
+        });
+        setIsRunning(false);
+        // Clear React state on finalize so the next start doesn't
+        // briefly show stale frame counts / hint banners from the
+        // previous capture.  Without this, the IncrementalStitcherView
+        // displayed acceptedCount from the prior pan if a late event
+        // had already updated state.
+        setState(null);
+        lastHintRef.current = null;
+        return result;
+    }, [native]);
+    const cancel = (0, react_1.useCallback)(async () => {
+        if (!native)
+            return;
+        await native.cancel();
+        setIsRunning(false);
+        setState(null);
+        lastHintRef.current = null;
+    }, [native]);
+    // Cleanup-on-unmount that actually works.  The previous version
+    // captured `isRunning` from the initial render (false), so the
+    // cancel never fired.  Reading from a ref keeps the latest
+    // value visible at unmount time.
+    const isRunningRef = (0, react_1.useRef)(false);
+    (0, react_1.useEffect)(() => {
+        isRunningRef.current = isRunning;
+    }, [isRunning]);
+    (0, react_1.useEffect)(() => {
+        return () => {
+            if (native && isRunningRef.current) {
+                native.cancel().catch(() => undefined);
+            }
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const confidenceLevel = state ? outcomeToConfidence(state.outcome) : null;
+    return {
+        isAvailable,
+        isRunning,
+        state,
+        hint: lastHintRef.current,
+        confidenceLevel,
+        start,
+        finalize,
+        cancel,
+    };
+}
+//# sourceMappingURL=useIncrementalStitcher.js.map

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Internal type definitions for `react-native-image-stitcher`.
+ *
+ * These are NOT re-exported from `src/index.ts` — they are consumed
+ * by internal modules (`useCapture`, `runQualityCheck`) and adapted
+ * to the public surface (e.g., `CameraCaptureResult` in
+ * `src/camera/Camera.tsx`) before reaching consumers.
+ *
+ * If something here needs to become public, expose it deliberately
+ * from `src/index.ts` rather than encouraging deep imports.
+ */
+export interface QualityThresholds {
+    /** Minimum Laplacian variance for blur detection */
+    minBlurScore: number;
+    /** Minimum brightness (0-255) */
+    minBrightness: number;
+    /** Maximum brightness (0-255) */
+    maxBrightness: number;
+}
+export interface QualityReport {
+    passed: boolean;
+    blurScore: number;
+    brightnessScore: number;
+    issues: QualityIssue[];
+}
+export interface QualityIssue {
+    type: 'blur' | 'brightness_low' | 'brightness_high' | 'framing';
+    message: string;
+    severity: 'warning' | 'error';
+}
+export interface DeviceMetadata {
+    platform: 'ios' | 'android';
+    osVersion: string;
+    deviceModel: string;
+    cameraId: string;
+    flashEnabled: boolean;
+}
+export interface CaptureResult {
+    /** Unique device-generated UUID */
+    deviceUuid: string;
+    /** Local file path to compressed image */
+    compressedUri: string;
+    /** Local file path to original image (if retained) */
+    originalUri?: string;
+    /** Image width in pixels, after EXIF orientation correction. */
+    width: number;
+    /** Image height in pixels, after EXIF orientation correction. */
+    height: number;
+    /** Whether this is a stitched panoramic image */
+    isStitched: boolean;
+    /** Capture timestamp (ISO 8601) */
+    capturedAt: string;
+    /** Quality check results (if enabled) */
+    qualityReport?: QualityReport;
+    /** Device metadata at capture time */
+    deviceMetadata: DeviceMetadata;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,15 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Internal type definitions for `react-native-image-stitcher`.
+ *
+ * These are NOT re-exported from `src/index.ts` — they are consumed
+ * by internal modules (`useCapture`, `runQualityCheck`) and adapted
+ * to the public surface (e.g., `CameraCaptureResult` in
+ * `src/camera/Camera.tsx`) before reaching consumers.
+ *
+ * If something here needs to become public, expose it deliberately
+ * from `src/index.ts` rather than encouraging deep imports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/ios/Package.swift

@@ -0,0 +1,72 @@
+// swift-tools-version:5.9
+//
+// Package.swift — SwiftPM manifest used **only for command-line testing**
+// of the algorithm layer (QualityChecker.swift).  Production builds
+// don't go through SwiftPM; the host iOS app pulls these same source
+// files via the `RNImageStitcher.podspec` at the SDK package
+// root.
+//
+// Why bother with SwiftPM at all when production uses CocoaPods?
+//   * `swift test` runs from the command line, in CI, in 2 seconds.
+//   * XCTest in CocoaPods needs an Xcode workspace and an iOS
+//     simulator boot — slow, flaky, and ergonomically bad.
+//   * The bridge layer (QualityCheckerBridge.swift) deliberately
+//     guards its React import behind `#if canImport(React)` so SwiftPM
+//     can compile the package WITHOUT React being available.
+//
+// Run from this directory:
+//
+//   cd retailens-capture-sdk/ios
+//   swift test
+
+import PackageDescription
+
+let package = Package(
+  name: "RNImageStitcher",
+  platforms: [
+    .iOS(.v14),
+    // macOS target needed so `swift test` can run on a Mac without
+    // an iOS simulator.  The algorithm layer uses Accelerate + Core
+    // Image — both of which are available on macOS too.
+    .macOS(.v12),
+  ],
+  products: [
+    .library(name: "RNImageStitcher", targets: ["RNImageStitcher"]),
+  ],
+  dependencies: [],
+  targets: [
+    .target(
+      name: "RNImageStitcher",
+      path: "Sources/RNImageStitcher",
+      // Excluded from `swift test` because they depend on either
+      // React (which isn't a SwiftPM dep) or OpenCV (which only
+      // ships as an iOS XCFramework via the podspec — no macOS
+      // build).  The host app's CocoaPods workspace picks them up.
+      exclude: [
+        // React-dependent
+        "QualityCheckerBridge.swift",
+        "QualityCheckerBridge.m",
+        "StitcherBridge.swift",
+        "StitcherBridge.m",
+        // OpenCV-dependent (Phase 2 stitcher)
+        "OpenCVStitcher.h",
+        "OpenCVStitcher.mm",
+        // OpenCV-dependent (V16 Phase 1 keyframe collector)
+        "OpenCVKeyframeCollector.h",
+        "OpenCVKeyframeCollector.mm",
+        // Stitcher.swift is `#if canImport(UIKit)`-gated so it
+        // compiles to nothing on macOS; including it keeps the
+        // file available to the Pods build without breaking
+        // `swift test`.
+      ]
+    ),
+    .testTarget(
+      name: "RNImageStitcherTests",
+      dependencies: ["RNImageStitcher"],
+      path: "Tests/RNImageStitcherTests",
+      resources: [
+        .copy("Fixtures"),
+      ]
+    ),
+  ]
+)

package/ios/Sources/RNImageStitcher/ARCameraViewManager.m

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// ARCameraViewManager.m
+//
+// RN bridge declaration for the Swift `RNSARCameraViewManager`.
+// Without this file the JS side's `requireNativeComponent('RNSARCameraView')`
+// would resolve to undefined because RN's component registry is
+// populated by RCT_EXTERN_MODULE / RCT_EXPORT_VIEW_PROPERTY macros,
+// not Swift @objc decorators alone.
+//
+// View name semantics:
+//   `RCT_EXTERN_MODULE(<ManagerName>, RCTViewManager)` registers the
+//   Swift manager class.  RN auto-derives the JS-visible component
+//   name by stripping the trailing "Manager" — so this manager
+//   exposes a component named "RNSARCameraView" on the JS side.
+//   That name MUST match what `requireNativeComponent('...')` looks
+//   up in `ARCameraView.tsx`.
+//
+
+#import <React/RCTViewManager.h>
+
+@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.
+
+@end

package/ios/Sources/RNImageStitcher/ARCameraViewManager.swift

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// ARCameraViewManager — RCTViewManager that vends RNSARCameraView
+// instances to React Native.
+//
+// React Native discovers native UI components via subclasses of
+// RCTViewManager (or its newer ComponentDescriptor/ShadowNode siblings
+// for Fabric).  We're on the bridge architecture (RN 0.84 Paper),
+// so a thin RCTViewManager subclass is enough: override `view()` to
+// return a fresh view instance, declare props via RCT_EXPORT_VIEW_PROPERTY
+// in the .m bridge file, and React Native handles the rest of the
+// view-tree integration.
+//
+// The class itself does almost nothing — view lifecycle (start/stop AR
+// session) lives on the view, props are bridged via the .m file.  Most
+// of the value here is the @objc(RNSARCameraViewManager) name
+// matching the JS-side `requireNativeComponent` call.
+
+#if canImport(React)
+import Foundation
+import React
+import UIKit
+
+
+@objc(RNSARCameraViewManager)
+public final class RNSARCameraViewManager: RCTViewManager {
+
+    /// Vends a new view instance per React Native mount.  RN reuses
+    /// view instances when possible (recycler) but during initial
+    /// hookup this is called once per `<ARCameraView>` element.
+    public override func view() -> UIView! {
+        return RNSARCameraView()
+    }
+
+    /// AR-camera view setup needs the main thread (UIKit + ARSCNView).
+    public override class func requiresMainQueueSetup() -> Bool {
+        return true
+    }
+}
+#endif