cursedbelt 5.77.0 → 5.78.0

package/src/react/hooks/useScrollMemory.ts

@@ -151,14 +151,17 @@ export interface ScrollMemoryOptions {
    */
   enabled?: boolean;
   /**
-   * How long a restore waits for the page to grow tall enough before settling as close as it
-   * got. Default 3000ms — a reload, where only the first page of a list exists, needs a few
-   * pages' round trips.
+   * How long a restore waits for the page to GROW before settling as close as it got — counted
+   * from the last time it grew, so a list paging itself down keeps being followed (up to 20s in
+   * all). Default 3000ms — a reload, where only the first page of a list exists, needs a few
+   * pages' round trips, each of which must land within it.
    */
   deadlineMs?: number;
 }
 
 const RESTORE_DEADLINE_MS = 3_000;
+/** The longest a restore keeps following a page that is still growing — the viewer can always take it back sooner. */
+const RESTORE_CEILING_MS = 20_000;
 /**
  * How long a landed restore holds its target against a scroll the viewer did not make. Long
  * enough for a list to finish settling (the late move in forge task 2784 came inside 800ms, under
@@ -271,7 +274,14 @@ function restore(
   deadlineMs: number,
   settled: (outcome: RestoreOutcome) => void,
 ): () => void {
-  const deadline = performance.now() + deadlineMs;
+  // 🔴 The deadline is for a page that has STOPPED growing, not a stopwatch from the start (forge
+  // task 3069): flix's phone grid, reloaded and coming back to 30,000px, pages itself down one round
+  // trip at a time, and with eight browsers sharing the Mac those trips took longer than 3s in all.
+  // The restore gave up at 29,731px while the pages were still arriving — a slow phone network is
+  // the same case. Each time the page grows the wait starts again, up to RESTORE_CEILING_MS.
+  const started = performance.now();
+  let deadline = started + deadlineMs;
+  let lastRoom = -1;
   let frame = 0;
   let holdTimer: ReturnType<typeof setTimeout> | undefined;
   let phase: 'waiting' | 'holding' | 'done' = 'waiting';
@@ -306,7 +316,12 @@ function restore(
     }
     // Short of it: go as far as the page allows — that is what asks an infinite list for more.
     scroller.set(Math.max(0, room));
-    if (performance.now() >= deadline) {
+    const now = performance.now();
+    if (room > lastRoom) {
+      lastRoom = room;
+      deadline = Math.min(now + deadlineMs, started + Math.max(deadlineMs, RESTORE_CEILING_MS));
+    }
+    if (now >= deadline) {
       finish();
       settled('deadline');
     } else frame = requestAnimationFrame(attempt);

package/src/react/media/FocusViewer.tsx

@@ -17,6 +17,10 @@ import "./focusViewer.css";
  *     which is the correct surface for a host with nowhere to put one.
  *   · `destination` — an arbitrary node in the action row, for a host that wants to choose
  *     WHERE (collections offers its folder picker there; binary-server offers nothing).
+ *   · `onSaveGif` — where a looping GIF of a section goes. Unlike a snapshot, a GIF is
+ *     offered to EVERY host: without a store it downloads to the device (owner, 2026-10-11:
+ *     *"In collections and the cb media player in general allow making a looping gif out of a
+ *     section of a video"* — "in general" is binary-server too, which keeps no stills).
  * Everything else — geometry, gestures, keyboard, the canvas capture — is the same code for
  * every consumer, which is the entire point of the lift.
  *
@@ -50,7 +54,7 @@ import "./focusViewer.css";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { Alert } from "../components/Alert.js";
 import { Button } from "../components/Button.js";
-import { NativeSelect } from "../components/NativeSelect.js";
+import { SelectField } from "../components/SelectField.js";
 import { Tooltip } from "../components/Tooltip.js";
 import { MediaResizeBar, MediaResizeCorner, useMediaResize } from "./MediaResize.js";
 import { FOCUS_HEIGHT_KEY } from "./stageResize.js";
@@ -58,6 +62,17 @@ import { PictureControls } from "./PictureControls.js";
 import { handOffPlayhead } from "./playheadHandoff.js";
 import { isPlayPauseSpace } from "./playerSpaceKey.js";
 import { PLAYBACK_RATES } from "./VideoPlayer.js";
+import {
+	clampGifSection,
+	formatGifBytes,
+	formatGifTime,
+	GIF_FRAME_RATES,
+	GIF_WIDTHS,
+	type GifSection,
+	gifFileName,
+	gifSectionAt,
+	MAX_GIF_SECONDS,
+} from "./gifClip.js";
 import {
 	FULL_REGION,
 	MAX_ZOOM,
@@ -87,6 +102,20 @@ import {
 } from "./videoEnhance.js";
 import { cn, RAW_BUTTON } from '../lib/cn.js';
 
+/**
+ * The GIF recorder and its encoder, fetched the first time the GIF panel opens — they are this
+ * feature's bytes, and a gallery that never makes a GIF should not carry them. Kept once
+ * fetched; a failed fetch is forgotten so the next press asks again.
+ */
+let gifRecorder: Promise<typeof import("./gifRecord.js")> | null = null;
+function loadGifRecorder(): Promise<typeof import("./gifRecord.js")> {
+	gifRecorder ??= import("./gifRecord.js").catch((error: unknown) => {
+		gifRecorder = null;
+		throw error;
+	});
+	return gifRecorder;
+}
+
 /** `m:ss`, or `h:mm:ss` past the hour. Local so this module has no app dependency. */
 function formatDuration(seconds: number): string {
 	if (!Number.isFinite(seconds) || seconds < 0) return "";
@@ -148,6 +177,16 @@ export interface FocusViewerProps {
 	) => Promise<FocusSaveResult | void> | FocusSaveResult | void;
 	/** An arbitrary control in the action row — collections puts its folder picker here. */
 	destination?: React.ReactNode;
+	/**
+	 * Keep a looping GIF of a section. OMIT IT and "Make a GIF" still works — it downloads the
+	 * file instead, because a GIF needs no store to be useful the way a filed still does.
+	 * `destination` applies to it as it does to a snapshot.
+	 */
+	onSaveGif?: (
+		gif: Blob,
+		meta: GifSection,
+	// biome-ignore lint/suspicious/noConfusingVoidType: as `onSaveSnapshot` — `() => {}` is the common handler
+	) => Promise<FocusSaveResult | void> | FocusSaveResult | void;
 	/**
 	 * How tall, in CSS pixels, the picture in the host's own player was when this opened.
 	 *
@@ -183,6 +222,7 @@ export function FocusViewer({
 	snapshots = [],
 	onSaveSnapshot,
 	destination,
+	onSaveGif,
 	matchHeight,
 	videoId,
 	onClose,
@@ -232,6 +272,19 @@ export function FocusViewer({
 	const [busy, setBusy] = useState(false);
 	const [error, setError] = useState<string | null>(null);
 	const [note, setNote] = useState<string | null>(null);
+	/*
+	 * ── A section, as a looping GIF ────────────────────────────────────────────────────
+	 * Null while the GIF panel is shut. Open, it is the section the GIF will hold, and while
+	 * `loopSection` is on the picture plays only that section, round and round — the preview
+	 * IS the GIF, before a frame is encoded.
+	 */
+	const [gif, setGif] = useState<GifSection | null>(null);
+	const [loopSection, setLoopSection] = useState(true);
+	const [gifFps, setGifFps] = useState<(typeof GIF_FRAME_RATES)[number]>(15);
+	const [gifWidth, setGifWidth] = useState<(typeof GIF_WIDTHS)[number]>(480);
+	/** `[done, total]` frames while one is being made. */
+	const [gifProgress, setGifProgress] = useState<[number, number] | null>(null);
+	const gifAbort = useRef<AbortController | null>(null);
 
 
 	/**
@@ -362,6 +415,110 @@ export function FocusViewer({
 		if (wasPlaying) void video.play().catch(() => undefined);
 	}, []);
 
+	/**
+	 * Play the GIF's section on a loop while it is being chosen.
+	 *
+	 * Checked every animation frame rather than on `timeupdate`, which fires about four times
+	 * a second and would let the picture run a quarter-second past the end before snapping
+	 * back — a preview that shows frames the GIF will not have. Only while PLAYING: a paused
+	 * scrub or frame-step outside the section is the person looking for a new end, and must not
+	 * be yanked back. Stands down while a GIF is being made, whose seeks are its own.
+	 */
+	useEffect(() => {
+		if (!gif || !loopSection || gifProgress) return;
+		let raf = 0;
+		const check = (): void => {
+			const video = videoRef.current;
+			if (video && !video.paused && !scrubbing.current) {
+				const t = video.currentTime;
+				if (t >= gif.endSeconds || t < gif.startSeconds - 0.05) video.currentTime = gif.startSeconds;
+			}
+			raf = requestAnimationFrame(check);
+		};
+		raf = requestAnimationFrame(check);
+		return () => cancelAnimationFrame(raf);
+	}, [gif, loopSection, gifProgress]);
+
+	/** Close the GIF panel, stopping a GIF still being made. */
+	const closeGif = (): void => {
+		gifAbort.current?.abort();
+		setGif(null);
+	};
+
+	/** Mark where the GIF starts or ends at the playhead — the `I` and `O` keys, as in an editor. */
+	const markGif = (end: "start" | "end"): void => {
+		const at = videoRef.current?.currentTime ?? position;
+		const total = duration || videoRef.current?.duration || 0;
+		// Fetched while the section is chosen, so "Save GIF" does not wait on the network.
+		void loadGifRecorder().catch(() => undefined);
+		setGif((current) => {
+			if (!current) return gifSectionAt(at, total);
+			const length = current.endSeconds - current.startSeconds;
+			return end === "start"
+				? // A start past the old end keeps the section's length rather than collapsing it.
+					clampGifSection(
+						{ startSeconds: at, endSeconds: at >= current.endSeconds ? at + length : current.endSeconds },
+						total,
+						"start",
+					)
+				: clampGifSection({ startSeconds: current.startSeconds, endSeconds: at }, total, "end");
+		});
+	};
+
+	/**
+	 * Make the GIF: seek through the section, encode what is ON SCREEN — the zoomed area and
+	 * the picture adjustments, exactly as a snapshot takes them — and save or download it.
+	 */
+	const makeGif = async (how: "save" | "download"): Promise<void> => {
+		const video = videoRef.current;
+		if (!video || !gif) return;
+		const abort = new AbortController();
+		gifAbort.current = abort;
+		setError(null);
+		setNote(null);
+		setGifProgress([0, 1]);
+		try {
+			const crop = regionPixels(shown, { width: video.videoWidth, height: video.videoHeight });
+			if (!crop) throw new Error("The video has not decoded a frame yet.");
+			// 🔴 A failed fetch here is almost always a deploy since this page opened — the chunk
+			// was renamed — and says so, rather than reloading away the section being made.
+			const { recordGifClip } = await loadGifRecorder().catch(() => {
+				throw new Error("This app was updated since the page opened — reload it to make a GIF.");
+			});
+			const blob = await recordGifClip(video, {
+				...gif,
+				fps: gifFps,
+				width: gifWidth,
+				crop,
+				...(isEnhanced(enhance) ? { filter: filterString(enhance) } : {}),
+				onProgress: (done, total) => setGifProgress([done, total]),
+				signal: abort.signal,
+			});
+			const weight = formatGifBytes(blob.size);
+			if (how === "save" && onSaveGif) {
+				const saved = (await onSaveGif(blob, gif)) ?? {};
+				setNote(
+					saved.message
+						? `${saved.message} (${weight} GIF)`
+						: saved.duplicate
+							? "That exact GIF was already saved — nothing added."
+							: `GIF saved — ${weight}.`,
+				);
+			} else {
+				downloadBlob(blob, gifFileName(title, gif.startSeconds));
+				setNote(`GIF downloaded — ${weight}.`);
+			}
+		} catch (err) {
+			if (err instanceof DOMException && err.name === "AbortError") setNote("GIF cancelled.");
+			else setError(err instanceof Error ? err.message : "The GIF could not be made.");
+		} finally {
+			if (gifAbort.current === abort) gifAbort.current = null;
+			setGifProgress(null);
+		}
+	};
+	// A GIF still being made is stopped when the viewer goes.
+	useEffect(() => () => gifAbort.current?.abort(), []);
+
 	/**
 	 * Drag the timeline to skip around LIVE.
 	 *
@@ -607,7 +764,10 @@ export function FocusViewer({
 				event.shiftKey
 			)
 				return;
-			if (event.key === "ArrowRight") {
+			if (gif && !gifProgress && (event.key === "i" || event.key === "o")) {
+				event.preventDefault();
+				markGif(event.key === "i" ? "start" : "end");
+			} else if (event.key === "ArrowRight") {
 				event.preventDefault();
 				stepFrame(1);
 			} else if (event.key === "ArrowLeft") {
@@ -797,23 +957,18 @@ export function FocusViewer({
 				    motion is a primary gesture in this viewer, not a preference. */}
 				<label className="inspector__speed" htmlFor="inspector-speed">
 					<span className="sr-only">Playback speed</span>
