react-native-image-stitcher 0.15.1 → 0.16.0

package/src/camera/guidanceGraphics.tsx

@@ -0,0 +1,347 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * guidanceGraphics — code-drawn replacements for the two authored guidance
+ * GIFs (rotate-to-landscape, pan-capture).  Built from pure React-Native
+ * core `View` + `Animated` primitives — NO `react-native-svg`, NO bundled
+ * image assets — so the library keeps its "zero extra native deps for
+ * guidance" contract (see `RectCropPreview`) AND no longer needs the host
+ * to add Fresco's `animated-gif` module on Android just to make the
+ * coach-marks move.
+ *
+ * Why not GIFs:  the authored GIFs were 280 px sources shown at 240 dp;
+ * on a ~2.6×-density phone that 240 dp is ~630 physical px, so the 280 px
+ * source was up-scaled ~2.25× → visibly pixelated.  A 256-colour GIF also
+ * bands.  These vector-ish primitives are resolution-independent (they're
+ * just borders + transforms the GPU rasterises at native density) and fully
+ * themeable via `GUIDANCE_TOKENS`.
+ *
+ * Both graphics:
+ *   • run a single `Animated.loop` on the NATIVE driver (transform/opacity
+ *     only) so the loop is off the JS thread;
+ *   • take a `playing` flag — the host renders them only while `visible`,
+ *     but we still gate the loop so a mounted-but-paused graphic costs
+ *     nothing;
+ *   • scale every dimension off a single `size` (defaults to the shared
+ *     `GUIDANCE_TOKENS.graphicSize`) so callers can resize without restyle.
+ */
+
+import React, { useEffect, useRef } from 'react';
+import {
+  Animated,
+  Easing,
+  StyleSheet,
+  View,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+
+import { GUIDANCE_TOKENS } from './guidanceTokens';
+
+
+const DEFAULT_SIZE = GUIDANCE_TOKENS.graphicSize;
+
+
+/** Pan direction the pan-graphic should animate (mirrors PanHowToOverlay). */
+export type PanGraphicDirection = 'down' | 'right';
+
+
+export interface GuidanceGraphicProps {
+  /** Canvas square size in px.  Defaults to `GUIDANCE_TOKENS.graphicSize`. */
+  size?: number;
+  /** Run the animation loop.  `false` parks the value at rest. */
+  playing?: boolean;
+  /** Outer style passthrough. */
+  style?: StyleProp<ViewStyle>;
+}
+
+
+/**
+ * A white rounded-rectangle "phone" outline with a small camera dot on its
+ * top short edge.  The dot makes the device's up-axis legible, so when the
+ * rotate graphic turns the body the rotation reads unambiguously.  Children
+ * (e.g. the pan sweep band) render over the screen area.
+ */
+function PhoneBody({
+  width,
+  height,
+  children,
+  style,
+}: {
+  width: number;
+  height: number;
+  children?: React.ReactNode;
+  style?: StyleProp<ViewStyle>;
+}): React.JSX.Element {
+  const radius = Math.min(width, height) * 0.16;
+  const short = Math.min(width, height);
+  const dotSize = Math.max(4, short * 0.09);
+  const inset = Math.max(4, short * 0.06);
+  // The front-facing camera always sits on a SHORT edge: top-centre for a
+  // tall (portrait) body, side-centre for a wide (landscape) body.  (Was
+  // top-centre unconditionally, which put the dot mid-LONG-edge on a
+  // landscape body.)
+  const isWide = width > height;
+  const dotPos: ViewStyle = isWide
+    ? { left: inset, top: height / 2 - dotSize / 2 }
+    : { top: inset, left: width / 2 - dotSize / 2 };
+  return (
+    <View
+      style={[
+        {
+          width,
+          height,
+          borderRadius: radius,
+          borderWidth: Math.max(2, width * 0.03),
+          borderColor: GUIDANCE_TOKENS.white,
+        },
+        styles.phoneBody,
+        style,
+      ]}
+    >
+      <View
+        style={[
+          styles.cameraDot,
+          { width: dotSize, height: dotSize, borderRadius: dotSize / 2 },
+          dotPos,
+        ]}
+      />
+      {children}
+    </View>
+  );
+}
+
+
+/**
+ * RotatePhoneGraphic — a portrait phone outline that rotates 0°→90°→0°
+ * (portrait → landscape → portrait) on a loop, riding a faint amber guide
+ * ring with a clockwise arrowhead, demonstrating the "rotate to landscape"
+ * gesture.  Replaces `rotate-to-landscape.gif`.
+ */
+export function RotatePhoneGraphic({
+  size = DEFAULT_SIZE,
+  playing = true,
+  style,
+  target = 'landscape',
+}: GuidanceGraphicProps & {
+  /** Orientation to rotate TO: 'landscape' (default) or 'portrait'. */
+  target?: 'landscape' | 'portrait';
+}): React.JSX.Element {
+  // Single 0→1 loop value drives a ONE-WAY demonstration: hold the START
+  // orientation, rotate to the TARGET, hold, then fade out + reset (the
+  // reverse rotation happens while invisible).  This avoids the symmetric
+  // oscillation, which dwelt at the target and read as "starts at target,
+  // rotates away" — i.e. backwards.
+  const t = useRef(new Animated.Value(0)).current;
+
+  useEffect(() => {
+    if (!playing) {
+      t.setValue(0);
+      return;
+    }
+    const loop = Animated.loop(
+      Animated.timing(t, {
+        toValue: 1,
+        duration: 2200,
+        easing: Easing.inOut(Easing.cubic),
+        useNativeDriver: true,
+      }),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [playing, t]);
+
+  // To-landscape: start portrait (tall), rotate anticlockwise to landscape.
+  // To-portrait: start landscape (wide), rotate clockwise to stand upright.
+  const toLandscape = target === 'landscape';
+  const targetDeg = toLandscape ? '-90deg' : '90deg';
+  // Hold START (0°) → rotate to TARGET → hold TARGET.
+  const rotate = t.interpolate({
+    inputRange: [0, 0.18, 0.62, 1],
+    outputRange: ['0deg', '0deg', targetDeg, targetDeg],
+  });
+  // Fade in at START, hold through the rotation, fade out at TARGET so the
+  // invisible reset (target→start on loop) is never seen.
+  const phoneOpacity = t.interpolate({
+    inputRange: [0, 0.12, 0.82, 1],
+    outputRange: [0, 1, 1, 0],
+  });
+
+  const ring = size * 0.78;
+  const ringInset = (size - ring) / 2;
+  const phoneW = toLandscape ? size * 0.3 : size * 0.56;
+  const phoneH = toLandscape ? size * 0.56 : size * 0.3;
+
+  return (
+    <View
+      style={[{ width: size, height: size }, styles.center, style]}
+      pointerEvents="none"
+    >
+      {/* Faint full guide ring — the rotation "path" (centred behind the
+          phone via explicit insets; absolute views don't honour the
+          parent's center alignment). */}
+      <View
+        style={[
+          styles.ring,
+          {
+            width: ring,
+            height: ring,
+            borderRadius: ring / 2,
+            top: ringInset,
+            left: ringInset,
+            borderColor: GUIDANCE_TOKENS.amber,
+          },
+        ]}
+      />
+      {/* Arrowhead on the ring at top-centre, pointing along the rotation's
+          tangent: LEFT for anticlockwise (to-landscape), RIGHT for clockwise
+          (to-portrait). */}
+      <View
+        style={[
+          styles.arrowHead,
+          toLandscape ? styles.arrowHeadLeft : styles.arrowHeadRight,
+          { top: ringInset - 5, left: size / 2 - 5 },
+        ]}
+      />
+
+      <Animated.View
+        style={{ opacity: phoneOpacity, transform: [{ rotate }] }}
+      >
+        <PhoneBody width={phoneW} height={phoneH} />
+      </Animated.View>
+    </View>
+  );
+}
+
+
+/**
+ * PanPhoneGraphic — a phone outline (landscape for Mode-A `down`, portrait
+ * for Mode-B `right`) with an amber sweep band that travels across the pan
+ * axis on a loop, demonstrating the camera sweep.  The band fades in/out at
+ * the travel ends so the loop reset is invisible.  Replaces
+ * `pan-capture.gif`.  The bouncing direction arrow stays in PanHowToOverlay.
+ */
+export function PanPhoneGraphic({
+  direction,
+  size = DEFAULT_SIZE,
+  playing = true,
+  style,
+}: GuidanceGraphicProps & { direction: PanGraphicDirection }): React.JSX.Element {
+  // One value loops 0→1; drives the phone's travel + perspective tilt
+  // together so the device reads as ROTATING as it sweeps along the arrow.
+  const t = useRef(new Animated.Value(0)).current;
+
+  useEffect(() => {
+    if (!playing) {
+      t.setValue(0);
+      return;
+    }
+    const loop = Animated.loop(
+      Animated.timing(t, {
+        toValue: 1,
+        duration: 1900,
+        easing: Easing.inOut(Easing.ease),
+        useNativeDriver: true,
+      }),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [playing, t, direction]);
+
+  const down = direction === 'down';
+  // Mode A (down) holds the phone LANDSCAPE; Mode B (right) PORTRAIT.
+  const phoneW = down ? size * 0.5 : size * 0.34;
+  const phoneH = down ? size * 0.34 : size * 0.5;
+
+  // Travel ± along the pan axis (down → +Y, right → +X), kept in-canvas.
+  const amp = size * 0.2;
+  const translate = t.interpolate({
+    inputRange: [0, 1],
+    outputRange: [-amp, amp],
+  });
+  // The device TILTS through the sweep — rotating about the cross-pan axis
+  // as it pans — which is the 3D "the phone is turning" read the flat
+  // band lacked.  rotateX for a vertical (down) pan, rotateY for horizontal.
+  // The horizontal (right) tilt is INVERTED vs the vertical one so the edge
+  // on the side the phone is currently on reads LONGER (convex toward the
+  // viewer) — matched to on-device feedback for the portrait Mode-B pan.
+  const tilt = t.interpolate({
+    inputRange: [0, 1],
+    outputRange: down ? ['-24deg', '24deg'] : ['24deg', '-24deg'],
+  });
+  // Fade at the travel ends so the loop's restart is invisible.
+  const opacity = t.interpolate({
+    inputRange: [0, 0.15, 0.85, 1],
+    outputRange: [0, 1, 1, 0],
+  });
+
+  // `perspective` makes the rotateX/rotateY read as depth (a turning
+  // device), not a flat vertical squash.
+  const transform = down
+    ? [{ perspective: 800 }, { translateY: translate }, { rotateX: tilt }]
+    : [{ perspective: 800 }, { translateX: translate }, { rotateY: tilt }];
+
+  return (
+    <View
+      style={[{ width: size, height: size }, styles.center, style]}
+      pointerEvents="none"
+    >
+      <Animated.View style={{ opacity, transform }}>
+        <PhoneBody width={phoneW} height={phoneH}>
+          {/* Faint amber "screen" so the turning glass catches the light. */}
+          <View style={styles.screenGlow} pointerEvents="none" />
+        </PhoneBody>
+      </Animated.View>
+    </View>
+  );
+}
+
+
+const styles = StyleSheet.create({
+  center: { alignItems: 'center', justifyContent: 'center' },
+  phoneBody: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: 'transparent',
+  },
+  cameraDot: {
+    position: 'absolute',
+    backgroundColor: GUIDANCE_TOKENS.white,
+  },
+  ring: {
+    position: 'absolute',
+    borderWidth: 1.5,
+    opacity: 0.28,
+    backgroundColor: 'transparent',
+  },
+  // Amber CSS-triangle arrowhead at the top of the ring.  The base props are
+  // shared; the direction-specific style colours the trailing border so the
+  // apex points along the rotation tangent.
+  arrowHead: {
+    position: 'absolute',
+    width: 0,
+    height: 0,
+    borderTopWidth: 6,
+    borderBottomWidth: 6,
+    borderTopColor: 'transparent',
+    borderBottomColor: 'transparent',
+  },
+  // Points LEFT (anticlockwise / to-landscape): RIGHT border amber.
+  arrowHeadLeft: {
+    borderRightWidth: 10,
+    borderRightColor: GUIDANCE_TOKENS.amber,
+  },
+  // Points RIGHT (clockwise / to-portrait): LEFT border amber.
+  arrowHeadRight: {
+    borderLeftWidth: 10,
+    borderLeftColor: GUIDANCE_TOKENS.amber,
+  },
+  // Faint amber fill inside the phone outline — a hint of the live
+  // preview so the turning device reads as a screen, not an empty frame.
+  screenGlow: {
+    width: '78%',
+    height: '70%',
+    borderRadius: 6,
+    backgroundColor: GUIDANCE_TOKENS.amber,
+    opacity: 0.14,
+  },
+});

package/src/camera/guidanceTokens.ts

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * guidanceTokens — the single source of truth for the panorama capture
+ * GUIDANCE visual language (rotate prompt, pan how-to, countdown, too-fast
+ * pill, lateral popup).  Values are taken verbatim from the design handoff
+ * ("Camera Capture Guides") so every guidance surface shares exact styling
+ * instead of re-declaring colors per component.
+ *
+ * The two looping device-motion graphics are drawn programmatically (see
+ * ./guidanceGraphics — pure RN View + Animated, no image assets); these
+ * tokens cover both those graphics and the code-built chrome around them.
+ */
+
+export const GUIDANCE_TOKENS = {
+  /** Device outline, caption text, countdown number. */
+  white: '#FFFFFF',
+  /** Rotation ring/arrow, pan guide line, dots, glow — the one accent. */
+  amber: '#FFC462',
+  /** Caption-pill / popup background scrim. */
+  scrim: 'rgba(0,0,0,0.42)',
+  /** Pill hairline border. */
+  hairline: 'rgba(255,255,255,0.16)',
+  /** On-screen size (px square) of the rotate / pan guidance graphics. */
+  graphicSize: 240,
+} as const;
+
+/**
+ * Caption-pill spec (item 2 "Rotate to landscape" + reused by the too-fast
+ * pill): full pill, scrim bg, hairline border, amber leading dot, white
+ * 13px/600 text.
+ */
+export const GUIDANCE_PILL = {
+  paddingVertical: 8,
+  paddingHorizontal: 15,
+  borderRadius: 999,
+  dotSize: 6,
+  dotGap: 7,
+  fontSize: 13,
+  fontWeight: '600' as const,
+} as const;
+
+/**
+ * Countdown spec (item 5): amber dot + glow, white 30px/700 tabular-nums
+ * number, whole timer blinks opacity 0.18↔1 over a 1s ease-in-out cycle.
+ */
+export const GUIDANCE_COUNTDOWN = {
+  dotSize: 9,
+  dotGap: 8,
+  dotGlow: 'rgba(255,196,98,0.85)',
+  fontSize: 30,
+  fontWeight: '700' as const,
+  blinkMinOpacity: 0.18,
+  blinkMaxOpacity: 1,
+  blinkPeriodMs: 1000,
+  /** top/left inset from the (user-perceived) corner. */
+  inset: 16,
+} as const;

package/src/camera/panModeGate.ts

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * panModeGate — pure decision helper for the first-time-user "rotate the
+ * device" gate (guidance item 1).
+ *
+ * The non-AR panorama flow has two pan directions:
+ *
+ *   - **vertical** — the user holds the phone LANDSCAPE and pans the camera
+ *     TOP → BOTTOM down a tall fixture.  Both `landscape-left` and
+ *     `landscape-right` are valid holds.
+ *   - **horizontal** — the user holds the phone PORTRAIT and pans LEFT →
+ *     RIGHT across a wide scene.  Both portrait holds are valid.
+ *
+ * A host restricts capture via the `panMode` flag:
+ *   - `'vertical'`   → landscape-only; a PORTRAIT hold is gated (rotate to
+ *                      landscape).
+ *   - `'horizontal'` → portrait-only; a LANDSCAPE hold is gated (rotate to
+ *                      portrait).
+ *   - `'both'`       → either; the gate never fires.
+ *
+ * When the gate fires the host must NOT start the capture — it shows the
+ * rotate prompt (guidance item 2, pointing at the target orientation) and
+ * waits for the user to rotate.
+ *
+ * This module is the single pure predicate for that decision: no React, no
+ * sensors, no side effects, so the gate logic is unit-testable in the node
+ * jest env without booting a render or mocking the accelerometer.
+ */
+
+import type { DeviceOrientation } from './useDeviceOrientation';
+
+
+/**
+ * Which device holds the panorama capture accepts.
+ *
+ *   - `'vertical'`   — LANDSCAPE only (top→bottom pan; the product default).
+ *     Portrait holds are gated behind the rotate-to-landscape prompt.
+ *   - `'horizontal'` — PORTRAIT only (left→right pan).  Landscape holds are
+ *     gated behind the rotate-to-portrait prompt.
+ *   - `'both'`       — LANDSCAPE or PORTRAIT; the gate never fires, the user
+ *     captures in whichever hold they're already in.
+ */
+export type PanMode = 'vertical' | 'horizontal' | 'both';
+
+
+function isPortrait(orientation: DeviceOrientation): boolean {
+  return (
+    orientation === 'portrait' || orientation === 'portrait-upside-down'
+  );
+}
+
+
+/**
+ * True when the caller must BLOCK capture-start and show the rotate prompt
+ * for the current device hold:
+ *   - `'vertical'`   gates a PORTRAIT hold (needs landscape).
+ *   - `'horizontal'` gates a LANDSCAPE hold (needs portrait).
+ *   - `'both'`       never gates.
+ */
+export function shouldGateForPanMode(
+  panMode: PanMode,
+  orientation: DeviceOrientation,
+): boolean {
+  if (panMode === 'vertical') return isPortrait(orientation);
+  if (panMode === 'horizontal') return !isPortrait(orientation);
+  return false; // 'both'
+}
+
+
+/**
+ * The orientation the user must rotate TO when a hold is gated, used to pick
+ * the rotate prompt's copy + graphic.  `'vertical'` wants landscape,
+ * `'horizontal'` wants portrait; `'both'` never gates so returns `null`.
+ */
+export function gateTargetOrientation(
+  panMode: PanMode,
+): 'landscape' | 'portrait' | null {
+  if (panMode === 'vertical') return 'landscape';
+  if (panMode === 'horizontal') return 'portrait';
+  return null;
+}

package/src/camera/pickCaptureFormat.ts

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * pickCaptureFormat — choose the vision-camera format for the capture stream.
+ *
+ * Replaces a plain `useCameraFormat([{ videoResolution: 'max' }, …])`, which
+ * picks the device's MAX-video format and lets the PHOTO resolution ride
+ * along — on the iPhone 16 Pro ultra-wide that pairs a **48 MP** still
+ * (8064×6048) with the 4032×3024 max-video format, so a tap photo came out
+ * ~6000 px.  vision-camera 4.x exposes each format's photo/video resolution
+ * but NOT its pixel format / bit-depth, so we can't filter for 8-bit; the
+ * empirical rule is that the device's MAX 4:3 video format is 8-bit (the
+ * frame processor needs 8-bit for non-AR stitching), and lower video
+ * resolutions risk 10-bit.
+ *
+ * Strategy: among the ~4:3 formats whose photo long-edge is within
+ * `maxPhotoLongEdge`, pick the one with the HIGHEST video resolution (keeps
+ * the preview/stitch stream as sharp as possible while bounding the still),
+ * tie-breaking on higher fps, then the largest photo under the cap, then
+ * non-HDR (a hedge toward 8-bit).  If NO format fits the cap, fall back to
+ * the overall max-video format (never returns nothing for a non-empty list).
+ *
+ * Verified against the real iPhone 16 Pro ultra-wide format list (see the
+ * unit test): cap 4032 → 4032×3024 photo (12 MP) + 3264×2448 video (was
+ * 8064×6048 photo); cap 2048 → 2016×1512 photo (3 MP) + 1920×1440 video.
+ *
+ * Pure + structurally-typed (no vision-camera import) so it unit-tests in the
+ * node jest env; `CameraDeviceFormat` is structurally assignable to
+ * `FormatLike`.
+ */
+
+/** The CameraDeviceFormat fields this picker reads. */
+export interface FormatLike {
+  photoWidth: number;
+  photoHeight: number;
+  videoWidth: number;
+  videoHeight: number;
+  maxFps: number;
+  supportsVideoHdr: boolean;
+}
+
+export interface PickFormatOptions {
+  /**
+   * Cap on the chosen format's photo LONG edge, in px.  The picker prefers
+   * the sharpest-video format whose photo fits this.  `0` disables the cap
+   * (reverts to pure max-video).  Default 4032 (≈12 MP at 4:3, "4K"-ish).
+   */
+  maxPhotoLongEdge?: number;
+  /** Target capture aspect (W/H in landscape). Default 4/3. */
+  aspect?: number;
+  /** Aspect match tolerance. Default 0.05. */
+  aspectTolerance?: number;
+  /**
+   * Prefer a SMOOTH (high-fps) preview over the sharpest video format.  Off by
+   * default → max-video-resolution-first (back-compat).  On (the panorama
+   * camera opts in) → rank by frame rate up to `fpsTarget` first, THEN video
+   * resolution.  The default video-first sort picks e.g. a 3264×2448 **@30 fps**
+   * format over a 1920×1440 **@60 fps** one, halving the preview frame rate —
+   * visible as jitter while panning.  The stitch clamps keyframes to 640/1280 px
+   * anyway, so the higher video resolution buys nothing for the panorama; a
+   * 60 fps stream just looks smooth.
+   */
+  preferHighFps?: boolean;
+  /**
+   * Ceiling for the fps preference when `preferHighFps` is on.  Formats at or
+   * above this are treated as equally smooth (so resolution breaks the tie
+   * instead of chasing 120 fps at a lower resolution).  Default 60.
+   */
+  fpsTarget?: number;
+}
+
+const DEFAULT_MAX_PHOTO_LONG_EDGE = 4032;
+const DEFAULT_FPS_TARGET = 60;
+
+const longEdge = (f: FormatLike): number =>
+  Math.max(f.photoWidth, f.photoHeight);
+const videoPixels = (f: FormatLike): number => f.videoWidth * f.videoHeight;
+
+/**
+ * Pick the best capture format, or `undefined` for an empty list.
+ */
+export function pickCaptureFormat<F extends FormatLike>(
+  formats: readonly F[],
+  opts: PickFormatOptions = {},
+): F | undefined {
+  if (!formats || formats.length === 0) return undefined;
+
+  const aspect = opts.aspect ?? 4 / 3;
+  const tol = opts.aspectTolerance ?? 0.05;
+  const cap = opts.maxPhotoLongEdge ?? DEFAULT_MAX_PHOTO_LONG_EDGE;
+  const preferHighFps = opts.preferHighFps ?? false;
+  const fpsTarget = opts.fpsTarget ?? DEFAULT_FPS_TARGET;
+  // Treat everything at/above the target as equally smooth so resolution, not
+  // a chase for 120 fps, breaks the tie.
+  const smoothness = (f: FormatLike): number => Math.min(f.maxFps, fpsTarget);
+
+  const matchesAspect = (f: FormatLike): boolean =>
+    f.photoHeight > 0
+    && f.videoHeight > 0
+    && Math.abs(f.photoWidth / f.photoHeight - aspect) < tol
+    && Math.abs(f.videoWidth / f.videoHeight - aspect) < tol;
+
+  // Prefer 4:3 formats; if the device has none, consider all.
+  const fourThree = formats.filter(matchesAspect);
+  const base = fourThree.length > 0 ? fourThree : formats.slice();
+
+  // Among those within the photo cap; if none fit, fall back to all (which
+  // then resolves to the max-video format — never worse than today).
+  const withinCap =
+    cap > 0 ? base.filter((f) => longEdge(f) <= cap) : base.slice();
+  const candidates = withinCap.length > 0 ? withinCap : base;
+
+  return candidates.slice().sort((a, b) => {
+    if (preferHighFps) {
+      // Smooth-preview priority: frame rate (up to the target) before video
+      // resolution.  Keeps the panorama preview at ~60 fps instead of dropping
+      // to a sharper-but-30fps format.
+      const sa = smoothness(a);
+      const sb = smoothness(b);
+      if (sb !== sa) return sb - sa;
+    }
+    const va = videoPixels(a);
+    const vb = videoPixels(b);
+    if (vb !== va) return vb - va; // highest video resolution first
+    if (b.maxFps !== a.maxFps) return b.maxFps - a.maxFps; // then higher fps
+    if (longEdge(b) !== longEdge(a)) return longEdge(b) - longEdge(a); // largest photo under cap
+    // Prefer non-HDR — a hedge toward an 8-bit pixel format (the stitch
+    // frame processor needs 8-bit; vision-camera doesn't expose bit-depth).
+    return (a.supportsVideoHdr ? 1 : 0) - (b.supportsVideoHdr ? 1 : 0);
+  })[0];
+}

package/src/camera/stitchDebugInfo.ts

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * buildStitchDebugInfo — format the stitcher's runtime stats as a compact,
+ * multi-line string for the __DEV__-only overlay on the output preview.
+ *
+ * The operator uses this to SEE how a panorama was built — which pipeline +
+ * warper ran, whether the low-memory stream/feather fallback kicked in, the
+ * confidence score the successful attempt used, and how many keyframes
+ * survived pruning.  Purely presentational; never shown in release.
+ *
+ * Pure + structurally typed so it unit-tests in the node jest env.
+ */
+
+export interface StitchDebugFields {
+  /** Native `debugSummary`: `"pipe=…;warp=…;route=…;seam=…;blend=…"`. */
+  debugSummary?: string;
+  stitchModeResolved?: 'panorama' | 'scans';
+  finalConfidenceThresh?: number;
+  framesIncluded?: number;
+  framesRequested?: number;
+  width?: number;
+  height?: number;
+}
+
+/**
+ * Build the overlay text.  Returns `''` when nothing useful is present (so the
+ * caller can skip rendering the pill entirely).  One `key: value` per line.
+ */
+export function buildStitchDebugInfo(r: StitchDebugFields): string {
+  const lines: string[] = [];
+
+  // Expand the native summary ("pipe=manual;warp=spherical;…") into one
+  // labelled line per pair, preserving order.  Malformed pairs are skipped.
+  if (r.debugSummary) {
+    for (const pair of r.debugSummary.split(';')) {
+      const eq = pair.indexOf('=');
+      if (eq <= 0) continue;
+      const key = pair.slice(0, eq).trim();
+      const value = pair.slice(eq + 1).trim();
+      if (key && value) lines.push(`${key}: ${value}`);
+    }
+  }
+
+  if (r.stitchModeResolved) lines.push(`mode: ${r.stitchModeResolved}`);
+
+  if (
+    typeof r.finalConfidenceThresh === 'number'
+    && r.finalConfidenceThresh >= 0
+  ) {
+    lines.push(`score: ${r.finalConfidenceThresh.toFixed(2)}`);
+  }
+
+  if (typeof r.framesIncluded === 'number' && r.framesIncluded >= 0) {
+    const req =
+      typeof r.framesRequested === 'number' && r.framesRequested >= 0
+        ? String(r.framesRequested)
+        : '?';
+    lines.push(`frames: ${r.framesIncluded}/${req}`);
+  }
+
+  if (
+    typeof r.width === 'number'
+    && typeof r.height === 'number'
+    && r.width > 0
+    && r.height > 0
+  ) {
+    lines.push(`size: ${r.width}×${r.height}`);
+  }
+
+  return lines.join('\n');
+}