react-native-image-stitcher 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -16,7 +16,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.1.0] — TBD
+## [0.1.1] — 2026-05-20
+
+### Added
+
+- **Layer 2 building blocks now public.**  The lower-level views,
+  hooks, and stitching-engine bindings that previously lived behind
+  the `<Camera>` wrapper are now exported from the package root.
+  Use these when `<Camera>` doesn't give you enough control — e.g.,
+  when you're hand-composing your own capture screen on top of the
+  same proven primitives.  Full list:
+  - Views: `ARCameraView`, `CameraView` (+ their handle/prop types).
+  - UI components: `CaptureHeader`, `CaptureControlsBar`,
+    `CapturePreview`, `CaptureStatusOverlay`, `CaptureThumbnailStrip`,
+    `IncrementalPanGuide`, `PanoramaBandOverlay`, `PanoramaGuidance`,
+    `PanoramaSettingsModal` (+ `DEFAULT_PANORAMA_SETTINGS` constant +
+    `PanoramaSettings` type), `ViewportCropOverlay`.
+  - Hooks: `useCapture`, `useVideoCapture`, `useDeviceOrientation`,
+    `useIncrementalStitcher`, `useIncrementalJSDriver`.
+  - Engine: `IncrementalOutcome`, `incrementalStitcherIsAvailable`,
+    `subscribeIncrementalState`, `getIncrementalNativeModule`,
+    `cleanupOldKeyframes`, `IncrementalState` (type).
+  - Batch stitching: `stitchVideo`.
+- The 0.1.0 → 1.0 stability gate still applies — the goal of
+  surfacing layer 2 is to support advanced consumers (e.g.,
+  `retailens-camera-sdk`) without forcing them to deep-import
+  package internals.  These are likely to keep their shape through
+  1.0, but the contract is not formally stable until then.
+
+### Changed
+
+- README now documents both layers and recommends `<Camera>` as the
+  default starting point.
+
+### Fixed
+
+(No bug fixes in this release — see 0.1.0 for the device-verified
+camera lifecycle fixes that shipped with the initial release.)
+
+## [0.1.0] — 2026-05-20
 
 First public release.
 

package/dist/index.d.ts

@@ -1,21 +1,23 @@
 /**
  * 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.
  */
 export { Camera, CameraError } from './camera/Camera';
 export type { CameraProps, CameraCaptureResult, CameraErrorCode, CaptureSource, CameraLens, StitchMode, Blender, SeamFinder, Warper, FramesDroppedInfo, } from './camera/Camera';
@@ -23,4 +25,30 @@ export { useARSession, ARTrackingState } from './ar/useARSession';
 export type { UseARSessionReturn, FramePose, } from './ar/useARSession';
 export { useIMUTranslationGate } from './sensors/useIMUTranslationGate';
 export type { UseIMUTranslationGateOptions, UseIMUTranslationGateReturn, } from './sensors/useIMUTranslationGate';
+export { ARCameraView } from './camera/ARCameraView';
+export type { ARCameraViewHandle, ARCameraViewProps } from './camera/ARCameraView';
+export { CameraView } from './camera/CameraView';
+export type { CameraViewProps } from './camera/CameraView';
+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';
+export { useCapture } from './camera/useCapture';
+export { useVideoCapture } from './camera/useVideoCapture';
+export { useDeviceOrientation } from './camera/useDeviceOrientation';
+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';
+export { stitchVideo } from './stitching/stitchVideo';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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/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,76 @@ 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 { 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';