react-native-image-stitcher 0.15.2 → 0.16.0

package/src/camera/RotateToLandscapePrompt.tsx

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * RotateToLandscapePrompt — full-screen, non-interactive overlay shown
+ * while a Mode-A (landscape, top→bottom pan) capture is waiting for the
+ * user to physically rotate the device to landscape.
+ *
+ *   ┌──────────────────────────────────────────────────────────┐
+ *   │                  (faint scrim over preview)               │
+ *   │                                                           │
+ *   │                    ┌───────────────┐                      │
+ *   │                    │   ⟳  phone    │  ← code-drawn        │
+ *   │                    │   line-art    │     (240px square)   │
+ *   │                    └───────────────┘                      │
+ *   │                                                           │
+ *   │             ●  Rotate to landscape   ← caption pill       │
+ *   └──────────────────────────────────────────────────────────┘
+ *
+ * Item 2 of the first-time-user guidance set.  It is the first thing a
+ * user sees after starting a landscape-only capture in portrait — the
+ * GIF demonstrates the rotation gesture and the pill names the goal.
+ *
+ * ## Pure-presentational
+ *
+ * The component owns no orientation/eligibility logic: the host
+ * (`<Camera>`) decides *when* a Mode-A capture is blocked on rotation
+ * and drives `visible`.  When `visible` is false we render `null` so
+ * the host can mount us unconditionally without layout churn — mirrors
+ * `CaptureStatusOverlay`'s `idle` → `null` contract.
+ *
+ * ## Why the WHOLE prompt counter-rotates
+ *
+ * The host app is typically portrait-locked, so when the user tilts to
+ * landscape the OS does NOT rotate the framebuffer and JS-"up" stays at
+ * the device's side edge.  We counter-rotate the entire prompt (graphic
+ * + caption) via `useContentRotation()` — the same hook the bottom
+ * controls use — so it reads upright relative to actual gravity.
+ *
+ * This matters for BOTH children, not just the text:
+ *   - the **caption** is text and must read left-to-right;
+ *   - the **graphic is now directional** — its camera dot starts on one
+ *     edge and rotates to another to demonstrate the gesture, so an
+ *     un-rotated graphic in a landscape hold reads 90° off (the dot
+ *     appears to start "down" and travel "left" instead of "left" →
+ *     "top").  It is therefore counter-rotated with the caption.
+ *   - the column **layout** (caption below the graphic) also only reads
+ *     as a physical column once the wrapper is upright — otherwise
+ *     "below" lands at the physical side edge.
+ *
+ * (An earlier version rotated only the caption, back when the graphic
+ * was a symmetric spinner with no start/end direction.)  In a portrait
+ * hold the hook returns 0° so this is a no-op; once the device reaches
+ * the target orientation the host flips `visible` to false anyway, but
+ * the counter-rotation keeps everything legible during the in-between
+ * tilt.
+ *
+ * ## Accessibility
+ *
+ * `accessibilityRole='alert'` + `accessibilityLiveRegion='polite'` so
+ * VoiceOver / TalkBack announce the rotation instruction when the
+ * prompt appears (and re-announce if the copy changes), matching the
+ * pattern in `PanoramaGuidance`.
+ */
+
+import React from 'react';
+import {
+  StyleSheet,
+  Text,
+  View,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+
+import { DEFAULT_GUIDANCE_COPY } from './cameraGuidanceCopy';
+import { RotatePhoneGraphic } from './guidanceGraphics';
+import { GUIDANCE_PILL, GUIDANCE_TOKENS } from './guidanceTokens';
+import { useContentRotation } from './useContentRotation';
+
+
+export interface RotateToLandscapePromptProps {
+  /**
+   * Show / hide.  Driven by the host while a Mode-A capture is blocked
+   * on the user rotating to landscape.  `false` renders nothing.
+   */
+  visible: boolean;
+  /**
+   * Caption copy.  Defaults to `DEFAULT_GUIDANCE_COPY.rotateToLandscape`
+   * ("Rotate to landscape").  Hosts localise via the `guidanceCopy`
+   * `<Camera>` prop and pass the resolved string here.  When `target` is
+   * `'portrait'`, pass the rotate-to-portrait copy.
+   */
+  copy?: string;
+  /**
+   * Orientation to rotate TO: `'landscape'` (default, panMode `'vertical'`)
+   * or `'portrait'` (panMode `'horizontal'`).  Drives the rotating-phone
+   * graphic's direction.
+   */
+  target?: 'landscape' | 'portrait';
+  /** Outer style passthrough (applied to the absolute-fill root). */
+  style?: StyleProp<ViewStyle>;
+}
+
+
+export function RotateToLandscapePrompt({
+  visible,
+  copy = DEFAULT_GUIDANCE_COPY.rotateToLandscape,
+  target = 'landscape',
+  style,
+}: RotateToLandscapePromptProps): React.JSX.Element | null {
+  // Counter-rotate the WHOLE prompt so it reads upright relative to
+  // gravity while the device is mid-tilt (locked-portrait hosts) — see
+  // the file header.  Called before the early return so the hook order
+  // stays stable across visible toggles.
+  const contentRotation = useContentRotation();
+
+  if (!visible) return null;
+
+  return (
+    <View
+      // pointerEvents=none — the prompt is read-only and must never
+      // steal taps from the camera / shutter beneath it.
+      pointerEvents="none"
+      style={[StyleSheet.absoluteFill, styles.root, style]}
+      accessibilityRole="alert"
+      accessibilityLiveRegion="polite"
+    >
+      {/* Graphic + caption share ONE counter-rotated column so both the
+          directional graphic and the "caption below" layout stay correct
+          relative to gravity (see header).  In portrait the rotation is a
+          no-op. */}
+      <View style={[styles.content, contentRotation]}>
+        {/* Code-drawn rotating-phone graphic (decorative — the caption
+            carries the instruction for assistive tech). */}
+        <RotatePhoneGraphic playing={visible} target={target} />
+
+        <View style={styles.pill}>
+          <View style={styles.dot} />
+          <Text style={styles.caption} numberOfLines={1}>
+            {copy}
+          </Text>
+        </View>
+      </View>
+    </View>
+  );
+}
+
+
+const styles = StyleSheet.create({
+  root: {
+    // Faint scrim over the live preview so the white line-art graphic and
+    // caption read against bright scenes, while the preview stays
+    // visible underneath (the user is framing a rotation, not a shot).
+    backgroundColor: GUIDANCE_TOKENS.scrim,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  // Counter-rotated column holding the graphic + caption.  Rotating this
+  // wrapper (not the children individually) keeps the "caption below the
+  // graphic" relationship intact while orienting the pair to gravity.
+  content: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  pill: {
+    // Caption pill directly below the rotating-phone graphic (both are
+    // centred in the column by the root's center alignment).
+    marginTop: 16,
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingVertical: GUIDANCE_PILL.paddingVertical,
+    paddingHorizontal: GUIDANCE_PILL.paddingHorizontal,
+    borderRadius: GUIDANCE_PILL.borderRadius,
+    backgroundColor: GUIDANCE_TOKENS.scrim,
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: GUIDANCE_TOKENS.hairline,
+  },
+  dot: {
+    width: GUIDANCE_PILL.dotSize,
+    height: GUIDANCE_PILL.dotSize,
+    borderRadius: GUIDANCE_PILL.dotSize / 2,
+    backgroundColor: GUIDANCE_TOKENS.amber,
+    marginRight: GUIDANCE_PILL.dotGap,
+  },
+  caption: {
+    color: GUIDANCE_TOKENS.white,
+    fontSize: GUIDANCE_PILL.fontSize,
+    fontWeight: GUIDANCE_PILL.fontWeight,
+  },
+});

package/src/camera/buildPanoramaInitialSettings.ts

@@ -32,6 +32,9 @@
 import {
   DEFAULT_FLOW_GATE_SETTINGS,
   DEFAULT_PANORAMA_SETTINGS,
+  type BatchStitcherSettings,
+  type FlowGateSettings,
+  type FrameSelectionSettings,
   type PanoramaSettings,
 } from './PanoramaSettings';
 
@@ -60,7 +63,7 @@ export interface PanoramaPropOverrides {
   defaultKeyframeOverlapThreshold?: number;
   /**
    * Initial value for `frameSelection.maxKeyframeIntervalMs` — the
-   * time-budget force-accept (ms).  `0` disables it.  Default 2000.
+   * time-budget force-accept (ms).  `0` disables it.  Default 1500.
    */
   defaultMaxKeyframeIntervalMs?: number;
   /**
@@ -69,6 +72,23 @@ export interface PanoramaPropOverrides {
    * Omitted ⇒ the stitcher default (false = bounding-rect crop).
    */
   maxInscribedRectCrop?: boolean;
+  /**
+   * v0.16 — pass the stitcher config as a JSON OBJECT (canonical field names:
+   * `warperType` / `blenderType` / `seamFinderType` / `stitchMode` /
+   * `enableMaxInscribedRectCrop`).  Any field set here OVERRIDES the matching
+   * flat `default*` prop; unset fields fall back to the flat prop, then the SDK
+   * default.  Partial — set only what you want.
+   */
+  stitcher?: Partial<BatchStitcherSettings>;
+  /**
+   * v0.16 — pass the frame-gate config as a JSON OBJECT (canonical field names:
+   * `mode` / `maxKeyframes` / `overlapThreshold` / `maxKeyframeIntervalMs` /
+   * `flow`).  Overrides the matching flat `default*` props; `flow` is
+   * DEEP-merged so you can set a single flow knob without restating the rest.
+   */
+  frameSelection?: Partial<Omit<FrameSelectionSettings, 'flow'>> & {
+    flow?: Partial<FlowGateSettings>;
+  };
 }
 
 
@@ -127,6 +147,8 @@ export function buildPanoramaInitialSettings(
       enableMaxInscribedRectCrop:
         overrides.maxInscribedRectCrop
         ?? stitcherDefaults.enableMaxInscribedRectCrop,
+      // The JSON-object prop wins over the flat default* props above.
+      ...(overrides.stitcher ?? {}),
     },
 
     frameSelection: {
@@ -139,6 +161,11 @@ export function buildPanoramaInitialSettings(
       maxKeyframeIntervalMs:
         overrides.defaultMaxKeyframeIntervalMs
         ?? base.frameSelection.maxKeyframeIntervalMs,
+      // The JSON-object prop wins over the flat default* props above for the
+      // scalar fields (mode / maxKeyframes / overlapThreshold / intervalMs).
+      // Its `flow` (if any) is dropped here and DEEP-merged in the explicit
+      // `flow:` key below, so a partial flow object doesn't wipe the rest.
+      ...(overrides.frameSelection ?? {}),
       flow: {
         ...flowDefaults,
         noveltyPercentile:
@@ -150,6 +177,8 @@ export function buildPanoramaInitialSettings(
         maxTranslationCm:
           overrides.defaultFlowMaxTranslationCm
           ?? flowDefaults.maxTranslationCm,
+        // The object prop's flow wins over the flat default*Flow* props.
+        ...(overrides.frameSelection?.flow ?? {}),
       },
     },
   };

package/src/camera/cameraErrorMessages.ts

@@ -31,7 +31,17 @@ export interface UserFacingStitchError {
  * dropped code breaks the build here rather than silently going
  * unhandled.
  */
-const RECOVERABLE_STITCH_GUIDANCE: Partial<
+/**
+ * A partial map of recoverable-error code → copy, for the `overrides`
+ * argument of {@link userFacingStitchError}.  Hosts localising the SDK pass
+ * their translated strings here (typically built from their i18n catalogue,
+ * keyed by the same `CameraErrorCode`s exposed by {@link RECOVERABLE_STITCH_CODES}).
+ */
+export type UserFacingStitchErrorOverrides = Partial<
+  Record<CameraErrorCode, UserFacingStitchError>
+>;
+
+export const RECOVERABLE_STITCH_GUIDANCE: Partial<
   Record<CameraErrorCode, UserFacingStitchError>
 > = {
   // cv::Stitcher ERR_NEED_MORE_IMGS / the manual pipeline's "0 valid
@@ -61,6 +71,15 @@ const RECOVERABLE_STITCH_GUIDANCE: Partial<
       "The frames couldn't be aligned — keep the phone level and steady so "
       + 'each frame overlaps the one before it.',
   },
+  // v0.16 — the post-stitch validator rejected the output as disjoint /
+  // fragmented: the frames stitched but didn't form one coherent panorama
+  // (usually a too-fast or jerky sweep that broke alignment partway).
+  STITCH_LOW_QUALITY: {
+    title: "That didn't come out right",
+    message:
+      "The panorama didn't stitch into one clean image — try again, panning "
+      + 'slowly and steadily in one direction so each frame overlaps the last.',
+  },
   // Ran out of memory finishing the stitch — usually an over-long sweep.
   STITCH_OOM: {
     title: 'Try a shorter sweep',
@@ -70,15 +89,33 @@ const RECOVERABLE_STITCH_GUIDANCE: Partial<
   },
 };
 
+/**
+ * The recoverable stitch-error codes this module has built-in copy for.
+ * A host wiring i18n iterates these to know exactly which codes need a
+ * translation (every other `CameraErrorCode` maps to `null` and uses the
+ * host's generic error UI).
+ */
+export const RECOVERABLE_STITCH_CODES = Object.keys(
+  RECOVERABLE_STITCH_GUIDANCE,
+) as CameraErrorCode[];
+
 /**
  * Maps a `CameraErrorCode` to friendly, action-guiding alert copy.
  *
+ * Localisation: pass `overrides` (a partial code→copy map, typically from
+ * your i18n catalogue) and any code present there wins over the built-in
+ * English; codes you omit fall back to the bundled copy.  This is the
+ * host-side mirror of the `guidanceCopy` prop — the recoverable-error alert
+ * is rendered by the HOST (in its `onError` handler), so it is localised
+ * here rather than through `<Camera>`.
+ *
  * @returns the title+message for a recoverable stitch failure, or `null`
  *   if `code` has no single user-recoverable action (the host should
  *   then show its generic error UI).
  */
 export function userFacingStitchError(
   code: CameraErrorCode,
+  overrides?: UserFacingStitchErrorOverrides,
 ): UserFacingStitchError | null {
-  return RECOVERABLE_STITCH_GUIDANCE[code] ?? null;
+  return overrides?.[code] ?? RECOVERABLE_STITCH_GUIDANCE[code] ?? null;
 }

package/src/camera/cameraGuidanceCopy.ts

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * cameraGuidanceCopy — the single user-overridable copy surface for EVERY
+ * string the panorama capture UI renders itself: the rotate prompt, pan
+ * hint, too-fast cue, lateral-stop popup, the capture-status banner
+ * (recording / stitching) AND the crop-editor warning banners.  Centralised
+ * so a host can localise or re-word the whole capture experience in one
+ * place via the `guidanceCopy` `<Camera>` prop (see the README's
+ * "Internationalization" section), and so the defaults live together.
+ *
+ * NOTE on coverage: the *recoverable stitch-error* alert copy
+ * (`userFacingStitchError`) is rendered by the HOST (it calls that helper
+ * in its `onError` handler), so it is localised there — see
+ * `cameraErrorMessages.ts`, which accepts an override map for the same
+ * reason.  Everything the SDK draws on screen flows through THIS object.
+ *
+ * Mirrors the override pattern of `PanoramaGuidance.messages` and
+ * `cameraErrorMessages.ts`.
+ */
+import {
+  DEFAULT_CAPTURE_WARNING_COPY,
+  type CaptureWarningCopy,
+} from './captureWarnings';
+
+export interface GuidanceCopy {
+  /** Item 2 — caption pill while waiting for the user to rotate to landscape
+   *  (panMode `'vertical'`). */
+  rotateToLandscape: string;
+  /** Item 2 — caption pill while waiting for the user to rotate to portrait
+   *  (panMode `'horizontal'`). */
+  rotateToPortrait: string;
+  /** Item 3 — short hint shown with the how-to-pan animation. */
+  panHint: string;
+  /** Item 4 — transient warning when the pan is too fast. */
+  tooFast: string;
+  /** Item 6 — popup title when the user drifts laterally (cross-axis). */
+  lateralStopTitle: string;
+  /** Item 6 — popup body / guidance for the lateral-drift stop. */
+  lateralStopBody: string;
+  /** Item 6 — popup dismiss button label. */
+  lateralStopDismiss: string;
+  /**
+   * Item 6 — popup TITLE when lateral drift stopped the capture before
+   * enough frames were captured to stitch (the user panned the wrong way
+   * almost immediately).  Nothing was produced, so the copy points them at
+   * the arrow instead of saying "we kept what you captured".
+   */
+  lateralWrongDirectionTitle: string;
+  /** Item 6 — popup BODY for the too-few-frames wrong-direction stop. */
+  lateralWrongDirectionBody: string;
+  /** Item 7 — confirm button on the crop editor. */
+  cropConfirm: string;
+  /** Item 7 — reset-corners button on the crop editor. */
+  cropReset: string;
+  /** Item 7 — "emit the stitch un-cropped" button on the crop editor. */
+  cropUseOriginal: string;
+  /** Item 7 — discard this capture and return to the camera. */
+  cropRetake: string;
+  /**
+   * Accept button in PREVIEW-ONLY mode (`showPreview` without `rectCrop`):
+   * the editor shows the stitched image with no crop box, and this confirms
+   * it as-is.
+   */
+  previewConfirm: string;
+
+  // ── Capture-status banner (CaptureStatusOverlay) ───────────────────────
+  /** Banner while a capture is recording (the calm, green state). */
+  statusRecording: string;
+  /** Banner while the panorama is being stitched after release. */
+  statusStitching: string;
+
+  // ── Crop-editor warning banner (buildCaptureWarnings) ──────────────────
+  // These re-use the capture-warning defaults verbatim (single source of
+  // truth in `captureWarnings.ts`); overriding them here re-words BOTH the
+  // crop-banner text AND the `message` carried on `onCapture(...).warnings`.
+  /**
+   * LOW_FRAME_UTILIZATION warning.  TEMPLATE — keep the `{included}`,
+   * `{requested}` and `{percent}` placeholders (substituted at runtime).
+   */
+  warnLowFrameUtilization: string;
+  /** LATERAL_DRIFT_FINALIZE warning. */
+  warnLateralDriftFinalize: string;
+  /** HIGH_PAN_SPEED warning. */
+  warnHighPanSpeed: string;
+}
+
+export const DEFAULT_GUIDANCE_COPY: GuidanceCopy = {
+  rotateToLandscape: 'Rotate to landscape',
+  rotateToPortrait: 'Rotate to portrait',
+  panHint: 'Pan slowly top to bottom',
+  tooFast: 'Moving too fast — slow down',
+  lateralStopTitle: 'Keep the pan straight',
+  lateralStopBody:
+    'You moved sideways. Pan in one direction only — we stitched what you captured.',
+  lateralStopDismiss: 'Got it',
+  lateralWrongDirectionTitle: 'Follow the arrow',
+  lateralWrongDirectionBody:
+    'You moved the phone the wrong way. Pan slowly in the direction the '
+    + 'arrow shows, in one straight line.',
+  cropConfirm: 'Crop',
+  cropReset: 'Reset',
+  cropUseOriginal: 'Use original',
+  cropRetake: 'Retake',
+  previewConfirm: 'Confirm',
+  statusRecording: 'Hold steady — pan slowly',
+  statusStitching: 'Stitching panorama…',
+  // DRY: the English warning copy lives once, in captureWarnings.ts.
+  warnLowFrameUtilization: DEFAULT_CAPTURE_WARNING_COPY.lowFrameUtilization,
+  warnLateralDriftFinalize: DEFAULT_CAPTURE_WARNING_COPY.lateralDriftFinalize,
+  warnHighPanSpeed: DEFAULT_CAPTURE_WARNING_COPY.highPanSpeed,
+};
+
+/**
+ * Project the warning keys of a resolved `GuidanceCopy` back onto the
+ * {@link CaptureWarningCopy} shape `buildCaptureWarnings` consumes.  Keeps
+ * the two call sites in `<Camera>` from re-spelling the mapping (DRY).
+ */
+export function captureWarningCopyFrom(g: GuidanceCopy): CaptureWarningCopy {
+  return {
+    lowFrameUtilization: g.warnLowFrameUtilization,
+    lateralDriftFinalize: g.warnLateralDriftFinalize,
+    highPanSpeed: g.warnHighPanSpeed,
+  };
+}
+
+/**
+ * Merge a partial host override onto the defaults.  Undefined / missing keys
+ * fall back to the default string; an empty-object / undefined override
+ * returns the defaults unchanged.
+ */
+export function mergeGuidanceCopy(
+  override?: Partial<GuidanceCopy>,
+): GuidanceCopy {
+  if (!override) return DEFAULT_GUIDANCE_COPY;
+  return { ...DEFAULT_GUIDANCE_COPY, ...stripUndefined(override) };
+}
+
+/** Drop keys whose value is `undefined` so they don't clobber a default. */
+function stripUndefined(o: Partial<GuidanceCopy>): Partial<GuidanceCopy> {
+  const out: Partial<GuidanceCopy> = {};
+  (Object.keys(o) as (keyof GuidanceCopy)[]).forEach((k) => {
+    if (o[k] !== undefined) out[k] = o[k];
+  });
+  return out;
+}

package/src/camera/captureCountdown.ts

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * captureCountdown — pure timing helpers for the recording-time countdown
+ * and auto-finalize (guidance item 5).
+ *
+ * The non-AR panorama hold-and-pan has a hard recording ceiling (`maxMs`).
+ * As the user pans, a blinking countdown shows the whole seconds remaining;
+ * when it hits 0 the host auto-finalizes (stops recording and stitches what
+ * was captured — the FINALIZE-on-zero decision is handled by `<Camera>`,
+ * not here).
+ *
+ * Both functions are pure (no React, no timers, no `Date.now()` baked in —
+ * the caller threads `now` from its own animation frame / interval) so the
+ * boundary behaviour is unit-testable in the node jest env.  Mirrors the
+ * pure-helper + `__tests__` pattern of `contentRotationDeg`.
+ *
+ * `maxMs <= 0` DISABLES the feature: `shouldAutoStop` never returns true
+ * (recording is unbounded) and the countdown is meant to be hidden by the
+ * caller.  `countdownSecondsFrom` still returns a clamped, non-negative
+ * number in that case (0) so a caller that renders it regardless won't show
+ * a negative value.
+ */
+
+
+/**
+ * Whole seconds remaining in the recording window, for the countdown UI.
+ *
+ *   - While recording (`recordingStartedAt` non-null):
+ *       `ceil((maxMs - elapsed) / 1000)`, where `elapsed = now - start`,
+ *       clamped to `[0, round(maxMs / 1000)]`.  `ceil` means the displayed
+ *       number ticks to N only once strictly fewer than N seconds remain
+ *       (e.g. at exactly 1 ms before the 1s boundary it still reads the
+ *       higher value), and it reaches 0 exactly at `elapsed === maxMs`.
+ *   - Before recording (`recordingStartedAt === null`): the full window,
+ *       `round(maxMs / 1000)` — the at-rest value shown before the user
+ *       starts the hold.
+ *   - `maxMs <= 0` (feature disabled): returns 0.
+ *
+ * The result is always a whole, non-negative number.
+ */
+export function countdownSecondsFrom(
+  recordingStartedAt: number | null,
+  now: number,
+  maxMs: number,
+): number {
+  if (maxMs <= 0) return 0;
+
+  const maxSeconds = Math.round(maxMs / 1000);
+
+  // Not recording yet — show the full window at rest.
+  if (recordingStartedAt === null) return maxSeconds;
+
+  const elapsed = now - recordingStartedAt;
+  const remainingSeconds = Math.ceil((maxMs - elapsed) / 1000);
+
+  // Clamp into [0, maxSeconds]: guards a clock that ran past the ceiling
+  // (negative remaining → 0) and a `now` before the start (`elapsed < 0`,
+  // remaining > maxSeconds → maxSeconds).
+  return Math.min(maxSeconds, Math.max(0, remainingSeconds));
+}
+
+
+/**
+ * True when the host should auto-finalize the recording NOW.
+ *
+ * Fires only when ALL of:
+ *   1. recording (`recordingStartedAt` non-null),
+ *   2. the window is enabled (`maxMs > 0`), AND
+ *   3. elapsed (`now - start`) has reached or passed the ceiling
+ *      (`>= maxMs`).
+ *
+ * `maxMs <= 0` disables auto-stop entirely (unbounded recording), so this
+ * returns false regardless of how long the user has been recording.
+ */
+export function shouldAutoStop(
+  recordingStartedAt: number | null,
+  now: number,
+  maxMs: number,
+): boolean {
+  if (recordingStartedAt === null) return false;
+  if (maxMs <= 0) return false;
+  return now - recordingStartedAt >= maxMs;
+}