@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/context.tsx

@@ -26,7 +26,25 @@ export function useStore(): ShotEditorStore {
 export function useShotEditor<T>(selector: (s: ShotEditorState) => T): T {
   const store = useStore();
   return useSyncExternalStore(
-    store.subscribe,
+    store.subscribeCold,
+    () => selector(store.getState()),
+    () => selector(store.getState()),
+  );
+}
+
+/**
+ * Subscribe to CLOCK-BEARING state.
+ *
+ * `useShotEditor` is deliberately deaf to a frame-only tick, which is what
+ * makes playback affordable for the chrome. A component that paints the
+ * playhead itself needs the opposite, and this is it — kept at the smallest
+ * leaf that must repaint every tick, never at a panel root, or the saving is
+ * handed straight back.
+ */
+export function useShotEditorHot<T>(selector: (s: ShotEditorState) => T): T {
+  const store = useStore();
+  return useSyncExternalStore(
+    store.subscribeHot,
     () => selector(store.getState()),
     () => selector(store.getState()),
   );

package/src/state/editorPrefs.ts

@@ -0,0 +1,220 @@
+// The editor's per-viewer preferences, remembered across reloads.
+//
+// How the AUTHOR likes to look at the editor: the grid floor, the two
+// diagnostic chips, motion paths, rulers, guides, labels, where the tool
+// footer sits and the playback resolution. Each is a fact about the person,
+// the way the theme is, never about the document, so it lives in
+// localStorage and not in the save. The playback resolution and the Insert
+// drawer's first meeting are facts about this browser too, so they never
+// reach the account copy (`accountPrefs.ts`).
+//
+// ONE KEY HOLDING ONE OBJECT, the way `layoutPrefs` keeps the workspace. A
+// toggle added later is one field here rather than one more key to name,
+// migrate and clear.
+//
+// WHAT IS NOT HERE. The theme stays in `dailies.theme` (the ui package owns it
+// and every surface reads it, not only this editor), and the panel layout stays
+// in `dailies.workspace` (`layoutPrefs.ts`, which has its own clamping rules).
+//
+// Guarded on both sides: private mode and a locked-down storage policy each
+// throw on access, and a preference is never worth an exception. A read that
+// fails answers the defaults, which is the state the chrome had before this
+// existed.
+import { isPlaybackResolution } from "../bridgeTypes.js";
+import type { PlaybackResolution } from "../bridgeTypes.js";
+import type { ShotEditorStore } from "./store.js";
+
+/** The one key, exported so the suite asserts against THIS string. */
+export const EDITOR_PREFS_KEY = "dailies.editor";
+
+/** The two keys `badgePrefs.ts` used to write, one string each. Read once by
+ *  `readEditorPrefs`, folded into the object and removed. */
+const LEGACY_BADGE_KEYS = {
+  showFpsBadge: "dailies.badge.fps",
+  showBackendBadge: "dailies.badge.backend",
+} as const;
+
+export interface EditorPrefs {
+  /** The selected layer's motion path on the stage. */
+  motionPaths: boolean;
+  /** A single plain pick moves a paused playhead into the layer's settled
+   *  window (`ShotEditorState.selectMovesPlayhead`). */
+  selectMovesPlayhead: boolean;
+  /** Rulers along the canvas edges. */
+  rulers: boolean;
+  /** Snapping guides while dragging. */
+  smartGuides: boolean;
+  /** Camera move bar labels on the timeline: fitted to the bar, or off. */
+  blockLabels: "fit" | "off";
+  /** Inspector field labels: the compact glyph, or the full name. */
+  fieldLabels: "compact" | "named";
+  /** Where the tool footer sits. */
+  toolbarPosition: "bottom" | "top";
+  /** The working pane's grid floor (`ShotEditorState.showGrid`). */
+  showGrid: boolean;
+  /** The canvas bar's frame-rate chip (`ShotEditorState.showFpsBadge`). */
+  showFpsBadge: boolean;
+  /** The canvas bar's renderer chip (`ShotEditorState.showBackendBadge`). */
+  showBackendBadge: boolean;
+  /** The author has met the Insert drawer: closed it, or added anything
+   *  (`ShotEditorState.insertDrawerSeen`). Until then an empty Project opens
+   *  it on its own, once. */
+  insertDrawerSeen: boolean;
+  /** What a played frame may render at (`ShotEditorState.playbackResolution`). */
+  playbackResolution: PlaybackResolution;
+}
+
+export const EDITOR_PREF_DEFAULTS: Readonly<EditorPrefs> = {
+  motionPaths: true,
+  selectMovesPlayhead: true,
+  rulers: false,
+  smartGuides: true,
+  blockLabels: "fit",
+  fieldLabels: "compact",
+  toolbarPosition: "bottom",
+  showGrid: true,
+  showFpsBadge: true,
+  showBackendBadge: true,
+  insertDrawerSeen: false,
+  playbackResolution: "auto",
+};
+
+/** Each field's own test. A field that fails it falls back to its default and
+ *  nothing else does: one bad value never costs the good ones. */
+export const EDITOR_PREF_VALID: { [K in keyof EditorPrefs]: (value: unknown) => value is EditorPrefs[K] } = {
+  motionPaths: isBoolean,
+  selectMovesPlayhead: isBoolean,
+  rulers: isBoolean,
+  smartGuides: isBoolean,
+  blockLabels: (v): v is EditorPrefs["blockLabels"] => v === "fit" || v === "off",
+  fieldLabels: (v): v is EditorPrefs["fieldLabels"] => v === "compact" || v === "named",
+  toolbarPosition: (v): v is EditorPrefs["toolbarPosition"] => v === "bottom" || v === "top",
+  showGrid: isBoolean,
+  showFpsBadge: isBoolean,
+  showBackendBadge: isBoolean,
+  insertDrawerSeen: isBoolean,
+  playbackResolution: isPlaybackResolution,
+};
+
+const FIELDS = Object.keys(EDITOR_PREF_DEFAULTS) as readonly (keyof EditorPrefs)[];
+
+function isBoolean(value: unknown): value is boolean {
+  return typeof value === "boolean";
+}
+
+/**
+ * The saved preferences, validated FIELD BY FIELD over the defaults.
+ *
+ * A missing key, corrupt JSON or a non-object all answer the defaults; one bad
+ * field answers its own default and keeps the rest.
+ *
+ * THE ONE-TIME MIGRATION lives here, because this is the first thing a boot
+ * reads: the old `dailies.badge.*` keys (only an explicit "0" hid a chip) fill
+ * the two badge fields when the object has no opinion of its own, the merged
+ * object is written, and the old keys are removed so the next boot never reads
+ * them again.
+ */
+export function readEditorPrefs(): EditorPrefs {
+  const prefs: EditorPrefs = { ...EDITOR_PREF_DEFAULTS };
+  let saved: Record<string, unknown> = {};
+  try {
+    const text = localStorage.getItem(EDITOR_PREFS_KEY);
+    if (text !== null) {
+      const parsed: unknown = JSON.parse(text);
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed))
+        saved = parsed as Record<string, unknown>;
+    }
+  } catch {
+    /* unreadable or corrupt: the defaults stand */
+  }
+  for (const field of FIELDS) {
+    const value = saved[field];
+    if (EDITOR_PREF_VALID[field](value)) (prefs as Record<keyof EditorPrefs, unknown>)[field] = value;
+  }
+  migrateBadgeKeys(prefs, saved);
+  return prefs;
+}
+
+function migrateBadgeKeys(prefs: EditorPrefs, saved: Record<string, unknown>): void {
+  try {
+    let found = false;
+    for (const field of ["showFpsBadge", "showBackendBadge"] as const) {
+      const old = localStorage.getItem(LEGACY_BADGE_KEYS[field]);
+      if (old === null) continue;
+      found = true;
+      if (!(field in saved)) prefs[field] = old !== "0";
+    }
+    if (!found) return;
+    writeEditorPrefs(prefs);
+    for (const key of Object.values(LEGACY_BADGE_KEYS)) localStorage.removeItem(key);
+  } catch {
+    /* storage disabled: the migration waits for a boot that can write */
+  }
+}
+
+/** Write the preferences. */
+export function writeEditorPrefs(prefs: EditorPrefs): void {
+  try {
+    localStorage.setItem(EDITOR_PREFS_KEY, JSON.stringify(prefs));
+  } catch {
+    /* storage disabled or full: the session still honours the toggle, it just forgets */
+  }
+}
+
+/** Whether this browser has ever written the preferences. */
+export function hasStoredEditorPrefs(): boolean {
+  try {
+    return localStorage.getItem(EDITOR_PREFS_KEY) !== null;
+  } catch {
+    return false;
+  }
+}
+
+/** Every field, read off the store's state. `base` stays for a field a later
+ *  lane adds here before the store owns it. */
+function prefsOf(store: ShotEditorStore, base: EditorPrefs): EditorPrefs {
+  const s = store.getState();
+  return {
+    ...base,
+    showGrid: s.showGrid,
+    showFpsBadge: s.showFpsBadge,
+    showBackendBadge: s.showBackendBadge,
+    selectMovesPlayhead: s.selectMovesPlayhead,
+    insertDrawerSeen: s.insertDrawerSeen,
+    motionPaths: s.motionPaths,
+    rulers: s.rulers,
+    smartGuides: s.smartGuides,
+    blockLabels: s.blockLabels,
+    fieldLabels: s.fieldLabels,
+    toolbarPosition: s.toolbarPosition,
+    playbackResolution: s.playbackResolution,
+  };
+}
+
+function samePrefs(a: EditorPrefs, b: EditorPrefs): boolean {
+  for (const field of FIELDS) if (!Object.is(a[field], b[field])) return false;
+  return true;
+}
+
+/**
+ * Writes the preferences whenever one of them changes, and returns the
+ * unsubscribe.
+ *
+ * SIGNATURE-GATED, like `persistLayoutPrefs`: the subscription runs on every
+ * store notification that is not a transport tick, so it compares a handful
+ * of fields and writes only on a real change. On the COLD lane, because no
+ * preference is the frame, and a raw one built this object sixty times a
+ * second while the transport played. The seed is the store as it stands,
+ * which `createShotEditorStore` built from `readEditorPrefs`, so subscribing
+ * writes nothing on its own.
+ */
+export function persistEditorPrefs(store: ShotEditorStore): () => void {
+  const base = readEditorPrefs();
+  let last = prefsOf(store, base);
+  return store.subscribeCold(() => {
+    const prefs = prefsOf(store, base);
+    if (samePrefs(prefs, last)) return;
+    last = prefs;
+    writeEditorPrefs(prefs);
+  });
+}

