react-native-image-stitcher 0.14.2 → 0.15.1

package/dist/camera/PanoramaSettingsBridge.js

@@ -43,8 +43,6 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.panoramaSettingsToNativeConfig = panoramaSettingsToNativeConfig;
-exports.slitscanSettingsToNativeConfig = slitscanSettingsToNativeConfig;
-exports.hybridSettingsToNativeConfig = hybridSettingsToNativeConfig;
 const PanoramaSettings_1 = require("./PanoramaSettings");
 /**
  * Convert a v0.4 PanoramaSettings tree into the flat dict the
@@ -69,6 +67,9 @@ function panoramaSettingsToNativeConfig(s) {
         frameSelectionMode: s.frameSelection.mode,
         keyframeMaxCount: s.frameSelection.maxKeyframes,
         keyframeOverlapThreshold: s.frameSelection.overlapThreshold,
+        // Time-budget force-accept (both strategies).  Native reads
+        // configOverrides["maxKeyframeIntervalMs"] → setMaxKeyframeIntervalMs.
+        maxKeyframeIntervalMs: s.frameSelection.maxKeyframeIntervalMs,
     };
     // Flow strategy knobs — always serialised, regardless of
     // `frameSelection.mode`.  Two reasons:
@@ -105,104 +106,4 @@ function panoramaSettingsToNativeConfig(s) {
     cfg.flowMinDistance = f.minDistance;
     return cfg;
 }
-/**
- * Convert a v0.4 SlitscanSettings tree into the flat dict the
- * slit-scan / firstwins native engines read.  Handles the
- * "presence-as-enable" boolean expansion: a non-undefined
- * `registration.ncc1d` means `enable1dNcc: true` on the wire,
- * with the sub-object's `searchRadius` carried alongside.
- *
- * Verified against:
- *   - iOS  `IncrementalStitcher.swift:1006-1100` (applyConfigOverrides)
- *   - iOS  `OpenCVSlitScanStitcher.mm` (all numbered references in
- *          the audit ground-truth matrix)
- */
-function slitscanSettingsToNativeConfig(s) {
-    const cfg = {
-        captureSource: s.captureSource,
-        // The native side reads `engine: 'slitscan-…'` at start time
-        // from a separate top-level field, NOT from configOverrides.
-        // We still serialise the variant here for hosts that want to
-        // round-trip a single settings object through both surfaces.
-        engineVariant: s.variant,
-        // ── Painting ─────────────────────────────────────────────────
-        paintMode: s.painting.paintMode,
-        sliverPosition: s.painting.sliverPosition,
-        firstFrameFullFrame: s.painting.firstFrameFullFrame,
-        // ── Registration (explicit booleans) ─────────────────────────
-        enableTriangulation: s.registration.enableTriangulation,
-        enableTriAccumulator: s.registration.enableTriAccumulator,
-        enableRansacHomography: s.registration.enableRansacHomography,
-        // ── Plane projection ─────────────────────────────────────────
-        planeSource: s.plane.source,
-    };
-    // ── 1D NCC: presence-as-enable ─────────────────────────────────
-    if (s.registration.ncc1d) {
-        cfg.enable1dNcc = true;
-        cfg.nccSearchRadius1d = s.registration.ncc1d.searchRadius;
-    }
-    else {
-        cfg.enable1dNcc = false;
-    }
-    // ── 2D NCC: presence-as-enable + nested optionals ──────────────
-    if (s.registration.ncc2d) {
-        const n2 = s.registration.ncc2d;
-        cfg.enable2dNcc = true;
-        cfg.nccSearchMargin2d = n2.searchMargin;
-        cfg.nccConfidenceThreshold2d = n2.confidenceThreshold;
-        if (n2.emaSmoothing) {
-            cfg.enableNcc2dEmaSmoothing = true;
-            cfg.ncc2dEmaAlpha = n2.emaSmoothing.alpha;
-        }
-        else {
-            cfg.enableNcc2dEmaSmoothing = false;
-        }
-        if (n2.panAxisLock) {
-            cfg.enableNcc2dPanAxisLock = true;
-            cfg.ncc2dCrossAxisLockPx = n2.panAxisLock.crossAxisLockPx;
-        }
-        else {
-            cfg.enableNcc2dPanAxisLock = false;
-        }
-    }
-    else {
-        cfg.enable2dNcc = false;
-    }
-    // ── Plane optionals ────────────────────────────────────────────
-    // Only emit when `source` actually consumes the field.  Native
-    // tolerates unsolicited keys but the modal also walks the dict
-    // to decide which sliders to render — extra keys would mislead.
-    if (s.plane.source !== 'Disabled' && s.plane.projectionStyle !== undefined) {
-        cfg.planeProjectionStyle = s.plane.projectionStyle;
-    }
-    if (s.plane.source === 'Virtual' && s.plane.virtualDepthMeters !== undefined) {
-        cfg.virtualPlaneDepthMeters = s.plane.virtualDepthMeters;
-    }
-    if (s.plane.source === 'ARKitDetected' && s.plane.alignmentThreshold !== undefined) {
-        cfg.arkitPlaneAlignmentThreshold = s.plane.alignmentThreshold;
-    }
-    // ── Advanced motion knobs (only emit if explicitly set) ────────
-    if (s.advanced?.panAxisFractionRect !== undefined) {
-        cfg.kPanAxisFractionRect = s.advanced.panAxisFractionRect;
-    }
-    if (s.advanced?.minAcceptDeltaPx !== undefined) {
-        cfg.kMinAcceptDeltaPx = s.advanced.minAcceptDeltaPx;
-    }
-    return cfg;
-}
-/**
- * Convert a v0.4 HybridSettings tree into the flat dict the hybrid
- * engine reads.  Minimal surface — hybrid presets internally clobber
- * almost everything; see HybridSettings JSDoc for context.
- *
- * Verified against:
- *   - iOS  `OpenCVIncrementalStitcher.mm:139-180` (preset paths)
- *   - iOS  `IncrementalStitcher.swift:1034-1040` (hybridProjection override)
- */
-function hybridSettingsToNativeConfig(s) {
-    return {
-        captureSource: s.captureSource,
-        hybridProjection: s.projection,
-    };
-}
 //# sourceMappingURL=PanoramaSettingsBridge.js.map

