react-native-image-stitcher 0.15.2 → 0.16.1

package/dist/camera/Camera.js

@@ -74,7 +74,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports._isSideEdgeForTests = exports._homeIndicatorEdgeForTests = exports.CameraError = void 0;
+exports._cameraShouldUnmountForTests = exports._isSideEdgeForTests = exports._homeIndicatorEdgeForTests = exports.CameraError = void 0;
 exports.Camera = Camera;
 const react_1 = __importStar(require("react"));
 const react_native_1 = require("react-native");
@@ -87,6 +87,7 @@ const CaptureHeader_1 = require("./CaptureHeader");
 const CapturePreview_1 = require("./CapturePreview");
 const CaptureThumbnailStrip_1 = require("./CaptureThumbnailStrip");
 const CaptureStatusOverlay_1 = require("./CaptureStatusOverlay");
+const classifyStitchError_1 = require("./classifyStitchError");
 const CaptureDebugOverlay_1 = require("./CaptureDebugOverlay");
 const CaptureMemoryPill_1 = require("./CaptureMemoryPill");
 const CaptureKeyframePill_1 = require("./CaptureKeyframePill");
@@ -102,6 +103,24 @@ const useDeviceOrientation_1 = require("./useDeviceOrientation");
 const useContentRotation_1 = require("./useContentRotation");
 const useOrientationDrift_1 = require("./useOrientationDrift");
 const OrientationDriftModal_1 = require("./OrientationDriftModal");
+// ── Panorama GUIDANCE building blocks (feature/pano-ux-guidance) ─────
+// Pure decision helpers + sensor hook + presentational surfaces for the
+// first-time-user pan-capture guidance (items 1–7).  All read directly
+// from the new <Camera> props below, NOT threaded through PanoramaSettings.
+const panModeGate_1 = require("./panModeGate");
+const captureCountdown_1 = require("./captureCountdown");
+const usePanMotion_1 = require("./usePanMotion");
+const cameraGuidanceCopy_1 = require("./cameraGuidanceCopy");
+const RotateToLandscapePrompt_1 = require("./RotateToLandscapePrompt");
+const PanHowToOverlay_1 = require("./PanHowToOverlay");
+const CaptureCountdownOverlay_1 = require("./CaptureCountdownOverlay");
+const CaptureFrameCounterOverlay_1 = require("./CaptureFrameCounterOverlay");
+const LateralMotionModal_1 = require("./LateralMotionModal");
+const RectCropPreview_1 = require("./RectCropPreview");
+const stitchDebugInfo_1 = require("./stitchDebugInfo");
+const cropQuad_1 = require("../stitching/cropQuad");
+const computeInscribedRect_1 = require("../stitching/computeInscribedRect");
+const captureWarnings_1 = require("./captureWarnings");
 const incremental_1 = require("../stitching/incremental");
 const useFrameProcessorDriver_1 = require("../stitching/useFrameProcessorDriver");
 const useIncrementalStitcher_1 = require("../stitching/useIncrementalStitcher");
@@ -266,7 +285,17 @@ function extractPanoramaOverrides(props) {
         defaultKeyframeMaxCount: props.defaultKeyframeMaxCount,
         defaultKeyframeOverlapThreshold: props.defaultKeyframeOverlapThreshold,
         defaultMaxKeyframeIntervalMs: props.defaultMaxKeyframeIntervalMs,
-        maxInscribedRectCrop: props.maxInscribedRectCrop,
+        // v0.16 — JSON-object form (wins over the flat default* props above).
+        stitcher: props.stitcher,
+        frameSelection: props.frameSelection,
+        // Item 2 — the interactive crop editor OWNS cropping, so when it's on we
+        // force the native auto-crop OFF: the editor needs the full un-cropped
+        // panorama (black borders included) so the user can drag the inscribed-
+        // rect seed outward to keep more content.  Letting the native auto-crop
+        // pre-trim would leave nothing to adjust.
+        maxInscribedRectCrop: props.rectCrop
+            ? false
+            : props.maxInscribedRectCrop,
     };
 }
 // `toFileUri` (used to be an inline `toFileUri` here) lives in
