react-native-image-stitcher 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -16,6 +16,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.2] — 2026-05-20
+
+### Added
+
+- **`outputDir` prop on `<Camera>`** + **`outputPath` per-call
+  option on `useCapture.takePhoto`** — captures (both tap-photos
+  and hold-panoramas) can now land at a host-controlled file
+  location instead of vision-camera's tmp dir.  Filename is
+  composed internally as `${outputDir}/photo-${ts}.jpg` /
+  `${outputDir}/panorama-${ts}.jpg` for `<Camera>`; per-call
+  `outputPath` on `useCapture` lets layer-2 hosts compose their
+  own filenames.
+  - On disk failure the capture rejects with
+    `CameraError('OUTPUT_WRITE_FAILED', ...)`.  **No silent
+    fallback** to a different path — that hides bugs.
+  - Host owns *picking* the path.  The lib treats the value as an
+    opaque writable filesystem path; it does not know about iOS
+    `UIFileSharingEnabled`, Android MediaStore, SAF, or any other
+    platform-specific shared-storage mechanism.  That's the host's
+    domain.
+  - **No peer deps required** — the move is handled by a small
+    native bridge (`RNImageStitcherFileUtils`) that ships with
+    the lib.
+- **Canonical default capture directory** — when neither
+  `outputDir` nor `outputPath` is set, the lib now writes captures
+  to a predictable per-platform location instead of vision-camera's
+  auto-generated tmp paths:
+  - iOS: `<NSCachesDirectory>/react-native-image-stitcher/photo-<ms>.jpg`
+    (and `panorama-<ms>.jpg`).
+  - Android: `<context.cacheDir>/react-native-image-stitcher/...`.
+  - Both are app-private, evictable by the OS under storage
+    pressure, not backed up.  Captures live here until the host
+    moves them somewhere durable — the lib doesn't promise
+    persistence beyond the immediate capture flow.
+  - This applies to BOTH tap-photo and panorama, so call-sites can
+    rely on a single naming + parent-dir convention regardless of
+    capture type.
+- **`RNImageStitcherFileUtils` native module** (internal) —
+  small Swift + Kotlin bridge exposing `moveFile(from, to)` and
+  `defaultCaptureDir()`.  Used by the lib's own JS layer to relocate
+  vision-camera's auto-named output into the canonical default dir
+  / `outputDir` without forcing a peer dep on `expo-file-system`
+  for every consumer.  Not re-exported from `src/index.ts`.
+
+### Fixed
+
+- **Android `cv::imwrite` rejected `file://`-scheme output paths.**
+  `IncrementalStitcher.finalize` (Kotlin) was passing the host-
+  provided `outputPath` straight to `cv::imwrite` without
+  normalisation, so consumers using `expo-file-system`'s
+  `documentDirectory` (which always prefixes `file://`) hit
+  "Stitch failed: cv::imwrite returned false (code=101)" on every
+  panorama capture.  iOS already stripped at the same boundary
+  (`IncrementalStitcher.swift:1215`); now Android does too via
+  `stripFileScheme()`, which already exists in the same file and
+  is used by `refinePanorama`.  The fix has zero behaviour impact
+  on hosts that were already passing bare paths.
+- **iOS modular-header build under `use_frameworks!`** — host apps
+  that opt into modular framework linkage (Expo + `use_frameworks!`,
+  RetaiLens-mobile is the immediate example) hit
+  ``'cstdint' file not found / could not build Objective-C module
+  'RNImageStitcher'`` because CocoaPods defaulted EVERY header in
+  `source_files` (including the shared `cpp/*.hpp` C++ headers) to
+  public.  The auto-generated `RNImageStitcher-umbrella.h` then
+  `#import`ed `keyframe_gate.hpp` / `stitcher.hpp` from a pure
+  Obj-C context and tripped on the C++ stdlib.  Pin
+  `s.public_header_files = ['ios/Sources/**/*.h']` so the umbrella
+  exposes only the iOS-side Obj-C `.h` files; the `.mm` source files
+  still locate the C++ headers via `HEADER_SEARCH_PATHS` set in
+  `pod_target_xcconfig`, so behaviour is unchanged for non-modular
+  hosts.  The umbrella now contains: `KeyframeGateBridge.h`,
+  `OpenCVIncrementalStitcher.h`, `OpenCVKeyframeCollector.h`,
+  `OpenCVSlitScanStitcher.h`, `OpenCVStitcher.h` — all Foundation /
+  CoreVideo-only declarations (the OpenCV C++ types stay inside the
+  `.mm` implementations).
+
 ## [0.1.1] — 2026-05-20
 
 ### Added