package/dist/camera/PanoramaSettingsModal.js

@@ -187,6 +187,12 @@ function PanoramaSettingsModal({ visible, settings, onChange, onClose, }) {
                         react_1.default.createElement(SegmentedControl, { options: ['20%', '30%', '40%', '50%', '60%'], value: `${Math.round(settings.frameSelection.overlapThreshold * 100)}%`, onChange: (v) => updateFrameSelection({
                                 overlapThreshold: parseInt(v, 10) / 100,
                             }), caption: "Required NEW-content fraction.  20% (default): generous, ~5\u20136 keyframes for a 90\u00B0 pan.  Native clamps to [10%, 80%]." }),
+                        react_1.default.createElement(SectionHeader, { title: "Keyframe interval (time-budget force-accept)" }),
+                        react_1.default.createElement(SegmentedControl, { options: ['off', '1s', '2s', '3s', '5s'], value: settings.frameSelection.maxKeyframeIntervalMs === 0
+                                ? 'off'
+                                : `${settings.frameSelection.maxKeyframeIntervalMs / 1000}s`, onChange: (v) => updateFrameSelection({
+                                maxKeyframeIntervalMs: v === 'off' ? 0 : parseInt(v, 10) * 1000,
+                            }), caption: "Force-accept a keyframe at least this often even if novelty is low, so slow / static pans don't leave gaps.  Counts toward the keyframe cap.  off = disabled.  2s (default).  Applies to AR + non-AR." }),
                         showFlowTunables && (react_1.default.createElement(react_native_1.View, { style: styles.nested },
                             react_1.default.createElement(react_native_1.Text, { style: styles.nestedLabel }, "Flow tuning"),
                             react_1.default.createElement(SectionHeader, { title: "Max corners (Shi-Tomasi)" }),
@@ -233,7 +239,7 @@ function PanoramaSettingsModal({ visible, settings, onChange, onClose, }) {
                         react_1.default.createElement(SectionHeader, { title: "Inscribed-rect crop" }),
                         react_1.default.createElement(SegmentedControl, { options: ['off', 'on'], value: settings.stitcher.enableMaxInscribedRectCrop ? 'on' : 'off', onChange: (v) => updateStitcher({
                                 enableMaxInscribedRectCrop: v === 'on',
-                            }), caption: "off (default): crop to cv::boundingRect of non-black pixels \u2014 preserves all stitched content; may leave black corners.  on: run MaxInscribedRectFromMask + column-projection second-pass for a clean rectangle (can shrink output if mask is lopsided)." })),
+                            }), caption: "off (default): crop to cv::boundingRect of non-black pixels \u2014 preserves all stitched content; may leave black corners.  on: run MaxInscribedRectFromMask + column-projection second-pass for a clean rectangle (can shrink output a lot if mask is lopsided / ultra-wide)." })),
                     react_1.default.createElement(react_native_1.Pressable, { onPress: () => onChange(PanoramaSettings_1.DEFAULT_PANORAMA_SETTINGS), style: styles.resetBtn, accessibilityRole: "button", accessibilityLabel: "Reset to defaults" },
                         react_1.default.createElement(react_native_1.Text, { style: styles.resetText }, "Reset to defaults")))))));
 }

package/dist/camera/buildPanoramaInitialSettings.d.ts

