react-native-image-stitcher 0.1.1 → 0.1.3

package/dist/utils/files.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Thin JS wrapper around the `RNImageStitcherFileUtils` native
+ * module (defined in `ios/Sources/RNImageStitcher/FileBridge.{swift,m}`
+ * and `android/src/main/.../FileBridge.kt`).  Internal — not
+ * re-exported from `src/index.ts`.
+ *
+ * Two operations:
+ *   - `moveFile(from, to)` — move a file, creating the destination's
+ *     parent directory tree on demand.  Used to relocate
+ *     vision-camera's auto-named tmp output into the lib's canonical
+ *     capture dir.
+ *   - `getDefaultCaptureDir()` — resolve (and create on first call)
+ *     the canonical default capture directory:
+ *
+ *       iOS:     `<NSCachesDirectory>/react-native-image-stitcher/`
+ *       Android: `<context.cacheDir>/react-native-image-stitcher/`
+ *
+ *     Predictable, evictable-by-OS, NOT backed up.  Captures live
+ *     here until the host moves them somewhere durable (which is
+ *     intentional — the lib doesn't promise persistence beyond the
+ *     immediate capture flow).
+ */
+/**
+ * Move a file via the native bridge.  Both paths accepted in bare
+ * or `file://`-prefixed form.  Resolves to the bare destination
+ * path on success.  Throws on disk failure.
+ */
+export declare function moveFile(from: string, to: string): Promise<string>;
+/**
+ * Resolve the canonical default capture directory.  Lazy +
+ * memoised — the native side creates the dir on first call, JS
+ * caches the result for the rest of the app session.
+ */
+export declare function getDefaultCaptureDir(): Promise<string>;
+/**
+ * Compose a default filename for a tap-photo capture, using a
+ * millisecond Unix timestamp for ordering.  Pure helper; no I/O.
+ */
+export declare function defaultPhotoFilename(): string;
+/**
+ * Same as `defaultPhotoFilename` but for panoramas.
+ */
+export declare function defaultPanoramaFilename(): string;
+//# sourceMappingURL=files.d.ts.map

package/dist/utils/files.js

@@ -0,0 +1,84 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Thin JS wrapper around the `RNImageStitcherFileUtils` native
+ * module (defined in `ios/Sources/RNImageStitcher/FileBridge.{swift,m}`
+ * and `android/src/main/.../FileBridge.kt`).  Internal — not
+ * re-exported from `src/index.ts`.
+ *
+ * Two operations:
+ *   - `moveFile(from, to)` — move a file, creating the destination's
+ *     parent directory tree on demand.  Used to relocate
+ *     vision-camera's auto-named tmp output into the lib's canonical
+ *     capture dir.
+ *   - `getDefaultCaptureDir()` — resolve (and create on first call)
+ *     the canonical default capture directory:
+ *
+ *       iOS:     `<NSCachesDirectory>/react-native-image-stitcher/`
+ *       Android: `<context.cacheDir>/react-native-image-stitcher/`
+ *
+ *     Predictable, evictable-by-OS, NOT backed up.  Captures live
+ *     here until the host moves them somewhere durable (which is
+ *     intentional — the lib doesn't promise persistence beyond the
+ *     immediate capture flow).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.moveFile = moveFile;
+exports.getDefaultCaptureDir = getDefaultCaptureDir;
+exports.defaultPhotoFilename = defaultPhotoFilename;
+exports.defaultPanoramaFilename = defaultPanoramaFilename;
+const react_native_1 = require("react-native");
+function bridge() {
+    const m = react_native_1.NativeModules.RNImageStitcherFileUtils;
+    if (!m || typeof m !== 'object')
+        return null;
+    return m;
+}
+/**
+ * Move a file via the native bridge.  Both paths accepted in bare
+ * or `file://`-prefixed form.  Resolves to the bare destination
+ * path on success.  Throws on disk failure.
+ */
+async function moveFile(from, to) {
+    const b = bridge();
+    if (!b) {
+        throw new Error('react-native-image-stitcher: RNImageStitcherFileUtils native '
+            + 'module is not registered.  Check that the host app has '
+            + 'rebuilt against the latest pod/Gradle install.');
+    }
+    return b.moveFile(from, to);
+}
+// Cached after the first resolve — the dir doesn't move during the
+// lifetime of the app, and the on-first-call mkdir is idempotent.
+let cachedDefaultDir = null;
+/**
+ * Resolve the canonical default capture directory.  Lazy +
+ * memoised — the native side creates the dir on first call, JS
+ * caches the result for the rest of the app session.
+ */
+async function getDefaultCaptureDir() {
+    if (cachedDefaultDir !== null)
+        return cachedDefaultDir;
+    const b = bridge();
+    if (!b) {
+        throw new Error('react-native-image-stitcher: RNImageStitcherFileUtils native '
+            + 'module is not registered.  Check that the host app has '
+            + 'rebuilt against the latest pod/Gradle install.');
+    }
+    cachedDefaultDir = await b.defaultCaptureDir();
+    return cachedDefaultDir;
+}
+/**
+ * Compose a default filename for a tap-photo capture, using a
+ * millisecond Unix timestamp for ordering.  Pure helper; no I/O.
+ */
+function defaultPhotoFilename() {
+    return `photo-${Date.now()}.jpg`;
+}
+/**
+ * Same as `defaultPhotoFilename` but for panoramas.
+ */
+function defaultPanoramaFilename() {
+    return `panorama-${Date.now()}.jpg`;
+}
+//# sourceMappingURL=files.js.map