package/RNImageStitcher.podspec

@@ -37,10 +37,16 @@ Pod::Spec.new do |s|
   # (cpp/) that both iOS and Android compile from a single source.
   s.source_files = ['ios/Sources/**/*.{swift,h,m,mm}',
                     'cpp/**/*.{h,hpp,cpp}']
-  # public_header_files intentionally omitted — React Native's
-  # @objc(...) dispatch doesn't need umbrella headers, and exposing
-  # all OpenCV*.h headers to consumers locks us into supporting
-  # internal Obj-C++ classes as public API.  See CHANGELOG v0.1.0.
+  # Restrict the umbrella header to ONLY the iOS-side Obj-C `.h`
+  # files.  Without this, CocoaPods defaults every header in
+  # `source_files` (including the C++ `.hpp` files under cpp/) to
+  # public — which is fine for non-modular builds, but breaks any
+  # host app using `use_frameworks!` (as RetaiLens does): the
+  # umbrella module is compiled in pure Obj-C context and chokes on
+  # `#import "keyframe_gate.hpp"` with `'cstdint' file not found`.
+  # The .mm files still find the C++ headers via HEADER_SEARCH_PATHS
+  # below; they just don't get pulled into the umbrella.
+  s.public_header_files = ['ios/Sources/**/*.h']
 
   # Frameworks shipped with iOS itself — no binary cost.
   s.frameworks = ['Accelerate', 'CoreImage', 'UIKit', 'ARKit']

package/android/src/main/java/io/imagestitcher/rn/FileBridge.kt

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// FileBridge.kt
+//
+// Android side of the same small file-utility module exposed on
+// iOS by FileBridge.swift / FileBridge.m.  See the Swift file for
+// the architectural rationale on why this exists.
+
+package io.imagestitcher.rn
+
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import java.io.File
+
+class FileBridge(reactContext: ReactApplicationContext)
+  : ReactContextBaseJavaModule(reactContext) {
+
+  override fun getName(): String = "RNImageStitcherFileUtils"
+
+  /**
+   * Move (with copy+delete fallback) a file from `from` to `to`.
+   * Both paths can be bare or `file://`-prefixed.  Creates the
+   * destination's parent dir tree on demand.  Resolves to the bare
+   * destination path.
+   */
+  @ReactMethod
+  fun moveFile(from: String, to: String, promise: Promise) {
+    try {
+      val cleanFrom = if (from.startsWith("file://")) from.substring(7) else from
+      val cleanTo = if (to.startsWith("file://")) to.substring(7) else to
+      val src = File(cleanFrom)
+      val dst = File(cleanTo)
+      dst.parentFile?.mkdirs()
+      if (dst.exists()) {
+        dst.delete()
+      }
+      // Cheap rename first (same volume); copyTo + delete fallback
+      // handles the theoretical cross-volume case.
+      if (!src.renameTo(dst)) {
+        src.copyTo(dst, overwrite = true)
+        src.delete()
+      }
+      promise.resolve(cleanTo)
+    } catch (e: Exception) {
+      promise.reject(
+        "FILE_MOVE_FAILED",
+        "Failed to move $from → $to: ${e.message}",
+        e,
+      )
+    }
+  }
+
+  /**
+   * Resolve the lib's canonical default capture dir, creating it on
+   * demand.  Returns a bare absolute path.
+   *
+   * Lives under `context.cacheDir` because that's the Android
+   * equivalent of iOS's `NSCachesDirectory`: persists across
+   * restarts, evictable by the OS under pressure, not backed up.
+   */
+  @ReactMethod
+  fun defaultCaptureDir(promise: Promise) {
+    try {
+      val dir = File(reactApplicationContext.cacheDir, "react-native-image-stitcher")
+      if (!dir.exists()) {
+        dir.mkdirs()
+      }
+      promise.resolve(dir.absolutePath)
+    } catch (e: Exception) {
+      promise.reject(
+        "DIR_CREATE_FAILED",
+        "Failed to create canonical capture dir: ${e.message}",
+        e,
+      )
+    }
+  }
+}