@@ -50,6 +50,17 @@ export interface PanoramaPropOverrides {
     defaultFlowMaxTranslationCm?: number;
     defaultKeyframeMaxCount?: number;
     defaultKeyframeOverlapThreshold?: number;
+    /**
+     * Initial value for `frameSelection.maxKeyframeIntervalMs` — the
+     * time-budget force-accept (ms).  `0` disables it.  Default 2000.
+     */
+    defaultMaxKeyframeIntervalMs?: number;
+    /**
+     * v0.15 — initial value for `stitcher.enableMaxInscribedRectCrop`.
+     * Maps from the standalone `maxInscribedRectCrop` <Camera> prop.
+     * Omitted ⇒ the stitcher default (false = bounding-rect crop).
+     */
+    maxInscribedRectCrop?: boolean;
 }
 /**
  * Whether this device is low-memory enough to benefit from the

package/dist/camera/buildPanoramaInitialSettings.js

@@ -76,12 +76,16 @@ function buildPanoramaInitialSettings(overrides, isLowMemDevice) {
             warperType: overrides.defaultWarper ?? stitcherDefaults.warperType,
             blenderType: overrides.defaultBlender ?? stitcherDefaults.blenderType,
             seamFinderType: overrides.defaultSeamFinder ?? stitcherDefaults.seamFinderType,
+            enableMaxInscribedRectCrop: overrides.maxInscribedRectCrop
+                ?? stitcherDefaults.enableMaxInscribedRectCrop,
         },
         frameSelection: {
             ...base.frameSelection,
             maxKeyframes: overrides.defaultKeyframeMaxCount ?? base.frameSelection.maxKeyframes,
             overlapThreshold: overrides.defaultKeyframeOverlapThreshold
                 ?? base.frameSelection.overlapThreshold,
+            maxKeyframeIntervalMs: overrides.defaultMaxKeyframeIntervalMs
+                ?? base.frameSelection.maxKeyframeIntervalMs,
             flow: {
                 ...flowDefaults,
                 noveltyPercentile: overrides.defaultFlowNoveltyPercentile

package/dist/camera/cameraErrorMessages.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Friendly, action-guiding copy for the *recoverable* stitch-failure
+ * `CameraErrorCode`s — the ones a user can fix by simply re-capturing.
+ * Hosts map these onto an Alert/toast instead of surfacing the raw
+ * cv::Stitcher diagnostic (e.g. "warpRoi too large (8171x12336) —
+ * estimator produced degenerate camera params").
+ *
+ * Returns `null` for every non-recoverable / non-stitch code (permission
+ * denied, device unavailable, generic finalize failure, unknown, ...):
+ * those have no single corrective action to suggest, so the host should
+ * fall back to its generic error display.
+ *
+ * Lives in the SDK (not per-host) so every consumer shows the same
+ * vetted guidance for the same failure — and so the mapping is
+ * unit-testable in isolation.
+ */
+import type { CameraErrorCode } from './Camera';
+export interface UserFacingStitchError {
+    /** Short, friendly alert title. */
+    title: string;
+    /** One-paragraph, plain-language corrective guidance. */
+    message: string;
+}
+/**
+ * Maps a `CameraErrorCode` to friendly, action-guiding alert copy.
+ *
+ * @returns the title+message for a recoverable stitch failure, or `null`
+ *   if `code` has no single user-recoverable action (the host should
+ *   then show its generic error UI).
+ */
+export declare function userFacingStitchError(code: CameraErrorCode): UserFacingStitchError | null;
+//# sourceMappingURL=cameraErrorMessages.d.ts.map

package/dist/camera/cameraErrorMessages.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.userFacingStitchError = userFacingStitchError;
+/**
+ * The four recoverable stitch outcomes, each with copy tuned to its
+ * actual root cause.  `Partial<Record<...>>` keeps the keys
+ * compile-checked against the `CameraErrorCode` union — a renamed or
+ * dropped code breaks the build here rather than silently going
+ * unhandled.
+ */
+const RECOVERABLE_STITCH_GUIDANCE = {
+    // cv::Stitcher ERR_NEED_MORE_IMGS / the manual pipeline's "0 valid
+    // pairwise matches" — the frames simply don't overlap enough to chain.
+    STITCH_NEED_MORE_IMGS: {
+        title: 'Please pan more slowly',
+        message: "There wasn't enough overlap between the frames to stitch them "
+            + 'together — each frame needs to overlap the one before it.',
+    },
+    // Bundle adjuster produced degenerate camera params (the warp canvas
+    // blew past the size guard) — almost always real camera *translation*
+    // breaking PANORAMA mode's pure-rotation assumption, amplified hugely
+    // on the ultra-wide lens.
+    STITCH_CAMERA_PARAMS_FAIL: {
+        title: 'Please pan more slowly',
+        message: 'The view moved too much between frames to line them up — usually '
+            + 'because the phone moved through space rather than just turning. '
+            + 'The ultra-wide (0.5x) lens is especially sensitive to this, so '
+            + 'try 1x for wide scenes.',
+    },
+    // Pairwise homography estimation failed — frames couldn't be aligned.
+    STITCH_HOMOGRAPHY_FAIL: {
+        title: 'Please pan more slowly',
+        message: "The frames couldn't be aligned — keep the phone level and steady so "
+            + 'each frame overlaps the one before it.',
+    },
+    // Ran out of memory finishing the stitch — usually an over-long sweep.
+    STITCH_OOM: {
+        title: 'Try a shorter sweep',
+        message: 'This panorama needs more memory than the device can spare to finish '
+            + '— a shorter, narrower sweep (or 1x for wide scenes) will fit.',
+    },
+};
+/**
+ * Maps a `CameraErrorCode` to friendly, action-guiding alert copy.
+ *
+ * @returns the title+message for a recoverable stitch failure, or `null`
+ *   if `code` has no single user-recoverable action (the host should
+ *   then show its generic error UI).
+ */
+function userFacingStitchError(code) {
+    return RECOVERABLE_STITCH_GUIDANCE[code] ?? null;
+}
+//# sourceMappingURL=cameraErrorMessages.js.map

package/dist/camera/selectCaptureDevice.d.ts

