react-native-image-stitcher 0.11.1 → 0.13.0

package/CHANGELOG.md

@@ -16,6 +16,157 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] — 2026-05-29
+
+### Added — Layer-2 components absorbed into `<Camera>` (opt-out)
+
+The flagship `<Camera>` now ships built-in defaults for every UX
+chrome piece previously exposed only as a Layer-2 component.  Hosts
+adopting `<Camera>` directly get a complete capture surface — flash
+button, pan-speed pill, drift-marker guide, header chrome,
+capture-history strip, and post-stitch preview — without having to
+import and wire each piece by hand.
+
+All built-ins use the opt-out pattern: enabled by default, disabled
+by setting the corresponding boolean to `false` or by omitting the
+corresponding payload prop.  Hosts that want their own chrome can
+opt out per piece and layer custom UI on top of `<Camera>` (the
+Layer-2 components remain exported and are unchanged).
+
+#### Flash control
+
+- `flash?: 'on' | 'off'` — controlled torch state.  Omit to let
+  `<Camera>` own it internally.
+- `onFlashChange?` — fires on tap (controlled and uncontrolled both).
+- `showFlashButton?: boolean` (default `true`) — built-in flash button
+  in the bottom-left slot.  AR mode auto-disables (ARKit / ARCore own
+  the device's torch; surfaces "Flash unavailable in AR mode" a11y
+  label and greyed styling).
+
+#### Pan guidance
+
+- `panGuide?: boolean` (default `true`) — built-in
+  `IncrementalPanGuide` ("keep the arrow on the line" drift marker).
+- `panoramaGuidance?: boolean` (default `true`) — built-in
+  `PanoramaGuidance` pan-speed pill.
+- Both are gyroscope-driven and only subscribe to the sensor while
+  recording — no idle cost.
+
+#### Header
+
+- `headerTitle?: string` — when set, renders a built-in
+  `CaptureHeader` at the top of the screen.  The existing settings
+  gear is absorbed into the header's right side (no duplicate gear).
+- `onHeaderBack?`, `headerBackLabel?`, `headerGuidance?`,
+  `headerColors?` — pass-through to `CaptureHeader`.
+
+#### Capture history + preview
+
+- `thumbnails?: CaptureThumbnailItem[]` — when supplied (even `[]`),
+  renders the built-in `CaptureThumbnailStrip` above the bottom
+  controls.  Hidden during recording so it doesn't overlap the
+  panorama band overlay.
+- `thumbnailsMin?`, `thumbnailsMax?` — count-line hints.
+- `onThumbnailPress?` — replaces the strip's built-in
+  tap-to-preview modal with a host handler.
+- `capturePreview?` — when set, renders a built-in `CapturePreview`
+  modal showing the supplied image.  Use for post-stitch
+  confirmation; the host clears the prop on dismiss via
+  `onCapturePreviewClose`.
+- `capturePreviewActions?` — pass-through action buttons for the
+  preview modal.
+
+### Migration
+
+- Hosts that were importing Layer-2 components (`CaptureHeader`,
+  `CaptureControlsBar`, `IncrementalPanGuide`, `PanoramaGuidance`,
+  `CaptureThumbnailStrip`, `CapturePreview`) directly can now drop
+  those imports and use the corresponding `<Camera>` props.
+- The Layer-2 components remain exported and unchanged in v0.13 for
+  backward compatibility.  Deprecation of those exports is targeted
+  for v0.14.
+- No behaviour change for hosts that already use `<Camera>` and
+  don't supply any of the new props — every new built-in defaults
+  to the previous (omitted) UX, except the flash button which
+  appears in the now-occupied bottom-left slot.  Hosts that previously
+  rendered chrome in that slot above `<Camera>` can pass
+  `showFlashButton={false}`.
+
+## [0.12.0] — 2026-05-28
+
+### Added — Orientation-aware `<Camera>` (R2-lite)
+
+`<Camera>` now works correctly under both portrait-locked and
+non-locked iOS hosts.  Pre-v0.12 the component assumed the host
+had restricted `UISupportedInterfaceOrientations` to Portrait;
+removing that restriction broke control layout, camera-preview
+rotation across modal close, and panorama capture mode selection.
+
+Five coupled changes:
+
+1. **`useOrientationDrift` hook + `OrientationDriftModal`**
+   (PR-1).  Snapshots device orientation at capture start and
+   latches a `drifted: true` flag if the user rotates mid-
+   capture.  The incremental engine doesn't support cross-
+   orientation captures (per the engine spec at
+   `incremental.ts:373-403`), so `<Camera>` auto-cancels via
+   `incremental.cancel()` and shows the modal to explain.
+
+2. **New `onCaptureAbandoned` prop** on `<Camera>`.  Fires when
+   the SDK auto-cancels an in-flight capture.  Currently the only
+   reason is `'orientation-drift'`; the union signature keeps the
+   prop stable for future reasons (low memory, etc.).
+
+3. **4-way home-indicator-edge anchor** for the bottom-controls
+   row (Layer A).  Combines `useWindowDimensions()` and
+   `useDeviceOrientation()` to compute the JS edge that
+   corresponds to the device's home-indicator side, then anchors
+   shutter / lens / AR toggle there.  Matches iOS Camera's
+   behaviour: shutter stays within thumb reach regardless of tilt.
+
+4. **AR `takePhoto` orientation parameter** (Fix #2).  Pre-v0.12
+   `RNSARSession.takePhoto` hardcoded `.right` (90° CW) to
+   rotate ARKit's sensor-native landscape buffer to portrait,
+   assuming portrait hold.  Now switches on the device
+   orientation passed from `useDeviceOrientation()` so landscape
+   captures produce correctly-oriented photos.
+
+5. **Modal `supportedOrientations={[all 4]}`** on
+   `OrientationDriftModal` and `PanoramaSettingsModal`.  RN's iOS
+   `Modal` defaults to portrait-only, which force-rotates the
+   window scene when opened under a non-locked host — leaving
+   the underlying `<Camera>`'s ARSession with stale orientation
+   state on dismiss (preview rendered sideways).  Declaring all
+   four orientations keeps the window aligned through the modal
+   cycle.
+
+### Added — Comment cleanup across native + JS surfaces
+
+Stale "portrait-locked host" comments in
+`useDeviceOrientation.ts`, `incremental.ts`, `StitcherFrame.ts`,
+`OpenCVIncrementalStitcher.{h,mm}`, and
+`IncrementalFirstwinsEngine.kt` rewritten to acknowledge both
+host configurations.  Pose-derived orientation detection remains
+the single source of truth — that didn't change; the rationale
+just got more accurate.
+
+### Known follow-ups (deferred to v0.12.1 or v0.13)
+
+- Portrait + non-AR stitching can regress under fast horizontal
+  pans — likely drift detection over-firing on lateral
+  acceleration.  Needs debounce or motion-aware threshold.
+- Component-render tests (`<OrientationDriftModal>`,
+  `<PanoramaBandOverlay>` per-orientation, `<ViewportCropOverlay>`
+  per-orientation, `<Camera>` composition) need
+  `@testing-library/react-native` + a jest preset flip.  Tracked
+  for v0.12.1.
+- Portrait-upside-down landscape detection on non-locked hosts —
+  the JS dims signal is ambiguous between locked-portrait + flipped
+  device and non-locked + screen-flipped-180°.  Needs a separate
+  signal.
+- Slot/hybrid API on `<Camera>` to absorb `CaptureControlsBar`,
+  `IncrementalPanGuide`, `PanoramaGuidance`, etc. — v0.13.
+
 ## [0.11.1] — 2026-05-28
 
 ### Fixed — AR-mode composed worklets silently throw

package/README.md

@@ -140,6 +140,34 @@ See `src/camera/Camera.tsx` for the full TSDoc.  Highlights:
 | `onFramesDropped(info)` | cv::Stitcher's confidence retry loop dropped one or more input frames. |
 | `onError(err)` | Classified error.  `err.code` from a known taxonomy (`STITCH_NEED_MORE_IMGS`, `STITCH_HOMOGRAPHY_FAIL`, `STITCH_CAMERA_PARAMS_FAIL`, `STITCH_OOM`, `CAMERA_PERMISSION_DENIED`, etc.). |
 
+## Orientation support
+
+`<Camera>` works in any device orientation regardless of host
+configuration.  No host setup required — the SDK adapts at runtime.
+
+**Portrait-locked host** (Info.plist `UISupportedInterfaceOrientations`
+restricted to Portrait — recommended for kiosks / single-task apps):
+the screen stays portrait; the SDK uses sensor-derived orientation
+for capture-mode selection and overlay layout.  This is the simpler
+configuration and the historical default.
+
+**Non-locked host** (Info.plist supports all 4 orientations — recommended
+for apps with other landscape-friendly screens): the screen rotates
+with the device.  `<Camera>`'s controls (shutter, lens chip, AR toggle)
+anchor to the home-indicator edge so they stay within thumb reach
+regardless of tilt — matching iOS Camera's behaviour.  The
+orientation-aware logic combines `useWindowDimensions()` (JS-layout)
+with `useDeviceOrientation()` (sensor) to compute the correct anchor.
+
+**Mid-capture rotation safety** — the incremental engine doesn't
+support cross-orientation captures (a portrait capture's keyframes
+can't be mixed with landscape-pan frames).  If the user rotates
+mid-capture, `<Camera>` auto-abandons via `incremental.cancel()`,
+fires `onCaptureAbandoned('orientation-drift')` if the host wired
+the callback, and shows the `OrientationDriftModal` to explain why.
+Host opt-in via the `onCaptureAbandoned` prop — the default UX is
+the modal alone.
+
 ## Lens ↔ AR interaction
 
 | Action | `arPreference` | `lens` | UI |

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

@@ -38,8 +38,9 @@ import kotlin.math.sqrt
  *   V12.4 — central 70% (pan) × 85% (perpendicular) post-warp crop
  *   V12.6 — orientation detection from R_panToCam at first frame
  *           (NOT from JS-passed frameRotationDegrees, which is wrong
- *           under iOS interface-orientation lock — Android equivalent
- *           is screen-orientation lock; same fix applies)
+ *           under portrait-locked hosts — pose-derived detection
+ *           works regardless of host orientation config, so it's
+ *           the single source of truth)
  *   V12.7 — rectilinear path: skip cylindrical warp entirely.  First
  *           frame pasted raw onto canvas; subsequent frames contribute
  *           a narrow central strip placed by pose-delta around the

package/dist/camera/ARCameraView.d.ts

@@ -60,6 +60,16 @@ export interface ARCameraViewHandle {
      */
     takePhoto: (options?: {
         quality?: number;
+        /**
+         * v0.12.0 — device orientation at capture time, used to bake
+         * correct rotation into the saved JPEG.  Pass the value from
+         * `useDeviceOrientation()`.  Defaults to `'portrait'` on the
+         * native side if omitted (preserves pre-v0.12 behavior).
+         * Without this, AR-mode photos taken in landscape come out
+         * sideways because the native side previously hardcoded the
+         * rotate-to-portrait assumption.
+         */
+        orientation?: 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right';
     }) => Promise<{
         path: string;
         width: number;

package/dist/camera/ARCameraView.js

@@ -90,6 +90,7 @@ exports.ARCameraView = (0, react_1.forwardRef)(function ARCameraView({ style, gu
             return native.takePhoto({
                 path: '',
                 quality: options.quality ?? 90,
+                orientation: options.orientation ?? 'portrait',
             });
         },
         startRecording: (options) => {

package/dist/camera/Camera.d.ts

@@ -41,6 +41,9 @@
 import React from 'react';
 import { type StyleProp, type ViewStyle } from 'react-native';
 import type { DrawableFrameProcessor, ReadonlyFrameProcessor } from 'react-native-vision-camera';
+import { type CaptureHeaderProps } from './CaptureHeader';
+import { type CapturePreviewAction } from './CapturePreview';
+import { type CaptureThumbnailItem } from './CaptureThumbnailStrip';
 export type CaptureSource = 'ar' | 'non-ar';
 export type CameraLens = '1x' | '0.5x';
 export type StitchMode = 'auto' | 'panorama' | 'scans';
@@ -191,6 +194,194 @@ export interface CameraProps {
     onLensChange?: (lens: CameraLens) => void;
     onFramesDropped?: (info: FramesDroppedInfo) => void;
     onError?: (err: CameraError) => void;
+    /**
+     * v0.12.0 — fires when the SDK auto-abandons an in-progress
+     * capture without producing output.  `reason` is a string union
+     * so future reasons (network loss, low memory, etc.) can be added
+     * without breaking the callback signature.
+     *
+     * Currently the only reason in v0.12 is `'orientation-drift'`:
+     * the user rotated the device between Mode A (landscape + vertical
+     * pan) and Mode B (portrait + horizontal pan) mid-capture.  The
+     * engine docstring at `incremental.ts:373-403` is explicit that
+     * cross-mode capture is "best-effort, not supported," so the SDK
+     * decisively cancels the capture (`incremental.cancel()`) and
+     * surfaces `OrientationDriftModal` to explain what happened.
+     *
+     * Hosts use this callback to clean up their own state (e.g., reset
+     * a wizard step, log telemetry, surface their own retry UX in
+     * addition to the SDK's built-in modal).  No `onCapture` will fire
+     * for an abandoned capture.
+     */
+    onCaptureAbandoned?: (reason: 'orientation-drift') => void;
+    /**
+     * v0.13.0 — flash (torch) state.  Controlled-or-uncontrolled.
+     *
+     *   - **Uncontrolled** (omit `flash`): `<Camera>` owns the flash
+     *     state internally.  Tapping the built-in flash button toggles
+     *     it on/off.  `onFlashChange` (if supplied) fires for telemetry.
+     *   - **Controlled** (supply `flash`): the parent owns the state.
+     *     The built-in button still renders and fires `onFlashChange`
+     *     on press, but it's a no-op unless the parent updates `flash`
+     *     in response.
+     *
+     * Both shapes coexist with the v0.13 "flash button is on by default"
+     * built-in (see the bottom-left bar slot in the JSX).  Hosts that
+     * want their own flash chrome can opt out via `showFlashButton={false}`
+     * and drive the underlying torch by controlling `flash` directly.
+     *
+     * ## AR-mode behaviour
+     *
+     * In AR mode (`defaultCaptureSource="ar"` or runtime-toggled),
+     * ARKit / ARCore own the `AVCaptureDevice` and don't expose the
+     * torch through vision-camera's pipeline.  The built-in flash
+     * button renders as visibly disabled (a11y label "Flash unavailable
+     * in AR mode") and `flash` is forced to `'off'` regardless of
+     * controlled/uncontrolled state.  Hosts that need flash should
+     * toggle to non-AR before enabling.
+     */
+    flash?: 'on' | 'off';
+    /**
+     * v0.13.0 — fires when the user taps the built-in flash button.
+     * In uncontrolled mode, the internal state has already flipped
+     * (single render delay).  In controlled mode, the parent must
+     * update the `flash` prop in response or the visual toggle is
+     * a no-op.  Useful in either mode for telemetry.
+     */
+    onFlashChange?: (next: 'on' | 'off') => void;
+    /**
+     * v0.13.0 — show the built-in flash button in the bottom-left
+     * slot.  Defaults to `true`.  Hosts that render their own flash
+     * chrome (and drive the underlying torch via the controlled
+     * `flash` prop) can opt out by setting this to `false`.
+     */
+    showFlashButton?: boolean;
+    /**
+     * v0.13.0 — show the built-in IncrementalPanGuide ("keep the
+     * arrow on the line" drift marker) while recording.  Defaults
+     * to `true`.  The guide is gyroscope-driven and only active
+     * during the recording phase (no idle sensor cost).  Hosts that
+     * want their own pan-guide chrome can opt out via `false`.
+     */
+    panGuide?: boolean;
+    /**
+     * v0.13.0 — show the built-in PanoramaGuidance pan-speed pill
+     * ("Pan slowly" / "Slow down" / "Too fast") while recording.
+     * Defaults to `true`.  Gyroscope-driven, only active during
+     * recording.  Hosts that want their own speed chrome can opt
+     * out via `false`.
+     */
+    panoramaGuidance?: boolean;
+    /**
+     * v0.13.0 — built-in CaptureHeader title.  When set, `<Camera>`
+     * renders a top-of-screen header showing this title (centred)
+     * with an optional back affordance + guidance subtitle + the
+     * existing settings gear absorbed into the header's right side.
+     *
+     * When `headerTitle` is undefined the header is not rendered
+     * (matches pre-v0.13 behaviour: top of preview is bare except
+     * for the standalone settings gear gated on `showSettingsButton`).
+     *
+     * Combine with `onHeaderBack`, `headerBackLabel`, `headerGuidance`,
+     * and `headerColors` to customise the rest of the header.  Hosts
+     * that need richer header chrome can omit `headerTitle` and
+     * compose their own `<CaptureHeader>` above `<Camera>`.
+     */
+    headerTitle?: string;
+    /**
+     * v0.13.0 — header back-button callback.  When supplied (and
+     * `headerTitle` is set), the header renders a back affordance
+     * on the left.  Omitted ⇒ no back button (the title stays
+     * centred).
+     */
+    onHeaderBack?: () => void;
+    /**
+     * v0.13.0 — header back-button label.  Defaults to "‹ Back".
+     * No effect unless `headerTitle` and `onHeaderBack` are both set.
+     */
+    headerBackLabel?: string;
+    /**
+     * v0.13.0 — optional second-line subtitle shown below the
+     * header title.  E.g. "Photograph the promotional cola end cap."
+     * Renders nothing when undefined.  No effect unless `headerTitle`
+     * is set.
+     */
+    headerGuidance?: string;
+    /**
+     * v0.13.0 — colour overrides for the built-in header.  Defaults
+     * are white-on-black to stay legible over the camera preview.
+     * No effect unless `headerTitle` is set.
+     */
+    headerColors?: CaptureHeaderProps['colors'];
+    /**
+     * v0.13.0 — when provided (even as `[]`), `<Camera>` renders a
+     * built-in `CaptureThumbnailStrip` above the bottom controls
+     * showing the host's capture history.  Each item is a plain
+     * `{ id, uri, width?, height? }` object; the strip handles
+     * aspect-ratio rendering, tap-to-preview, and the count line.
+     *
+     * Omit (`undefined`) to skip the strip entirely.  Hosts using
+     * the strip independently (e.g. on a non-camera screen) can keep
+     * importing `CaptureThumbnailStrip` directly from the library —
+     * the prop here is the convenience wiring for in-`<Camera>` use.
+     *
+     * Captures emitted by `<Camera>`'s `onCapture` are NOT added to
+     * this array automatically — the host owns the canonical list
+     * (typically persisted to its own DB) and updates the prop in
+     * response.  This matches the SDK's "Camera owns runtime state,
+     * host persists" pattern.
+     */
+    thumbnails?: CaptureThumbnailItem[];
+    /**
+     * v0.13.0 — minimum-photos hint for the count line.  Renders
+     * "n / minPhotos min" with the success colour when reached,
+     * warning colour otherwise.
+     */
+    thumbnailsMin?: number;
+    /**
+     * v0.13.0 — maximum-photos hint for the count line.  Renders
+     * "· maxPhotos max" suffix.  No enforcement — the host decides
+     * what to do at the cap.
+     */
+    thumbnailsMax?: number;
+    /**
+     * v0.13.0 — tap handler for thumbnails.  When set, replaces the
+     * strip's built-in tap-to-preview modal; the host shows its own
+     * preview UI (e.g. with delete / recapture buttons gated on
+     * sync state).  Omit to use the built-in preview.
+     */
+    onThumbnailPress?: (item: CaptureThumbnailItem) => void;
+    /**
+     * v0.13.0 — when set, `<Camera>` renders a built-in `CapturePreview`
+     * modal as `visible`.  Use this for post-stitch confirmation:
+     * after `onCapture` emits, the host stores the result and sets
+     * `capturePreview` to the new image, with `capturePreviewActions`
+     * = `[Discard, Save]` (or similar).  Setting `undefined` hides
+     * the modal.
+     *
+     * Hosts using the modal for thumbnail tap-to-preview can leave
+     * this undefined and let the built-in strip's preview handle
+     * that case.
+     */
+    capturePreview?: {
+        imageUri: string;
+        imageWidth?: number;
+        imageHeight?: number;
+        title?: string;
+    };
+    /**
+     * v0.13.0 — action buttons rendered along the bottom of the
+     * `CapturePreview` modal.  Empty array (or undefined) renders
+     * no buttons, only the close affordance.
+     */
+    capturePreviewActions?: CapturePreviewAction[];
+    /**
+     * v0.13.0 — fires when the user dismisses the `capturePreview`
+     * modal (tap close, backdrop tap, hardware back on Android).
+     * The host is expected to clear the `capturePreview` prop in
+     * response.
+     */
+    onCapturePreviewClose?: () => void;
     /**
      * Optional host-supplied vision-camera frame processor.
      *