-					<NativeSelect
+					<SelectField
 						id="inspector-speed"
 						className="w-auto"
-						onChange={(event) => {
-							const next = Number(event.target.value);
+						onValueChange={(value) => {
+							const next = Number(value);
 							setRate(next);
 							if (videoRef.current) videoRef.current.playbackRate = next;
 						}}
+						options={PLAYBACK_RATES.map((option) => ({ value: String(option), label: `${option}×` }))}
 						size="sm"
-						value={rate}
-					>
-						{PLAYBACK_RATES.map((option) => (
-							<option key={option} value={option}>
-								{option}×
-							</option>
-						))}
-					</NativeSelect>
+						value={String(rate)}
+					/>
 				</label>
 			</div>
 
@@ -911,25 +1066,29 @@ export function FocusViewer({
 				{onSaveSnapshot ? (
 				<label className="picture__slider" htmlFor="inspector-upscale">
 					<span>Save at</span>
-					<NativeSelect
+					<SelectField
 						id="inspector-upscale"
 						className="w-auto"
-						onChange={(event) => setUpscale(Number(event.target.value))}
+						onValueChange={(value) => setUpscale(Number(value))}
+						options={UPSCALE_FACTORS.map((factor) => ({
+							value: String(factor),
+							label: `${factor}× ${factor === 1 ? "(as-is)" : "upscaled"}`,
+						}))}
 						size="sm"
-						value={upscale}
-					>
-						{UPSCALE_FACTORS.map((factor) => (
-							<option key={factor} value={factor}>
-								{factor}× {factor === 1 ? "(as-is)" : "upscaled"}
-							</option>
-						))}
-					</NativeSelect>
+						value={String(upscale)}
+					/>
 				</label>
 				) : null}
 			</PictureControls>
 
-			{onSaveSnapshot ? (
+			{/*
+			 * 🔴 The save row is drawn for EVERY host now, because "Make a GIF" is: a host with no
+			 * store downloads the GIF instead (see `onSaveGif`). Only the snapshot buttons still
+			 * need `onSaveSnapshot`.
+			 */}
 			<div className="inspector__save">
+				{onSaveSnapshot ? (
+				<>
 				<Button
 					disabled={busy}
 					onClick={() => void takeSnapshot(false)}
@@ -952,8 +1111,132 @@ export function FocusViewer({
 						Snapshot whole frame
 					</Button>
 				)}
-				{destination}
+				</>
+				) : null}
+				<Button
+					aria-expanded={gif !== null}
+					disabled={gifProgress !== null}
+					onClick={() => (gif ? closeGif() : markGif("start"))}
+					tooltip={
+						gif
+							? "Put the GIF away"
+							: "Turn a few seconds of this video into a looping GIF, starting here"
+					}
+					variant={gif ? "primary" : "secondary"}
+				>
+					Make a GIF
+				</Button>
+				{onSaveSnapshot || onSaveGif ? destination : null}
 			</div>
+
+			{gif ? (
+				<section aria-label="Make a GIF" className="inspector__gif">
+					<div className="inspector__gifrange">
+						<Button
+							disabled={gifProgress !== null}
+							onClick={() => markGif("start")}
+							tooltip="Start the GIF at the playhead (I)"
+							variant="secondary"
+						>
+							Start here
+						</Button>
+						<span className="inspector__gifspan">
+							<span>{formatGifTime(gif.startSeconds)}</span>
+							<span aria-hidden="true">–</span>
+							<span>{formatGifTime(gif.endSeconds)}</span>
+							<span className="inspector__time">
+								{(gif.endSeconds - gif.startSeconds).toFixed(1)} s
+								{gif.endSeconds - gif.startSeconds >= MAX_GIF_SECONDS - 0.05 ? " · the longest a GIF can be" : ""}
+							</span>
+						</span>
+						<Button
+							disabled={gifProgress !== null}
+							onClick={() => markGif("end")}
+							tooltip={`End the GIF at the playhead (O) — up to ${MAX_GIF_SECONDS} s`}
+							variant="secondary"
+						>
+							End here
+						</Button>
+						<Button
+							aria-pressed={loopSection}
+							disabled={gifProgress !== null}
+							onClick={() => setLoopSection((on) => !on)}
+							tooltip={
+								loopSection
+									? "Playing only the section, on a loop — press to play the whole video again"
+									: "Play only the section, on a loop, the way the GIF will"
+							}
+							variant={loopSection ? "primary" : "ghost"}
+						>
+							Loop section
+						</Button>
+					</div>
+					<div className="inspector__gifout">
+						{/* SelectFields, like "Save at" beside them: the viewer already carries the
+						    one, and a segmented strip would pull Radix Tabs into every gallery. */}
+						<label className="picture__slider" htmlFor="inspector-gif-fps">
+							<span>Smoothness</span>
+							<SelectField
+								id="inspector-gif-fps"
+								className="w-auto"
+								disabled={gifProgress !== null}
+								onValueChange={(value) => setGifFps(Number(value) as (typeof GIF_FRAME_RATES)[number])}
+								options={GIF_FRAME_RATES.map((fps) => ({ value: String(fps), label: `${fps} fps` }))}
+								size="sm"
+								value={String(gifFps)}
+							/>
+						</label>
+						<label className="picture__slider" htmlFor="inspector-gif-width">
+							<span>Width</span>
+							<SelectField
+								id="inspector-gif-width"
+								className="w-auto"
+								disabled={gifProgress !== null}
+								onValueChange={(value) => setGifWidth(Number(value) as (typeof GIF_WIDTHS)[number])}
+								options={GIF_WIDTHS.map((width) => ({ value: String(width), label: `${width} px` }))}
+								size="sm"
+								value={String(gifWidth)}
+							/>
+						</label>
+						{gifProgress ? (
+							<>
+								<span aria-live="polite" className="inspector__time">
+									Making the GIF — frame {gifProgress[0]} of {gifProgress[1]}
+								</span>
+								<Button onClick={() => gifAbort.current?.abort()} tooltip="Stop making this GIF" variant="ghost">
+									Cancel
+								</Button>
+							</>
+						) : (
+							<>
+								{onSaveGif ? (
+									<Button
+										onClick={() => void makeGif("save")}
+										tooltip={
+											isFullRegion(region)
+												? "Save the section as a looping GIF beside this video"
+												: "Save the section as a looping GIF — just the part you are looking at"
+										}
+										variant="primary"
+									>
+										Save GIF
+									</Button>
+								) : null}
+								<Button
+									onClick={() => void makeGif("download")}
+									tooltip={
+										isFullRegion(region)
+											? "Download the section as a looping GIF"
+											: "Download the section as a looping GIF — just the part you are looking at"
+									}
+									variant={onSaveGif ? "secondary" : "primary"}
+								>
+									{onSaveGif ? "Download" : "Download GIF"}
+								</Button>
+							</>
+						)}
+					</div>
+				</section>
 			) : null}
 
 			{error ? <Alert tone="error">{error}</Alert> : null}
@@ -1037,3 +1320,17 @@ function marqueeStyle(rect: Region): React.CSSProperties {
 		height: `${box.h * 100}%`,
 	};
 }
+
+/** Hand a made file to the browser's own download — the GIF of a host with no store. */
+function downloadBlob(blob: Blob, name: string): void {
+	const url = URL.createObjectURL(blob);
+	const link = document.createElement("a");
+	link.href = url;
+	link.download = name;
+	link.rel = "noopener";
+	document.body.append(link);
+	link.click();
+	link.remove();
+	// After the click has been handed to the browser; revoking at once cancels it in Safari.
+	setTimeout(() => URL.revokeObjectURL(url), 30_000);
+}

package/src/react/media/focusViewer.css

@@ -246,3 +246,34 @@
 	max-inline-size: none;
 	max-block-size: none;
 }
+
+/*
+ * The GIF panel — a section of the video, as a looping GIF (owner, 2026-10-11). Two rows that
+ * wrap like the tools above them: WHAT (the section and its loop) and HOW (rate, width, make).
+ */
+.inspector__gif {
+	display: flex;
+	flex-direction: column;
+	gap: 0.5rem;
+	padding: 0.625rem 0.75rem;
+	border: 1px solid var(--border);
+	border-radius: var(--radius-md, 0.5rem);
+	background: var(--surface-raised, transparent);
+}
+
+.inspector__gifrange,
+.inspector__gifout {
+	display: flex;
+	align-items: center;
+	gap: 0.5rem;
+	flex-wrap: wrap;
+}
+
+.inspector__gifspan {
+	display: inline-flex;
+	align-items: baseline;
+	gap: 0.4rem;
+	padding-inline: 0.25rem;
+	font-variant-numeric: tabular-nums;
+	color: var(--text);
+}

package/src/react/media/gifClip.ts

@@ -0,0 +1,90 @@
+// ── A section of a video, as a looping GIF ───────────────────────────────────────────
+// The capture half of the owner's 2026-10-11 ask (*"allow making a looping gif out of a
+// section of a video"*): the section's rules and words, which the focus viewer's panel draws
+// from. The capture is `gifRecord.ts` and the encoding `gifEncode.ts` — both loaded only when a
+// GIF is made, so a gallery that never makes one carries neither.
+// Not on the media entry's export list yet: a second player that wants them adds the line and
+// its `publicSurface.baseline` entry together.
+
+/** Longest section a GIF may be. Past this a GIF is a worse video: tens of MB, and slow to open. */
+export const MAX_GIF_SECONDS = 15;
+/** Shortest section worth looping — two frames at the lowest rate. */
+export const MIN_GIF_SECONDS = 0.2;
+/** What a new section spans from the playhead, before either end is moved. */
+export const DEFAULT_GIF_SECONDS = 3;
+/** The frame rates offered. A GIF's delay is in hundredths of a second, so 20 is near the top of what plays evenly. */
+export const GIF_FRAME_RATES = [10, 15, 20] as const;
+/** Output widths offered, in pixels — the height follows the picture's shape. */
+export const GIF_WIDTHS = [320, 480, 640] as const;
+
+export interface GifSection {
+  startSeconds: number;
+  endSeconds: number;
+}
+
+/**
+ * A section made sensible: inside the video, start before end, no shorter than
+ * {@link MIN_GIF_SECONDS} and no longer than {@link MAX_GIF_SECONDS}. When an edit would break
+ * a rule, the END that was not just moved gives way — `moved` says which end the hand is on,
+ * so marking a new start past the end drags the end along instead of refusing the start.
+ */
+export function clampGifSection(section: GifSection, durationSeconds: number, moved: "start" | "end" = "end"): GifSection {
+  const duration = Number.isFinite(durationSeconds) && durationSeconds > 0 ? durationSeconds : Number.POSITIVE_INFINITY;
+  const span = (s: number) => Math.min(MAX_GIF_SECONDS, Math.max(MIN_GIF_SECONDS, s));
+  if (moved === "start") {
+    const start = Math.min(Math.max(0, section.startSeconds), Math.max(0, duration - MIN_GIF_SECONDS));
+    const length = span(section.endSeconds - start);
+    return { startSeconds: start, endSeconds: Math.min(duration, start + length) };
+  }
+  const end = Math.max(Math.min(duration, section.endSeconds), Math.min(duration, MIN_GIF_SECONDS));
+  const length = span(end - section.startSeconds);
+  return { startSeconds: Math.max(0, end - length), endSeconds: end };
+}
+
+/** The new section a "Make a GIF" press opens with: from the playhead, {@link DEFAULT_GIF_SECONDS} long. */
+export function gifSectionAt(playheadSeconds: number, durationSeconds: number): GifSection {
+  return clampGifSection(
+    { startSeconds: playheadSeconds, endSeconds: playheadSeconds + DEFAULT_GIF_SECONDS },
+    durationSeconds,
+    "start",
+  );
+}
+
+/**
+ * The moments a section is sampled at: one every `1/fps` seconds from the start, the last
+ * strictly before the end — so a loop never shows the start frame twice in a row.
+ */
+export function gifFrameTimes(section: GifSection, fps: number): number[] {
+  const length = section.endSeconds - section.startSeconds;
+  const count = Math.max(1, Math.round(length * fps));
+  return Array.from({ length: count }, (_, i) => section.startSeconds + i / fps);
+}
+
+/**
+ * The GIF's pixel size for a crop of `crop` source pixels at a requested `width` — never
+ * wider than the crop itself (upscaling a GIF only adds bytes) and never below 2×2.
+ */
+export function gifSize(crop: { sw: number; sh: number }, width: number): { width: number; height: number } {
+  const w = Math.max(2, Math.round(Math.min(width, crop.sw)));
+  return { width: w, height: Math.max(2, Math.round((w * crop.sh) / crop.sw)) };
+}
+
+/** `0:12.4` — tenths, because a GIF section is set to the frame, not to the second. */
+export function formatGifTime(seconds: number): string {
+  const safe = Math.max(0, Number.isFinite(seconds) ? seconds : 0);
+  const tenths = Math.round(safe * 10);
+  const m = Math.floor(tenths / 600);
+  const s = (tenths % 600) / 10;
+  return `${m}:${s.toFixed(1).padStart(4, "0")}`;
+}
+
+/** `2.4 MB` / `840 KB` — what a saved GIF weighs, said after it is made. */
+export function formatGifBytes(bytes: number): string {
+  return bytes >= 1024 * 1024 ? `${(bytes / (1024 * 1024)).toFixed(1)} MB` : `${Math.max(1, Math.round(bytes / 1024))} KB`;
+}
+
+/** A file name for a downloaded GIF: the video's name without its extension, and where it starts. */
+export function gifFileName(title: string | undefined, startSeconds: number): string {
+  const base = (title ?? "").replace(/\.[^./\\]+$/, "").replace(/[\\/:*?"<>|]+/g, " ").trim() || "clip";
+  return `${base} @ ${formatGifTime(startSeconds).replace(":", "-")}.gif`;
+}