@@ -43,7 +43,11 @@ export interface DeviceLike {
 export type CaptureDeviceMode = 
 /** One multi-cam device spans wide + ultra-wide; switch lenses via zoom. */
 'multicam'
-/** Separate standalone wide + ultra-wide devices; switch by remounting. */
+/**
+ * Ultra-wide reached by remounting a dedicated ultra-wide device on 0.5x
+ * (the 1x primary may be a multi-cam *or* a standalone wide).  Used when
+ * no multi-cam device can reach the ultra-wide by zoom.
+ */
  | 'standalone-uw'
 /** No ultra-wide anywhere; wide-angle only (no 0.5× chip). */
  | 'wide-only';

package/dist/camera/selectCaptureDevice.js

@@ -29,6 +29,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.selectCaptureDevice = selectCaptureDevice;
 exports.zoomForLens = zoomForLens;
 const hasLens = (d, lens) => d.physicalDevices.includes(lens);
+/**
+ * Max `minZoom` a multi-cam device may report and still count as able to
+ * reach the ultra-wide *by zoom*.  Real ultra-wides sit at ~0.5-0.65x, so a
+ * logical device whose zoom range genuinely extends to the ultra-wide reports
+ * `minZoom <= ~0.65`.  A device that only *lists* the ultra-wide (a separate
+ * physical camera on Android/Camera2, not a zoom target) reports
+ * `minZoom = 1.0`.  0.7 cleanly separates the two.
+ */
+const UW_ZOOM_REACH_MAX = 0.7;
 /**
  * Choose the back-camera device(s) for capture.
  *
@@ -59,7 +68,13 @@ function selectCaptureDevice(devices) {
     // (more lenses → more reach), as a stable tiebreak.
     const multicamCandidates = back.filter((d) => d.isMultiCam &&
         hasLens(d, 'wide-angle-camera') &&
-        hasLens(d, 'ultra-wide-angle-camera'));
+        hasLens(d, 'ultra-wide-angle-camera') &&
+        // Must reach the ultra-wide by zoom.  On iOS the virtual device's zoom
+        // range spans it (minZoom ~0.5); on Android a logical device often
+        // *lists* the ultra-wide while its zoom range starts at 1.0 (separate
+        // physical camera, not a zoom target).  If it can't zoom there, it
+        // does NOT qualify -- we fall through to the device-swap path below.
+        d.minZoom <= UW_ZOOM_REACH_MAX);
     if (multicamCandidates.length > 0) {
         const device = multicamCandidates.reduce((best, d) => {
             // torch-bearing wins; then wider zoom span; then more lenses.
@@ -87,8 +102,13 @@ function selectCaptureDevice(devices) {
     //
     // Prefer a torch-bearing wide-angle device as the `1×`/primary mount.
     const wideDevices = back.filter((d) => hasLens(d, 'wide-angle-camera'));
+    // A *true* standalone ultra-wide (its own id, NOT a multi-cam grouping).
+    // We deliberately do NOT fall back to a multi-cam device: mounting a
+    // logical multi-cam yields its WIDE member, not the ultra-wide, so a
+    // "swap" to it would silently show the wrong FOV.  If the only ultra-wide
+    // lives inside a non-zoomable multi-cam device, it is undeliverable and we
+    // hide the chooser (wide-only) below.
     const ultraWide = back.find((d) => !d.isMultiCam && hasLens(d, 'ultra-wide-angle-camera')) ??
-        back.find((d) => hasLens(d, 'ultra-wide-angle-camera')) ??
         null;
     if (wideDevices.length > 0 && ultraWide != null) {
         // Prefer the simplest wide device (fewest extra lenses) with a torch

package/dist/camera/useCapture.js

@@ -109,6 +109,44 @@ function useCapture(options = {}) {
         device = legacyDevice ?? legacyFallback;
         activeZoom = undefined;
     }
+    // v0.15 diagnostic (dev-only) — for the "0.5× pill shows but tapping
+    // doesn't switch the camera" report on Android (Samsung).  Logs the
+    // resolved capture mode + the mounted device's zoom range so logcat
+    // reveals whether `minZoom` actually reaches the ultra-wide.  On
+    // Camera2 the logical multi-camera's zoom range usually starts at 1.0
+    // (the ultra-wide is a separate physical id, not a zoom target), so a
+    // zoom-based 0.5× switch is a silent no-op.
+    (0, react_1.useEffect)(() => {
+        if (!__DEV__)
+            return;
+        const summarise = (d) => d
+            ? {
+                id: d.id,
+                physical: d.physicalDevices,
+                isMultiCam: d.isMultiCam,
+                minZoom: d.minZoom,
+                neutralZoom: d.neutralZoom,
+                maxZoom: d.maxZoom,
+                hasTorch: d.hasTorch,
+            }
+            : null;
+        const back = allDevices.filter((d) => d.position === 'back');
+        // eslint-disable-next-line no-console
+        console.log('[rnimagestitcher] lens-select ' +
+            JSON.stringify({
+                lens: lens ?? null,
+                mode: selection.mode,
+                has0_5x: selection.has0_5x,
+                activeZoom: activeZoom ?? null,
+                selected: summarise(selection.device),
+                ultraWide: summarise(selection.ultraWideDevice),
+                // Full back-camera enumeration — reveals whether a multicam
+                // device merely *lists* the ultra-wide while its zoom range
+                // can't reach it (minZoom ~1.0), and whether a STANDALONE
+                // ultra-wide device exists for the standalone-uw fallback.
+                allBack: back.map(summarise),
+            }));
+    }, [allDevices, selection, lens, activeZoom]);
     // Enumerate ALL physical lens types available on the chosen
     // position so the host can decide whether to render a switcher.
     // Vision-camera's `useCameraDevices()` returns CameraDevice[]; each

package/dist/index.d.ts

@@ -21,6 +21,8 @@
  */
 export { Camera, CameraError } from './camera/Camera';
 export type { CameraProps, CameraCaptureResult, CameraErrorCode, CaptureSource, CaptureSourcesMode, CameraLens, StitchMode, Blender, SeamFinder, Warper, FramesDroppedInfo, } from './camera/Camera';
+export { userFacingStitchError } from './camera/cameraErrorMessages';
+export type { UserFacingStitchError } from './camera/cameraErrorMessages';
 export { useARSession, ARTrackingState } from './ar/useARSession';
 export type { UseARSessionReturn, FramePose, } from './ar/useARSession';
 export { useIMUTranslationGate } from './sensors/useIMUTranslationGate';
@@ -50,9 +52,9 @@ export type { CaptureThumbnailItem } from './camera/CaptureThumbnailStrip';
 export { PanoramaBandOverlay } from './camera/PanoramaBandOverlay';
 export { PanoramaSettingsModal } from './camera/PanoramaSettingsModal';
 export type { PanoramaSettingsModalProps } from './camera/PanoramaSettingsModal';
-export { DEFAULT_PANORAMA_SETTINGS, DEFAULT_FLOW_GATE_SETTINGS, DEFAULT_SLITSCAN_SETTINGS, DEFAULT_HYBRID_SETTINGS, } from './camera/PanoramaSettings';
-export type { CaptureBaseSettings, PanoramaSettings, BatchStitcherSettings, FrameSelectionSettings, FlowGateSettings, SlitscanSettings, SlitscanPaintingSettings, SlitscanRegistrationSettings, SlitscanAdvancedSettings, Ncc1dSettings, Ncc2dSettings, PlaneProjectionSettings, HybridSettings, } from './camera/PanoramaSettings';
-export { panoramaSettingsToNativeConfig, slitscanSettingsToNativeConfig, hybridSettingsToNativeConfig, } from './camera/PanoramaSettingsBridge';
+export { DEFAULT_PANORAMA_SETTINGS, DEFAULT_FLOW_GATE_SETTINGS, } from './camera/PanoramaSettings';
+export type { CaptureBaseSettings, PanoramaSettings, BatchStitcherSettings, FrameSelectionSettings, FlowGateSettings, } from './camera/PanoramaSettings';
+export { panoramaSettingsToNativeConfig, } from './camera/PanoramaSettingsBridge';
 export type { NativeConfigDict } from './camera/PanoramaSettingsBridge';
 export { ViewportCropOverlay } from './camera/ViewportCropOverlay';
 export { useCapture } from './camera/useCapture';
@@ -69,11 +71,6 @@ export type { IncrementalState, AcceptedKeyframe } from './stitching/incremental
 export { useIncrementalStitcher } from './stitching/useIncrementalStitcher';
 export { useKeyframeStream } from './stitching/useKeyframeStream';
 export type { StitcherFrame, StitcherFrameProcessor, ARAnchor, } from './stitching/StitcherFrame';
-export { useFrameProcessor } from './stitching/useFrameProcessor';
-export { useThrottledFrameProcessor } from './stitching/useThrottledFrameProcessor';
-export type { ThrottledFrameProcessorOptions } from './types';
-export { useFrameStream } from './stitching/useFrameStream';
-export type { FrameStreamOptions, SampledFrame } from './types';
 export { useFrameProcessorDriver } from './stitching/useFrameProcessorDriver';
 export type { UseFrameProcessorDriverOptions, FrameProcessorDriverHandle, } from './stitching/useFrameProcessorDriver';
 export { useStitcherWorklet } from './stitching/useStitcherWorklet';

package/dist/index.js

@@ -22,13 +22,18 @@
  * adds RetaiLens-specific features on top.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stitchVideo = exports.useStitcherWorklet = exports.useFrameProcessorDriver = exports.useFrameStream = exports.useThrottledFrameProcessor = exports.useFrameProcessor = exports.useKeyframeStream = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = exports.OrientationDriftModal = exports.useOrientationDrift = exports.useDeviceOrientation = exports.useVideoCapture = exports.useCapture = exports.ViewportCropOverlay = exports.hybridSettingsToNativeConfig = exports.slitscanSettingsToNativeConfig = exports.panoramaSettingsToNativeConfig = exports.DEFAULT_HYBRID_SETTINGS = exports.DEFAULT_SLITSCAN_SETTINGS = exports.DEFAULT_FLOW_GATE_SETTINGS = exports.DEFAULT_PANORAMA_SETTINGS = exports.PanoramaSettingsModal = exports.PanoramaBandOverlay = exports.CaptureThumbnailStrip = exports.useStitchStatsToast = exports.CaptureStitchStatsToast = exports.CaptureOrientationPill = exports.CaptureKeyframePill = exports.CaptureMemoryPill = exports.CaptureDebugOverlay = exports.CaptureStatusOverlay = exports.CapturePreview = exports.CaptureControlsBar = exports.CaptureHeader = exports.CameraView = exports.ARCameraView = exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.CameraError = exports.Camera = void 0;
+exports.stitchVideo = exports.useStitcherWorklet = exports.useFrameProcessorDriver = exports.useKeyframeStream = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = exports.OrientationDriftModal = exports.useOrientationDrift = exports.useDeviceOrientation = exports.useVideoCapture = exports.useCapture = exports.ViewportCropOverlay = exports.panoramaSettingsToNativeConfig = exports.DEFAULT_FLOW_GATE_SETTINGS = exports.DEFAULT_PANORAMA_SETTINGS = exports.PanoramaSettingsModal = exports.PanoramaBandOverlay = exports.CaptureThumbnailStrip = exports.useStitchStatsToast = exports.CaptureStitchStatsToast = exports.CaptureOrientationPill = exports.CaptureKeyframePill = exports.CaptureMemoryPill = exports.CaptureDebugOverlay = exports.CaptureStatusOverlay = exports.CapturePreview = exports.CaptureControlsBar = exports.CaptureHeader = exports.CameraView = exports.ARCameraView = exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.userFacingStitchError = 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; } });
+// Recoverable-stitch-failure → friendly Alert copy.  Hosts call this in
+// their onError handler to surface actionable guidance ("pan more slowly",
+// "pivot in place") instead of the raw cv::Stitcher diagnostic.
+var cameraErrorMessages_1 = require("./camera/cameraErrorMessages");
+Object.defineProperty(exports, "userFacingStitchError", { enumerable: true, get: function () { return cameraErrorMessages_1.userFacingStitchError; } });
 // ─────────────────────────────────────────────────────────────────────
 // AR foundation (public since 0.1.0)
 // ─────────────────────────────────────────────────────────────────────
