react-native-image-stitcher 0.1.0 → 0.1.2

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,

package/src/camera/useCapture.ts

@@ -38,6 +38,12 @@ import {
 
 import { runQualityCheck } from '../quality/runQualityCheck';
 import { normaliseOrientation } from '../quality/normaliseOrientation';
+import { toBareFilePath } from '../utils/paths';
+import {
+  defaultPhotoFilename,
+  getDefaultCaptureDir,
+  moveFile,
+} from '../utils/files';
 import type {
   CaptureResult,
   QualityReport,
@@ -91,6 +97,27 @@ export interface UseCaptureOptions {
 }
 
 
+/**
+ * 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
@@ -114,8 +141,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
@@ -217,7 +255,7 @@ export function useCapture(options: UseCaptureOptions = {}): UseCaptureReturn {
     setFlash((prev) => (prev === 'off' ? 'on' : 'off'));
   }, []);
 
-  const takePhoto = useCallback(async (): Promise<CaptureResult> => {
+  const takePhoto = useCallback(async (callOptions?: TakePhotoCallOptions): Promise<CaptureResult> => {
     if (inFlightRef.current) {
       return inFlightRef.current;
     }
@@ -245,12 +283,33 @@ export function useCapture(options: UseCaptureOptions = {}): UseCaptureReturn {
           width: photo.width,
           height: photo.height,
         });
-        const orientedPhoto: PhotoFile = {
+        let orientedPhoto: PhotoFile = {
           ...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
+            ? toBareFilePath(callOptions.outputPath)
+            : `${await getDefaultCaptureDir()}/${defaultPhotoFilename()}`;
+          await 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: QualityReport | undefined;
         if (enableQualityChecks && qualityThresholds) {
           report = await runQualityCheck(orientedPhoto.path, qualityThresholds);

package/src/index.ts

@@ -2,24 +2,28 @@
 /**
  * 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.
  */
 
-// ── The main component ────────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────
+// Layer 1 — the high-level <Camera> component
+// ─────────────────────────────────────────────────────────────────────
 export { Camera, CameraError } from './camera/Camera';
 export type {
   CameraProps,
@@ -34,7 +38,9 @@ export type {
   FramesDroppedInfo,
 } from './camera/Camera';
 
-// ── 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.
 export { useARSession, ARTrackingState } from './ar/useARSession';
@@ -43,11 +49,77 @@ export type {
   FramePose,
 } from './ar/useARSession';
 
-// ── 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.
 export { useIMUTranslationGate } from './sensors/useIMUTranslationGate';
 export type {
   UseIMUTranslationGateOptions,
   UseIMUTranslationGateReturn,
 } from './sensors/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>.
+export { ARCameraView } from './camera/ARCameraView';
+export type { ARCameraViewHandle, ARCameraViewProps } from './camera/ARCameraView';
+export { CameraView } from './camera/CameraView';
+export type { CameraViewProps } from './camera/CameraView';
+
+// ── UI components ─────────────────────────────────────────────────────
+// Presentational pieces of the standard capture screen.  Each is a
+// pure component; the host wires the props.
+export { CaptureHeader } from './camera/CaptureHeader';
+export { CaptureControlsBar } from './camera/CaptureControlsBar';
+export { CapturePreview } from './camera/CapturePreview';
+export type { CapturePreviewAction } from './camera/CapturePreview';
+export { CaptureStatusOverlay } from './camera/CaptureStatusOverlay';
+export type { CaptureStatusPhase } from './camera/CaptureStatusOverlay';
+export { CaptureThumbnailStrip } from './camera/CaptureThumbnailStrip';
+export type { CaptureThumbnailItem } from './camera/CaptureThumbnailStrip';
+export { IncrementalPanGuide } from './camera/IncrementalPanGuide';
+export { PanoramaBandOverlay } from './camera/PanoramaBandOverlay';
+export { PanoramaGuidance } from './camera/PanoramaGuidance';
+export {
+  PanoramaSettingsModal,
+  DEFAULT_PANORAMA_SETTINGS,
+} from './camera/PanoramaSettingsModal';
+export type { PanoramaSettings } from './camera/PanoramaSettingsModal';
+export { ViewportCropOverlay } from './camera/ViewportCropOverlay';
+
+// ── Capture hooks ─────────────────────────────────────────────────────
+// vision-camera wrappers (useCapture / useVideoCapture) + a
+// device-orientation reader that works under iOS portrait-lock.
+export { useCapture } from './camera/useCapture';
+export type { TakePhotoCallOptions } from './camera/useCapture';
+export { useVideoCapture } from './camera/useVideoCapture';
+export { useDeviceOrientation } from './camera/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).
+export {
+  IncrementalOutcome,
+  incrementalStitcherIsAvailable,
+  subscribeIncrementalState,
+  getIncrementalNativeModule,
+  cleanupOldKeyframes,
+} from './stitching/incremental';
+export type { IncrementalState } from './stitching/incremental';
+export { useIncrementalStitcher } from './stitching/useIncrementalStitcher';
+export { useIncrementalJSDriver } from './stitching/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.
+export { stitchVideo } from './stitching/stitchVideo';

package/src/utils/files.ts

@@ -0,0 +1,97 @@
+// 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).
+ */
+
+import { NativeModules } from 'react-native';
+
+
+interface FileUtilsBridge {
+  moveFile(from: string, to: string): Promise<string>;
+  defaultCaptureDir(): Promise<string>;
+}
+
+
+function bridge(): FileUtilsBridge | null {
+  const m = (NativeModules as Record<string, unknown>).RNImageStitcherFileUtils;
+  if (!m || typeof m !== 'object') return null;
+  return m as FileUtilsBridge;
+}
+
+
+/**
+ * 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 async function moveFile(from: string, to: string): Promise<string> {
+  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: string | null = 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.
+ */
+export async function getDefaultCaptureDir(): Promise<string> {
+  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.
+ */
+export function defaultPhotoFilename(): string {
+  return `photo-${Date.now()}.jpg`;
+}
+
+
+/**
+ * Same as `defaultPhotoFilename` but for panoramas.
+ */
+export function defaultPanoramaFilename(): string {
+  return `panorama-${Date.now()}.jpg`;
+}

package/src/utils/paths.ts

@@ -0,0 +1,42 @@
+// 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.)
+ */
+
+/** Add the `file://` scheme to a bare path, idempotently. */
+export function toFileUri(path: string | null | undefined): string {
+  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. */
+export function toBareFilePath(path: string | null | undefined): string {
+  if (!path) return '';
+  if (path.startsWith('file://')) return path.slice('file://'.length);
+  return path;
+}