@@ -281,7 +310,16 @@ function extractPanoramaOverrides(props) {
  * The public `<Camera>` component.
  */
 function Camera(props) {
-    const { defaultCaptureSource = 'non-ar', defaultLens = '1x', captureSources = 'both', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, onLensChange, onFramesDropped, onError, onCaptureAbandoned, flash: controlledFlash, onFlashChange, showFlashButton = true, headerTitle, onHeaderBack, headerBackLabel, headerGuidance, headerColors, thumbnails, thumbnailsMin, thumbnailsMax, onThumbnailPress, capturePreview, capturePreviewActions, onCapturePreviewClose, frameProcessor: hostFrameProcessor, engine = 'batch-keyframe', } = props;
+    const { defaultCaptureSource = 'non-ar', defaultLens = '1x', captureSources = 'both', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, onLensChange, onFramesDropped, onError, onCaptureAbandoned, flash: controlledFlash, onFlashChange, showFlashButton = true, headerTitle, onHeaderBack, headerBackLabel, headerGuidance, headerColors, thumbnails, thumbnailsMin, thumbnailsMax, onThumbnailPress, capturePreview, capturePreviewActions, onCapturePreviewClose, frameProcessor: hostFrameProcessor, engine = 'batch-keyframe', 
+    // ── Panorama GUIDANCE (feature/pano-ux-guidance) ──────────────
+    panMode = 'vertical', panGuidance = true, maxPanDurationMs = 0, panTooFastThreshold, lateralBudgetCm = 4, rectCrop = false, showPreview = false, guidanceCopy, } = props;
+    // Derived guidance state.  The landscape-only gate decision itself is
+    // computed inline at the call sites via `shouldGateForPanMode(panMode,
+    // deviceOrientation)` (the rotate gate + resume effect), so there's no
+    // standalone `modeAOnly` flag to keep in sync.  `guidanceCopyResolved`
+    // merges the host override onto the defaults once per `guidanceCopy`
+    // identity.
+    const guidanceCopyResolved = (0, react_1.useMemo)(() => (0, cameraGuidanceCopy_1.mergeGuidanceCopy)(guidanceCopy), [guidanceCopy]);
     // v0.13.2 — capture-source constraint (default 'both').  Derives which
     // sources are permitted; `captureSources` overrides any conflicting
     // `defaultCaptureSource`.  Used to constrain the initial AR preference
@@ -317,6 +355,30 @@ function Camera(props) {
     const [statusPhase, setStatusPhase] = (0, react_1.useState)('idle');
     const [recordingStartedAt, setRecordingStartedAt] = (0, react_1.useState)(null);
     const [incrementalState, setIncrementalState] = (0, react_1.useState)(null);
+    // ── Panorama GUIDANCE state (feature/pano-ux-guidance) ──────────
+    // Item 1/2 — a hold that was BLOCKED on the rotate-to-landscape gate.
+    // Latches when the user holds the shutter in portrait under Mode A;
+    // an effect below resumes the capture the instant they rotate.
+    const [pendingPanStart, setPendingPanStart] = (0, react_1.useState)(false);
+    // Item 6 — the latched lateral-drift popup (capture already finalized
+    // by the time it shows).
+    const [lateralStopVisible, setLateralStopVisible] = (0, react_1.useState)(false);
+    // Item 6 — true when the lateral stop happened with too few frames to
+    // stitch (the user veered off almost immediately): the popup then shows
+    // the "follow the arrow" copy and the capture is abandoned, not finalized.
+    const [lateralWrongDirection, setLateralWrongDirection] = (0, react_1.useState)(false);
+    // Item 3 — the brief pan how-to overlay shown at the start of a
+    // recording, auto-dismissed after a timeout.
+    const [howToVisible, setHowToVisible] = (0, react_1.useState)(false);
+    // Item 5 — a ~250 ms ticking clock that drives the displayed countdown
+    // seconds while recording (the authoritative auto-stop is a setTimeout,
+    // not this tick).
+    const [nowTick, setNowTick] = (0, react_1.useState)(() => Date.now());
+    // Item 7 — a finalized panorama awaiting the user's crop decision.
+    // Non-null mounts the RectCropPreview; `captureResultObj` is the exact
+    // CameraCaptureResult we'd otherwise have emitted, stashed so cancel /
+    // crop-confirm can emit it (possibly with cropped dims) afterwards.
+    const [cropPending, setCropPending] = (0, react_1.useState)(null);
     // 2026-05-22 (audit F9 + F3) — debug stitch-stats toast.  Hook
     // exposes an imperative API; we fire `showResult(finalizeResult)`
     // on every successful finalize when settings.debug is on (gated
@@ -350,6 +412,17 @@ function Camera(props) {
     // cases that resolve to AR once support is confirmed.
     const arSupportPending = arPreference && lens !== '0.5x' && !isARSupportProbed;
     const deviceOrientation = (0, useDeviceOrientation_1.useDeviceOrientation)();
+    // ── Panorama GUIDANCE — shared motion signals (item 3/4/6) ──────
+    // One gyro + one accelerometer subscription, live only while a non-AR
+    // capture is recording.  Feeds the too-fast pill (`panSpeedBucket`)
+    // and the lateral-drift FINALIZE (`lateralExceeded`).  `panTooFast-
+    // Threshold` (if set) tunes the 'warn'→'bad' boundary; `lateralBudget-
+    // Cm` tunes the drift latch (0 disables the latch in the hook).
+    const panMotion = (0, usePanMotion_1.usePanMotion)({
+        active: statusPhase === 'recording' && isNonAR,
+        warnMaxRadPerSec: panTooFastThreshold,
+        lateralBudgetCm,
+    });
     // v0.13.1 — counter-rotation for control CONTENT (AR toggle, lens
     // pill, flash icon, thumbnails) so their labels read upright relative
     // to gravity when the device is held landscape under a PORTRAIT-LOCKED
@@ -522,9 +595,43 @@ function Camera(props) {
     // The imperative pattern (start on hold-start, stop on hold-end)
     // avoids the re-render churn entirely.
     const fpDriver = (0, useFrameProcessorDriver_1.useFrameProcessorDriver)();
-    // Safety: stop the driver if the component unmounts mid-recording.
+    // Safety: stop the driver AND clear the pan-duration auto-finalize
+    // timer if the component unmounts mid-recording (item 5 exit path #4).
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    (0, react_1.useEffect)(() => () => { fpDriver.stop(); }, []);
+    (0, react_1.useEffect)(() => () => { fpDriver.stop(); clearPanTimer(); }, []);
+    // ── Panorama GUIDANCE — auto-finalize timer + ref bridges ───────
+    // The 9 s pan-duration ceiling (item 5) is an authoritative
+    // `setTimeout` (not derived from the cosmetic countdown tick).  Stored
+    // in a ref so the start logic can schedule it and ALL four capture-exit
+    // paths (manual release, drift cancel, lateral stop, unmount) clear it.
+    const panDurationTimerRef = (0, react_1.useRef)(null);
+    const clearPanTimer = (0, react_1.useCallback)(() => {
+        if (panDurationTimerRef.current) {
+            clearTimeout(panDurationTimerRef.current);
+            panDurationTimerRef.current = null;
+        }
+    }, []);
+    // `handleHoldEnd` / `startCapture` are defined further down but are
+    // referenced from effects + timers declared above them.  Refs break
+    // the declaration-order + circular-useCallback-dep cycle: each is
+    // kept current by a commit-phase effect, and callers invoke via the
+    // ref (`handleHoldEndRef.current?.()`) — mirroring how the drift
+    // effect avoids putting these in its dep array.
+    const handleHoldEndRef = (0, react_1.useRef)(null);
+    const startCaptureRef = (0, react_1.useRef)(null);
+    // Synchronous re-entrancy latch for the finalize path: the auto-finalize
+    // timer and a manual release can both pass the async statusPhase guard in
+    // the same tick before React commits 'stitching'.
+    const finalizingRef = (0, react_1.useRef)(false);
+    // Item 6 — set by the lateral-drift effect just before it calls
+    // handleHoldEnd, so the finalize knows this stop was a sideways-drift
+    // auto-stop and can attach the LATERAL_DRIFT_FINALIZE warning.  Consumed
+    // (reset) at the start of handleHoldEnd so it never leaks to the next pan.
+    const lateralFinalizeRef = (0, react_1.useRef)(false);
+    // Item 4 — latched true if the pan ever exceeded the recommended pace (the
+    // live "too fast" cue fired) during the capture, so the finalize attaches a
+    // HIGH_PAN_SPEED warning.  Reset at capture start; consumed at finalize.
+    const fastPanRef = (0, react_1.useRef)(false);
     // ── v0.12.0 — Orientation drift detection + auto-abandon ────────
     //
     // The incremental engine supports both portrait (Mode B, horizontal
@@ -541,11 +648,20 @@ function Camera(props) {
     // the engine spec.
     const drift = (0, useOrientationDrift_1.useOrientationDrift)(statusPhase === 'recording');
     const [driftModalDismissed, setDriftModalDismissed] = (0, react_1.useState)(false);
-    // Reset the dismissed flag when a new capture starts (or any non-
-    // recording state) so the next drift event surfaces a fresh modal.
+    // Reset the modal flags when a new capture STARTS (statusPhase →
+    // 'recording'), NOT when one stops.  v0.16 fix: the old "any non-recording
+    // state" condition cleared `lateralStopVisible` the instant a lateral stop
+    // moved statusPhase out of 'recording' — so the popup was hidden before it
+    // could ever show (the user only saw the downstream error).  Clearing on
+    // capture START instead lets the lateral / drift popups persist after the
+    // stop until the user dismisses them, while still giving the next capture
+    // a clean slate.
     (0, react_1.useEffect)(() => {
-        if (statusPhase !== 'recording')
+        if (statusPhase === 'recording') {
             setDriftModalDismissed(false);
+            setLateralStopVisible(false);
+            setLateralWrongDirection(false);
+        }
     }, [statusPhase]);
     (0, react_1.useEffect)(() => {
         if (!drift.drifted || statusPhase !== 'recording')
@@ -563,6 +679,9 @@ function Camera(props) {
         // through `onError` — abandonment must succeed even if the engine
         // is in a weird state.
         void (async () => {
+            // item 5 exit path #2 — kill the pan-duration auto-finalize timer
+            // so it can't fire into an already-cancelled capture.
+            clearPanTimer();
             fpDriver.stop();
             try {
                 await incremental.cancel();
@@ -747,25 +866,29 @@ function Camera(props) {
                 width = result.width;
                 height = result.height;
             }
-            onCapture?.({ type: 'photo', uri, width, height });
+            onCapture?.({ ok: true, type: 'photo', uri, width, height, warnings: [] });
         }
         catch (err) {
             const e = err instanceof CameraError
                 ? err
                 : new CameraError('PHOTO_CAPTURE_FAILED', err instanceof Error ? err.message : String(err), err);
+            // v0.16 — failures now reach `onCapture` too (ok:false), with
+            // `onError` kept as a mirror so existing handlers keep working.
             onError?.(e);
+            onCapture?.({ ok: false, type: 'photo', error: e, warnings: [] });
         }
     }, [enablePhotoMode, isAR, capture, outputDir, onCapture, onError]);
-    const handleHoldStart = (0, react_1.useCallback)(async () => {
-        if (!enablePanoramaMode)
-            return;
-        if (!(0, incremental_1.incrementalStitcherIsAvailable)()) {
-            onError?.(new CameraError('PANORAMA_START_FAILED', 'Native incremental stitcher module not available'));
-            return;
-        }
+    // ── startCapture — the "actually start recording" logic ─────────
+    // Extracted from `handleHoldStart` so the rotate-to-landscape gate
+    // (item 1/2) can DEFER it: a portrait Mode-A hold latches
+    // `pendingPanStart` and an effect calls this once the user rotates.
+    // Identical behaviour to the inline body it replaced — the only new
+    // line is the item-5 auto-finalize timer scheduled right after
+    // `setRecordingStartedAt`.
+    const startCapture = (0, react_1.useCallback)(async () => {
         try {
             // 2026-05-23 (race fix) — synchronously clear thumbnails +
-            // engine state at the top of handleHoldStart, BEFORE awaiting
+            // engine state at the top of startCapture, BEFORE awaiting
             // incremental.start().  In the previous effect-based design
             // the GL thread could ingest an AR frame during the await
             // window and add to thumbnails BEFORE React's
@@ -775,8 +898,21 @@ function Camera(props) {
             // an empty array and accumulates from there.
             setBatchKeyframeThumbnails([]);
             setIncrementalState(null);
+            // Item 4 — fresh capture: clear the latched too-fast flag.
+            fastPanRef.current = false;
             setStatusPhase('recording');
             setRecordingStartedAt(Date.now());
+            // Item 5 — schedule the hard-ceiling auto-finalize.  Fires
+            // `handleHoldEnd` (via ref to dodge the circular useCallback dep),
+            // which finalizes what's captured — the FINALIZE-on-zero product
+            // decision.  Cleared on every other capture-exit path.  Skipped
+            // when the feature is disabled (`maxPanDurationMs <= 0`).
+            clearPanTimer();
+            if (maxPanDurationMs > 0) {
+                panDurationTimerRef.current = setTimeout(() => {
+                    handleHoldEndRef.current?.();
+                }, maxPanDurationMs);
+            }
             const orientationRotation = deviceOrientation === 'portrait' ? 90
                 : deviceOrientation === 'portrait-upside-down' ? 270
                     : 0;
@@ -835,10 +971,10 @@ function Camera(props) {
         }
         catch (err) {
             setStatusPhase('idle');
+            clearPanTimer();
             onError?.(new CameraError('PANORAMA_START_FAILED', err instanceof Error ? err.message : String(err), err));
         }
     }, [
-        enablePanoramaMode,
         incremental,
         isNonAR,
         deviceOrientation,
@@ -848,15 +984,93 @@ function Camera(props) {
         fpDriver,
         engine,
         onError,
+        maxPanDurationMs,
+        clearPanTimer,
+    ]);
+    // Keep the ref current so the auto-finalize timer + the rotate-resume
+    // effect can invoke the latest `startCapture` without taking it as a
+    // dep (which would re-run them on every recording-driven re-render).
+    (0, react_1.useEffect)(() => {
+        startCaptureRef.current = () => { void startCapture(); };
+    });
+    // ── handleHoldStart — early guards + the rotate-to-landscape gate ─
+    // The "actually start" body lives in `startCapture`; this wrapper only
+    // decides WHETHER to start now.  Under Mode A in portrait it latches
+    // `pendingPanStart` instead (item 1/2) and the resume effect below
+    // starts the capture once the user rotates to landscape.
+    const handleHoldStart = (0, react_1.useCallback)(() => {
+        if (!enablePanoramaMode)
+            return;
+        if (!(0, incremental_1.incrementalStitcherIsAvailable)()) {
+            onError?.(new CameraError('PANORAMA_START_FAILED', 'Native incremental stitcher module not available'));
+            return;
+        }
+        if ((0, panModeGate_1.shouldGateForPanMode)(panMode, deviceOrientation)) {
+            // Mode-A + portrait — block the start and show the rotate prompt.
+            // The resume effect picks this up the instant the device rotates.
+            setPendingPanStart(true);
+            return;
+        }
+        void startCapture();
+    }, [
+        enablePanoramaMode,
+        onError,
+        panMode,
+        deviceOrientation,
+        startCapture,
     ]);
+    // ── Rotate-to-landscape resume (item 1/2) ───────────────────────
+    // When a hold was gated (`pendingPanStart`) and the user has since
+    // rotated so the gate no longer fires, start the deferred capture.
+    // Invoked through `startCaptureRef` (kept current above) so this
+    // effect's deps don't churn on every recording re-render.
+    (0, react_1.useEffect)(() => {
+        if (pendingPanStart && !(0, panModeGate_1.shouldGateForPanMode)(panMode, deviceOrientation)) {
+            setPendingPanStart(false);
+            startCaptureRef.current?.();
+        }
+    }, [pendingPanStart, deviceOrientation, panMode]);
     const handleHoldEnd = (0, react_1.useCallback)(async () => {
+        // Item 5 exit path #1 — always kill the auto-finalize timer on
+        // release, even on the early-return below (it's idempotent).
+        clearPanTimer();
+        // Item 1/2 — if the shutter is released while a rotate-gated hold is
+        // pending (user let go before rotating to landscape), abandon the
+        // deferred start rather than starting on the next rotation.
+        if (pendingPanStart)
+            setPendingPanStart(false);
         if (statusPhase !== 'recording')
             return;
+        // Re-entrancy latch — close the timer-vs-release double-finalize window
+        // synchronously so incremental.finalize()/onCapture fire exactly once.
+        if (finalizingRef.current)
+            return;
+        finalizingRef.current = true;
+        // Consume the lateral-drift flag once, here, so it's cleared on BOTH the
+        // success and failure paths and never leaks into the next capture.
+        const wasLateralFinalize = lateralFinalizeRef.current;
+        lateralFinalizeRef.current = false;
+        const wasFastPan = fastPanRef.current;
+        fastPanRef.current = false;
+        if (__DEV__) {
+            // eslint-disable-next-line no-console
+            console.log(`[capture] finalize: wasFastPan=${wasFastPan} `
+                + `wasLateralFinalize=${wasLateralFinalize}`);
+        }
         setStatusPhase('stitching');
         // Stop pumping new frames before finalizing so the engine isn't
         // racing the final cv::Stitcher pass against late-arriving
         // keyframes.  No-op in AR mode (the driver was never started).
         fpDriver.stop();
+        // V12.14.8 restore (regressed in the SDK camera extraction): the
+        // render below unmounts <CameraView>/<ARCameraView> while
+        // statusPhase==='stitching'.  Yield a macrotask so React commits that
+        // unmount and vision-camera tears down the AVCaptureSession + preview
+        // buffers (~150-250 MB) BEFORE the memory-heavy stitch runs.  Without
+        // it the live-camera footprint and the stitch peak coexist and
+        // jetsam (iOS) / lmkd (Android) OOM-kill the app — the exact
+        // WatchdogTermination crash V12.14.8 originally fixed.
+        await new Promise((resolve) => setTimeout(resolve, 50));
         try {
             // Compose the panorama output path: host-controlled if
             // `outputDir` is set, else the lib's canonical capture dir
@@ -874,7 +1088,7 @@ function Camera(props) {
             // native side uses pose-derived translation and ignores this).
             const imuTotalTranslationM = isNonAR ? imuGate.getTotalAbsMetres() : 0;
             const result = await incremental.finalize(panoOutputPath, 90, // default JPEG quality
-            deviceOrientation, imuTotalTranslationM);
+            deviceOrientation, imuTotalTranslationM, lens);
             if (typeof result.framesRequested === 'number'
                 && typeof result.framesIncluded === 'number'
                 && result.framesIncluded < result.framesRequested) {
@@ -883,7 +1097,19 @@ function Camera(props) {
                     included: result.framesIncluded,
                 });
             }
-            onCapture?.({
+            // v0.16 — non-fatal quality signals attached to the result + (when
+            // the crop editor shows) the crop banner.  LOW_FRAME_UTILIZATION when
+            // <70 % of captured frames survived; LATERAL_DRIFT_FINALIZE when item-6
+            // stopped this capture early.
+            const warnings = (0, captureWarnings_1.buildCaptureWarnings)({
+                framesRequested: result.framesRequested,
+                framesIncluded: result.framesIncluded,
+                lateralFinalize: wasLateralFinalize,
+                highPanSpeed: wasFastPan,
+                copy: (0, cameraGuidanceCopy_1.captureWarningCopyFrom)(guidanceCopyResolved),
+            });
+            const captureResultObj = {
+                ok: true,
                 type: 'panorama',
                 // Native finalize() returns a bare `/data/.../foo.jpg` path;
                 // normalise to `file://` for Android <Image>.
@@ -896,7 +1122,56 @@ function Camera(props) {
                 finalConfidenceThresh: result.finalConfidenceThresh ?? -1,
                 durationMs: Date.now() - (recordingStartedAt ?? Date.now()),
                 stitchModeResolved: result.stitchModeResolved,
-            });
+                rRadians: result.rRadians,
+                tMeters: result.tMeters,
+                decisionRatio: result.decisionRatio,
+                debugSummary: result.debugSummary,
+                keyframePaths: result.batchKeyframePaths,
+                captureOrientation: result.captureOrientation,
+                warnings,
+            };
+            // When the crop editor OR a plain preview is enabled AND the panorama
+            // has valid intrinsic dims, defer `onCapture`: stash the result and
+            // mount RectCropPreview (crop mode when `rectCrop`, preview-only when
+            // just `showPreview`).  The modal's confirm / use-original / retake
+            // decision emits the final result.  Otherwise emit immediately.
+            if ((rectCrop || showPreview)
+                && result.width > 0
+                && result.height > 0) {
+                // Crop mode only — seed the quad from the max-inscribed rectangle of
+                // the (un-cropped) panorama so the editor opens on the tightest clean
+                // rectangle, not a blind 8 % inset.  Best-effort: an absent native
+                // module / decode failure falls back to the default seed.  Skipped in
+                // preview-only mode (no quad to seed).
+                let initialRect;
+                if (rectCrop) {
+                    try {
+                        const inscribed = await (0, computeInscribedRect_1.computeInscribedRect)(captureResultObj.uri);
+                        if (inscribed && inscribed.width > 0 && inscribed.height > 0) {
+                            initialRect = {
+                                x: inscribed.x,
+                                y: inscribed.y,
+                                width: inscribed.width,
+                                height: inscribed.height,
+                            };
+                        }
+                    }
+                    catch {
+                        // No seed — RectCropPreview uses its default inset.
+                    }
+                }
+                setCropPending({
+                    uri: captureResultObj.uri,
+                    width: result.width,
+                    height: result.height,
+                    captureResultObj,
+                    initialRect,
+                    warnings,
+                });
+            }
+            else {
+                onCapture?.(captureResultObj);
+            }
             // 2026-05-22 (audit F9) — fire the debug stitch-stats toast on
             // every successful finalize when settings.debug is on.  Shows
             // the leaveBiggestComponent retry telemetry + resolved mode so
@@ -907,19 +1182,30 @@ function Camera(props) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            const code = 
-            // Insufficient overlap surfaces two ways: cv::Stitcher's
-            // ERR_NEED_MORE_IMGS ("need more images") and the manual
-            // pipeline's "0 valid pairwise matches / frames may not overlap
-            // enough" — both are the same recoverable "pan more slowly" case.
-            /need more images|pairwise match|overlap enough/i.test(message) ? 'STITCH_NEED_MORE_IMGS'
-                : /homography/i.test(message) ? 'STITCH_HOMOGRAPHY_FAIL'
-                    : /camera params/i.test(message) ? 'STITCH_CAMERA_PARAMS_FAIL'
-                        : /out of memory|oom/i.test(message) ? 'STITCH_OOM'
-                            : 'PANORAMA_FINALIZE_FAILED';
-            onError?.(new CameraError(code, message, err));
+            // Classify the raw native failure string → typed code.  The chain
+            // lives in classifyStitchError() (the load-bearing C++↔JS contract,
+            // unit-tested against the actual native strings) so a future reword
+            // of a cpp throw can't silently drop the "pan more slowly" path.
+            const code = (0, classifyStitchError_1.classifyStitchError)(message);
+            const error = new CameraError(code, message, err);
+            // v0.16 — surface the failure on BOTH callbacks: `onError` (unchanged
+            // mirror) and `onCapture` (ok:false) so a host has one place to learn
+            // the outcome.  A lateral-drift stop that then failed to stitch still
+            // reports that cause via the warning.
+            onError?.(error);
+            onCapture?.({
+                ok: false,
+                type: 'panorama',
+                error,
+                warnings: (0, captureWarnings_1.buildCaptureWarnings)({
+                    lateralFinalize: wasLateralFinalize,
+                    highPanSpeed: wasFastPan,
+                    copy: (0, cameraGuidanceCopy_1.captureWarningCopyFrom)(guidanceCopyResolved),
+                }),
+            });
         }
         finally {
+            finalizingRef.current = false;
             setStatusPhase('idle');
             setRecordingStartedAt(null);
         }
@@ -944,7 +1230,147 @@ function Camera(props) {
         isNonAR,
         imuGate,
         stitchToast,
+        // 2026-06-16 — the finalize passes `lens` (the high-level warper tree's zoom
+        // signal); without it here the closure would send a STALE lens if the user
+        // switched 1x↔0.5x after this callback was last memoized.
+        lens,
+        // feature/pano-ux-guidance — the release also tears down the
+        // pan-duration timer + a pending rotate-gate, and decides whether to
+        // route the result through the crop editor.
+        clearPanTimer,
+        pendingPanStart,
+        rectCrop,
+        showPreview,
+    ]);
+    // Keep `handleHoldEndRef` current so the auto-finalize timer + the
+    // lateral-drift effect invoke the latest `handleHoldEnd` without
+    // adding it as a dep (it changes identity on every recording tick).
+    (0, react_1.useEffect)(() => {
+        handleHoldEndRef.current = () => { void handleHoldEnd(); };
+    });
+    // ── Item 6 — lateral drift → FINALIZE + popup ───────────────────
+    // Mirrors the orientation-drift effect, but FINALIZES the capture
+    // (keeps what was stitched) rather than cancelling it: clear the
+    // pan-duration timer, latch the popup, then call handleHoldEnd via
+    // its ref.  Gated off when the budget is disabled (`<= 0`).
+    (0, react_1.useEffect)(() => {
+        if (!panMotion.lateralExceeded
+            || statusPhase !== 'recording'
+            || lateralBudgetCm <= 0) {
+            return;
+        }
+        clearPanTimer();
+        // #3 — if the user veered off before enough frames were captured to
+        // stitch, finalizing would fail with a misleading "need more images"
+        // error.  Instead ABANDON the capture (no stitch → no error) and show
+        // the "follow the arrow" popup.  Otherwise FINALIZE what was captured
+        // (a usable partial pano) and show the "keep it straight" popup.
+        const MIN_STITCHABLE_KEYFRAMES = 2;
+        if (acceptedKeyframeCount < MIN_STITCHABLE_KEYFRAMES) {
+            setLateralWrongDirection(true);
+            setLateralStopVisible(true);
+            void (async () => {
+                fpDriver.stop();
+                try {
+                    await incremental.cancel();
+                }
+                catch {
+                    // best-effort — abandonment must succeed even in a weird state.
+                }
+                finally {
+                    setStatusPhase('idle');
+                    setRecordingStartedAt(null);
+                    onCaptureAbandoned?.('lateral-drift');
+                }
+            })();
+            return;
+        }
+        setLateralWrongDirection(false);
+        setLateralStopVisible(true);
+        // Mark this finalize as lateral-drift-triggered so handleHoldEnd attaches
+        // the LATERAL_DRIFT_FINALIZE warning to the result.
+        lateralFinalizeRef.current = true;
+        handleHoldEndRef.current?.();
+        // Deps mirror the drift effect: re-run when the latch trips or the
+        // recording state changes.  Other reads are stable setters / refs.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [panMotion.lateralExceeded, statusPhase, lateralBudgetCm]);
+    // ── Item 7 — auto-finalize when the configured keyframe count is hit ─
+    // The engine caps accepted keyframes at `keyframeMaxCount`; once it
+    // reports that many, no more frames will be accepted, so stop + stitch
+    // (same finalize path as releasing the shutter).  `handleHoldEnd`'s
+    // re-entrancy latch makes this idempotent vs. a manual release in the
+    // same tick.  This is the PRIMARY auto-stop (the time cap is opt-in).
+    const keyframeMaxCount = settings.frameSelection.maxKeyframes;
+    const acceptedKeyframeCount = incrementalState?.acceptedCount ?? 0;
+    // Item 4 — speed cue routed into the REC banner/border colour (green→red).
+    // Gated on panGuidance so opting out keeps the banner calm/green.
+    const recordingTooFast = panGuidance && panMotion.panSpeedBucket !== 'good';
+    // Latch the too-fast flag for the HIGH_PAN_SPEED warning (shown on the crop
+    // editor + returned in onCapture.warnings).  Latches when the live cue is
+    // active OR — per the user's request — when a KEYFRAME the stitch will use
+    // is accepted while the pan is too fast (so a captured frame was actually
+    // taken at speed).  Depending on panSpeedBucket + acceptedKeyframeCount
+    // directly (not just the derived `recordingTooFast`) makes the effect run
+    // on every bucket / keyframe change, so a brief red window can't be missed.
+    // Reset at capture start.
+    const prevAcceptedForSpeedRef = (0, react_1.useRef)(0);
+    (0, react_1.useEffect)(() => {
+        if (statusPhase !== 'recording') {
+            prevAcceptedForSpeedRef.current = acceptedKeyframeCount;
+            return;
+        }
+        const newKeyframe = acceptedKeyframeCount > prevAcceptedForSpeedRef.current;
+        prevAcceptedForSpeedRef.current = acceptedKeyframeCount;
+        if (recordingTooFast) {
+            if (__DEV__ && !fastPanRef.current) {
+                // eslint-disable-next-line no-console
+                console.log(`[panMotion] HIGH_PAN_SPEED latched (bucket=`
+                    + `${panMotion.panSpeedBucket} acceptedCount=${acceptedKeyframeCount}`
+                    + `${newKeyframe ? ' on a keyframe' : ''})`);
+            }
+            fastPanRef.current = true;
+        }
+    }, [
+        statusPhase,
+        recordingTooFast,
+        acceptedKeyframeCount,
+        panMotion.panSpeedBucket,
     ]);
+    (0, react_1.useEffect)(() => {
+        if (statusPhase === 'recording'
+            && keyframeMaxCount > 0
+            && acceptedKeyframeCount >= keyframeMaxCount) {
+            handleHoldEndRef.current?.();
+        }
+    }, [statusPhase, keyframeMaxCount, acceptedKeyframeCount]);
+    // ── Item 3 — brief pan how-to overlay at recording start ────────
+    // Show the how-to GIF + direction arrow for a short window when a
+    // recording begins, then auto-fade.  The component never self-times;
+    // this effect owns the lifecycle.
+    (0, react_1.useEffect)(() => {
+        if (statusPhase !== 'recording') {
+            setHowToVisible(false);
+            return;
+        }
+        setHowToVisible(true);
+        const t = setTimeout(() => setHowToVisible(false), 2500);
+        return () => clearTimeout(t);
+    }, [statusPhase]);
+    // ── Item 5 — cosmetic countdown tick ────────────────────────────
+    // While recording, bump `nowTick` ~4×/s so `countdownSecondsFrom`
+    // recomputes the displayed whole-seconds.  The authoritative auto-stop
+    // is the `panDurationTimerRef` setTimeout, NOT this interval.  Skipped
+    // when the countdown feature is disabled (`maxPanDurationMs <= 0`).
+    (0, react_1.useEffect)(() => {
+        if (statusPhase !== 'recording' || maxPanDurationMs <= 0)
+            return;
+        const id = setInterval(() => setNowTick(Date.now()), 250);
+        return () => clearInterval(id);
+    }, [statusPhase, maxPanDurationMs]);
+    // Whole seconds remaining for the countdown overlay (item 5).  Pure
+    // helper; clamps to [0, round(maxPanDurationMs/1000)].
+    const countdownSeconds = (0, captureCountdown_1.countdownSecondsFrom)(recordingStartedAt, nowTick, maxPanDurationMs);
     // ── Lens / AR-toggle handlers ───────────────────────────────────
     const handleLensChange = (0, react_1.useCallback)((next) => {
         setLens(next);
@@ -993,8 +1419,13 @@ function Camera(props) {
             : insets.top + 8;
     // ── JSX ─────────────────────────────────────────────────────────
     return (react_1.default.createElement(react_native_1.View, { style: [styles.container, style] },
-        inFlightTransition || arSupportPending ? (react_1.default.createElement(react_native_1.View, { style: [react_native_1.StyleSheet.absoluteFill, styles.transitionPlaceholder] },
-            react_1.default.createElement(react_native_1.Text, { style: styles.transitionLabel }, "Switching camera\u2026"))) : isAR ? (react_1.default.createElement(ARCameraView_1.ARCameraView, { ref: arViewRef, style: react_native_1.StyleSheet.absoluteFill })) : (react_1.default.createElement(CameraView_1.CameraView, { ref: visionCameraRef, device: capture.device, isActive: true, 
+        cameraShouldUnmount(inFlightTransition, arSupportPending, statusPhase) ? (
+        // statusPhase==='stitching' UNMOUNTS the camera so vision-camera
+        // frees the AVCaptureSession + preview buffers during the stitch
+        // (V12.14.8 OOM fix).  The CaptureStatusOverlay renders the
+        // "Stitching…" state on top, so no placeholder label is needed
+        // in that case — only for the camera-switch transition.
+        react_1.default.createElement(react_native_1.View, { style: [react_native_1.StyleSheet.absoluteFill, styles.transitionPlaceholder] }, statusPhase === 'stitching' ? null : (react_1.default.createElement(react_native_1.Text, { style: styles.transitionLabel }, "Switching camera\u2026")))) : isAR ? (react_1.default.createElement(ARCameraView_1.ARCameraView, { ref: arViewRef, style: react_native_1.StyleSheet.absoluteFill })) : (react_1.default.createElement(CameraView_1.CameraView, { ref: visionCameraRef, device: capture.device, isActive: true, 
             // `video={true}` is REQUIRED for takeSnapshot to work on iOS.
             // vision-camera v4's iOS implementation of takeSnapshot waits
             // for a frame on the video pipeline; with video disabled, the
@@ -1027,7 +1458,12 @@ function Camera(props) {
                 const msg = e?.message ?? String(err);
                 onError?.(new CameraError('VISION_CAMERA_RUNTIME', `${codeStr}: ${msg}`, err));
             } })),
-        react_1.default.createElement(CaptureStatusOverlay_1.CaptureStatusOverlay, { phase: statusPhase, topInset: insets.top, recordingStartedAt: recordingStartedAt ?? undefined }),
+        react_1.default.createElement(CaptureStatusOverlay_1.CaptureStatusOverlay, { phase: statusPhase, topInset: insets.top, recordingStartedAt: recordingStartedAt ?? undefined, tooFast: recordingTooFast, recordingMessage: recordingTooFast
+                ? guidanceCopyResolved.tooFast
+                : guidanceCopyResolved.statusRecording, stitchingMessage: guidanceCopyResolved.statusStitching }),
+        react_1.default.createElement(CaptureFrameCounterOverlay_1.CaptureFrameCounterOverlay, { visible: statusPhase === 'recording' && panGuidance, framesCaptured: acceptedKeyframeCount, framesMax: keyframeMaxCount, orientation: deviceOrientation }),
+        react_1.default.createElement(CaptureCountdownOverlay_1.CaptureCountdownOverlay, { visible: statusPhase === 'recording' && panGuidance && maxPanDurationMs > 0, secondsRemaining: countdownSeconds, orientation: deviceOrientation }),
+        react_1.default.createElement(PanHowToOverlay_1.PanHowToOverlay, { visible: statusPhase === 'recording' && panGuidance && howToVisible, orientation: deviceOrientation }),
         settings.debug && (react_1.default.createElement(react_1.default.Fragment, null,
             react_1.default.createElement(CaptureOrientationPill_1.CaptureOrientationPill, { orientation: deviceOrientation, topInset: insets.top }),
             react_1.default.createElement(CaptureKeyframePill_1.CaptureKeyframePill, { state: incrementalState, topInset: insets.top }),
@@ -1069,8 +1505,91 @@ function Camera(props) {
                         contentRotation,
                     ] }, "\u26A1")))),
         react_1.default.createElement(PanoramaSettingsModal_1.PanoramaSettingsModal, { visible: settingsModalVisible, settings: settings, onChange: setSettings, onClose: () => setSettingsModalVisible(false) }),
+        react_1.default.createElement(RotateToLandscapePrompt_1.RotateToLandscapePrompt, { visible: pendingPanStart, target: (0, panModeGate_1.gateTargetOrientation)(panMode) ?? 'landscape', copy: (0, panModeGate_1.gateTargetOrientation)(panMode) === 'portrait'
+                ? guidanceCopyResolved.rotateToPortrait
+                : guidanceCopyResolved.rotateToLandscape }),
         react_1.default.createElement(OrientationDriftModal_1.OrientationDriftModal, { visible: drift.drifted && !driftModalDismissed, captureOrientation: drift.captureOrientation, currentOrientation: drift.currentOrientation, onAcknowledge: () => setDriftModalDismissed(true) }),
-        react_1.default.createElement(CapturePreview_1.CapturePreview, { visible: capturePreview != null, imageUri: capturePreview?.imageUri ?? '', imageWidth: capturePreview?.imageWidth, imageHeight: capturePreview?.imageHeight, title: capturePreview?.title, actions: capturePreviewActions, onClose: onCapturePreviewClose ?? noop })));
+        react_1.default.createElement(LateralMotionModal_1.LateralMotionModal, { visible: lateralStopVisible, title: lateralWrongDirection
+                ? guidanceCopyResolved.lateralWrongDirectionTitle
+                : guidanceCopyResolved.lateralStopTitle, body: lateralWrongDirection
+                ? guidanceCopyResolved.lateralWrongDirectionBody
+                : guidanceCopyResolved.lateralStopBody, dismissLabel: guidanceCopyResolved.lateralStopDismiss, onDismiss: () => {
+                setLateralStopVisible(false);
+                setLateralWrongDirection(false);
+            } }),
+        react_1.default.createElement(CapturePreview_1.CapturePreview, { visible: capturePreview != null, imageUri: capturePreview?.imageUri ?? '', imageWidth: capturePreview?.imageWidth, imageHeight: capturePreview?.imageHeight, title: capturePreview?.title, actions: capturePreviewActions, onClose: onCapturePreviewClose ?? noop }),
+        react_1.default.createElement(RectCropPreview_1.RectCropPreview
+        // Remount per capture so the dragged-quad + layout state re-seed to
+        // the new image (RectCropPreview seeds its quad once via useState).
+        , { 
+            // Remount per capture so the dragged-quad + layout state re-seed to
+            // the new image (RectCropPreview seeds its quad once via useState).
+            key: cropPending?.uri ?? 'crop', visible: cropPending != null, imageUri: cropPending?.uri ?? '', imageWidth: cropPending?.width ?? 0, imageHeight: cropPending?.height ?? 0, initialRect: cropPending?.initialRect, warnings: cropPending?.warnings.map((w) => w.message) ?? [], showCropControls: rectCrop, topInset: insets.top, bottomInset: insets.bottom, copy: guidanceCopyResolved, 
+            // Carry the live memory pill onto the preview too (same settings.debug
+            // gate as the camera), so the operator can watch the RSS spike when the
+            // on-demand high-level re-stitch fires.
+            showMemoryPill: settings.debug, 
+            // DEV overlay — show the stitcher's runtime choices (pipeline / warper /
+            // route / seam / blend) + score / frames / size for this output, so the
+            // operator can see HOW it was built.  __DEV__ only.
+            debugInfo: __DEV__ && cropPending
+                ? (0, stitchDebugInfo_1.buildStitchDebugInfo)(cropPending.captureResultObj)
+                : undefined, onUseOriginal: (altUri) => {
+                if (cropPending) {
+                    // altUri set → the user picked the alt (manual) pipeline's output
+                    // in the A/B toggle; emit THAT image (cache-bust for <Image>).
+                    onCapture?.(altUri
+                        ? {
+                            ...cropPending.captureResultObj,
+                            uri: `${altUri}?t=${Date.now()}`,
+                        }
+                        : cropPending.captureResultObj);
+                }
+                setCropPending(null);
+            }, onRetake: () => {
+                // Discard this capture entirely — no onCapture — and return to
+                // the live camera (statusPhase is already 'idle' post-finalize).
+                setCropPending(null);
+            }, onConfirm: async ({ quad, perspective }) => {
+                if (!cropPending)
+                    return;
+                const pending = cropPending;
+                // perspective=true → rectify the dragged quad to an upright
+                // rectangle (cropToQuad).  perspective=false (the user dragged a
+                // ~rectangular quad) → crop to the quad's axis-aligned bounding box
+                // — a plain crop, no warp.
+                const xs = quad.map((p) => p.x);
+                const ys = quad.map((p) => p.y);
+                const cropPoints = perspective
+                    ? quad
+                    : [
+                        { x: Math.min(...xs), y: Math.min(...ys) },
+                        { x: Math.max(...xs), y: Math.min(...ys) },
+                        { x: Math.max(...xs), y: Math.max(...ys) },
+                        { x: Math.min(...xs), y: Math.max(...ys) },
+                    ];
+                try {
+                    // cropQuad takes a BARE path; the stashed uri is a file://
+                    // URI.  Overwrites in place (pass the same path).
+                    const cropped = await (0, cropQuad_1.cropQuad)((0, paths_1.toBareFilePath)(pending.uri), cropPoints, undefined, { quality: 90 });
+                    onCapture?.({
+                        ...pending.captureResultObj,
+                        // Cache-bust so <Image> reloads the overwritten file.
+                        uri: `${(0, paths_1.toFileUri)(cropped.outputPath)}?t=${Date.now()}`,
+                        width: cropped.width,
+                        height: cropped.height,
+                    });
+                }
+                catch (err) {
+                    onError?.(new CameraError('OUTPUT_WRITE_FAILED', err instanceof Error ? err.message : String(err), err));
+                    // Fall back to the un-cropped panorama so the capture isn't
+                    // lost on a crop failure.
+                    onCapture?.(pending.captureResultObj);
+                }
+                finally {
+                    setCropPending(null);
+                }
+            } })));
 }
 function noop() {
     /* no-op handler used when panorama mode is disabled */
@@ -1102,6 +1621,26 @@ function isSideEdge(edge) {
 exports._homeIndicatorEdgeForTests = homeIndicatorEdge;
 /** @internal test-only — see `isSideEdge`. */
 exports._isSideEdgeForTests = isSideEdge;
+/**
+ * cameraShouldUnmount — whether the live camera (<CameraView> /
+ * <ARCameraView>) should be UNMOUNTED (replaced by the placeholder) this
+ * render rather than mounted.
+ *
+ * True while a camera-switch transition or AR-support probe is in flight,
+ * OR during the stitch (statusPhase==='stitching').  The stitching case is
+ * the V12.14.8 OOM fix: unmounting frees vision-camera's AVCaptureSession +
+ * preview buffers (~150-250 MB) BEFORE the memory-heavy stitch, so the
+ * live-camera footprint and the stitch peak never coexist and jetsam (iOS)
+ * / lmkd (Android) don't OOM-kill the app.
+ *
+ * Pure + exported for test — the lib's jest config can't mount <Camera>,
+ * so this boolean is the unit-testable core of the OOM render gate.
+ */
+function cameraShouldUnmount(inFlightTransition, arSupportPending, statusPhase) {
+    return inFlightTransition || arSupportPending || statusPhase === 'stitching';
+}
+/** @internal test-only — see `cameraShouldUnmount`. */
+exports._cameraShouldUnmountForTests = cameraShouldUnmount;
 /**
  * v0.12.0 — bottom-controls outer container positioning.  Anchors
  * to the home-indicator JS edge with the appropriate flex direction