react-native-image-stitcher 0.15.2 → 0.16.0

package/src/camera/CaptureStatusOverlay.tsx

@@ -48,9 +48,9 @@ export type CaptureStatusPhase = 'idle' | 'recording' | 'stitching';
 export interface CaptureStatusOverlayProps {
   /**
    * Current phase.  `idle` renders nothing.  `recording` shows the
-   * REC banner + red glowing border.  `stitching` swaps to a neutral
-   * "Stitching..." banner with no border (recording is over; UI
-   * cue should de-escalate).
+   * REC banner + glowing border (GREEN normally, RED when `tooFast`).
+   * `stitching` swaps to a neutral "Stitching..." banner with no border
+   * (recording is over; UI cue should de-escalate).
    */
   phase: CaptureStatusPhase;
   /**
@@ -60,6 +60,13 @@ export interface CaptureStatusOverlayProps {
    * type.
    */
   recordingMessage?: string;
+  /**
+   * v0.16 — speed feedback.  When `false` (default) the recording banner +
+   * border are GREEN ("your pace is fine"); when `true` they turn RED to
+   * signal the pan is too fast.  This consolidates the old always-red border
+   * + separate amber "slow down" pill into one calm-by-default cue.
+   */
+  tooFast?: boolean;
   /**
    * Optional override for the stitching-phase message.  Defaults to
    * "Stitching panorama…".
@@ -92,6 +99,7 @@ export interface CaptureStatusOverlayProps {
 export function CaptureStatusOverlay({
   phase,
   recordingMessage = 'Hold steady — pan slowly',
+  tooFast = false,
   stitchingMessage = 'Stitching panorama…',
   countdownMs,
   recordingStartedAt,
@@ -207,14 +215,22 @@ export function CaptureStatusOverlay({
       accessibilityLiveRegion="polite"
     >
       {showBorder ? (
-        <View pointerEvents="none" style={styles.recordBorder} />
+        <View
+          pointerEvents="none"
+          style={[
+            styles.recordBorder,
+            tooFast ? styles.recordBorderTooFast : styles.recordBorderOk,
+          ]}
+        />
       ) : null}
 
       <View
         pointerEvents="none"
         style={[
           styles.banner,
-          phase === 'recording' ? styles.bannerRecording : styles.bannerStitching,
+          phase === 'recording'
+            ? (tooFast ? styles.bannerTooFast : styles.bannerRecording)
+            : styles.bannerStitching,
           bannerOrientationStyle,
         ]}
       >
@@ -353,7 +369,12 @@ const styles = StyleSheet.create({
     minHeight: 36,
   },
   bannerRecording: {
-    backgroundColor: 'rgba(255,59,48,0.92)',
+    // Green by default — "you're recording and your pace is fine".
+    backgroundColor: 'rgba(52,199,89,0.92)',
+  },
+  bannerTooFast: {
+    // Red only when the pan is too fast (consolidates the old amber pill).
+    backgroundColor: 'rgba(255,59,48,0.94)',
   },
   bannerStitching: {
     // Neutral grey while we wait for the stitcher; communicates
@@ -386,6 +407,13 @@ const styles = StyleSheet.create({
   recordBorder: {
     ...StyleSheet.absoluteFillObject,
     borderWidth: 4,
-    borderColor: 'rgba(255,59,48,0.9)',
+  },
+  recordBorderOk: {
+    // Green by default (calm — the pan pace is fine).
+    borderColor: 'rgba(52,199,89,0.9)',
+  },
+  recordBorderTooFast: {
+    // Red only when too fast.
+    borderColor: 'rgba(255,59,48,0.95)',
   },
 });

package/src/camera/CaptureThumbnailStrip.tsx

@@ -49,6 +49,7 @@ import {
 } from 'react-native';
 
 import { CapturePreview } from './CapturePreview';
+import { DISPLAY_DECODE_IMAGE_PROPS } from './displayDecodeImageProps';
 
 
 export interface CaptureThumbnailItem {
@@ -247,6 +248,9 @@ export function CaptureThumbnailStrip({
               source={{ uri: item.uri }}
               style={[styles.thumbImage, contentRotation]}
               resizeMode="cover"
+              // OOM fix — decode at thumbnail size, not full capture res
+              // (see DISPLAY_DECODE_IMAGE_PROPS for the native-heap rationale).
+              {...DISPLAY_DECODE_IMAGE_PROPS}
             />
           </Pressable>
         )}

package/src/camera/LateralMotionModal.tsx

@@ -0,0 +1,199 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * LateralMotionModal — informational popup shown when the SDK stops an
+ * in-progress capture because the user panned sideways (cross-axis /
+ * lateral drift) instead of holding the single sweep direction
+ * (Mode A: top→bottom; Mode B: left→right).
+ *
+ * ## When this modal appears
+ *
+ * This is the item-6 sibling of `OrientationDriftModal` — the "you
+ * moved sideways" variant.  By the time the modal renders, the capture
+ * has ALREADY been finalized by the parent `<Camera>` (the lateral-stop
+ * effect calls the engine's `stop()` and keeps whatever was captured up
+ * to that point — there is no malformed-output risk, so the copy says
+ * "we stitched what you captured").  The modal exists solely to explain
+ * to the user what happened and how to avoid it next time; the single
+ * dismiss button just clears the latched lateral-stop state so the next
+ * capture can start fresh.
+ *
+ * ## Layer-2 host usage
+ *
+ * Hosts using `CameraView` directly (rather than the flagship
+ * `<Camera>`) can compose this modal with their own lateral-drift
+ * detector for the same finalize-and-explain UX:
+ *
+ *   const lateral = useLateralDrift(captureActive);
+ *   useEffect(() => {
+ *     if (lateral.stopped) {
+ *       // host finalizes capture (engine stop + keep captured output)
+ *       finalizeCapture();
+ *     }
+ *   }, [lateral.stopped]);
+ *
+ *   return <>
+ *     <CameraView ... />
+ *     <LateralMotionModal
+ *       visible={lateral.stopped}
+ *       onDismiss={dismissLateralModal}
+ *     />
+ *   </>;
+ *
+ * ## Copy
+ *
+ * `title` / `body` / `dismissLabel` default to the centralised
+ * `DEFAULT_GUIDANCE_COPY.lateralStop*` strings so hosts can localise or
+ * re-word every guidance message in one place via the `guidanceCopy`
+ * `<Camera>` prop; pass explicit props to override per-instance.
+ *
+ * ## Accessibility
+ *
+ * Modal `role` defaults to RN's native dialog handling.  The dismiss
+ * button carries an `accessibilityRole='button'` + label.  Body text
+ * uses `accessibilityRole='text'` so the guidance is read by VoiceOver
+ * / TalkBack.
+ */
+
+import React from 'react';
+import { Modal, Pressable, StyleSheet, Text, View } from 'react-native';
+
+import { DEFAULT_GUIDANCE_COPY } from './cameraGuidanceCopy';
+
+
+export interface LateralMotionModalProps {
+  /**
+   * Show / hide.  In the `<Camera>` integration this is driven by the
+   * latched lateral-stop flag (capture already finalized when true).
+   */
+  visible: boolean;
+
+  /**
+   * Popup title.  Defaults to
+   * `DEFAULT_GUIDANCE_COPY.lateralStopTitle`.
+   */
+  title?: string;
+
+  /**
+   * Popup body / guidance copy.  Defaults to
+   * `DEFAULT_GUIDANCE_COPY.lateralStopBody`.
+   */
+  body?: string;
+
+  /**
+   * Dismiss button label.  Defaults to
+   * `DEFAULT_GUIDANCE_COPY.lateralStopDismiss`.
+   */
+  dismissLabel?: string;
+
+  /**
+   * Tapped when the user dismisses.  By the time the modal renders the
+   * capture is already finalized; this callback exists only to clear
+   * the latched lateral-stop state so the next capture can start fresh.
+   */
+  onDismiss: () => void;
+}
+
+
+export function LateralMotionModal(
+  props: LateralMotionModalProps,
+): React.JSX.Element {
+  const {
+    visible,
+    title = DEFAULT_GUIDANCE_COPY.lateralStopTitle,
+    body = DEFAULT_GUIDANCE_COPY.lateralStopBody,
+    dismissLabel = DEFAULT_GUIDANCE_COPY.lateralStopDismiss,
+    onDismiss,
+  } = props;
+
+  return (
+    <Modal
+      visible={visible}
+      transparent
+      animationType="fade"
+      onRequestClose={onDismiss}
+      accessibilityLabel="Capture finalized — moved sideways"
+      // v0.12.0 — see OrientationDriftModal / PanoramaSettingsModal for
+      // the same prop's rationale.  Declaring all orientations prevents
+      // iOS from force-rotating the window to portrait when this modal
+      // opens mid-rotation, which would otherwise leave the underlying
+      // <Camera>'s ARSession in a stale-orientation state on dismiss.
+      supportedOrientations={[
+        'portrait',
+        'portrait-upside-down',
+        'landscape-left',
+        'landscape-right',
+      ]}
+    >
+      <View style={styles.backdrop}>
+        <View style={styles.card}>
+          <Text style={styles.title} accessibilityRole="header">
+            {title}
+          </Text>
+
+          <Text style={styles.body} accessibilityRole="text">
+            {body}
+          </Text>
+
+          <Pressable
+            style={({ pressed }) => [
+              styles.button,
+              pressed && styles.buttonPressed,
+            ]}
+            onPress={onDismiss}
+            accessibilityRole="button"
+            accessibilityLabel={dismissLabel}
+          >
+            <Text style={styles.buttonLabel}>{dismissLabel}</Text>
+          </Pressable>
+        </View>
+      </View>
+    </Modal>
+  );
+}
+
+
+const styles = StyleSheet.create({
+  backdrop: {
+    flex: 1,
+    backgroundColor: 'rgba(0, 0, 0, 0.6)',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingHorizontal: 32,
+  },
+  card: {
+    backgroundColor: '#1c1c1e',
+    borderRadius: 14,
+    paddingHorizontal: 20,
+    paddingVertical: 24,
+    width: '100%',
+    maxWidth: 340,
+  },
+  title: {
+    color: '#fff',
+    fontSize: 18,
+    fontWeight: '600',
+    marginBottom: 12,
+    textAlign: 'center',
+  },
+  body: {
+    color: '#e5e5ea',
+    fontSize: 15,
+    lineHeight: 21,
+    textAlign: 'center',
+    marginBottom: 20,
+  },
+  button: {
+    backgroundColor: '#0a84ff',
+    borderRadius: 10,
+    paddingVertical: 12,
+    alignItems: 'center',
+  },
+  buttonPressed: {
+    backgroundColor: '#0860c0',
+  },
+  buttonLabel: {
+    color: '#fff',
+    fontSize: 17,
+    fontWeight: '600',
+  },
+});

package/src/camera/PanHowToOverlay.tsx

@@ -0,0 +1,246 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * PanHowToOverlay — the "how to pan" coach-mark (guidance item 3).
+ *
+ * Shown briefly at the START of a capture to teach the panning
+ * gesture before the live pan-speed pill (`PanoramaGuidance`) takes
+ * over.  It pairs the code-drawn `PanPhoneGraphic` (white phone +
+ * sweeping amber band) with a code-built bouncing arrow so the
+ * direction reads instantly without any copy.
+ *
+ *   ┌──────────────────────────────────────────────────────────┐
+ *   │                                                          │
+ *   │                  ┌───────────────┐                       │
+ *   │                  │  PanPhone     │   (240px graphic, the │
+ *   │                  │  Graphic      │    white phone +      │
+ *   │                  └───────────────┘    amber sweep)       │
+ *   │                         ▼  ← amber triangle              │
+ *   │                         ▼     bouncing ~12px along the   │
+ *   │                              pan axis, back and forth    │
+ *   └──────────────────────────────────────────────────────────┘
+ *
+ * Direction follows the capture mode (derived from the physical
+ * device orientation, sensor-based — works under portrait-lock):
+ *
+ *   Mode A — LANDSCAPE  → pan TOP → BOTTOM → arrow points DOWN.
+ *   Mode B — PORTRAIT   → pan LEFT → RIGHT → arrow points RIGHT.
+ *
+ * Both `landscape-left` and `landscape-right` are valid Mode A.
+ *
+ * ## Visibility & timing
+ *
+ * This component is intentionally pure-presentational: the PARENT
+ * owns `visible` and the brief auto-fade lifecycle (mount → show →
+ * dismiss once recording is under way).  We never self-time;
+ * `visible === false` renders `null` so the host can mount us
+ * unconditionally without layout shift.
+ *
+ * ## Upright under portrait-lock
+ *
+ * The app layout is typically portrait-locked, so when the user
+ * holds the device in landscape (Mode A) the JS framebuffer is NOT
+ * rotated.  We counter-rotate the whole coach-mark with
+ * `useContentRotation()` (same hook the bottom controls use) so the
+ * graphic and arrow read upright relative to gravity.  The arrow's
+ * bounce axis and triangle point are expressed in that upright frame
+ * — i.e. the user's view — so "down" / "right" mean what the user
+ * sees, not the layout's raw axes.
+ *
+ * ## No SVG / no extra deps
+ *
+ * The arrow is a pure CSS border-width triangle (a zero-size View
+ * whose thick coloured border on one edge + transparent borders on
+ * the adjacent edges read as a filled triangle).  Bounce is a single
+ * `Animated.loop` on the native driver — cheap, and only running
+ * while `visible`.
+ */
+
+import React, { useEffect, useMemo, useRef } from 'react';
+import {
+  Animated,
+  Easing,
+  StyleSheet,
+  View,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+
+import { PanPhoneGraphic } from './guidanceGraphics';
+import { GUIDANCE_TOKENS } from './guidanceTokens';
+import { useContentRotation } from './useContentRotation';
+import { type DeviceOrientation } from './useDeviceOrientation';
+
+
+/** Distance (px) the arrow travels along the pan axis each bounce. */
+const BOUNCE_DISTANCE = 12;
+/** Half-period of the bounce (out, then back) — ~700 ms each leg. */
+const BOUNCE_DURATION_MS = 700;
+/** Visual size of the CSS-triangle arrow (base width / height in px). */
+const ARROW_SIZE = 18;
+
+
+export interface PanHowToOverlayProps {
+  /**
+   * Show / hide.  `false` renders `null`.  The host owns the brief
+   * auto-fade lifecycle — this component never self-times.
+   */
+  visible: boolean;
+  /**
+   * Physical device orientation (sensor-based, from
+   * `useDeviceOrientation`).  Selects the pan mode → arrow
+   * direction: landscape-* → DOWN (Mode A), portrait-* → RIGHT
+   * (Mode B).
+   */
+  orientation: DeviceOrientation;
+  /** Outer style passthrough (positioning / opacity from the host). */
+  style?: StyleProp<ViewStyle>;
+}
+
+
+type PanDirection = 'down' | 'right';
+
+
+/**
+ * Map a physical orientation to the pan direction the user should
+ * sweep.  Mode A (either landscape) pans top→bottom (DOWN); Mode B
+ * (either portrait variant) pans left→right (RIGHT).  Directions are
+ * in the user's upright view — the content wrapper is counter-rotated
+ * so these read correctly under portrait-lock.
+ */
+function directionForOrientation(orientation: DeviceOrientation): PanDirection {
+  switch (orientation) {
+    case 'landscape-left':
+    case 'landscape-right':
+      return 'down';
+    case 'portrait':
+    case 'portrait-upside-down':
+    default:
+      return 'right';
+  }
+}
+
+
+export function PanHowToOverlay({
+  visible,
+  orientation,
+  style,
+}: PanHowToOverlayProps): React.JSX.Element | null {
+  // Counter-rotation so the GIF + arrow read upright relative to
+  // gravity even when the app is portrait-locked and the device is
+  // held in landscape (Mode A).  Always called so hook order is
+  // stable across the `visible` toggle.
+  const contentRotation = useContentRotation();
+
+  // Single Animated value driving the bounce, 0 → 1 → 0.  Native
+  // driver (transform-only), so the loop runs off the JS thread.
+  const bounce = useRef(new Animated.Value(0)).current;
+
+  const direction = directionForOrientation(orientation);
+
+  useEffect(() => {
+    if (!visible) {
+      bounce.setValue(0);
+      return;
+    }
+    const loop = Animated.loop(
+      Animated.sequence([
+        Animated.timing(bounce, {
+          toValue: 1,
+          duration: BOUNCE_DURATION_MS,
+          easing: Easing.inOut(Easing.ease),
+          useNativeDriver: true,
+        }),
+        Animated.timing(bounce, {
+          toValue: 0,
+          duration: BOUNCE_DURATION_MS,
+          easing: Easing.inOut(Easing.ease),
+          useNativeDriver: true,
+        }),
+      ]),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [visible, bounce]);
+
+  // Translate 0→BOUNCE_DISTANCE along the pan axis.  In the upright
+  // (counter-rotated) frame, "down" moves +Y and "right" moves +X.
+  const travel = bounce.interpolate({
+    inputRange: [0, 1],
+    outputRange: [0, BOUNCE_DISTANCE],
+  });
+  const arrowTransform = useMemo<ViewStyle['transform']>(
+    () =>
+      direction === 'down'
+        ? [{ translateY: travel }]
+        : [{ translateX: travel }],
+    [direction, travel],
+  );
+
+  if (!visible) return null;
+
+  return (
+    <View
+      // box-none on the root: never intercept taps anywhere on the
+      // full-screen layer.  The inner content is also non-interactive.
+      pointerEvents="none"
+      style={[styles.root, style]}
+    >
+      <View style={[styles.content, contentRotation]}>
+        {/* Code-drawn phone + sweeping band (decorative — the bouncing
+            arrow + parent copy convey the gesture for assistive tech). */}
+        <PanPhoneGraphic direction={direction} playing={visible} />
+        <Animated.View
+          style={[
+            styles.arrow,
+            direction === 'down' ? styles.arrowDown : styles.arrowRight,
+            { transform: arrowTransform },
+          ]}
+        />
+      </View>
+    </View>
+  );
+}
+
+
+const styles = StyleSheet.create({
+  root: {
+    ...StyleSheet.absoluteFillObject,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  content: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  // CSS-triangle base: a zero-size box whose borders are coloured on
+  // one edge and transparent on the two adjacent edges, producing a
+  // filled triangle pointing away from the coloured edge.  The
+  // direction-specific styles below set which edge is amber.
+  arrow: {
+    width: 0,
+    height: 0,
+    backgroundColor: 'transparent',
+    borderStyle: 'solid',
+    marginTop: 8,
+  },
+  // Triangle pointing DOWN (Mode A): left + right borders transparent,
+  // TOP border amber → apex at the bottom.
+  arrowDown: {
+    borderLeftWidth: ARROW_SIZE / 2,
+    borderRightWidth: ARROW_SIZE / 2,
+    borderTopWidth: ARROW_SIZE,
+    borderLeftColor: 'transparent',
+    borderRightColor: 'transparent',
+    borderTopColor: GUIDANCE_TOKENS.amber,
+  },
+  // Triangle pointing RIGHT (Mode B): top + bottom borders
+  // transparent, LEFT border amber → apex on the right.
+  arrowRight: {
+    borderTopWidth: ARROW_SIZE / 2,
+    borderBottomWidth: ARROW_SIZE / 2,
+    borderLeftWidth: ARROW_SIZE,
+    borderTopColor: 'transparent',
+    borderBottomColor: 'transparent',
+    borderLeftColor: GUIDANCE_TOKENS.amber,
+  },
+});

package/src/camera/PanoramaSettings.ts

@@ -195,11 +195,11 @@ export interface FrameSelectionSettings {
 
   /**
    * Required NEW-content fraction (0..1) for a candidate frame to
-   * be accepted.  Default 0.20 = 20% novel content per accept.
-   * Lower = more frames accepted, larger panoramas.  Higher = fewer
-   * frames, faster captures but more conservative about coverage.
-   * Clamped to `[0.10, 0.80]` natively
-   * (`IncrementalStitcher.swift:962`).
+   * be accepted.  Default 0.15 = 15% novel content per accept (v0.16;
+   * was 0.20).  Lower = more frames accepted, denser overlap, more
+   * robust registration.  Higher = fewer frames, faster captures but
+   * more conservative about coverage.  Clamped to `[0.10, 0.80]`
+   * natively (`IncrementalStitcher.swift:962`) — 0.10 is the floor.
    */
   overlapThreshold: number;
 
@@ -210,7 +210,9 @@ export interface FrameSelectionSettings {
    * overlap threshold wasn't met — so a slow or static pan never goes
    * longer than this without a keyframe.  Counts toward `maxKeyframes`
    * (the cap still finalises the capture).  `0` disables it.  Default
-   * `2000` (2 s).  Maps to the native gate's `setMaxKeyframeIntervalMs`.
+   * `1500` (1.5 s) — with `maxKeyframes` 8 this bounds a static/slow
+   * capture to ~8×1.5 ≈ 12 s before the keyframe-count auto-finalize.
+   * Maps to the native gate's `setMaxKeyframeIntervalMs`.
    */
   maxKeyframeIntervalMs: number;
 
@@ -312,8 +314,21 @@ export const DEFAULT_PANORAMA_SETTINGS: PanoramaSettings = {
   captureSource: 'ar',
   debug: false,
   stitcher: {
-    stitchMode: 'auto',
-    warperType: 'plane',
+    // v0.16 — PANORAMA by default (was 'auto').  The auto-resolver's SCANS
+    // branch leans on double-integrated IMU translation, which is unreliable
+    // during rotation (gravity leakage inflates the translation estimate); in
+    // practice rotational pans are the common case and resolve to panorama
+    // anyway.  Defaulting to panorama is the robust choice — host apps that
+    // genuinely capture flat documents/walls can still opt into 'auto' or
+    // 'scans' via the ⚙️ panel or the `defaultStitchMode` / `stitcher` props.
+    stitchMode: 'panorama',
+    // v0.16 — SPHERICAL by default (bounds both axes; the proven-robust wide/
+    // vertical-pan projection).  This is now the single source of truth — the
+    // native side no longer hardcodes a warper, so the ⚙️ panel + the host's
+    // `defaultWarper` prop actually take effect.  Note: choosing `plane` here
+    // re-arms the dynamic plane→spherical fallback/divergence switch in the
+    // manual pipeline (it only fires when warperType != spherical).
+    warperType: 'spherical',
     blenderType: 'multiband',
     seamFinderType: 'graphcut',
     // v0.15 — inscribed-rect crop is OFF by default (bbox crop keeps all
@@ -324,9 +339,17 @@ export const DEFAULT_PANORAMA_SETTINGS: PanoramaSettings = {
   },
   frameSelection: {
     mode: 'flow-based',
-    maxKeyframes: 6,
-    overlapThreshold: 0.20,
-    maxKeyframeIntervalMs: 2000,
+    // v0.16 — denser keyframes by default: a 15% novelty gate, up to 8 frames,
+    // plus a 1.5 s time-budget force-accept (so a slow/static pan still lands a
+    // keyframe every 1.5 s even when novelty is low).  With 8 frames this bounds
+    // a static/slow capture to ~8×1.5 ≈ 12 s before the keyframe-count
+    // auto-finalize.  More overlap between consecutive keyframes ⇒ stronger
+    // feature matching ⇒ more robust registration.  Memory-checked: 8 frames fit
+    // the BATCH held-set cap on both platforms.  Overlap selectable in the
+    // settings panel {10,15,20,30}% (native clamp floor 10%); cap clamps [3,10].
+    maxKeyframes: 8,
+    overlapThreshold: 0.15,
+    maxKeyframeIntervalMs: 1500,
     flow: DEFAULT_FLOW_GATE_SETTINGS,
   },
 };

package/src/camera/PanoramaSettingsModal.tsx

@@ -253,16 +253,16 @@ export function PanoramaSettingsModal({
                 onChange={(v) => updateFrameSelection({
                   maxKeyframes: parseInt(v, 10),
                 })}
-                caption="Hard cap on accepted keyframes; native clamps to [3, 10].  6 (default) matches Samsung Pano's behaviour and is the sweet spot for cv::Stitcher BA convergence."
+                caption="Hard cap on accepted keyframes; native clamps to [3, 10].  8 (default) is the sweet spot for cv::detail BA convergence while giving the 15%-overlap + 1 s time gate room to land frames."
               />
               <SectionHeader title="Overlap threshold (new content per keyframe)" />
               <SegmentedControl
-                options={['20%', '30%', '40%', '50%', '60%']}
+                options={['10%', '15%', '20%', '30%']}
                 value={`${Math.round(settings.frameSelection.overlapThreshold * 100)}%`}
                 onChange={(v) => updateFrameSelection({
                   overlapThreshold: parseInt(v, 10) / 100,
                 })}
-                caption="Required NEW-content fraction.  20% (default): generous, ~5–6 keyframes for a 90° pan.  Native clamps to [10%, 80%]."
+                caption="Required NEW-content fraction (lower = denser keyframes, more overlap).  15% (default): ~7–9 keyframes for a 90° pan.  10% is the native clamp floor."
               />
               <SectionHeader title="Keyframe interval (time-budget force-accept)" />
               <SegmentedControl
@@ -275,7 +275,7 @@ export function PanoramaSettingsModal({
                 onChange={(v) => updateFrameSelection({
                   maxKeyframeIntervalMs: v === 'off' ? 0 : parseInt(v, 10) * 1000,
                 })}
-                caption="Force-accept a keyframe at least this often even if novelty is low, so slow / static pans don't leave gaps.  Counts toward the keyframe cap.  off = disabled.  2s (default).  Applies to AR + non-AR."
+                caption="Force-accept a keyframe at least this often even if novelty is low, so slow / static pans don't leave gaps.  Counts toward the keyframe cap.  off = disabled.  1s (default).  Applies to AR + non-AR."
               />
 
               {showFlowTunables && (