react-native-image-stitcher 0.2.1 → 0.3.0

package/dist/camera/Camera.js

@@ -84,6 +84,11 @@ 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 PanoramaSettingsModal_1 = require("./PanoramaSettingsModal");
 const useCapture_1 = require("./useCapture");
@@ -273,6 +278,11 @@ 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);
+    // 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,6 +390,15 @@ 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.
     const imuGate = (0, useIMUTranslationGate_1.useIMUTranslationGate)({
         enabled: isNonAR
             && statusPhase === 'recording'
@@ -430,12 +449,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,6 +562,17 @@ 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
@@ -520,16 +590,35 @@ function Camera(props) {
                 canvasHeight: 5000,
                 engine: 'batch-keyframe',
                 config: {
+                    // ── cv::Stitcher (batch finalize) ─────────────────────────
                     stitchMode: settings.stitchMode,
                     warperType: settings.warperType,
                     blenderType: settings.blenderType,
                     seamFinderType: settings.seamFinderType,
+                    enableMaxInscribedRectCrop: settings.enableMaxInscribedRectCrop,
+                    // ── KeyframeGate (per-frame selection) ────────────────────
+                    // F6 audit fix: pass settings.frameSelectionMode through
+                    // instead of hardcoding 'flow-based' (which silently made the
+                    // time-based / pose-based modal options no-ops).
+                    frameSelectionMode: settings.frameSelectionMode,
+                    keyframeMaxCount: settings.keyframeMaxCount,
+                    keyframeOverlapThreshold: settings.keyframeOverlapThreshold,
+                    // ── Flow-strategy tunables ────────────────────────────────
+                    // F4 audit fix: previously omitted, which made the modal
+                    // sliders for these three a complete no-op (only iOS native
+                    // even read them, and only when JS sent them).
                     flowNoveltyPercentile: settings.flowNoveltyPercentile,
                     flowEvalEveryNFrames: settings.flowEvalEveryNFrames,
                     flowMaxTranslationCm: settings.flowMaxTranslationCm,
-                    keyframeMaxCount: settings.keyframeMaxCount,
-                    keyframeOverlapThreshold: settings.keyframeOverlapThreshold,
-                    frameSelectionMode: 'flow-based',
+                    flowMaxCorners: settings.flowMaxCorners,
+                    flowQualityLevel: settings.flowQualityLevel,
+                    flowMinDistance: settings.flowMinDistance,
+                    // ── Engine-routing flags consumed by native ───────────────
+                    // F1 audit fix: Android keyframe gate's disableAngularFallback
+                    // opt-out reads this to decide whether to skip the angular
+                    // fallback (gyro pose is too noisy for the FoV-overlap calc
+                    // in non-AR mode, causing degenerate cv::Stitcher params).
+                    captureSource: settings.captureSource,
                 },
             });
             imuGate.resetAnchor();
@@ -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);
@@ -641,6 +745,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.frameSelectionMode, stitchMode: settings.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

package/dist/camera/CaptureMemoryPill.js

@@ -0,0 +1,109 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CaptureMemoryPill = CaptureMemoryPill;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const incremental_1 = require("../stitching/incremental");
+function CaptureMemoryPill({ topInset = 0, pollIntervalMs = 500, }) {
+    const [memMB, setMemMB] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        const native = (0, incremental_1.getIncrementalNativeModule)();
+        if (!native?.getMemoryFootprintMB)
+            return undefined;
+        let cancelled = false;
+        const tick = async () => {
+            try {
+                const mb = await native.getMemoryFootprintMB();
+                if (!cancelled)
+                    setMemMB(mb);
+            }
+            catch {
+                // Bridge error — leave the previous reading visible.
+            }
+        };
+        tick();
+        const id = setInterval(tick, pollIntervalMs);
+        return () => {
+            cancelled = true;
+            clearInterval(id);
+        };
+    }, [pollIntervalMs]);
+    if (memMB === null || memMB < 0)
+        return null;
+    const bg = memMB > 2200 ? 'rgba(239, 68, 68, 0.92)' // red
+        : memMB > 1500 ? 'rgba(245, 158, 11, 0.92)' // amber
+            : 'rgba(34, 197, 94, 0.92)'; // green
+    return (react_1.default.createElement(react_native_1.View, { pointerEvents: "none", style: [
+            styles.container,
+            { top: topInset + 56, backgroundColor: bg },
+        ], accessibilityRole: "alert" },
+        react_1.default.createElement(react_native_1.Text, { style: styles.text }, `${Math.round(memMB)} MB`)));
+}
+const styles = react_native_1.StyleSheet.create({
+    container: {
+        position: 'absolute',
+        right: 12,
+        paddingHorizontal: 10,
+        paddingVertical: 5,
+        borderRadius: 999,
+        zIndex: 100,
+    },
+    text: {
+        color: '#fff',
+        fontSize: 12,
+        fontWeight: '700',
+        fontFamily: 'Menlo',
+    },
+});
+//# sourceMappingURL=CaptureMemoryPill.js.map

package/dist/camera/CaptureOrientationPill.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CaptureOrientationPill — diagnostic pill showing the operator's
+ * current hold orientation as detected by the pose-derived hook.
+ *
+ * Useful for diagnosing rotation issues — if the pill says
+ * `landscape-left` but the band overlay is rendering as if it's
+ * `portrait`, there's a mismatch between the JS orientation hook
+ * and the engine's pose-derived isLandscape signal.
+ *
+ * Pinned top-left below the status bar.  Layer-2 hosts can mount
+ * this directly; Layer-1 `<Camera>` mounts it automatically when
+ * `settings.debug = true`.
+ */
+import React from 'react';
+export interface CaptureOrientationPillProps {
+    /** Current device orientation (typically from useDeviceOrientation). */
+    orientation: string;
+    /** Top inset for safe-area placement.  Pill pinned `topInset + 56`. */
+    topInset?: number;
+}
+export declare function CaptureOrientationPill({ orientation, topInset, }: CaptureOrientationPillProps): React.JSX.Element;
+//# sourceMappingURL=CaptureOrientationPill.d.ts.map