react-native-image-stitcher 0.2.1 → 0.4.0

package/src/camera/Camera.tsx

@@ -63,12 +63,20 @@ import { ARCameraView, type ARCameraViewHandle } from './ARCameraView';
 import { CameraShutter } from './CameraShutter';
 import { CameraView } from './CameraView';
 import { CaptureStatusOverlay, type CaptureStatusPhase } from './CaptureStatusOverlay';
+import { CaptureDebugOverlay } from './CaptureDebugOverlay';
+import { CaptureMemoryPill } from './CaptureMemoryPill';
+import { CaptureKeyframePill } from './CaptureKeyframePill';
+import { CaptureOrientationPill } from './CaptureOrientationPill';
+import { CaptureStitchStatsToast, useStitchStatsToast } from './CaptureStitchStatsToast';
 import { PanoramaBandOverlay } from './PanoramaBandOverlay';
+import { type PanoramaSettings } from './PanoramaSettings';
+import { panoramaSettingsToNativeConfig } from './PanoramaSettingsBridge';
+import { PanoramaSettingsModal } from './PanoramaSettingsModal';
 import {
-  DEFAULT_PANORAMA_SETTINGS,
-  PanoramaSettingsModal,
-  type PanoramaSettings,
-} from './PanoramaSettingsModal';
+  buildPanoramaInitialSettings,
+  type PanoramaPropOverrides,
+} from './buildPanoramaInitialSettings';
+import { isLowMemDevice } from './lowMemDevice';
 import { useCapture } from './useCapture';
 import { useDeviceOrientation } from './useDeviceOrientation';
 import {
@@ -129,6 +137,15 @@ export type CameraCaptureResult =
       framesDropped: number;
       finalConfidenceThresh: number;
       durationMs: number;
+      /**
+       * 2026-05-22 (audit F2g) — which cv::Stitcher pipeline the
+       * batch finalize ran (after auto-resolution if applicable).
+       * Useful for displaying a "Stitched as: scans" pill on the
+       * output preview.  Undefined when the engine wasn't
+       * batch-keyframe (hybrid / slit-scan don't go through
+       * cv::Stitcher at finalize).
+       */
+      stitchModeResolved?: 'panorama' | 'scans';
     };
 
 