package/dist/utils/paths.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Path normalisation helpers.  Internal — NOT re-exported from
+ * `src/index.ts`; the public surface intentionally doesn't promise
+ * these utilities to consumers (every host app has its own copy).
+ *
+ * Two shapes a file path can take when crossing the JS / native /
+ * React layers in this library:
+ *
+ *   - **`file://`-prefixed URI** — what RN's `<Image source={{ uri }}>`
+ *     (Android strict, iOS lenient) and `expo-file-system` APIs
+ *     accept.  Whenever this library emits a path to JS (via
+ *     `onCapture`, the `IncrementalStateUpdate` event, etc.) it
+ *     should be in this form so consumers can render it directly.
+ *
+ *   - **Bare path** — what `fs`-style native APIs (`cv::imwrite`,
+ *     `NSFileManager`, `BitmapFactory.decodeFile`) accept.  These
+ *     treat a `file://` prefix as part of the literal filename and
+ *     fail to open it.  Native bridges expect bare paths in.
+ *
+ * Both helpers are pure and idempotent.  No-op on the empty string.
+ *
+ * (The Swift and Kotlin sides have their own `stripFileScheme` —
+ * cross-language sharing isn't worth a small helper.  Keeping the
+ * JS copy here just centralises the rule for the TS surface.)
+ */
+/** Add the `file://` scheme to a bare path, idempotently. */
+export declare function toFileUri(path: string | null | undefined): string;
+/** Strip the `file://` scheme from a URI, idempotently. */
+export declare function toBareFilePath(path: string | null | undefined): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/utils/paths.js

