react-native-image-stitcher 0.2.1 → 0.4.0

package/dist/camera/Camera.js

@@ -84,8 +84,16 @@ const ARCameraView_1 = require("./ARCameraView");
 const CameraShutter_1 = require("./CameraShutter");
 const CameraView_1 = require("./CameraView");
 const CaptureStatusOverlay_1 = require("./CaptureStatusOverlay");
+const CaptureDebugOverlay_1 = require("./CaptureDebugOverlay");
+const CaptureMemoryPill_1 = require("./CaptureMemoryPill");
+const CaptureKeyframePill_1 = require("./CaptureKeyframePill");
+const CaptureOrientationPill_1 = require("./CaptureOrientationPill");
+const CaptureStitchStatsToast_1 = require("./CaptureStitchStatsToast");
 const PanoramaBandOverlay_1 = require("./PanoramaBandOverlay");
+const PanoramaSettingsBridge_1 = require("./PanoramaSettingsBridge");
 const PanoramaSettingsModal_1 = require("./PanoramaSettingsModal");
+const buildPanoramaInitialSettings_1 = require("./buildPanoramaInitialSettings");
+const lowMemDevice_1 = require("./lowMemDevice");
 const useCapture_1 = require("./useCapture");
 const useDeviceOrientation_1 = require("./useDeviceOrientation");
 const incremental_1 = require("../stitching/incremental");
@@ -223,32 +231,31 @@ function deriveEffectiveCaptureSource(arPreference, lens, isARSupportedOnDevice)
     return arPreference ? 'ar' : 'non-ar';
 }
 /**
- * Apply per-prop defaults to build the initial settings snapshot.
- * The settings live in component state from there; the prop values
- * never re-flow.
+ * Pluck the props that influence the initial PanoramaSettings tree.
+ * Kept inline (vs. a wide structural type) so future Camera prop
+ * additions don't accidentally widen the settings-translation
+ * surface — the pure builder in `./buildPanoramaInitialSettings.ts`
+ * has the canonical interface; this just forwards the relevant
+ * fields.
  *
- * Note: the `default*ResolMP` props don't have a home on PanoramaSettings
- * yet — they're accepted on the prop interface for forward compatibility
- * but ignored here.  Wiring is a follow-up once PanoramaSettings is
- * extended.
+ * The `default*ResolMP` props on `CameraProps` are documented as
+ * forward-looking no-ops; the new PanoramaSettings tree has no home
+ * for them yet (the v0.3 audit found cv::Stitcher's resol knobs
+ * aren't reached by either platform's bridge).  They're accepted on
+ * the prop interface for API stability and ignored here.
  */