package/src/state/errorReports.ts

@@ -0,0 +1,121 @@
+// What broke for a person in the HOSTED editor, told to the Worker
+// (`POST /api/error-reports`), so the admin panel can show what broke, for
+// whom and since when.
+//
+// Hosted only (`dailiesHost`): the local CLI server has no such route and
+// nobody to tell. NEVER DOCUMENT CONTENT: a code, ids, numbers and the error's
+// own message, never a layer's text, props, code or a file. FIRE AND FORGET:
+// a report never throws, never waits and is never retried. The same report
+// goes at most once per `ERROR_REPORT_WINDOW_MS`, a tab sends at most
+// `ERROR_REPORT_CAP`, and a 429 (rate-limited) or a 401, 403 or 404 (signed
+// out, not hosted) ends sending for the tab.
+import { stageFailuresOf } from "@dailies-studio/shot/doc";
+import { dailiesHost } from "../hostApi.js";
+import { subscribeRuntimeErrors } from "./runtimeErrors.js";
+import { stageHealthReport } from "./stageHealth.js";
+import type { ShotEditorStore } from "./store.js";
+
+/** The route's body, as the chrome fills it. */
+export interface ErrorReport {
+  /** Stable: `/^[a-z0-9][a-z0-9_.:-]*$/`, at most 80 characters. */
+  code: string;
+  /** The error's own message; cut to `MESSAGE_MAX` characters. */
+  message?: string;
+  /** The open Project's document id. */
+  projectId?: string;
+  /** The Shot (scene) id, when one is involved. */
+  shot?: string;
+  /** Small facts (a piece kind, a layer id, a frame, a refusal name), at
+   *  most `DETAIL_MAX` characters of JSON or left out. */
+  detail?: Readonly<Record<string, string | number | boolean | null>>;
+}
+
+export const ERROR_REPORT_WINDOW_MS = 10 * 60_000;
+export const ERROR_REPORT_CAP = 30;
+const MESSAGE_MAX = 300;
+const DETAIL_MAX = 1024;
+/** The answers after which this tab sends nothing more. */
+const STOP_STATUSES = [401, 403, 404, 429];
+
+let sent = 0;
+let stopped = false;
+/** Each report's key, and when it was last sent. */
+const lastSent = new Map<string, number>();
+
+export function reportError(report: ErrorReport): void {
+  if (stopped || sent >= ERROR_REPORT_CAP || dailiesHost() === undefined) return;
+  try {
+    // Where a failure was first seen is not what failed: two reports that
+    // differ only in `frame` are the same report.
+    const key = JSON.stringify([report.code, report.projectId, report.shot, { ...report.detail, frame: undefined }]);
+    const now = Date.now();
+    const last = lastSent.get(key);
+    if (last !== undefined && now - last < ERROR_REPORT_WINDOW_MS) return;
+    lastSent.set(key, now);
+    sent += 1;
+    const { message, detail, ...ids } = report;
+    const body = {
+      ...ids,
+      ...(message === undefined ? {} : { message: message.slice(0, MESSAGE_MAX) }),
+      ...(detail === undefined || JSON.stringify(detail).length > DETAIL_MAX ? {} : { detail }),
+    };
+    void fetch("/api/error-reports", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      keepalive: true,
+    }).then(
+      (res) => {
+        if (STOP_STATUSES.includes(res.status)) stopped = true;
+      },
+      () => {},
+    );
+  } catch {
+    // A report must never break what it reports on.
+  }
+}
+
+/**
+ * Hosted, report what is wrong on this tab's stage, as an agent's stage check
+ * reads it (`stageFailuresOf`): every time the stage's health changes (a new
+ * revision drawn, a piece isolated, a crash, a link that failed) or the
+ * chrome's error log moves, never per frame. Returns the unsubscribe.
+ */
+export function reportStageFailures(store: ShotEditorStore): () => void {
+  if (dailiesHost() === undefined) return () => {};
+  const check = (): void => {
+    try {
+      const state = store.getState();
+      const projectId = state.doc === null ? {} : { projectId: state.doc.id };
+      // The errors seen at the revision on screen, as the log stamps them
+      // (renderEvents.ts `setRuntimeErrorRevision`).
+      for (const failure of stageFailuresOf(stageHealthReport(store), state.dirty ? null : state.rev)) {
+        const piece = failure.piece;
+        reportError(
+          piece === undefined
+            ? { code: "stage.health_failure", message: failure.message, ...projectId, detail: { kind: failure.kind, source: failure.source ?? null } }
+            : {
+                code: "stage.piece_failure",
+                message: piece.message,
+                ...projectId,
+                shot: piece.sceneId,
+                detail: { piece: piece.kind, layer: piece.layerId ?? null, field: piece.fieldPath ?? null, frame: piece.firstFrame },
+              },
+        );
+      }
+    } catch {
+      // The store calls this from its own lanes (attachStage among them).
+    }
+  };
+  const stops = [store.subscribeStageHealth(check), subscribeRuntimeErrors(check)];
+  return () => {
+    for (const stop of stops) stop();
+  };
+}
+
+/** Test seam: a fresh tab. */
+export function resetErrorReports(): void {
+  sent = 0;
+  stopped = false;
+  lastSent.clear();
+}