@@ -0,0 +1,48 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Path normalisation helpers.  Internal — NOT re-exported from
+ * `src/index.ts`; the public surface intentionally doesn't promise
+ * these utilities to consumers (every host app has its own copy).
+ *
+ * Two shapes a file path can take when crossing the JS / native /
+ * React layers in this library:
+ *
+ *   - **`file://`-prefixed URI** — what RN's `<Image source={{ uri }}>`
+ *     (Android strict, iOS lenient) and `expo-file-system` APIs
+ *     accept.  Whenever this library emits a path to JS (via
+ *     `onCapture`, the `IncrementalStateUpdate` event, etc.) it
+ *     should be in this form so consumers can render it directly.
+ *
+ *   - **Bare path** — what `fs`-style native APIs (`cv::imwrite`,
+ *     `NSFileManager`, `BitmapFactory.decodeFile`) accept.  These
+ *     treat a `file://` prefix as part of the literal filename and
+ *     fail to open it.  Native bridges expect bare paths in.
+ *
+ * Both helpers are pure and idempotent.  No-op on the empty string.
+ *
+ * (The Swift and Kotlin sides have their own `stripFileScheme` —
+ * cross-language sharing isn't worth a small helper.  Keeping the
+ * JS copy here just centralises the rule for the TS surface.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toFileUri = toFileUri;
+exports.toBareFilePath = toBareFilePath;
+/** Add the `file://` scheme to a bare path, idempotently. */
+function toFileUri(path) {
+    if (!path)
+        return '';
+    if (path.startsWith('file://') || path.startsWith('content://') || path.startsWith('http')) {
+        return path;
+    }
+    return `file://${path}`;
+}
+/** Strip the `file://` scheme from a URI, idempotently. */
+function toBareFilePath(path) {
+    if (!path)
+        return '';
+    if (path.startsWith('file://'))
+        return path.slice('file://'.length);
+    return path;
+}
+//# sourceMappingURL=paths.js.map

package/ios/Package.swift

@@ -16,7 +16,7 @@
 //
 // Run from this directory:
 //
-//   cd retailens-capture-sdk/ios
+//   cd react-native-image-stitcher/ios
 //   swift test
 
 import PackageDescription

package/ios/Sources/RNImageStitcher/FileBridge.m

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// FileBridge.m — Obj-C side of the React Native module registration
+// for `FileBridge.swift`.  Required because RN's bridge discovery
+// scans for `@interface RCT_EXTERN_MODULE(...)` blocks via Obj-C
+// runtime introspection; Swift-only modules aren't visible.
+
+#import <React/RCTBridgeModule.h>
+
+@interface RCT_EXTERN_MODULE(RNImageStitcherFileUtils, NSObject)
+
+RCT_EXTERN_METHOD(moveFile:(NSString *)from
+                  to:(NSString *)to
+                  resolver:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
+RCT_EXTERN_METHOD(defaultCaptureDir:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
+@end

package/ios/Sources/RNImageStitcher/FileBridge.swift

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// FileBridge.swift
+//
+// Small native module exposing two file operations the JS layer
+// needs in order to:
+//
+//   1. Move vision-camera's auto-named tmp photo into our canonical
+//      default capture dir, so JS-level paths returned to the host
+//      are predictable (vs. opaque `<uuid>.jpg` paths in
+//      `NSTemporaryDirectory()`).
+//   2. Resolve the canonical default capture dir itself, so the JS
+//      layer can compose `<defaultDir>/photo-<ms>.jpg` filenames
+//      consistently across both platforms.
+//
+// Kept narrow on purpose — this isn't a general-purpose fs API.  If
+// host apps want to read/write arbitrary files they can pull in
+// `expo-file-system` themselves; the lib only exposes what it needs
+// for its own capture flow.
+//
+// Canonical capture dir lives under `NSCachesDirectory` (`Library/
+// Caches/`) because:
+//   * It persists across app restarts (unlike `NSTemporaryDirectory()`).
+//   * iOS may evict cache files under memory pressure, which matches
+//     the lib's contract: "capture file lives until host moves it
+//     somewhere durable."
+//   * Not backed up to iCloud, so the user doesn't pay for the
+//     ephemeral capture files.
+
+import Foundation
+import React
+
+@objc(RNImageStitcherFileUtils)
+public class FileBridge: NSObject {
+
+  @objc public static func requiresMainQueueSetup() -> Bool {
+    return false
+  }
+
+  /// Move (or copy+delete fallback for cross-volume moves) a file
+  /// from `from` to `to`.  Both paths can be bare or `file://`-prefixed
+  /// — bridge normalises internally.  Creates the destination's
+  /// parent directory tree if missing.  Resolves to the bare
+  /// destination path.
+  @objc(moveFile:to:resolver:rejecter:)
+  public func moveFile(_ from: String,
+                       to dst: String,
+                       resolver: @escaping RCTPromiseResolveBlock,
+                       rejecter: @escaping RCTPromiseRejectBlock) {
+    let fm = FileManager.default
+    let cleanFrom = from.hasPrefix("file://") ? String(from.dropFirst(7)) : from
+    let cleanTo = dst.hasPrefix("file://") ? String(dst.dropFirst(7)) : dst
+    do {
+      let dstDir = (cleanTo as NSString).deletingLastPathComponent
+      if !fm.fileExists(atPath: dstDir) {
+        try fm.createDirectory(
+          atPath: dstDir,
+          withIntermediateDirectories: true,
+          attributes: nil,
+        )
+      }
+      if fm.fileExists(atPath: cleanTo) {
+        try fm.removeItem(atPath: cleanTo)
+      }
+      // Cheap rename first (same volume).  iOS caches + tmp are on the
+      // same APFS volume so this is fast; the catch is for the
+      // theoretical cross-volume move that copyItem can still handle.
+      do {
+        try fm.moveItem(atPath: cleanFrom, toPath: cleanTo)
+      } catch {
+        try fm.copyItem(atPath: cleanFrom, toPath: cleanTo)
+        try? fm.removeItem(atPath: cleanFrom)
+      }
+      resolver(cleanTo)
+    } catch {
+      rejecter(
+        "FILE_MOVE_FAILED",
+        "Failed to move \(cleanFrom) → \(cleanTo): \(error.localizedDescription)",
+        error,
+      )
+    }
+  }
+
+  /// Resolve the lib's canonical default capture dir, creating it on
+  /// demand.  Returns a bare absolute path.
+  @objc(defaultCaptureDir:rejecter:)
+  public func defaultCaptureDir(_ resolver: @escaping RCTPromiseResolveBlock,
+                                rejecter: @escaping RCTPromiseRejectBlock) {
+    let caches = NSSearchPathForDirectoriesInDomains(
+      .cachesDirectory, .userDomainMask, true,
+    ).first ?? NSTemporaryDirectory()
+    let dir = (caches as NSString).appendingPathComponent("react-native-image-stitcher")
+    do {
+      if !FileManager.default.fileExists(atPath: dir) {
+        try FileManager.default.createDirectory(
+          atPath: dir,
+          withIntermediateDirectories: true,
+          attributes: nil,
+        )
+      }
+      resolver(dir)
+    } catch {
+      rejecter(
+        "DIR_CREATE_FAILED",
+        "Failed to create canonical capture dir \(dir): \(error.localizedDescription)",
+        error,
+      )
+    }
+  }
+}

package/ios/Sources/RNImageStitcher/IncrementalStitcher.swift

@@ -289,7 +289,7 @@ public final class IncrementalStitcher: NSObject {
     /// fix is non-trivial; deferred until pose-driven stitch work
     /// lands (which will rework the queue topology anyway).
     private let workQueue = DispatchQueue(
-        label: "com.retailens.incremental.stitcher",
+        label: "io.imagestitcher.incremental.stitcher",
         qos: .userInitiated
     )
 
@@ -306,7 +306,7 @@ public final class IncrementalStitcher: NSObject {
     /// is out of scope for this MVP — see prompt's "deliberately out
     /// of scope" list).
     private let refineQueue = DispatchQueue(
-        label: "com.retailens.incremental.refine",
+        label: "io.imagestitcher.incremental.refine",
         qos: .utility
     )
 
@@ -1136,7 +1136,7 @@ public final class IncrementalStitcher: NSObject {
         // Why this matters (RCA from Sentry crashes 2026-05-09
         // 21:59-22:03, all 3 .ips traces):
         //   EXC_BAD_ACCESS at objc_retain+16, frame 1 = closure #1
-        //   in finalize+2648, queue = com.retailens.incremental.
+        //   in finalize+2648, queue = io.imagestitcher.incremental.
         //   stitcher.  +2648 lands inside the os_log call that
         //   bridges self.batchWarperType → NSString via
         //   swift_bridgeObjectRetain → objc_retain.  The retain
@@ -1269,7 +1269,7 @@ public final class IncrementalStitcher: NSObject {
         // under stateLock, closing the visible torn-pointer race.
         // Three Sentry traces post-fix4 still showed the same crash
         // signature (frame 1 = closure #1 in finalize+N, queue =
-        // com.retailens.incremental.stitcher), which per the
+        // io.imagestitcher.incremental.stitcher), which per the
         // systematic-debugging skill (3+ fixes failed on the same
         // symptom = wrong architecture) means the workQueue.async
         // pattern itself is the problem, not any specific captured

package/ios/Sources/RNImageStitcher/KeyframeGate.swift

@@ -4,7 +4,7 @@
 //
 // This file used to BE the algorithm (~545 lines of Swift simd math).
 // As of P3-B of the Android-iOS parity work, the algorithm lives in
-// retailens-capture-sdk/cpp/keyframe_gate.{hpp,cpp} and is shared with
+// react-native-image-stitcher/cpp/keyframe_gate.{hpp,cpp} and is shared with
 // the Android side via JNI.  This Swift class is now a thin facade
 // that:
 //

package/ios/Sources/RNImageStitcher/KeyframeGateBridge.h

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 // KeyframeGateBridge.h — Obj-C++ wrapper exposing the shared C++
-// KeyframeGate (in retailens-capture-sdk/cpp/) to Swift.
+// KeyframeGate (in react-native-image-stitcher/cpp/) to Swift.
 //
 // Why this exists:
 //   The pose-driven keyframe-selection algorithm is the single most

package/ios/Sources/RNImageStitcher/KeyframeGateBridge.mm

@@ -18,7 +18,7 @@
 // Single source of truth for the reason-code → string mapping.  These
 // strings MUST stay 1:1 with the labels emitted by the original
 // KeyframeGate.swift (and read by the JS telemetry layer in
-// retailens-capture-sdk/src/stitching/incremental.ts).  Drift will
+// react-native-image-stitcher/src/stitching/incremental.ts).  Drift will
 // silently break the JS UI's pill text.
 static NSString *kReasonStringFor(retailens::KeyframeGateDecisionReason r) {
     using R = retailens::KeyframeGateDecisionReason;

package/ios/Sources/RNImageStitcher/RNSARSession.swift

@@ -150,7 +150,7 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
     /// recordings.  Phase 5 stitching will query by timestamp.
     private var poseLog: [(TimeInterval, RNSARFramePose)] = []
     private let poseLogQueue = DispatchQueue(
-        label: "com.retailens.arsession.poselog",
+        label: "io.imagestitcher.arsession.poselog",
         attributes: .concurrent
     )
     private static let MAX_POSE_LOG = 600  // ~10 s @ 60Hz

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Pose-aware panorama capture + stitching for React Native. One <Camera> component, both tap-to-photo and hold-to-pan modes, both AR-backed and IMU-fallback capture paths.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/camera/Camera.tsx

@@ -80,6 +80,13 @@ import {
 import { useIncrementalJSDriver } from '../stitching/useIncrementalJSDriver';
 import { useIncrementalStitcher } from '../stitching/useIncrementalStitcher';
 import { useIMUTranslationGate } from '../sensors/useIMUTranslationGate';
+import { toBareFilePath, toFileUri } from '../utils/paths';
+import {
+  defaultPanoramaFilename,
+  defaultPhotoFilename,
+  getDefaultCaptureDir,
+  moveFile,
+} from '../utils/files';
 
 
 // ─── Types ──────────────────────────────────────────────────────────
@@ -139,6 +146,7 @@ export type CameraErrorCode =
   | 'STITCH_HOMOGRAPHY_FAIL'
   | 'STITCH_CAMERA_PARAMS_FAIL'
   | 'STITCH_OOM'
+  | 'OUTPUT_WRITE_FAILED'
   | 'UNKNOWN';
 
 
@@ -196,6 +204,35 @@ export interface CameraProps {
   showSettingsButton?: boolean;
   style?: StyleProp<ViewStyle>;
 
+  /**
+   * Optional destination directory for captures.  When set, the lib
+   * lands tap-photos at `${outputDir}/photo-${ts}.jpg` and panoramas
+   * at `${outputDir}/panorama-${ts}.jpg` and the returned uri points
+   * at the persisted file (vs. vision-camera's tmp dir, which is
+   * what you get when this prop is omitted).
+   *
+   * The host is solely responsible for:
+   *   - Choosing a writable directory (the lib does NOT pick this for
+   *     you on either platform — particularly relevant on Android,
+   *     where scoped-storage rules differ between app-private storage
+   *     and user-visible Documents/Pictures dirs).
+   *   - Ensuring the directory exists.  The lib will create it if it
+   *     doesn't, but only inside paths the OS lets it write to.
+   *   - Making the path user-visible if that matters (`UIFileSharingEnabled`
+   *     on iOS for `FileSystem.documentDirectory`; MediaStore /
+   *     `Documents/...` on Android — see your platform's docs).
+   *
+   * On disk failure the capture promise rejects via `onError` with
+   * `CameraError('OUTPUT_WRITE_FAILED', ...)`.  No silent fallback to
+   * tmp — that hides bugs.
+   *
+   * Requires `expo-file-system` (declared as an OPTIONAL peer dep;
+   * only needed when this prop is set).
+   *
+   * Format: bare path or `file://` URI.  Both accepted.
+   */
+  outputDir?: string;
+
   // ── Callbacks ─────────────────────────────────────────────────────
   onCapture?: (result: CameraCaptureResult) => void;
   onCaptureSourceChange?: (source: CaptureSource) => void;
@@ -458,29 +495,14 @@ function buildInitialSettings(props: CameraProps): PanoramaSettings {
 }
 
 
-/**
- * Normalise a native-side file path into the `file://...` URI form
- * that React Native's `<Image>` requires on Android.  iOS is lenient,
- * but Android rejects bare `/data/...` paths and renders a blank
- * Image with no error in the JS layer.
- *
- * Native code in this lib emits paths in two flavours:
- *   - useCapture.compressedUri already includes `file://` (it's
- *     normalised in `makeCaptureResult`).
- *   - ARCameraView.takePhoto, IncrementalStitcher.finalize, and the
- *     `batchKeyframeThumbnailPath` from `IncrementalStateUpdate` all
- *     return bare paths.  Those are the cases this helper handles.
- *
- * Already-prefixed inputs are passed through unchanged, so it's safe
- * to call defensively at every public-API boundary.
- */
-function ensureFileUri(path: string | null | undefined): string {
-  if (!path) return '';
-  if (path.startsWith('file://') || path.startsWith('content://') || path.startsWith('http')) {
-    return path;
-  }
-  return `file://${path}`;
-}
+// `toFileUri` (used to be an inline `toFileUri` here) lives in
+// `../utils/paths.ts` so every call-site in this lib funnels through
+// one canonical implementation.  Native bridges return paths in
+// mixed shapes — useCapture.compressedUri already has `file://`,
+// while ARCameraView.takePhoto + IncrementalStitcher.finalize +
+// `batchKeyframeThumbnailPath` events all return bare paths — and we
+// normalise to the URI form on the way out to JS consumers (Android
+// `<Image>` requires the scheme; iOS is lenient).
 
 
 /**
@@ -494,6 +516,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
     enablePanoramaMode = true,
     showSettingsButton = false,
     style,
+    outputDir,
     onCapture,
     onCaptureSourceChange,
     onLensChange,
@@ -683,7 +706,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
           // De-dupe — same path may emit on subsequent ticks.
           // Normalise to `file://...` so Android <Image> in the band
           // overlay can actually render the thumbnail.
-          const path = ensureFileUri(state.batchKeyframeThumbnailPath!);
+          const path = toFileUri(state.batchKeyframeThumbnailPath!);
           if (prev.includes(path)) return prev;
           return [...prev, path];
         });
@@ -706,12 +729,32 @@ export function Camera(props: CameraProps): React.JSX.Element {
       let uri: string;
       let width: number;
       let height: number;
+      // Compose the destination path BEFORE the capture so both the
+      // AR and non-AR branches land at the same predictable location.
+      // If `outputDir` is set, the lib lands the file at a host-
+      // controlled path; otherwise, in the lib's canonical capture
+      // dir (`<cache>/react-native-image-stitcher/photo-<ms>.jpg`).
+      const photoOutputPath = outputDir
+        ? `${toBareFilePath(outputDir).replace(/\/$/, '')}/${defaultPhotoFilename()}`
+        : `${await getDefaultCaptureDir()}/${defaultPhotoFilename()}`;
       if (isAR && arViewRef.current) {
+        // ARCameraView writes to its own tmp location; relocate to
+        // photoOutputPath via the native FileBridge so both branches
+        // return paths under the same dir.
         const photo = await arViewRef.current.takePhoto({ quality: 90 });
-        // Native side returns a bare `/data/.../foo.jpg` path.  Android
-        // <Image> needs the `file://` scheme to render it; iOS is OK
-        // either way.
-        uri = ensureFileUri(photo.path);
+        try {
+          await moveFile(photo.path, photoOutputPath);
+        } catch (moveErr) {
+          throw new CameraError(
+            'OUTPUT_WRITE_FAILED',
+            `Failed to move AR photo to ${photoOutputPath}.  The destination `
+            + 'directory must be writable.',
+            moveErr,
+          );
+        }
+        // Android <Image> needs the `file://` scheme to render the
+        // returned uri; iOS is OK either way.  Normalise once here.
+        uri = toFileUri(photoOutputPath);
         width = photo.width;
         height = photo.height;
       } else {
@@ -724,12 +767,11 @@ export function Camera(props: CameraProps): React.JSX.Element {
         // useCapture.takePhoto wraps the cameraRef internally;
         // attach via assignment so the hook's ref points at our
         // local ref.  This works because RefObject is just { current }.
-        // Effect: capture.takePhoto() resolves with the SDK's
-        // CaptureResult (with compressedUri / width / height).
-        // We adapt to the public CameraCaptureResult shape.
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         (capture.cameraRef as any).current = visionCameraRef.current;
-        const result = await capture.takePhoto();
+        // useCapture handles the move internally; the returned
+        // `compressedUri` already points at `photoOutputPath`.
+        const result = await capture.takePhoto({ outputPath: photoOutputPath });
         uri = result.compressedUri;
         width = result.width;
         height = result.height;
@@ -745,7 +787,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
         );
       onError?.(e);
     }
-  }, [enablePhotoMode, isAR, capture, onCapture, onError]);
+  }, [enablePhotoMode, isAR, capture, outputDir, onCapture, onError]);
 
   const handleHoldStart = useCallback(async () => {
     if (!enablePanoramaMode) return;
@@ -828,8 +870,16 @@ export function Camera(props: CameraProps): React.JSX.Element {
     // No-op in AR mode where jsDriver was never started.
     jsDriver.stop();
     try {
+      // Compose the panorama output path: host-controlled if
+      // `outputDir` is set, else the lib's canonical capture dir
+      // (`<cache>/react-native-image-stitcher/panorama-<ms>.jpg`).
+      // `incremental.finalize` writes the stitched JPEG straight to
+      // this path natively (no JS-side move needed for panoramas).
+      const panoOutputPath = outputDir
+        ? `${toBareFilePath(outputDir).replace(/\/$/, '')}/${defaultPanoramaFilename()}`
+        : `${await getDefaultCaptureDir()}/${defaultPanoramaFilename()}`;
       const result = await incremental.finalize(
-        undefined,
+        panoOutputPath,
         90,
         deviceOrientation,
       );
@@ -847,7 +897,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
         type: 'panorama',
         // Native finalize() returns a bare `/data/.../foo.jpg` path;
         // normalise to `file://` for Android <Image>.
-        uri: ensureFileUri(result.panoramaPath),
+        uri: toFileUri(result.panoramaPath),
         width: result.width,
         height: result.height,
         framesRequested: result.framesRequested ?? -1,