react-native-image-stitcher 0.1.0 → 0.1.2

package/dist/index.js

@@ -3,37 +3,110 @@
 /**
  * react-native-image-stitcher — public API surface.
  *
- * Single component (`<Camera>`) + supporting types + the two public
- * hooks the design doc calls out (`useARSession`, `useIMUTranslationGate`).
- * Everything else (internal sub-components, drivers, bridges) is
- * deliberately NOT re-exported so the v0.1.0 → 1.0 stability window
- * doesn't lock us into an inflated public surface.
+ * Two layers:
+ *   1. The high-level `<Camera>` component for hosts that want a
+ *      drop-in capture experience.  Tap = photo, hold + pan + release
+ *      = panorama.  Single mount, all UI included.
+ *   2. The lower-level building blocks (views, hooks, stitching
+ *      engine bindings, settings modal, status overlays) for hosts
+ *      that want to compose their own capture UX while reusing the
+ *      battle-tested camera and stitching internals.
  *
- * If you need access to something that used to be exported and isn't
- * now, please open an issue describing the use-case before reaching
- * into the package internals.
+ * Layer 1 (`<Camera>`) is the recommended starting point.  Reach for
+ * layer 2 when the high-level component doesn't give you enough
+ * control — e.g., the private `retailens-camera-sdk` adds
+ * measurement + packet detection on top of these building blocks.
  *
  * Public/private split: this lib is the open-source foundation.  The
- * `retailens-camera-sdk` package depends on this lib and adds
- * RetaiLens-specific features (measurement, packet detection, etc.)
- * on top.  Consumers wanting those features install
- * `retailens-camera-sdk` instead.
+ * `retailens-camera-sdk` package depends on this lib (peer dep) and
+ * adds RetaiLens-specific features on top.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.CameraError = exports.Camera = void 0;
-// ── The main component ────────────────────────────────────────────────────
+exports.stitchVideo = exports.useIncrementalJSDriver = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = exports.useDeviceOrientation = exports.useVideoCapture = exports.useCapture = exports.ViewportCropOverlay = exports.DEFAULT_PANORAMA_SETTINGS = exports.PanoramaSettingsModal = exports.PanoramaGuidance = exports.PanoramaBandOverlay = exports.IncrementalPanGuide = exports.CaptureThumbnailStrip = exports.CaptureStatusOverlay = exports.CapturePreview = exports.CaptureControlsBar = exports.CaptureHeader = exports.CameraView = exports.ARCameraView = exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.CameraError = exports.Camera = void 0;
+// ─────────────────────────────────────────────────────────────────────
+// Layer 1 — the high-level <Camera> component
+// ─────────────────────────────────────────────────────────────────────
 var Camera_1 = require("./camera/Camera");
 Object.defineProperty(exports, "Camera", { enumerable: true, get: function () { return Camera_1.Camera; } });
 Object.defineProperty(exports, "CameraError", { enumerable: true, get: function () { return Camera_1.CameraError; } });
-// ── AR foundation (public per design doc) ─────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────
+// AR foundation (public since 0.1.0)
+// ─────────────────────────────────────────────────────────────────────
 // Hosts that want raw AR pose access (e.g., to build their own
 // measurement/detection on top) consume these directly.
 var useARSession_1 = require("./ar/useARSession");
 Object.defineProperty(exports, "useARSession", { enumerable: true, get: function () { return useARSession_1.useARSession; } });
 Object.defineProperty(exports, "ARTrackingState", { enumerable: true, get: function () { return useARSession_1.ARTrackingState; } });
-// ── IMU translation gate (public per design doc R5) ───────────────────────
+// ─────────────────────────────────────────────────────────────────────
+// IMU translation gate (public since 0.1.0)
+// ─────────────────────────────────────────────────────────────────────
 // Hosts running their own non-AR capture flow can reuse this hook to
-// get the same gating logic <Camera> uses internally.
+// get the same translation-budget gating logic <Camera> uses internally.
 var useIMUTranslationGate_1 = require("./sensors/useIMUTranslationGate");
 Object.defineProperty(exports, "useIMUTranslationGate", { enumerable: true, get: function () { return useIMUTranslationGate_1.useIMUTranslationGate; } });
+// ═════════════════════════════════════════════════════════════════════
+// Layer 2 — composable building blocks (added in 0.1.1)
+// ═════════════════════════════════════════════════════════════════════
+// ── Camera view components ────────────────────────────────────────────
+// Drop-in replacements for vision-camera's raw <Camera> (non-AR) and a
+// parallel ARKit/ARCore-backed view (AR).  Use these when you need to
+// hand-compose your capture UI instead of mounting <Camera>.
+var ARCameraView_1 = require("./camera/ARCameraView");
+Object.defineProperty(exports, "ARCameraView", { enumerable: true, get: function () { return ARCameraView_1.ARCameraView; } });
+var CameraView_1 = require("./camera/CameraView");
+Object.defineProperty(exports, "CameraView", { enumerable: true, get: function () { return CameraView_1.CameraView; } });
+// ── UI components ─────────────────────────────────────────────────────
+// Presentational pieces of the standard capture screen.  Each is a
+// pure component; the host wires the props.
+var CaptureHeader_1 = require("./camera/CaptureHeader");
+Object.defineProperty(exports, "CaptureHeader", { enumerable: true, get: function () { return CaptureHeader_1.CaptureHeader; } });
+var CaptureControlsBar_1 = require("./camera/CaptureControlsBar");
+Object.defineProperty(exports, "CaptureControlsBar", { enumerable: true, get: function () { return CaptureControlsBar_1.CaptureControlsBar; } });
+var CapturePreview_1 = require("./camera/CapturePreview");
+Object.defineProperty(exports, "CapturePreview", { enumerable: true, get: function () { return CapturePreview_1.CapturePreview; } });
+var CaptureStatusOverlay_1 = require("./camera/CaptureStatusOverlay");
+Object.defineProperty(exports, "CaptureStatusOverlay", { enumerable: true, get: function () { return CaptureStatusOverlay_1.CaptureStatusOverlay; } });
+var CaptureThumbnailStrip_1 = require("./camera/CaptureThumbnailStrip");
+Object.defineProperty(exports, "CaptureThumbnailStrip", { enumerable: true, get: function () { return CaptureThumbnailStrip_1.CaptureThumbnailStrip; } });
+var IncrementalPanGuide_1 = require("./camera/IncrementalPanGuide");
+Object.defineProperty(exports, "IncrementalPanGuide", { enumerable: true, get: function () { return IncrementalPanGuide_1.IncrementalPanGuide; } });
+var PanoramaBandOverlay_1 = require("./camera/PanoramaBandOverlay");
+Object.defineProperty(exports, "PanoramaBandOverlay", { enumerable: true, get: function () { return PanoramaBandOverlay_1.PanoramaBandOverlay; } });
+var PanoramaGuidance_1 = require("./camera/PanoramaGuidance");
+Object.defineProperty(exports, "PanoramaGuidance", { enumerable: true, get: function () { return PanoramaGuidance_1.PanoramaGuidance; } });
+var PanoramaSettingsModal_1 = require("./camera/PanoramaSettingsModal");
+Object.defineProperty(exports, "PanoramaSettingsModal", { enumerable: true, get: function () { return PanoramaSettingsModal_1.PanoramaSettingsModal; } });
+Object.defineProperty(exports, "DEFAULT_PANORAMA_SETTINGS", { enumerable: true, get: function () { return PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS; } });
+var ViewportCropOverlay_1 = require("./camera/ViewportCropOverlay");
+Object.defineProperty(exports, "ViewportCropOverlay", { enumerable: true, get: function () { return ViewportCropOverlay_1.ViewportCropOverlay; } });
+// ── Capture hooks ─────────────────────────────────────────────────────
+// vision-camera wrappers (useCapture / useVideoCapture) + a
+// device-orientation reader that works under iOS portrait-lock.
+var useCapture_1 = require("./camera/useCapture");
+Object.defineProperty(exports, "useCapture", { enumerable: true, get: function () { return useCapture_1.useCapture; } });
+var useVideoCapture_1 = require("./camera/useVideoCapture");
+Object.defineProperty(exports, "useVideoCapture", { enumerable: true, get: function () { return useVideoCapture_1.useVideoCapture; } });
+var useDeviceOrientation_1 = require("./camera/useDeviceOrientation");
+Object.defineProperty(exports, "useDeviceOrientation", { enumerable: true, get: function () { return useDeviceOrientation_1.useDeviceOrientation; } });
+// ── Incremental stitching engine ──────────────────────────────────────
+// JS bindings around the native `IncrementalStitcher` module.  Use
+// these when you need finer control than <Camera>'s built-in
+// hold-to-pan flow (e.g., feeding frames from a custom source, or
+// reading the engine's running state to drive a custom UI).
+var incremental_1 = require("./stitching/incremental");
+Object.defineProperty(exports, "IncrementalOutcome", { enumerable: true, get: function () { return incremental_1.IncrementalOutcome; } });
+Object.defineProperty(exports, "incrementalStitcherIsAvailable", { enumerable: true, get: function () { return incremental_1.incrementalStitcherIsAvailable; } });
+Object.defineProperty(exports, "subscribeIncrementalState", { enumerable: true, get: function () { return incremental_1.subscribeIncrementalState; } });
+Object.defineProperty(exports, "getIncrementalNativeModule", { enumerable: true, get: function () { return incremental_1.getIncrementalNativeModule; } });
+Object.defineProperty(exports, "cleanupOldKeyframes", { enumerable: true, get: function () { return incremental_1.cleanupOldKeyframes; } });
+var useIncrementalStitcher_1 = require("./stitching/useIncrementalStitcher");
+Object.defineProperty(exports, "useIncrementalStitcher", { enumerable: true, get: function () { return useIncrementalStitcher_1.useIncrementalStitcher; } });
+var useIncrementalJSDriver_1 = require("./stitching/useIncrementalJSDriver");
+Object.defineProperty(exports, "useIncrementalJSDriver", { enumerable: true, get: function () { return useIncrementalJSDriver_1.useIncrementalJSDriver; } });
+// ── Batch stitching ───────────────────────────────────────────────────
+// Feed a video file straight to OpenCV's cv::Stitcher, bypassing the
+// incremental pipeline.  Useful when you have content captured
+// outside the SDK and just want a panorama out.
+var stitchVideo_1 = require("./stitching/stitchVideo");
+Object.defineProperty(exports, "stitchVideo", { enumerable: true, get: function () { return stitchVideo_1.stitchVideo; } });
 //# sourceMappingURL=index.js.map

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",