react-native-image-stitcher 0.2.1 → 0.3.0

package/src/camera/Camera.tsx

@@ -63,6 +63,11 @@ 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 {
   DEFAULT_PANORAMA_SETTINGS,
@@ -129,6 +134,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';
     };
 
 
@@ -540,6 +554,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,6 +685,15 @@ 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.
   const imuGate = useIMUTranslationGate({
     enabled:
       isNonAR
@@ -718,12 +746,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,6 +873,17 @@ 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 =
@@ -823,16 +902,35 @@ export function Camera(props: CameraProps): React.JSX.Element {
         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();
@@ -882,10 +980,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 +1017,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 =
@@ -988,6 +1103,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.frameSelectionMode}
+            stitchMode={settings.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',
+  },
+});

package/src/camera/CaptureMemoryPill.tsx

@@ -0,0 +1,96 @@
+// 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.
+ */
+
+import React, { useEffect, useState } from 'react';
+import { StyleSheet, Text, View } from 'react-native';
+
+import { getIncrementalNativeModule } from '../stitching/incremental';
+
+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 function CaptureMemoryPill({
+  topInset = 0,
+  pollIntervalMs = 500,
+}: CaptureMemoryPillProps): React.JSX.Element | null {
+  const [memMB, setMemMB] = useState<number | null>(null);
+
+  useEffect(() => {
+    const native = 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 (
+    <View
+      pointerEvents="none"
+      style={[
+        styles.container,
+        { top: topInset + 56, backgroundColor: bg },
+      ]}
+      accessibilityRole="alert"
+    >
+      <Text style={styles.text}>{`${Math.round(memMB)} MB`}</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    position: 'absolute',
+    right: 12,
+    paddingHorizontal: 10,
+    paddingVertical: 5,
+    borderRadius: 999,
+    zIndex: 100,
+  },
+  text: {
+    color: '#fff',
+    fontSize: 12,
+    fontWeight: '700',
+    fontFamily: 'Menlo',
+  },
+});

package/src/camera/CaptureOrientationPill.tsx

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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';
+import { StyleSheet, Text, View } from 'react-native';
+
+export interface CaptureOrientationPillProps {
+  /** Current device orientation (typically from useDeviceOrientation). */
+  orientation: string;
+  /** Top inset for safe-area placement.  Pill pinned `topInset + 56`. */
+  topInset?: number;
+}
+
+export function CaptureOrientationPill({
+  orientation,
+  topInset = 0,
+}: CaptureOrientationPillProps): React.JSX.Element {
+  return (
+    <View
+      pointerEvents="none"
+      style={[styles.container, { top: topInset + 56 }]}
+      accessibilityRole="alert"
+    >
+      <Text style={styles.text}>{`orient: ${orientation}`}</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    position: 'absolute',
+    left: 12,
+    paddingHorizontal: 10,
+    paddingVertical: 5,
+    borderRadius: 999,
+    backgroundColor: 'rgba(99, 102, 241, 0.92)',
+    zIndex: 100,
+  },
+  text: {
+    color: '#fff',
+    fontSize: 11,
+    fontWeight: '700',
+    fontFamily: 'Menlo',
+  },
+});