@@ -457,40 +474,31 @@ function deriveEffectiveCaptureSource(
 
 
 /**
- * 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: CameraProps): PanoramaSettings {
+function extractPanoramaOverrides(props: CameraProps): PanoramaPropOverrides {
   return {
-    ...DEFAULT_PANORAMA_SETTINGS,
-    stitchMode: props.defaultStitchMode ?? DEFAULT_PANORAMA_SETTINGS.stitchMode,
-    blenderType:
-      props.defaultBlender ?? DEFAULT_PANORAMA_SETTINGS.blenderType,
-    seamFinderType:
-      props.defaultSeamFinder ?? DEFAULT_PANORAMA_SETTINGS.seamFinderType,
-    warperType:
-      props.defaultWarper ?? DEFAULT_PANORAMA_SETTINGS.warperType,
-    flowNoveltyPercentile:
-      props.defaultFlowNoveltyPercentile ??
-      DEFAULT_PANORAMA_SETTINGS.flowNoveltyPercentile,
-    flowEvalEveryNFrames:
-      props.defaultFlowEvalEveryNFrames ??
-      DEFAULT_PANORAMA_SETTINGS.flowEvalEveryNFrames,
-    flowMaxTranslationCm:
-      props.defaultFlowMaxTranslationCm ??
-      DEFAULT_PANORAMA_SETTINGS.flowMaxTranslationCm,
-    keyframeMaxCount:
-      props.defaultKeyframeMaxCount ??
-      DEFAULT_PANORAMA_SETTINGS.keyframeMaxCount,
-    keyframeOverlapThreshold:
-      props.defaultKeyframeOverlapThreshold ??
-      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,
   };
 }
 
@@ -532,7 +540,10 @@ export function Camera(props: CameraProps): React.JSX.Element {
   );
   const [lens, setLens] = useState<CameraLens>(defaultLens);
   const [settings, setSettings] = useState<PanoramaSettings>(() =>
-    buildInitialSettings(props),
+    buildPanoramaInitialSettings(
+      extractPanoramaOverrides(props),
+      isLowMemDevice(),
+    ),
   );
   const [settingsModalVisible, setSettingsModalVisible] = useState(false);
   const [statusPhase, setStatusPhase] = useState<CaptureStatusPhase>('idle');
@@ -540,6 +551,11 @@ export function Camera(props: CameraProps): React.JSX.Element {
     null,
   );
   const [incrementalState, setIncrementalState] = useState<IncrementalState | null>(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 = useStitchStatsToast();
   const [batchKeyframeThumbnails, setBatchKeyframeThumbnails] = useState<
     string[]
   >([]);
@@ -666,12 +682,27 @@ export function Camera(props: CameraProps): React.JSX.Element {
   // 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 = 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 = getIncrementalNativeModule();
       mod?.markNextFrameAsLastKeyframe?.().catch(() => undefined);
@@ -718,12 +749,52 @@ export function Camera(props: CameraProps): React.JSX.Element {
     });
     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 = useRef(0);
   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 ────────────────────────────────────────────
 
@@ -805,12 +876,42 @@ export function Camera(props: CameraProps): React.JSX.Element {
       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: 0 | 90 | 180 | 270 =
         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,
@@ -822,18 +923,10 @@ export function Camera(props: CameraProps): React.JSX.Element {
         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: panoramaSettingsToNativeConfig({
+          ...settings,
+          captureSource: effectiveCaptureSource,
+        }),
       });
       imuGate.resetAnchor();
       // Start pumping vision-camera snapshots into the engine for
@@ -861,6 +954,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
     isNonAR,
     deviceOrientation,
     settings,
+    effectiveCaptureSource,
     imuGate,
     jsDriver,
     onError,
@@ -882,10 +976,19 @@ export function Camera(props: CameraProps): React.JSX.Element {
       const panoOutputPath = outputDir
         ? `${toBareFilePath(outputDir).replace(/\/$/, '')}/${defaultPanoramaFilename()}`
         : `${await getDefaultCaptureDir()}/${defaultPanoramaFilename()}`;
+      // 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'
@@ -910,7 +1013,15 @@ export function Camera(props: CameraProps): React.JSX.Element {
           (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);
       const code: CameraErrorCode =
@@ -933,6 +1044,18 @@ export function Camera(props: CameraProps): React.JSX.Element {
     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 ───────────────────────────────────
@@ -988,6 +1111,49 @@ export function Camera(props: CameraProps): React.JSX.Element {
         recordingStartedAt={recordingStartedAt ?? undefined}
       />
 
+      {/*
+        2026-05-22 (audit F9 + F3) — debug UI suite, all gated on
+        settings.debug.  Mounts in <Camera> automatically; Layer-2
+        hosts can import the individual components from the public
+        API and compose their own debug surface.  Layout:
+          - top-left:    orientation pill (purple)
+          - top-center:  keyframes pill (green/amber)
+          - top-right:   memory pill (green/amber/red)
+          - top-center:  stitch-stats toast (dark capsule, transient)
+          - left-mid:    detailed metrics block (overlap, processing,
+                         imuΔ, etc.) — uses CaptureDebugOverlay
+       */}
+      {settings.debug && (
+        <>
+          <CaptureOrientationPill
+            orientation={deviceOrientation}
+            topInset={insets.top}
+          />
+          <CaptureKeyframePill
+            state={incrementalState}
+            topInset={insets.top}
+          />
+          <CaptureMemoryPill topInset={insets.top} />
+          <CaptureDebugOverlay
+            incrementalState={incrementalState}
+            imuTranslationMetres={
+              isNonAR ? imuGate.getTranslationMetres() : null
+            }
+            captureSource={effectiveCaptureSource}
+            frameSelectionMode={settings.frameSelection.mode}
+            stitchMode={settings.stitcher.stitchMode}
+          />
+        </>
+      )}
+      {/* Toast renders regardless of `settings.debug` — toast hook
+       *  is only ever fired from the debug-gated path, but mounting
+       *  unconditionally lets Layer-2 hosts wire their own showFor()
+       *  callers without needing a separate mount. */}
+      <CaptureStitchStatsToast
+        message={stitchToast.message}
+        topInset={insets.top}
+      />
+
       {/* Settings gear (top-right), gated on showSettingsButton. */}
       {showSettingsButton && (
         <SettingsButton

package/src/camera/CaptureDebugOverlay.tsx

@@ -0,0 +1,180 @@
+// 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.
+ */
+
+import React from 'react';
+import { StyleSheet, Text, View } from 'react-native';
+
+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';
+}
+
+/**
+ * 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: number | undefined): string {
+  switch (outcome) {
+    case 1: return 'accept';
+    case 2: return 'reject';
+    case 3: return 'cap-hit';
+    default: return outcome == null ? '—' : String(outcome);
+  }
+}
+
+
+export function CaptureDebugOverlay({
+  incrementalState,
+  imuTranslationMetres,
+  captureSource,
+  frameSelectionMode,
+  stitchMode,
+}: CaptureDebugOverlayProps): React.JSX.Element {
+  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 (
+    <View pointerEvents="none" style={styles.container}>
+      {/* Top row: mode summary */}
+      <View style={styles.row}>
+        <Text style={styles.label}>
+          {captureSource}/{frameSelectionMode}/{stitchMode}
+        </Text>
+      </View>
+      {/* Keyframes pill */}
+      <View style={styles.row}>
+        <Text style={styles.metricKey}>frames</Text>
+        <Text style={styles.metricVal}>
+          {accepted}{cap > 0 ? ` / ${cap}` : ''}
+        </Text>
+      </View>
+      {/* Outcome */}
+      <View style={styles.row}>
+        <Text style={styles.metricKey}>last</Text>
+        <Text style={styles.metricVal}>{outcome}</Text>
+      </View>
+      {/* Overlap + processing */}
+      {(overlap != null && overlap >= 0) && (
+        <View style={styles.row}>
+          <Text style={styles.metricKey}>overlap</Text>
+          <Text style={styles.metricVal}>{overlap.toFixed(0)}%</Text>
+        </View>
+      )}
+      {(proc != null && proc > 0) && (
+        <View style={styles.row}>
+          <Text style={styles.metricKey}>proc</Text>
+          <Text style={styles.metricVal}>{proc.toFixed(0)}ms</Text>
+        </View>
+      )}
+      {/* Pan progress (band overlay metric) */}
+      {panTotal > 0 && (
+        <View style={styles.row}>
+          <Text style={styles.metricKey}>pan</Text>
+          <Text style={styles.metricVal}>
+            {fillPct}% ({isLandscape ? 'L' : 'P'})
+          </Text>
+        </View>
+      )}
+      {/* IMU translation — only in non-AR mode */}
+      {showImu && (
+        <View style={styles.row}>
+          <Text style={styles.metricKey}>imuΔ</Text>
+          <Text style={styles.metricVal}>{imuCm}cm</Text>
+        </View>
+      )}
+    </View>
+  );
+}
+
+const styles = 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',
+  },
+});

package/src/camera/CaptureKeyframePill.tsx

@@ -0,0 +1,77 @@
+// 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`.
+ */
+
+import React from 'react';
+import { StyleSheet, Text, View } from 'react-native';
+
+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 function CaptureKeyframePill({
+  state,
+  topInset = 0,
+}: CaptureKeyframePillProps): React.JSX.Element | null {
+  const accepted = state?.acceptedCount ?? 0;
+  const max = state?.keyframeMax ?? 0;
+  if (max <= 0) return null;
+
+  const isAmber = accepted >= max - 1;
+
+  return (
+    <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"
+    >
+      <Text style={styles.text}>{`Keyframes: ${accepted}/${max}`}</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    position: 'absolute',
+    alignSelf: 'center',
+    paddingHorizontal: 14,
+    paddingVertical: 6,
+    borderRadius: 999,
+    zIndex: 100,
+  },
+  text: {
+    color: '#fff',
+    fontSize: 13,
+    fontWeight: '600',
+  },
+});