@@ -106,16 +111,12 @@ Object.defineProperty(exports, "PanoramaSettingsModal", { enumerable: true, get:
 var PanoramaSettings_1 = require("./camera/PanoramaSettings");
 Object.defineProperty(exports, "DEFAULT_PANORAMA_SETTINGS", { enumerable: true, get: function () { return PanoramaSettings_1.DEFAULT_PANORAMA_SETTINGS; } });
 Object.defineProperty(exports, "DEFAULT_FLOW_GATE_SETTINGS", { enumerable: true, get: function () { return PanoramaSettings_1.DEFAULT_FLOW_GATE_SETTINGS; } });
-Object.defineProperty(exports, "DEFAULT_SLITSCAN_SETTINGS", { enumerable: true, get: function () { return PanoramaSettings_1.DEFAULT_SLITSCAN_SETTINGS; } });
-Object.defineProperty(exports, "DEFAULT_HYBRID_SETTINGS", { enumerable: true, get: function () { return PanoramaSettings_1.DEFAULT_HYBRID_SETTINGS; } });
 // Settings → native config adapters.  Layer 2 hosts building their
 // own capture flow on top of `incremental.start()` should always
 // pass the result of the matching adapter as `config`; the bridge is
 // the single source of truth for the JS↔native wire format.
 var PanoramaSettingsBridge_1 = require("./camera/PanoramaSettingsBridge");
 Object.defineProperty(exports, "panoramaSettingsToNativeConfig", { enumerable: true, get: function () { return PanoramaSettingsBridge_1.panoramaSettingsToNativeConfig; } });
-Object.defineProperty(exports, "slitscanSettingsToNativeConfig", { enumerable: true, get: function () { return PanoramaSettingsBridge_1.slitscanSettingsToNativeConfig; } });
-Object.defineProperty(exports, "hybridSettingsToNativeConfig", { enumerable: true, get: function () { return PanoramaSettingsBridge_1.hybridSettingsToNativeConfig; } });
 var ViewportCropOverlay_1 = require("./camera/ViewportCropOverlay");
 Object.defineProperty(exports, "ViewportCropOverlay", { enumerable: true, get: function () { return ViewportCropOverlay_1.ViewportCropOverlay; } });
 // ── Capture hooks ─────────────────────────────────────────────────────
@@ -157,35 +158,11 @@ Object.defineProperty(exports, "useIncrementalStitcher", { enumerable: true, get
 // keyframe, packet detection, server-side analysis, etc.).
 var useKeyframeStream_1 = require("./stitching/useKeyframeStream");
 Object.defineProperty(exports, "useKeyframeStream", { enumerable: true, get: function () { return useKeyframeStream_1.useKeyframeStream; } });
-// v0.8.0 Phase 4a — public host-worklet hook.  Hosts that want a
-// per-frame callback (OCR overlay, packet detection, ML inference)
-// use this to attach a `'worklet'`-prefixed function that fires
-// on the camera producer thread.  Non-AR mode is fully wired
-// today via vision-camera passthrough; AR-mode dispatch is
-// API-stable but registration-only until Phase 4b lands the
-// cross-runtime handoff (the AR runtime iterating the registry).
-// See the hook's docstring + StitcherFrame.ts for the contract.
-var useFrameProcessor_1 = require("./stitching/useFrameProcessor");
-Object.defineProperty(exports, "useFrameProcessor", { enumerable: true, get: function () { return useFrameProcessor_1.useFrameProcessor; } });
-// v0.9.0 Layer 2 — `useThrottledFrameProcessor`.  Throttle gate over
-// `useFrameProcessor` for sub-frame-rate worklet-native processing
-// (native OCR via Vision.framework / ML Kit, TFLite ML detection,
-// LiDAR depth).  The worklet runtime has direct access to
-// `frame.toArrayBuffer()` / `frame.arDepth`; bridge small payloads
-// (bboxes, depth-derived metrics) to JS via `runOnJS`.  For JS-thread
-// JPEG consumers (file-path OCR libs, cloud upload, thumbnail UI),
-// prefer `useFrameStream` (Layer 3, ships in the same release).
-var useThrottledFrameProcessor_1 = require("./stitching/useThrottledFrameProcessor");
-Object.defineProperty(exports, "useThrottledFrameProcessor", { enumerable: true, get: function () { return useThrottledFrameProcessor_1.useThrottledFrameProcessor; } });
-// v0.9.0 Layer 3 — `useFrameStream`.  JS-thread sampled-frame
-// stream over Layer 1 (`save_frame_as_jpeg` vc plugin) + Layer 2
-// (`useThrottledFrameProcessor`).  Use for JS-thread consumers:
-// file-path OCR libs (RN modules), cloud upload, thumbnail UI.
-// For worklet-native processing (Vision/ML Kit as vc plugins,
-// TFLite ML, LiDAR depth), prefer `useThrottledFrameProcessor`
-// (Layer 2) — lower latency, no JPEG roundtrip.
-var useFrameStream_1 = require("./stitching/useFrameStream");
-Object.defineProperty(exports, "useFrameStream", { enumerable: true, get: function () { return useFrameStream_1.useFrameStream; } });
+// NOTE: the host-worklet / frame-stream hooks `useFrameProcessor`,
+// `useThrottledFrameProcessor` and `useFrameStream` (v0.8–v0.9) were
+// archived in the batch-keyframe cleanup — they drove the third-party
+// `__stitcherProxy` observer API, not batch-keyframe capture. Source is
+// preserved under archive/src/stitching/ to build on later.
 // vision-camera Frame Processor driver for non-AR captures.  As
 // of v0.6 the only non-AR driver exported (the legacy
 // `useIncrementalJSDriver` was removed; was deprecated in v0.5).

package/dist/stitching/incremental.d.ts

@@ -403,7 +403,7 @@ export interface IncrementalStartOptions {
      * 'slitscan' fall back to 'slitscan-both' with a deprecation warning
      * in the native log.
      */
-    engine?: 'hybrid' | 'slitscan-rotate' | 'slitscan-both' | 'batch-keyframe' | 'firstwins' | 'firstwins-zoomed' | 'firstwins-rectilinear' | 'slitscan';
+    engine?: 'batch-keyframe';
     /**
      * V15 — per-stage correction config overrides.  Mode-driven defaults
      * are applied first (see RLISStitcherConfig +configForMode:); fields
@@ -418,122 +418,6 @@ export interface IncrementalStartOptions {
  * fields optional (omit to accept the engine-mode default).
  */
 export interface StitcherConfig {
-    /** Fraction of pan-axis the rectilinear slit retains per frame.
-     *  Range 0.10 – 0.70, default 0.30 in V15 slit-scan modes. */
-    kPanAxisFractionRect: number;
-    /** Minimum pan-axis advance (px) before a frame is accepted.
-     *  0 = accept on every consumeFrame (Apple-dense slit-scan, V15
-     *  default).  50 = V13.0g default. */
-    kMinAcceptDeltaPx: number;
-    /** V13.0e+ ORB triangulation + median-Z parallax correction. */
-    enableTriangulation: boolean;
-    /** V13.0g per-accept incremental Δt accumulator on top of triangulation. */
-    enableTriAccumulator: boolean;
-    /** V15 1D NCC perpendicular-axis wobble correction (slitscan-rotate
-     *  default).  Independent of the other correction stages. */
-    enable1dNcc: boolean;
-    /** 1D NCC search radius in pixels (5 – 60). */
-    nccSearchRadius1d: number;
-    /** V13.0g 2D NCC fine-alignment after triangulation. */
-    enable2dNcc: boolean;
-    /** V14.0a RANSAC homography per slit + cv::warpPerspective.  When
-     *  enabled and successful, supersedes the rectangular paste path. */
-    enableRansacHomography: boolean;
-    /** 'FirstPaintedWins' protects already-painted pixels (V13.0e+
-     *  default).  'FeatherBlend' alpha-blends new content into already-
-     *  painted overlap pixels (V13.0d-style; V15 slitscan-both default). */
-    paintMode: 'FirstPaintedWins' | 'FeatherBlend';
-    /** 'Cylindrical' (V12.x – V14.0a behaviour) or 'Planar' (V15 default;
-     *  cv::detail::PlaneWarper).  Planar is well-behaved for pans <60°. */
-    hybridProjection: 'Cylindrical' | 'Planar';
-    /** V15.0c — where on the camera frame the per-accept sliver is taken.
-     *  'Center' (V13.x default), 'Bottom' (leading edge for top-to-bottom
-     *  pan), or 'Top' (leading edge for bottom-to-top pan). */
-    sliverPosition: 'Center' | 'Bottom' | 'Top';
-    /** V15.0c — when true, the FIRST accepted frame paints the entire
-     *  camera frame at canvas (0, 0); subsequent frames still use the
-     *  configured sliver clip.  Default false; set true when sliverPosition
-     *  is Bottom/Top so the canvas is anchored with full-frame content. */
-    firstFrameFullFrame: boolean;
-    /** **DEPRECATED in V15.0d** — use `planeSource` instead.
-     *
-     *  V15.0b boolean toggle for the plane-projected stitch path.
-     *  Kept for backward compat: when `planeSource` is left at its
-     *  default (Disabled), `useDetectedPlane = true` upgrades it to
-     *  ARKitDetected.  New callers should set `planeSource` directly. */
-    useDetectedPlane: boolean;
-    /** V15.0d — source of the plane used by the V15.0b plane-projected
-     *  stitch path.
-     *
-     *  - 'Disabled' (default): no plane projection; slit-scan path runs.
-     *  - 'ARKitDetected': use ARKit's first vertical plane that aligns
-     *    with the camera's view direction (filter threshold:
-     *    `arkitPlaneAlignmentThreshold`).  Falls back to slit-scan
-     *    silently when no aligned plane is found.
-     *  - 'Virtual': synthesize a plane at first frame: origin =
-     *    camera_pos + `virtualPlaneDepthMeters` × camera_forward;
-     *    normal = -camera_forward.  Always works; no ARKit dependency.
-     *
-     *  Field testing showed ARKit plane detection often picks the WRONG
-     *  surface (side wall, doorframe) — Virtual mode is the safer
-     *  default for arbitrary scenes.  ARKitDetected wins when ARKit
-     *  finds the correct fixture face. */
-    planeSource: 'Disabled' | 'ARKitDetected' | 'Virtual';
-    /** V15.0d — depth (metres) at which the synthetic plane is placed
-     *  in front of the camera when `planeSource = Virtual`.  Set to
-     *  the user's typical scan distance.  Range 0.3 – 5.0 m.  Default
-     *  1.5 m. */
-    virtualPlaneDepthMeters: number;
-    /** V15.0d — minimum dot product between an ARKit-detected plane's
-     *  surface normal and the camera's facing direction for the plane
-     *  to be accepted (when `planeSource = ARKitDetected`).  1.0 =
-     *  plane perfectly facing camera; 0.0 = plane edge-on; negative
-     *  = facing away.  Range 0.0 – 1.0.  Default 0.6 (≈53° max angle
-     *  off-camera). */
-    arkitPlaneAlignmentThreshold: number;
-    /** V15.0g — how the plane-projection helper renders each frame onto
-     *  the canvas.  Affects ARKitDetected and Virtual modes; ignored
-     *  when planeSource = Disabled.
-     *
-     *  - 'Trapezoidal' (V15.0b legacy): geometrically-correct 3D
-     *    raycast.  Each camera pixel maps to its plane intersection.
-     *    Result is a trapezoid that grows distorted with tilt
-     *    (cooler-bottom-2.3×-wider-than-top problem).
-     *  - 'Rectified' (V15.0g default): camera frame pasted as a clean
-     *    rectangle around its plane-projected anchor.  Eliminates the
-     *    tilt-induced trapezoidal distortion at the cost of strict 3D-
-     *    correctness — the camera's per-pixel perspective stays inside
-     *    the rectangle but doesn't reconcile across tilts. */
-    planeProjectionStyle: 'Trapezoidal' | 'Rectified';
-    /** V15.0d — 2D NCC search half-window in pixels.  Was hardcoded
-     *  ±12 in V15.0c.4.  Smaller = less wandering on repetitive
-     *  textures (peg holes, slatted panels), but easier to miss the
-     *  true overlap when pose noise is high.  Range 4 – 30.  Default
-     *  12. */
-    nccSearchMargin2d: number;
-    /** V15.0d — 2D NCC confidence threshold below which the correction
-     *  is rejected.  Was hardcoded 0.75 in V15.0c.4.  Higher = stricter,
-     *  fewer false matches on repetitive textures, but more frames
-     *  where NCC silently doesn't fire.  Range 0.30 – 0.99.  Default
-     *  0.75. */
-    nccConfidenceThreshold2d: number;
-    /** V15.0d (1B) — exponential-moving-average smoothing on 2D NCC
-     *  corrections.  When enabled, the applied correction is
-     *  `α × current + (1−α) × prev` instead of just `current`.  Damps
-     *  single-frame snaps to spurious peaks.  Default false. */
-    enableNcc2dEmaSmoothing: boolean;
-    /** V15.0d — EMA weight on the CURRENT-frame NCC correction
-     *  (1 − α weight on the previous correction).  Range 0.05 – 0.95.
-     *  Default 0.4 (60% prev / 40% current — heavy damping). */
-    ncc2dEmaAlpha: number;
-    /** V15.0d (1C) — pan-axis-aware 2D NCC.  When enabled, the cross-
-     *  axis (perpendicular to pan) NCC correction is clamped tighter
-     *  than the pan-axis (since 1D NCC + pose already handle cross-
-     *  axis wobble).  Default false. */
-    enableNcc2dPanAxisLock: boolean;
-    /** V15.0d — cross-axis clamp (pixels) for the pan-axis-aware mode.
-     *  Range 0 – 30.  Default 5. */
-    ncc2dCrossAxisLockPx: number;
     /** V16 — how the engine decides which ARFrames to ingest.
      *
      *  - 'time-based' (default): every frame the AR delegate delivers