-function buildInitialSettings(props) {
+function extractPanoramaOverrides(props) {
     return {
-        ...PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS,
-        stitchMode: props.defaultStitchMode ?? PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.stitchMode,
-        blenderType: props.defaultBlender ?? PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.blenderType,
-        seamFinderType: props.defaultSeamFinder ?? PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.seamFinderType,
-        warperType: props.defaultWarper ?? PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.warperType,
-        flowNoveltyPercentile: props.defaultFlowNoveltyPercentile ??
-            PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.flowNoveltyPercentile,
-        flowEvalEveryNFrames: props.defaultFlowEvalEveryNFrames ??
-            PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.flowEvalEveryNFrames,
-        flowMaxTranslationCm: props.defaultFlowMaxTranslationCm ??
-            PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.flowMaxTranslationCm,
-        keyframeMaxCount: props.defaultKeyframeMaxCount ??
-            PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.keyframeMaxCount,
-        keyframeOverlapThreshold: props.defaultKeyframeOverlapThreshold ??
-            PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.keyframeOverlapThreshold,
+        defaultCaptureSource: props.defaultCaptureSource,
+        defaultStitchMode: props.defaultStitchMode,
+        defaultBlender: props.defaultBlender,
+        defaultSeamFinder: props.defaultSeamFinder,
+        defaultWarper: props.defaultWarper,
+        defaultFlowNoveltyPercentile: props.defaultFlowNoveltyPercentile,
+        defaultFlowEvalEveryNFrames: props.defaultFlowEvalEveryNFrames,
+        defaultFlowMaxTranslationCm: props.defaultFlowMaxTranslationCm,
+        defaultKeyframeMaxCount: props.defaultKeyframeMaxCount,
+        defaultKeyframeOverlapThreshold: props.defaultKeyframeOverlapThreshold,
     };
 }
 // `toFileUri` (used to be an inline `toFileUri` here) lives in
@@ -268,11 +275,16 @@ function Camera(props) {
     // ── State ───────────────────────────────────────────────────────
     const [arPreference, setArPreference] = (0, react_1.useState)(defaultCaptureSource === 'ar');
     const [lens, setLens] = (0, react_1.useState)(defaultLens);
-    const [settings, setSettings] = (0, react_1.useState)(() => buildInitialSettings(props));
+    const [settings, setSettings] = (0, react_1.useState)(() => (0, buildPanoramaInitialSettings_1.buildPanoramaInitialSettings)(extractPanoramaOverrides(props), (0, lowMemDevice_1.isLowMemDevice)()));
     const [settingsModalVisible, setSettingsModalVisible] = (0, react_1.useState)(false);
     const [statusPhase, setStatusPhase] = (0, react_1.useState)('idle');
     const [recordingStartedAt, setRecordingStartedAt] = (0, react_1.useState)(null);
     const [incrementalState, setIncrementalState] = (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
+    // a few hundred lines below in handleHoldEnd's onCapture branch).
+    const stitchToast = (0, CaptureStitchStatsToast_1.useStitchStatsToast)();
     const [batchKeyframeThumbnails, setBatchKeyframeThumbnails] = (0, react_1.useState)([]);
     const [cameraTransitioning, setCameraTransitioning] = (0, react_1.useState)(false);
     // ARKit / ARCore device-support probe.  `isAvailable` is `false`
@@ -380,11 +392,25 @@ function Camera(props) {
     // the C++ engine to force-accept the next frame.  This is what
     // keeps non-AR captures producing keyframes at all (the flow-
     // novelty algorithm alone is too strict in practice).
+    //
+    // 2026-05-22 (audit F2f) — IMU translation gate.  The gate's own
+    // `totalAbsMetres` accumulator (banks each segment's |displacement|
+    // at every anchor reset) is the right input for the finalize-time
+    // auto-resolver in non-AR mode (where pose-derived translation is
+    // 0).  Pre-F2f this was reconstructed from `fires × budget +
+    // |residual|` — which undercounted any time a non-IMU accept
+    // (flow novelty, force-last) reset the integrator before the
+    // budget threshold was reached.
+    // The translation budget lives at `frameSelection.flow.maxTranslationCm`
+    // in the new hierarchical settings shape.  When `flow` is undefined
+    // (the consumer opted out of the flow strategy entirely), the gate
+    // stays disabled — same observable behaviour as v0.3's `0` default.
+    const flowMaxTranslationCm = settings.frameSelection.flow?.maxTranslationCm ?? 0;
     const imuGate = (0, useIMUTranslationGate_1.useIMUTranslationGate)({
         enabled: isNonAR
             && statusPhase === 'recording'
-            && settings.flowMaxTranslationCm > 0,
-        budgetMeters: Math.max(0.001, settings.flowMaxTranslationCm / 100.0),
+            && flowMaxTranslationCm > 0,
+        budgetMeters: Math.max(0.001, flowMaxTranslationCm / 100.0),
         onBudgetExceeded: () => {
             const mod = (0, incremental_1.getIncrementalNativeModule)();
             mod?.markNextFrameAsLastKeyframe?.().catch(() => undefined);
@@ -430,12 +456,52 @@ function Camera(props) {
         });
         return () => { sub?.remove?.(); };
     }, []);
+    // 2026-05-23 (race fix) — Previously this useEffect cleared
+    // `batchKeyframeThumbnails` + `incrementalState` when statusPhase
+    // transitioned to 'recording'.  But handleHoldStart is async
+    // (`await incremental.start(...)`), and on Android the ARSession
+    // was already alive on the GL thread — it could emit an ACCEPT
+    // event during the await window, BEFORE the effect ran.  Order
+    // observed in logcat:
+    //   1. setStatusPhase('recording') queued
+    //   2. await incremental.start() yields
+    //   3. ARCore frame → ingest → JS [state] emit
+    //   4. setBatchKeyframeThumbnails((prev=[]) => [keyframe-0.jpg])
+    //   5. React commits statusPhase change → THIS effect ran
+    //   6. setBatchKeyframeThumbnails([])  ← WIPED frame 0!
+    //   7. Frame 1 arrives → updater sees prev=[] → adds only frame 1
+    //   ⇒ final array missing keyframe-0.jpg
+    // The reset is now done synchronously at the top of
+    // handleHoldStart, before any await, so the GL thread can't race
+    // ahead.  This effect is intentionally removed.
+    // 2026-05-22 (audit F2f) — every accepted keyframe is a fresh
+    // anchor for the IMU translation gate, regardless of which
+    // mechanism qualified the frame (flow novelty, plane-overlap,
+    // angular fallback, IMU-budget force-accept, force-last).  Reset
+    // the gate's per-segment integrator on every acceptedCount
+    // increment so the operator sees `imuΔ` reset to 0 in the debug
+    // overlay after every accept — consistent UX regardless of WHY
+    // the gate took the frame.  Pre-F2f only the IMU-budget path
+    // reset the integrator; flow accepts left `posX` ticking up
+    // forever, which surprised the user.
+    //
+    // The gate's `totalAbsMetres` cumulative accumulator banks the
+    // |segment displacement| before zeroing, so finalize-time
+    // translation magnitude is preserved across non-IMU accepts.
+    const lastAcceptedCountRef = (0, react_1.useRef)(0);
     (0, react_1.useEffect)(() => {
-        if (statusPhase === 'recording') {
-            setBatchKeyframeThumbnails([]);
-            setIncrementalState(null);
+        const accepted = incrementalState?.acceptedCount ?? 0;
+        if (accepted > lastAcceptedCountRef.current) {
+            lastAcceptedCountRef.current = accepted;
+            if (isNonAR) {
+                imuGate.resetAnchor();
+            }
+        }
+        else if (accepted === 0) {
+            // New capture (state cleared) — reset our edge-detect ref.
+            lastAcceptedCountRef.current = 0;
         }
-    }, [statusPhase]);
+    }, [incrementalState?.acceptedCount, isNonAR, imuGate]);
     // ── Shutter handlers ────────────────────────────────────────────
     const handleTap = (0, react_1.useCallback)(async () => {
         if (!enablePhotoMode)
@@ -503,11 +569,41 @@ function Camera(props) {
             return;
         }
         try {
+            // 2026-05-23 (race fix) — synchronously clear thumbnails +
+            // engine state at the top of handleHoldStart, 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
+            // statusPhase-effect ran and wiped them.  See the removed
+            // useEffect a few hundred lines above for the full log trace.
+            // Synchronous reset here means any racing frame ingest sees
+            // an empty array and accumulates from there.
+            setBatchKeyframeThumbnails([]);
+            setIncrementalState(null);
             setStatusPhase('recording');
             setRecordingStartedAt(Date.now());
             const orientationRotation = deviceOrientation === 'portrait' ? 90
                 : deviceOrientation === 'portrait-upside-down' ? 270
                     : 0;
+            // v0.4 — the inline-flat config dict that v0.3 maintained here
+            // moved into `panoramaSettingsToNativeConfig` (see
+            // PanoramaSettingsBridge.ts).  That adapter is the single source
+            // of truth for the JS→native wire format; both this call site
+            // AND the modal's reset-to-defaults preview agree on the same
+            // mapping.  Audit fixes F1 / F4 / F6 from v0.3 are now properties
+            // of the bridge (verified by the unit tests in
+            // src/camera/__tests__/PanoramaSettingsBridge.test.ts).
+            //
+            // 2026-05-23 — override `captureSource` with the runtime-derived
+            // `effectiveCaptureSource` (from `arPreference + lens +
+            // AR-device-support`).  Pre-this change the camera-screen AR
+            // toggle wrote ONLY to local `arPreference` state while the
+            // bridge read `settings.captureSource` — so native could think
+            // the capture was AR while the operator had toggled it off (or
+            // vice-versa).  Single source of truth now: whatever camera the
+            // operator can see is what native is told it is.  The settings
+            // modal's `captureSource` control has been removed for the same
+            // reason — see PanoramaSettingsModal.tsx for the rationale.
             await incremental.start({
                 snapshotJpegQuality: 75,
                 snapshotEveryNAccepts: 1,
@@ -519,18 +615,10 @@ function Camera(props) {
                 canvasWidth: 5000,
                 canvasHeight: 5000,
                 engine: 'batch-keyframe',
-                config: {
-                    stitchMode: settings.stitchMode,
-                    warperType: settings.warperType,
-                    blenderType: settings.blenderType,
-                    seamFinderType: settings.seamFinderType,
-                    flowNoveltyPercentile: settings.flowNoveltyPercentile,
-                    flowEvalEveryNFrames: settings.flowEvalEveryNFrames,
-                    flowMaxTranslationCm: settings.flowMaxTranslationCm,
-                    keyframeMaxCount: settings.keyframeMaxCount,
-                    keyframeOverlapThreshold: settings.keyframeOverlapThreshold,
-                    frameSelectionMode: 'flow-based',
-                },
+                config: (0, PanoramaSettingsBridge_1.panoramaSettingsToNativeConfig)({
+                    ...settings,
+                    captureSource: effectiveCaptureSource,
+                }),
             });
             imuGate.resetAnchor();
             // Start pumping vision-camera snapshots into the engine for
@@ -553,6 +641,7 @@ function Camera(props) {
         isNonAR,
         deviceOrientation,
         settings,
+        effectiveCaptureSource,
         imuGate,
         jsDriver,
         onError,
@@ -574,7 +663,14 @@ function Camera(props) {
             const panoOutputPath = outputDir
                 ? `${(0, paths_1.toBareFilePath)(outputDir).replace(/\/$/, '')}/${(0, files_1.defaultPanoramaFilename)()}`
                 : `${await (0, files_1.getDefaultCaptureDir)()}/${(0, files_1.defaultPanoramaFilename)()}`;
-            const result = await incremental.finalize(panoOutputPath, 90, deviceOrientation);
+            // 2026-05-22 (audit F2f) — total IMU translation directly from
+            // the gate's cumulative accumulator (banks |segment displacement|
+            // at every anchor reset, including non-IMU-driven resets like
+            // flow-novelty accepts).  No more fires × budget + residual
+            // reconstruction.  Only meaningful in non-AR mode (in AR the
+            // native side uses pose-derived translation and ignores this).
+            const imuTotalTranslationM = isNonAR ? imuGate.getTotalAbsMetres() : 0;
+            const result = await incremental.finalize(panoOutputPath, 90, deviceOrientation, imuTotalTranslationM);
             if (typeof result.framesRequested === 'number'
                 && typeof result.framesIncluded === 'number'
                 && result.framesIncluded < result.framesRequested) {
@@ -595,7 +691,15 @@ function Camera(props) {
                 framesDropped: (result.framesRequested ?? 0) - (result.framesIncluded ?? 0),
                 finalConfidenceThresh: result.finalConfidenceThresh ?? -1,
                 durationMs: Date.now() - (recordingStartedAt ?? Date.now()),
+                stitchModeResolved: result.stitchModeResolved,
             });
+            // 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
+            // the operator can see what choice the auto-resolver made.
+            if (settings.debug) {
+                stitchToast.showResult(result);
+            }
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -619,6 +723,18 @@ function Camera(props) {
         onError,
         recordingStartedAt,
         jsDriver,
+        // F10 Phase 2 review N1 — these four were missing pre-fix.  The
+        // callback reads `settings.debug` (to gate the stitchToast),
+        // `isNonAR` (to decide whether to read IMU totalAbs translation),
+        // `imuGate` (the read itself), and `stitchToast` (the toast hook
+        // object).  If any of those identities change between the user
+        // pressing-and-holding the shutter and the release, the stale-
+        // closure read could disagree with the actual current state.
+        // Pre-existing v0.3 bug; v0.4 was the natural time to address it.
+        settings,
+        isNonAR,
+        imuGate,
+        stitchToast,
     ]);
     // ── Lens / AR-toggle handlers ───────────────────────────────────
     const handleLensChange = (0, react_1.useCallback)((next) => {
@@ -641,6 +757,12 @@ function Camera(props) {
             // which has run on `video` (true) for months without issue.
             video: true, flash: "off", style: react_native_1.StyleSheet.absoluteFill })),
         react_1.default.createElement(CaptureStatusOverlay_1.CaptureStatusOverlay, { phase: statusPhase, topInset: insets.top, recordingStartedAt: recordingStartedAt ?? undefined }),
+        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 }),
+            react_1.default.createElement(CaptureMemoryPill_1.CaptureMemoryPill, { topInset: insets.top }),
+            react_1.default.createElement(CaptureDebugOverlay_1.CaptureDebugOverlay, { incrementalState: incrementalState, imuTranslationMetres: isNonAR ? imuGate.getTranslationMetres() : null, captureSource: effectiveCaptureSource, frameSelectionMode: settings.frameSelection.mode, stitchMode: settings.stitcher.stitchMode }))),
+        react_1.default.createElement(CaptureStitchStatsToast_1.CaptureStitchStatsToast, { message: stitchToast.message, topInset: insets.top }),
         showSettingsButton && (react_1.default.createElement(SettingsButton, { topInset: insets.top, onPress: () => setSettingsModalVisible(true) })),
         react_1.default.createElement(react_native_1.View, { pointerEvents: "box-none", style: [styles.bottomArea, { paddingBottom: insets.bottom + 12 }] },
             statusPhase === 'recording' && (react_1.default.createElement(PanoramaBandOverlay_1.PanoramaBandOverlay, { state: incrementalState, frameUris: batchKeyframeThumbnails, captureOrientation: deviceOrientation })),

package/dist/camera/CaptureDebugOverlay.d.ts

@@ -0,0 +1,45 @@
+/**
+ * CaptureDebugOverlay — diagnostic overlay for capture sessions.
+ *
+ * Shows the live engine state in a floating pill at the top of the
+ * capture screen so operators can see:
+ *
+ *   - which frame outcome the engine just emitted (accept/skip/reject)
+ *   - keyframe count vs. cap (e.g. "3 / 6")
+ *   - per-frame newContent fraction + overlap percent
+ *   - latest processingMs (how long the gate eval took)
+ *   - JS-side IMU translation accumulator (when non-AR)
+ *   - JS heap usage estimate (rough — RN doesn't expose Native heap)
+ *
+ * The overlay is gated by `<Camera>`'s `settings.debug` flag.  When
+ * `debug = false` the component renders null and consumes no CPU.
+ *
+ * Why a separate component (not inline in Camera.tsx)?
+ *
+ *   Camera.tsx is already a 1200-line beast and the debug pill needs
+ *   its own styling/layout that would distract from the main capture
+ *   UX.  Splitting it out keeps Camera.tsx focused and the debug
+ *   surface easy to evolve independently (future F9 work — port the
+ *   richer memory bubble + stitch toast from the RetaiLens host).
+ *
+ *   This component is intentionally PRESENTATIONAL — all data is
+ *   pushed in as props.  The host (Camera.tsx) owns the
+ *   subscriptions / refs / state and decides when to mount the
+ *   overlay.
+ */
+import React from 'react';
+import type { IncrementalState } from '../stitching/incremental';
+export interface CaptureDebugOverlayProps {
+    /** Latest engine state (null = no capture in progress). */
+    incrementalState: IncrementalState | null;
+    /** JS-side IMU translation accumulator in metres (non-AR mode). */
+    imuTranslationMetres?: number | null;
+    /** Capture-source label so the operator knows which gate path is live. */
+    captureSource: 'ar' | 'non-ar';
+    /** Effective frame selection mode that's running right now. */
+    frameSelectionMode: 'time-based' | 'pose-based' | 'flow-based';
+    /** Effective stitchMode setting (operator-set, before auto-resolution). */
+    stitchMode: 'auto' | 'panorama' | 'scans';
+}
+export declare function CaptureDebugOverlay({ incrementalState, imuTranslationMetres, captureSource, frameSelectionMode, stitchMode, }: CaptureDebugOverlayProps): React.JSX.Element;
+//# sourceMappingURL=CaptureDebugOverlay.d.ts.map

package/dist/camera/CaptureDebugOverlay.js

@@ -0,0 +1,146 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CaptureDebugOverlay — diagnostic overlay for capture sessions.
+ *
+ * Shows the live engine state in a floating pill at the top of the
+ * capture screen so operators can see:
+ *
+ *   - which frame outcome the engine just emitted (accept/skip/reject)
+ *   - keyframe count vs. cap (e.g. "3 / 6")
+ *   - per-frame newContent fraction + overlap percent
+ *   - latest processingMs (how long the gate eval took)
+ *   - JS-side IMU translation accumulator (when non-AR)
+ *   - JS heap usage estimate (rough — RN doesn't expose Native heap)
+ *
+ * The overlay is gated by `<Camera>`'s `settings.debug` flag.  When
+ * `debug = false` the component renders null and consumes no CPU.
+ *
+ * Why a separate component (not inline in Camera.tsx)?
+ *
+ *   Camera.tsx is already a 1200-line beast and the debug pill needs
+ *   its own styling/layout that would distract from the main capture
+ *   UX.  Splitting it out keeps Camera.tsx focused and the debug
+ *   surface easy to evolve independently (future F9 work — port the
+ *   richer memory bubble + stitch toast from the RetaiLens host).
+ *
+ *   This component is intentionally PRESENTATIONAL — all data is
+ *   pushed in as props.  The host (Camera.tsx) owns the
+ *   subscriptions / refs / state and decides when to mount the
+ *   overlay.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CaptureDebugOverlay = CaptureDebugOverlay;
+const react_1 = __importDefault(require("react"));
+const react_native_1 = require("react-native");
+/**
+ * Map the numeric `outcome` enum to a short human label.  Mirrors
+ * the iOS/Android C++ enum.  Hidden in production builds — only
+ * surfaced via this debug overlay.
+ */
+function outcomeLabel(outcome) {
+    switch (outcome) {
+        case 1: return 'accept';
+        case 2: return 'reject';
+        case 3: return 'cap-hit';
+        default: return outcome == null ? '—' : String(outcome);
+    }
+}
+function CaptureDebugOverlay({ incrementalState, imuTranslationMetres, captureSource, frameSelectionMode, stitchMode, }) {
+    const accepted = incrementalState?.acceptedCount ?? 0;
+    const cap = incrementalState?.keyframeMax ?? 0;
+    const overlap = incrementalState?.overlapPercent;
+    const proc = incrementalState?.processingMs;
+    const outcome = outcomeLabel(incrementalState?.outcome);
+    const isLandscape = incrementalState?.isLandscape;
+    const painted = incrementalState?.paintedExtent ?? 0;
+    const panTotal = incrementalState?.panExtent ?? 0;
+    const fillPct = panTotal > 0 ? Math.round((painted / panTotal) * 100) : 0;
+    // Translation pill is only meaningful in non-AR mode (in AR the
+    // engine's own pose is the source of truth; we don't surface the
+    // tx/ty/tz separately because the operator can't act on them).
+    const showImu = captureSource === 'non-ar' && imuTranslationMetres != null;
+    const imuCm = showImu ? (imuTranslationMetres * 100).toFixed(1) : null;
+    return (react_1.default.createElement(react_native_1.View, { pointerEvents: "none", style: styles.container },
+        react_1.default.createElement(react_native_1.View, { style: styles.row },
+            react_1.default.createElement(react_native_1.Text, { style: styles.label },
+                captureSource,
+                "/",
+                frameSelectionMode,
+                "/",
+                stitchMode)),
+        react_1.default.createElement(react_native_1.View, { style: styles.row },
+            react_1.default.createElement(react_native_1.Text, { style: styles.metricKey }, "frames"),
+            react_1.default.createElement(react_native_1.Text, { style: styles.metricVal },
+                accepted,
+                cap > 0 ? ` / ${cap}` : '')),
+        react_1.default.createElement(react_native_1.View, { style: styles.row },
+            react_1.default.createElement(react_native_1.Text, { style: styles.metricKey }, "last"),
+            react_1.default.createElement(react_native_1.Text, { style: styles.metricVal }, outcome)),
+        (overlap != null && overlap >= 0) && (react_1.default.createElement(react_native_1.View, { style: styles.row },
+            react_1.default.createElement(react_native_1.Text, { style: styles.metricKey }, "overlap"),
+            react_1.default.createElement(react_native_1.Text, { style: styles.metricVal },
+                overlap.toFixed(0),
+                "%"))),
+        (proc != null && proc > 0) && (react_1.default.createElement(react_native_1.View, { style: styles.row },
+            react_1.default.createElement(react_native_1.Text, { style: styles.metricKey }, "proc"),
+            react_1.default.createElement(react_native_1.Text, { style: styles.metricVal },
+                proc.toFixed(0),
+                "ms"))),
+        panTotal > 0 && (react_1.default.createElement(react_native_1.View, { style: styles.row },
+            react_1.default.createElement(react_native_1.Text, { style: styles.metricKey }, "pan"),
+            react_1.default.createElement(react_native_1.Text, { style: styles.metricVal },
+                fillPct,
+                "% (",
+                isLandscape ? 'L' : 'P',
+                ")"))),
+        showImu && (react_1.default.createElement(react_native_1.View, { style: styles.row },
+            react_1.default.createElement(react_native_1.Text, { style: styles.metricKey }, "imu\u0394"),
+            react_1.default.createElement(react_native_1.Text, { style: styles.metricVal },
+                imuCm,
+                "cm")))));
+}
+const styles = react_native_1.StyleSheet.create({
+    container: {
+        position: 'absolute',
+        // 2026-05-22 — moved from top-left to left-middle so it doesn't
+        // collide with the orientation pill (top-left) or the keyframe
+        // pill (top-center) when all three are mounted together in
+        // <Camera>'s debug mode.
+        top: 160,
+        left: 12,
+        backgroundColor: 'rgba(0, 0, 0, 0.65)',
+        paddingHorizontal: 10,
+        paddingVertical: 6,
+        borderRadius: 8,
+        minWidth: 130,
+    },
+    row: {
+        flexDirection: 'row',
+        justifyContent: 'space-between',
+        alignItems: 'center',
+        marginVertical: 1,
+    },
+    label: {
+        color: '#fff',
+        fontSize: 11,
+        fontWeight: '600',
+        fontFamily: 'Menlo',
+    },
+    metricKey: {
+        color: '#9aa',
+        fontSize: 10,
+        fontFamily: 'Menlo',
+        marginRight: 8,
+    },
+    metricVal: {
+        color: '#fff',
+        fontSize: 11,
+        fontWeight: '600',
+        fontFamily: 'Menlo',
+    },
+});
+//# sourceMappingURL=CaptureDebugOverlay.js.map

package/dist/camera/CaptureKeyframePill.d.ts

@@ -0,0 +1,28 @@
+/**
+ * CaptureKeyframePill — top-center "Keyframes: N/M" diagnostic pill.
+ *
+ * Renders while a capture is in flight AND the engine is running
+ * the pose-driven / flow-driven keyframe gate (keyframeMax > 0).
+ * Hidden when the gate is disabled (time-based frame selection) or
+ * when no capture is active.
+ *
+ * Color-coded by closeness to the cap:
+ *
+ *   - green  N < M − 1   (plenty of budget remaining)
+ *   - amber  N ≥ M − 1   (last frame, or cap already hit — next
+ *                        accept will be rejected)
+ *
+ * Layer-2 hosts that compose their own capture UI can mount this
+ * pill directly; Layer-1 `<Camera>` mounts it automatically when
+ * `settings.debug = true`.
+ */
+import React from 'react';
+import type { IncrementalState } from '../stitching/incremental';
+export interface CaptureKeyframePillProps {
+    /** Latest engine state.  Null = capture not running. */
+    state: IncrementalState | null;
+    /** Top inset for safe-area placement.  Pill pinned `topInset + 56`. */
+    topInset?: number;
+}
+export declare function CaptureKeyframePill({ state, topInset, }: CaptureKeyframePillProps): React.JSX.Element | null;
+//# sourceMappingURL=CaptureKeyframePill.d.ts.map

package/dist/camera/CaptureKeyframePill.js

@@ -0,0 +1,60 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CaptureKeyframePill — top-center "Keyframes: N/M" diagnostic pill.
+ *
+ * Renders while a capture is in flight AND the engine is running
+ * the pose-driven / flow-driven keyframe gate (keyframeMax > 0).
+ * Hidden when the gate is disabled (time-based frame selection) or
+ * when no capture is active.
+ *
+ * Color-coded by closeness to the cap:
+ *
+ *   - green  N < M − 1   (plenty of budget remaining)
+ *   - amber  N ≥ M − 1   (last frame, or cap already hit — next
+ *                        accept will be rejected)
+ *
+ * Layer-2 hosts that compose their own capture UI can mount this
+ * pill directly; Layer-1 `<Camera>` mounts it automatically when
+ * `settings.debug = true`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CaptureKeyframePill = CaptureKeyframePill;
+const react_1 = __importDefault(require("react"));
+const react_native_1 = require("react-native");
+function CaptureKeyframePill({ state, topInset = 0, }) {
+    const accepted = state?.acceptedCount ?? 0;
+    const max = state?.keyframeMax ?? 0;
+    if (max <= 0)
+        return null;
+    const isAmber = accepted >= max - 1;
+    return (react_1.default.createElement(react_native_1.View, { pointerEvents: "none", style: [
+            styles.container,
+            {
+                top: topInset + 56,
+                backgroundColor: isAmber
+                    ? 'rgba(245, 158, 11, 0.95)'
+                    : 'rgba(34, 197, 94, 0.95)',
+            },
+        ], accessibilityRole: "alert", accessibilityLiveRegion: "polite" },
+        react_1.default.createElement(react_native_1.Text, { style: styles.text }, `Keyframes: ${accepted}/${max}`)));
+}
+const styles = react_native_1.StyleSheet.create({
+    container: {
+        position: 'absolute',
+        alignSelf: 'center',
+        paddingHorizontal: 14,
+        paddingVertical: 6,
+        borderRadius: 999,
+        zIndex: 100,
+    },
+    text: {
+        color: '#fff',
+        fontSize: 13,
+        fontWeight: '600',
+    },
+});
+//# sourceMappingURL=CaptureKeyframePill.js.map

package/dist/camera/CaptureMemoryPill.d.ts

@@ -0,0 +1,28 @@
+/**
+ * CaptureMemoryPill — top-right diagnostic pill showing native
+ * process memory footprint in MB, polled at 500 ms.
+ *
+ * Color-coded against the iPhone 16 Pro per-process jetsam limit:
+ *
+ *   - green  <1500 MB   (comfortable)
+ *   - amber  1500–2200  (approaching pressure)
+ *   - red    >2200      (close to limit — capture may be killed)
+ *
+ * Backed by the existing `getMemoryFootprintMB()` native module
+ * (iOS: `task_info phys_footprint`, Android: `Debug.MemoryInfo
+ * getTotalPss * 1024`).  Returns -1 if the native call fails.
+ *
+ * Mount this pill inside a `settings.debug`-gated branch — it
+ * polls native every 500 ms and is unwanted in production builds.
+ */
+import React from 'react';
+export interface CaptureMemoryPillProps {
+    /** Top inset (status bar / notch).  Pill pinned `topInset + 56`. */
+    topInset?: number;
+    /** Polling interval in ms.  Default 500.  Lower wastes battery
+     *  for no visible benefit; higher loses correlation with capture
+     *  activity. */
+    pollIntervalMs?: number;
+}
+export declare function CaptureMemoryPill({ topInset, pollIntervalMs, }: CaptureMemoryPillProps): React.JSX.Element | null;
+//# sourceMappingURL=CaptureMemoryPill.d.ts.map