package/android/src/main/java/io/imagestitcher/rn/IncrementalStitcher.kt

@@ -731,7 +731,15 @@ class IncrementalStitcher(
         val outputPath = if (outputPathOpt.isEmpty()) {
             File(reactContext.cacheDir, "RNImageStitcherIncremental-${System.nanoTime()}.jpg").absolutePath
         } else {
-            outputPathOpt
+            // Strip the `file://` scheme — hosts commonly pass paths
+            // sourced from `expo-file-system`'s `documentDirectory`,
+            // which always prefixes `file://`.  cv::imwrite (used
+            // downstream by the batch-keyframe + hybrid + slit-scan
+            // engines) silently returns false on URI-scheme paths,
+            // surfacing as "Stitch failed: cv::imwrite returned
+            // false".  iOS already strips at the same boundary —
+            // see IncrementalStitcher.swift:1215.
+            stripFileScheme(outputPathOpt)
         }
         val quality = options.getIntOrDefault("quality", 90)
         // 2026-05-18 (iOS cross-orientation fix; symmetric on Android) —

package/android/src/main/java/io/imagestitcher/rn/RNImageStitcherPackage.kt

@@ -29,6 +29,7 @@ class RNImageStitcherPackage : ReactPackage {
         BatchStitcher(reactContext),
         RNSARSession(reactContext),
         IncrementalStitcher(reactContext),
+        FileBridge(reactContext),
     )
 
     override fun createViewManagers(

package/dist/camera/Camera.d.ts

@@ -79,7 +79,7 @@ export type CameraCaptureResult = {
  * Errors surfaced via `onError`.  Classified codes so consumers can
  * branch on the kind of failure (toast vs retry vs report).
  */
-export type CameraErrorCode = 'CAMERA_PERMISSION_DENIED' | 'CAMERA_DEVICE_UNAVAILABLE' | 'PHOTO_CAPTURE_FAILED' | 'PANORAMA_START_FAILED' | 'PANORAMA_FINALIZE_FAILED' | 'STITCH_NEED_MORE_IMGS' | 'STITCH_HOMOGRAPHY_FAIL' | 'STITCH_CAMERA_PARAMS_FAIL' | 'STITCH_OOM' | 'UNKNOWN';
+export type CameraErrorCode = 'CAMERA_PERMISSION_DENIED' | 'CAMERA_DEVICE_UNAVAILABLE' | 'PHOTO_CAPTURE_FAILED' | 'PANORAMA_START_FAILED' | 'PANORAMA_FINALIZE_FAILED' | 'STITCH_NEED_MORE_IMGS' | 'STITCH_HOMOGRAPHY_FAIL' | 'STITCH_CAMERA_PARAMS_FAIL' | 'STITCH_OOM' | 'OUTPUT_WRITE_FAILED' | 'UNKNOWN';
 export declare class CameraError extends Error {
     readonly code: CameraErrorCode;
     readonly cause?: unknown;
@@ -121,6 +121,34 @@ export interface CameraProps {
     enablePanoramaMode?: boolean;
     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;
     onCapture?: (result: CameraCaptureResult) => void;
     onCaptureSourceChange?: (source: CaptureSource) => void;
     onLensChange?: (lens: CameraLens) => void;

package/dist/camera/Camera.js

@@ -92,6 +92,8 @@ const incremental_1 = require("../stitching/incremental");
 const useIncrementalJSDriver_1 = require("../stitching/useIncrementalJSDriver");
 const useIncrementalStitcher_1 = require("../stitching/useIncrementalStitcher");
 const useIMUTranslationGate_1 = require("../sensors/useIMUTranslationGate");
+const paths_1 = require("../utils/paths");
+const files_1 = require("../utils/files");
 class CameraError extends Error {
     constructor(code, message, cause) {
         super(message);
@@ -249,35 +251,19 @@ function buildInitialSettings(props) {
             PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.keyframeOverlapThreshold,
     };
 }
-/**
- * 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) {
-    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).
 /**
  * The public `<Camera>` component.
  */
 function Camera(props) {
-    const { defaultCaptureSource = 'ar', defaultLens = '1x', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, onCapture, onCaptureSourceChange, onLensChange, onFramesDropped, onError, } = props;
+    const { defaultCaptureSource = 'ar', defaultLens = '1x', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, onLensChange, onFramesDropped, onError, } = props;
     const insets = (0, react_native_safe_area_context_1.useSafeAreaInsets)();
     // ── State ───────────────────────────────────────────────────────
     const [arPreference, setArPreference] = (0, react_1.useState)(defaultCaptureSource === 'ar');
@@ -431,7 +417,7 @@ function Camera(props) {
                     // 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 = (0, paths_1.toFileUri)(state.batchKeyframeThumbnailPath);
                     if (prev.includes(path))
                         return prev;
                     return [...prev, path];
@@ -454,12 +440,29 @@ function Camera(props) {
             let uri;
             let width;
             let height;
+            // 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
+                ? `${(0, paths_1.toBareFilePath)(outputDir).replace(/\/$/, '')}/${(0, files_1.defaultPhotoFilename)()}`
+                : `${await (0, files_1.getDefaultCaptureDir)()}/${(0, files_1.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 (0, files_1.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 = (0, paths_1.toFileUri)(photoOutputPath);
                 width = photo.width;
                 height = photo.height;
             }
@@ -470,12 +473,11 @@ function Camera(props) {
                 // 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.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;
@@ -488,7 +490,7 @@ function Camera(props) {
                 : new CameraError('PHOTO_CAPTURE_FAILED', err instanceof Error ? err.message : String(err), err);
             onError?.(e);
         }
-    }, [enablePhotoMode, isAR, capture, onCapture, onError]);
+    }, [enablePhotoMode, isAR, capture, outputDir, onCapture, onError]);
     const handleHoldStart = (0, react_1.useCallback)(async () => {
         if (!enablePanoramaMode)
             return;
@@ -560,7 +562,15 @@ function Camera(props) {
         // No-op in AR mode where jsDriver was never started.
         jsDriver.stop();
         try {
-            const result = await incremental.finalize(undefined, 90, deviceOrientation);
+            // 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
+                ? `${(0, paths_1.toBareFilePath)(outputDir).replace(/\/$/, '')}/${(0, files_1.defaultPanoramaFilename)()}`
+                : `${await (0, files_1.getDefaultCaptureDir)()}/${(0, files_1.defaultPanoramaFilename)()}`;
+            const result = await incremental.finalize(panoOutputPath, 90, deviceOrientation);
             if (typeof result.framesRequested === 'number'
                 && typeof result.framesIncluded === 'number'
                 && result.framesIncluded < result.framesRequested) {
@@ -573,7 +583,7 @@ function Camera(props) {
                 type: 'panorama',
                 // Native finalize() returns a bare `/data/.../foo.jpg` path;
                 // normalise to `file://` for Android <Image>.
-                uri: ensureFileUri(result.panoramaPath),
+                uri: (0, paths_1.toFileUri)(result.panoramaPath),
                 width: result.width,
                 height: result.height,
                 framesRequested: result.framesRequested ?? -1,

package/dist/camera/useCapture.d.ts

@@ -69,6 +69,25 @@ export interface UseCaptureOptions {
      */
     preferredPhysicalDevice?: PhysicalCameraDeviceType;
 }
+/**
+ * Per-call options for `takePhoto`.  Separate from `UseCaptureOptions`
+ * (the hook-level config) so callers can vary the destination
+ * filename per capture without re-creating the hook.
+ */
+export interface TakePhotoCallOptions {
+    /**
+     * Move the captured JPEG to this fully-resolved path after EXIF
+     * orientation correction.  Requires `expo-file-system` in the
+     * host (declared as an OPTIONAL peer — only needed when
+     * `outputPath` is set).  Host is responsible for the destination
+     * directory's existence and writability; lib rejects loudly on
+     * disk failure rather than silently falling back to a tmp path.
+     *
+     * Format: bare path (e.g. `/data/.../foo.jpg`) or `file://`-prefixed
+     * URI — both accepted; lib normalises internally.
+     */
+    outputPath?: string;
+}
 /**
  * Hook output.  Intentionally flat so destructuring a subset is
  * cheap and the API doesn't force callers to drill into nested
@@ -92,8 +111,19 @@ export interface UseCaptureReturn {
      * Take a photo.  Single-flight: parallel calls return the in-flight
      * promise.  Returns a CaptureResult (with an optional QualityReport
      * when ``enableQualityChecks`` is on).
+     *
+     * `outputPath` (optional): a fully-resolved destination path.  When
+     * set, the lib moves the captured JPEG to that path after EXIF
+     * orientation correction, and the returned `compressedUri` points
+     * at the moved file.  The host is responsible for ensuring the
+     * destination directory exists and is writable; on disk failure,
+     * the promise rejects with an error referencing `outputPath`.
+     *
+     * Requires `expo-file-system` to be installed in the host app
+     * (declared as an OPTIONAL peer dep — consumers that don't pass
+     * `outputPath` aren't required to have it).
      */
-    takePhoto: () => Promise<CaptureResult>;
+    takePhoto: (options?: TakePhotoCallOptions) => Promise<CaptureResult>;
     /**
      * 2026-05-14 — physical lens types available on the chosen
      * `cameraPosition`.  Computed once at the first vision-camera

package/dist/camera/useCapture.js

@@ -31,6 +31,8 @@ const react_1 = require("react");
 const react_native_vision_camera_1 = require("react-native-vision-camera");
 const runQualityCheck_1 = require("../quality/runQualityCheck");
 const normaliseOrientation_1 = require("../quality/normaliseOrientation");
+const paths_1 = require("../utils/paths");
+const files_1 = require("../utils/files");
 function makeCaptureResult(photo, qualityReport) {
     const capturedAt = new Date().toISOString();
     return {
@@ -101,7 +103,7 @@ function useCapture(options = {}) {
     const toggleFlash = (0, react_1.useCallback)(() => {
         setFlash((prev) => (prev === 'off' ? 'on' : 'off'));
     }, []);
-    const takePhoto = (0, react_1.useCallback)(async () => {
+    const takePhoto = (0, react_1.useCallback)(async (callOptions) => {
         if (inFlightRef.current) {
             return inFlightRef.current;
         }
@@ -126,11 +128,30 @@ function useCapture(options = {}) {
                     width: photo.width,
                     height: photo.height,
                 });
-                const orientedPhoto = {
+                let orientedPhoto = {
                     ...photo,
                     width: normalised.width || photo.width,
                     height: normalised.height || photo.height,
                 };
+                // Move the orientation-corrected file to its final location.
+                // If the caller passed `outputPath`, use that.  Otherwise, the
+                // lib publishes captures into its canonical default dir so
+                // returned paths are predictable across consumers (vs.
+                // vision-camera's auto-generated UUID-named tmp file).  The
+                // move is performed via the `RNImageStitcherFileUtils` native
+                // bridge — no peer-dep on `expo-file-system` etc.
+                try {
+                    const dstPath = callOptions?.outputPath
+                        ? (0, paths_1.toBareFilePath)(callOptions.outputPath)
+                        : `${await (0, files_1.getDefaultCaptureDir)()}/${(0, files_1.defaultPhotoFilename)()}`;
+                    await (0, files_1.moveFile)(orientedPhoto.path, dstPath);
+                    orientedPhoto = { ...orientedPhoto, path: dstPath };
+                }
+                catch (e) {
+                    throw new Error('useCapture.takePhoto: failed to move captured photo to its '
+                        + `destination${callOptions?.outputPath ? ` (${callOptions.outputPath})` : ' (default capture dir)'}. `
+                        + `Underlying: ${e instanceof Error ? e.message : String(e)}`);
+                }
                 let report;
                 if (enableQualityChecks && qualityThresholds) {
                     report = await (0, runQualityCheck_1.runQualityCheck)(orientedPhoto.path, qualityThresholds);

package/dist/index.d.ts

@@ -44,6 +44,7 @@ export { PanoramaSettingsModal, DEFAULT_PANORAMA_SETTINGS, } from './camera/Pano
 export type { PanoramaSettings } from './camera/PanoramaSettingsModal';
 export { ViewportCropOverlay } from './camera/ViewportCropOverlay';
 export { useCapture } from './camera/useCapture';
+export type { TakePhotoCallOptions } from './camera/useCapture';
 export { useVideoCapture } from './camera/useVideoCapture';
 export { useDeviceOrientation } from './camera/useDeviceOrientation';
 export { IncrementalOutcome, incrementalStitcherIsAvailable, subscribeIncrementalState, getIncrementalNativeModule, cleanupOldKeyframes, } from './stitching/incremental';

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