package/src/state/fieldWrite.ts

@@ -0,0 +1,161 @@
+// The selection fan-out and the typed transform field, as plain functions over
+// the store. They live in state/ rather than beside the inspector hooks so the
+// store's own key verbs (digit opacity) and the in-tab WebMCP tools can run the
+// identical write without importing a React module.
+import type { ShotEditorStore } from "./store.js";
+import {
+  containerFrame,
+  effectiveTransform,
+  fixedTextBox,
+  homeOf,
+  keyframeMinter,
+  lockRefusal,
+  lockRefuses,
+  patchHome,
+  routeShownEdit,
+  setEffectiveField,
+} from "@dailies-studio/shot/doc";
+import type { Doc3D, Layer3D, Transform3D, TransformField } from "@dailies-studio/shot/doc";
+import { authoringFrame } from "./viewMode.js";
+
+/**
+ * The fan-out itself, PURE and over the document it is HANDED.
+ *
+ * Both write paths run it, which is the point: a typed value and a drag must
+ * reach the same layers, refuse the same locked ones and leave the same document
+ * identity behind, or the inspector has two answers to "what did that edit do".
+ * The commit path hands it `edit`'s document; a scrub capture hands it the
+ * gesture's BASE re-derived, which is what stops a drag compounding.
+ *
+ * IDENTITY WHEN NOTHING CHANGED is load-bearing at both call sites: `edit`
+ * records no history entry and schedules no save for a document it gets back
+ * unchanged, and a scrub that ends where it started commits nothing at all.
+ */
+export function writeSelection(
+  doc: Doc3D,
+  containerId: string,
+  ids: readonly string[],
+  build: (layer: Layer3D) => Layer3D,
+  sceneFrame: number,
+): { doc: Doc3D; refusal: string | null } {
+  const home = homeOf(doc, containerId);
+  if (home === null) return { doc, refusal: null };
+  const layersById = { ...home.layersById };
+  const mintId = keyframeMinter(doc);
+  let changed = false;
+  let refusal: string | null = null;
+  for (const id of ids) {
+    const layer = layersById[id];
+    if (layer === undefined) continue;
+    // The section builds from the layer as it shows it: an animated field at
+    // its value on the playhead. So typing a field back to its stored base is
+    // a change from what is on screen, and the router keys it.
+    const { from, built, next } = routeShownEdit(layer, build, sceneFrame, doc.fps, mintId);
+    if (built === from) continue;
+    // A locked layer takes no edit but its own Visible and Locked flags, and
+    // says so by name rather than leaving a field that silently did nothing.
+    if (lockRefuses(from, built)) {
+      refusal ??= lockRefusal(layer);
+      continue;
+    }
+    // ── KEYFRAME-AWARE, ONCE, FOR EVERY SECTION ────────────────────────────
+    //
+    // `build` is a section's own `layer -> layer` and knows nothing about
+    // tracks. `routeLayerEdit` turns the diff it produced into a keyframe on
+    // any path this layer animates, which is what makes every colour picker,
+    // radius field and shadow slider in the inspector honour a track without
+    // one of them being edited. Untracked layers return `after` by reference,
+    // so the common case is unchanged.
+    if (next === layer) continue;
+    layersById[id] = next;
+    changed = true;
+  }
+  return { doc: changed ? patchHome(doc, containerId, { layers: home.layers, layersById }) : doc, refusal };
+}
+
+/** One transform field's number, read off a transform. */
+export function readField(t: Transform3D, field: TransformField): number {
+  switch (field) {
+    case "x":
+      return t.position[0];
+    case "y":
+      return t.position[1];
+    case "z":
+      return t.position[2];
+    case "w":
+      return t.size[0];
+    case "h":
+      return t.size[1];
+    case "tiltX":
+      return t.tilt[0];
+    case "tiltY":
+      return t.tilt[1];
+    case "roll":
+      return t.rollDeg;
+    case "opacity":
+      return t.opacity;
+  }
+}
+
+/**
+ * `layer` with one transform field typed, for `writeSelection` to route.
+ *
+ * The typed path and the drag (`useTransformScrub`) both build with this, so a
+ * number typed and the same number dragged leave one document. The new
+ * transform is a BASE (`setEffectiveField`): `writeSelection`'s
+ * `routeLayerEdit` turns a tracked field into a key at the playhead and leaves
+ * an untracked one a constant.
+ *
+ * The SAME LAYER when the value is already there. `routeLayerEdit` hands an
+ * untracked layer's edit back as it is, so without this a typed no-op would
+ * cost an undo entry.
+ */
+export function typeTransformField(
+  layer: Layer3D,
+  field: TransformField,
+  value: number,
+  sceneFrame: number,
+  fps: Doc3D["fps"],
+): Layer3D {
+  const transform = setEffectiveField(layer, field, value, sceneFrame, fps);
+  if (readField(transform, field) === readField(effectiveTransform(layer, sceneFrame, fps), field)) return layer;
+  const posed = { ...layer, transform };
+  return field === "w" || field === "h" ? fixedTextBox(posed) : posed;
+}
+
+/**
+ * Type a transform field onto `ids`, PURE over the store, returning the refusal.
+ *
+ * Extracted from the hook below so a caller that is not a React tree — the
+ * in-tab WebMCP tools (`state/webmcp.ts`) — runs the identical operation rather
+ * than a second one that looks like it. Animate mode needs no fork here: the
+ * store's `noteChange` records the edit as keys, for this write and every other.
+ *
+ * `ids` is the fan-out, so the hook passes the live selection and a tool may
+ * pass one layer.
+ */
+export function commitTransformField(
+  store: ShotEditorStore,
+  field: TransformField,
+  value: number,
+  ids: readonly string[],
+): string | null {
+  // LIVE state at the keystroke, never the display hook's coalesced frame: the
+  // compensation arithmetic must target the frame actually painted, or the
+  // typed value lands up to 100ms of playhead away from where it reads back.
+  const s = store.getState();
+  const doc = s.doc;
+  // The CONTAINER, and its own clock: with a definition open the write targets
+  // its interior at the DEF-LOCAL playhead.
+  const container = s.editingDef ?? s.sceneId;
+  if (doc === null || container === null) return null;
+  const sceneFrame = containerFrame(doc, container, authoringFrame(s));
+  let refusal: string | null = null;
+  const build = (layer: Layer3D): Layer3D => typeTransformField(layer, field, value, sceneFrame, doc.fps);
+  const ran = store.edit((next) => {
+    const out = writeSelection(next, container, ids, build, sceneFrame);
+    refusal = out.refusal;
+    return out.doc;
+  });
+  return ran ? refusal : store.getState().error;
+}

package/src/state/fontRecents.ts

@@ -0,0 +1,70 @@
+// THE FONT PICKER'S RECENT LIST: the families this viewer picked last, newest
+// first, in this browser only (`localStorage`). A convenience, so every read
+// and write is guarded (private mode and a locked-down storage policy throw on
+// access) and a bad entry is dropped field by field, never the whole list.
+//
+// An entry names where the family comes from, not a Project's files: a Google
+// family by its catalog name, a workspace family by its name, so it resolves in
+// any Project of the workspace. A family only one Project holds as an upload is
+// not recorded: it is already listed under In this Project there.
+
+/** The one key, exported so the suite asserts against THIS string. */
+export const FONT_RECENTS_KEY = "dailies.fonts.recent";
+
+/** How many families the list keeps. */
+export const FONT_RECENTS_MAX = 8;
+
+/** A name past this is not a family anyone typed. */
+const FAMILY_MAX = 200;
+
+export interface FontRecent {
+  kind: "google" | "workspace";
+  family: string;
+}
+
+/** A family's key: case-folded, runs of spaces as one. The picker's modules
+ *  share this one copy; it must stay the same as the private copies in
+ *  state/fonts.ts (`ProjectFontFamily.key`) and fonts/googleFonts.ts. */
+export const fold = (family: string): string => family.toLowerCase().replace(/\s+/gu, " ").trim();
+const sameRecent = (a: FontRecent, b: FontRecent): boolean => a.kind === b.kind && fold(a.family) === fold(b.family);
+
+/** One stored entry, or null when any field is not what a write stores. */
+function recentOf(value: unknown): FontRecent | null {
+  if (typeof value !== "object" || value === null) return null;
+  const { kind, family } = value as Record<string, unknown>;
+  if (kind !== "google" && kind !== "workspace") return null;
+  if (typeof family !== "string" || family.trim() === "" || family.length > FAMILY_MAX) return null;
+  return { kind, family };
+}
+
+/** The list, newest first: valid entries only, each once, at most the cap. */
+export function readFontRecents(): FontRecent[] {
+  let parsed: unknown;
+  try {
+    const text = localStorage.getItem(FONT_RECENTS_KEY);
+    if (text === null) return [];
+    parsed = JSON.parse(text);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  const list: FontRecent[] = [];
+  for (const value of parsed) {
+    const recent = recentOf(value);
+    if (recent !== null && !list.some((held) => sameRecent(held, recent))) list.push(recent);
+    if (list.length === FONT_RECENTS_MAX) break;
+  }
+  return list;
+}
+
+/** Put `recent` first (moving it up if it was listed) and save; answers the
+ *  new list. A write that fails leaves the session as it was. */
+export function recordFontRecent(recent: FontRecent): FontRecent[] {
+  const list = [recent, ...readFontRecents().filter((held) => !sameRecent(held, recent))].slice(0, FONT_RECENTS_MAX);
+  try {
+    localStorage.setItem(FONT_RECENTS_KEY, JSON.stringify(list));
+  } catch {
+    // Storage disabled or full: the pick still applied, it is just not remembered.
+  }
+  return list;
+}