From 2444a87e674ce8ee84f075857e7b5f236a312d86 Mon Sep 17 00:00:00 2001
From: Bryan Li <15131870+btli@users.noreply.github.com>
Date: Mon, 20 Jul 2026 10:19:13 -0700
Subject: [PATCH 1/6] feat(web): load selected fonts via a curated catalog +
 webfont loader
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Settings font controls only set a font NAME; nothing loaded the
family, so picking a Nerd Font or any non-installed IDE font silently
rendered the fallback stack. Add the loader half of the fix (the
dropdown is PR 2):

- fontCatalog.ts: a curated registry in three roles — sans (UI/chrome),
  fixedWidth (mono UI), and code (editor/terminal) — each entry carrying
  a stable id, label, CSS family, category, and delivery metadata
  (bundled | google-css2 | self-hosted).
- webFontLoader.ts: a deduplicated loader that injects a keyless Google
  CSS2 <link> or explicit @font-face rules and awaits readiness via
  document.fonts.load(). No-ops for bundled/system families; never
  injects the same stylesheet twice; concurrent loads share one promise.
- Wire the loader into the preference-application path: applyUiFontFamily
  and writeCodeFontFamily kick a catalog load; after the code font lands,
  re-emit so Monaco re-measures (remeasureFonts) and xterm refits. Restore
  on boot from main.tsx and embed.tsx.

Self-hosted fonts (Cascadia Code via Fontsource CDN, four Nerd Font Mono
variants via a pinned ryanoasis/nerd-fonts tag) are lazy-loaded on demand
— not eagerly imported — so the bundle stays lean.

The free-text inputs still work unchanged: a typed name that matches a
catalog family now loads; anything else is left to the OS as before.

Co-authored-by: omnigent <noreply@omnigent.ai>
Signed-off-by: Bryan Li <bryan.li@gmail.com>
---
 web/src/embed.tsx                  |  17 ++
 web/src/lib/codeFontPreferences.ts |  26 +++
 web/src/lib/fontCatalog.test.ts    | 112 ++++++++++
 web/src/lib/fontCatalog.ts         | 316 +++++++++++++++++++++++++++++
 web/src/lib/uiFontPreferences.ts   |   8 +
 web/src/lib/webFontLoader.test.ts  | 125 ++++++++++++
 web/src/lib/webFontLoader.ts       | 126 ++++++++++++
 web/src/main.tsx                   |   9 +
 web/src/shell/MonacoCodeEditor.tsx |  15 +-
 9 files changed, 749 insertions(+), 5 deletions(-)
 create mode 100644 web/src/lib/fontCatalog.test.ts
 create mode 100644 web/src/lib/fontCatalog.ts
 create mode 100644 web/src/lib/webFontLoader.test.ts
 create mode 100644 web/src/lib/webFontLoader.ts

diff --git a/web/src/embed.tsx b/web/src/embed.tsx
index 1bb73a3bba..9f3c200fe4 100644
--- a/web/src/embed.tsx
+++ b/web/src/embed.tsx
@@ -45,6 +45,23 @@ import { initChatStore } from "./store/chatStore";
 import "./index.css";
 import { QueueFlushProvider } from "./hooks/QueueFlushProvider";
 import { SessionUpdatesProvider } from "./hooks/SessionUpdatesProvider";
+import {
+  applyUiFontFamily,
+  applyUiFontScale,
+  readUiFontFamily,
+  readUiFontSizePx,
+} from "./lib/uiFontPreferences";
+import { loadCodeFontFamily, readCodeFontFamily } from "./lib/codeFontPreferences";
+
+// Restore the saved font preferences (and kick off any catalog webfont loads)
+// when the embed module loads. The UI/code font controls stay visible when
+// embedded (per-device readability prefs that don't conflict with host theming),
+// so a chosen font must be applied + fetched here just as standalone does in
+// main.tsx — otherwise the selection would only take effect on the next Settings
+// change. Guarded for SSR by the apply/load helpers.
+applyUiFontScale(readUiFontSizePx());
+applyUiFontFamily(readUiFontFamily());
+loadCodeFontFamily(readCodeFontFamily());
 
 export type { OmnigentHostConfig } from "./lib/host";
 export type { RoutingApi } from "./lib/routing";
diff --git a/web/src/lib/codeFontPreferences.ts b/web/src/lib/codeFontPreferences.ts
index 92c4a7c41c..e809f02db2 100644
--- a/web/src/lib/codeFontPreferences.ts
+++ b/web/src/lib/codeFontPreferences.ts
@@ -12,6 +12,8 @@
 // (editor.updateOptions / term.options + refit) so a Settings change lands live
 // without a reload or reconnect.
 
+import { loadFontByFamily } from "./webFontLoader";
+
 const SIZE_STORAGE_KEY = "omnigent:code-font-size";
 const FAMILY_STORAGE_KEY = "omnigent:code-font-family";
 
@@ -144,6 +146,30 @@ export function writeCodeFontFamily(name: string): void {
   // Broadcast the intended value, not a storage re-read: a failed write must
   // still live-apply the new family to mounted editors/terminals.
   emit({ sizePx: readCodeFontSizePx(), family });
+  // If the family is a catalog font that needs fetching, load it and re-emit
+  // once its glyphs are ready. The first emit applies the family to the widgets
+  // immediately (fallback stack paints); the second, post-load emit makes them
+  // re-measure/refit against the real glyph cell so the editor/terminal pick up
+  // the newly-available face. No-ops for bundled/system/non-catalog families.
+  loadCodeFontFamily(family);
+}
+
+/**
+ * Load the webfont for a code family (if it's a catalog font that needs
+ * fetching) and re-emit the current code font once its glyphs are ready, so
+ * mounted Monaco/xterm widgets re-measure against the real cell metrics. A
+ * bundled/system/non-catalog family, or an SSR context, is a no-op. Exposed for
+ * boot-time restore in main.tsx / embed.tsx.
+ */
+export function loadCodeFontFamily(family: string): void {
+  const normalized = normalizeCodeFontFamily(family);
+  const { entry, ready } = loadFontByFamily(normalized);
+  if (!entry) return;
+  void ready.then(() => {
+    // Re-read live prefs at resolution time: if the user changed the family
+    // again while this was loading, don't clobber the newer choice.
+    emit(readCodeFont());
+  });
 }
 
 /**
diff --git a/web/src/lib/fontCatalog.test.ts b/web/src/lib/fontCatalog.test.ts
new file mode 100644
index 0000000000..e5677b304b
--- /dev/null
+++ b/web/src/lib/fontCatalog.test.ts
@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest";
+import {
+  FONT_CATALOG,
+  FONT_CATALOG_BY_CATEGORY,
+  type FontCategory,
+  getFontByFamily,
+  getFontById,
+} from "./fontCatalog";
+
+const CATEGORIES: FontCategory[] = ["sans", "fixedWidth", "code"];
+
+describe("fontCatalog — integrity", () => {
+  it("has unique ids across the whole catalog", () => {
+    const ids = FONT_CATALOG.map((e) => e.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it("groups every entry under exactly its declared category", () => {
+    for (const category of CATEGORIES) {
+      for (const entry of FONT_CATALOG_BY_CATEGORY[category]) {
+        expect(entry.category).toBe(category);
+      }
+    }
+  });
+
+  it("the by-category groups partition the flat catalog", () => {
+    const grouped = CATEGORIES.flatMap((c) => FONT_CATALOG_BY_CATEGORY[c]);
+    expect(grouped.length).toBe(FONT_CATALOG.length);
+    expect(new Set(grouped)).toEqual(new Set(FONT_CATALOG));
+  });
+
+  it("populates each category the interface uses", () => {
+    for (const category of CATEGORIES) {
+      expect(FONT_CATALOG_BY_CATEGORY[category].length).toBeGreaterThan(0);
+    }
+  });
+
+  it("carries valid source metadata for every entry", () => {
+    for (const entry of FONT_CATALOG) {
+      if (entry.source === "google-css2") {
+        // A CSS2 entry must have a fetchable stylesheet href.
+        expect(entry.cssUrl).toMatch(/^https:\/\/fonts\.googleapis\.com\/css2\?/);
+        expect(entry.faces).toBeUndefined();
+      } else if (entry.source === "self-hosted") {
+        // A self-hosted entry must carry at least one @font-face with an https URL.
+        expect(entry.faces?.length).toBeGreaterThan(0);
+        for (const face of entry.faces ?? []) {
+          expect(face.url).toMatch(/^https:\/\//);
+        }
+        expect(entry.cssUrl).toBeUndefined();
+      } else {
+        // Bundled: nothing to fetch.
+        expect(entry.cssUrl).toBeUndefined();
+        expect(entry.faces).toBeUndefined();
+      }
+    }
+  });
+
+  it("includes the bundled Geist Mono and a system default with no fetch", () => {
+    const geist = getFontById("geist-mono");
+    expect(geist?.source).toBe("bundled");
+    expect(geist?.family).toBe("Geist Mono Variable");
+
+    const system = getFontById("system-ui");
+    expect(system?.source).toBe("bundled");
+    // Empty family = "System default" (maps to --font-sans, nothing to load).
+    expect(system?.family).toBe("");
+  });
+
+  it("includes the expected common families and Nerd Font variants", () => {
+    const labels = new Set(FONT_CATALOG.map((e) => e.label));
+    for (const expected of [
+      "Inter",
+      "Roboto",
+      "JetBrains Mono",
+      "Fira Code",
+      "Cascadia Code",
+      "JetBrainsMono Nerd Font Mono",
+      "CaskaydiaCove Nerd Font Mono",
+    ]) {
+      expect(labels).toContain(expected);
+    }
+  });
+});
+
+describe("fontCatalog — lookups", () => {
+  it("resolves an entry by id", () => {
+    expect(getFontById("inter")?.family).toBe("Inter");
+    expect(getFontById("nope")).toBeUndefined();
+  });
+
+  it("resolves a typed family name case-insensitively", () => {
+    expect(getFontByFamily("Fira Code")?.id).toBe("fira-code");
+    expect(getFontByFamily("fira code")?.id).toBe("fira-code");
+    expect(getFontByFamily("  FIRA CODE  ")?.id).toBe("fira-code");
+  });
+
+  it("returns undefined for an empty name or a non-catalog family", () => {
+    expect(getFontByFamily("")).toBeUndefined();
+    expect(getFontByFamily("   ")).toBeUndefined();
+    // A locally-installed font the catalog doesn't know is left to the OS.
+    expect(getFontByFamily("Comic Sans MS")).toBeUndefined();
+  });
+
+  it("resolves a family shared across categories to a single entry", () => {
+    // IBM Plex Mono is offered in both fixedWidth and code; family lookup must
+    // still resolve deterministically (first catalog occurrence wins).
+    const entry = getFontByFamily("IBM Plex Mono");
+    expect(entry).toBeDefined();
+    expect(entry?.family).toBe("IBM Plex Mono");
+  });
+});
diff --git a/web/src/lib/fontCatalog.ts b/web/src/lib/fontCatalog.ts
new file mode 100644
index 0000000000..3e9f9830ab
--- /dev/null
+++ b/web/src/lib/fontCatalog.ts
@@ -0,0 +1,316 @@
+// Curated registry of fonts the app can load on demand.
+//
+// The Settings font controls only set a font NAME; nothing loads the font, so
+// picking a family the OS doesn't have installed renders the fallback stack
+// instead. This catalog pairs each offered family with the metadata a loader
+// (see lib/webFontLoader.ts) needs to actually fetch it, so a selected family
+// works without a local install.
+//
+// Fonts are grouped into three roles the interface uses distinctly:
+//   - `sans`       — UI/chrome text (the --ui-font-family variable).
+//   - `fixedWidth` — general monospace UI usage.
+//   - `code`       — the code editor (Monaco) and terminal (xterm).
+// PR 2's Settings dropdowns render one control per category off this shape.
+
+/** The three distinct font roles the interface exposes. */
+export type FontCategory = "sans" | "fixedWidth" | "code";
+
+/**
+ * How a catalog entry's face data is delivered:
+ *   - `bundled`      — already shipped in the app bundle (Fontsource import in
+ *     index.css); no network fetch, the loader no-ops.
+ *   - `google-css2`  — a keyless Google Fonts CSS2 stylesheet (`<link>`); Google
+ *     serves the right woff2 per browser. Used for common web families.
+ *   - `self-hosted`  — explicit `@font-face` rules the loader injects, pointing
+ *     at a CDN/asset woff2/ttf. Used for Cascadia Code + the Nerd Font variants,
+ *     which aren't on Google Fonts (or whose glyph coverage we pin explicitly).
+ */
+export type FontSource = "bundled" | "google-css2" | "self-hosted";
+
+/** A single `@font-face` the self-hosted loader path injects. */
+export interface FontFaceAsset {
+  /** Absolute URL to the font file (woff2/woff/ttf). */
+  readonly url: string;
+  /** CSS `font-weight` for this face, e.g. `"400"` or `"400 700"`. */
+  readonly weight?: string;
+  /** CSS `font-style` for this face; defaults to `"normal"`. */
+  readonly style?: string;
+  /** `format(...)` hint, e.g. `"woff2"` or `"truetype"`. */
+  readonly format?: string;
+}
+
+/** One offered font, with everything needed to display AND load it. */
+export interface FontCatalogEntry {
+  /** Stable, URL/attribute-safe id. Never reused or renamed. */
+  readonly id: string;
+  /** Human-facing label for the Settings dropdown, e.g. `"JetBrains Mono"`. */
+  readonly label: string;
+  /**
+   * The CSS `font-family` name to apply and to await via `document.fonts.load`.
+   * Must match the family name the delivered face registers under.
+   */
+  readonly family: string;
+  /** Which of the three interface roles this font is offered for. */
+  readonly category: FontCategory;
+  /** How the face data is delivered (see {@link FontSource}). */
+  readonly source: FontSource;
+  /**
+   * `google-css2`: the stylesheet href to inject.
+   * Ignored for other sources.
+   */
+  readonly cssUrl?: string;
+  /**
+   * `self-hosted`: the `@font-face` faces to inject.
+   * Ignored for other sources.
+   */
+  readonly faces?: readonly FontFaceAsset[];
+}
+
+// Pinned Nerd Fonts release — a tag, never `@master`, so the patched-font paths
+// and glyph coverage stay stable across deploys.
+const NERD_FONTS_TAG = "v3.4.0";
+const NERD_FONTS_BASE = `https://cdn.jsdelivr.net/gh/ryanoasis/nerd-fonts@${NERD_FONTS_TAG}/patched-fonts`;
+
+// Fontsource CDN version for Cascadia Code (not on Google Fonts). Pinned so the
+// woff2 URLs don't drift.
+const CASCADIA_FONTSOURCE = "https://cdn.jsdelivr.net/fontsource/fonts/cascadia-code@5.2.3";
+
+/**
+ * Build a keyless Google Fonts CSS2 href for `family` at the given weights.
+ * Spaces become `+`; the `:wght@…;…` axis spec uses the literal `:@;` Google's
+ * CSS2 endpoint expects (all URL-safe here — no user input reaches this).
+ */
+function googleCss2Url(family: string, weights: readonly number[]): string {
+  const spec = `${family.replace(/ /g, "+")}:wght@${weights.join(";")}`;
+  return `https://fonts.googleapis.com/css2?family=${spec}&display=swap`;
+}
+
+/** A single-file Nerd Font Mono face (regular weight) from the pinned CDN. */
+function nerdFace(path: string): readonly FontFaceAsset[] {
+  return [{ url: `${NERD_FONTS_BASE}/${path}`, weight: "400", format: "truetype" }];
+}
+
+// ---- Sans (UI/chrome) -----------------------------------------------------
+
+const SANS_FONTS: readonly FontCatalogEntry[] = [
+  // System default: no face to load — the empty family maps to --font-sans.
+  { id: "system-ui", label: "System default", family: "", category: "sans", source: "bundled" },
+  {
+    id: "inter",
+    label: "Inter",
+    family: "Inter",
+    category: "sans",
+    source: "google-css2",
+    cssUrl: googleCss2Url("Inter", [400, 500, 600, 700]),
+  },
+  {
+    id: "roboto",
+    label: "Roboto",
+    family: "Roboto",
+    category: "sans",
+    source: "google-css2",
+    cssUrl: googleCss2Url("Roboto", [400, 500, 700]),
+  },
+  {
+    id: "open-sans",
+    label: "Open Sans",
+    family: "Open Sans",
+    category: "sans",
+    source: "google-css2",
+    cssUrl: googleCss2Url("Open Sans", [400, 600, 700]),
+  },
+  {
+    id: "lato",
+    label: "Lato",
+    family: "Lato",
+    category: "sans",
+    source: "google-css2",
+    cssUrl: googleCss2Url("Lato", [400, 700]),
+  },
+  {
+    id: "source-sans-3",
+    label: "Source Sans 3",
+    family: "Source Sans 3",
+    category: "sans",
+    source: "google-css2",
+    cssUrl: googleCss2Url("Source Sans 3", [400, 600, 700]),
+  },
+  {
+    id: "geist",
+    label: "Geist",
+    family: "Geist",
+    category: "sans",
+    source: "google-css2",
+    cssUrl: googleCss2Url("Geist", [400, 500, 600, 700]),
+  },
+];
+
+// ---- Fixed width (general monospace UI) -----------------------------------
+
+const FIXED_WIDTH_FONTS: readonly FontCatalogEntry[] = [
+  // Bundled via Fontsource (@fontsource-variable/geist-mono in index.css) — the
+  // loader no-ops for this one.
+  {
+    id: "geist-mono",
+    label: "Geist Mono",
+    family: "Geist Mono Variable",
+    category: "fixedWidth",
+    source: "bundled",
+  },
+  {
+    id: "ibm-plex-mono",
+    label: "IBM Plex Mono",
+    family: "IBM Plex Mono",
+    category: "fixedWidth",
+    source: "google-css2",
+    cssUrl: googleCss2Url("IBM Plex Mono", [400, 500, 600, 700]),
+  },
+  {
+    id: "roboto-mono",
+    label: "Roboto Mono",
+    family: "Roboto Mono",
+    category: "fixedWidth",
+    source: "google-css2",
+    cssUrl: googleCss2Url("Roboto Mono", [400, 500, 700]),
+  },
+  {
+    id: "space-mono",
+    label: "Space Mono",
+    family: "Space Mono",
+    category: "fixedWidth",
+    source: "google-css2",
+    cssUrl: googleCss2Url("Space Mono", [400, 700]),
+  },
+];
+
+// ---- Code (editor + terminal) ---------------------------------------------
+
+const CODE_FONTS: readonly FontCatalogEntry[] = [
+  {
+    id: "jetbrains-mono",
+    label: "JetBrains Mono",
+    family: "JetBrains Mono",
+    category: "code",
+    source: "google-css2",
+    cssUrl: googleCss2Url("JetBrains Mono", [400, 500, 700]),
+  },
+  {
+    id: "fira-code",
+    label: "Fira Code",
+    family: "Fira Code",
+    category: "code",
+    source: "google-css2",
+    cssUrl: googleCss2Url("Fira Code", [400, 500, 700]),
+  },
+  {
+    id: "source-code-pro",
+    label: "Source Code Pro",
+    family: "Source Code Pro",
+    category: "code",
+    source: "google-css2",
+    cssUrl: googleCss2Url("Source Code Pro", [400, 500, 700]),
+  },
+  {
+    id: "ibm-plex-mono-code",
+    label: "IBM Plex Mono",
+    family: "IBM Plex Mono",
+    category: "code",
+    source: "google-css2",
+    cssUrl: googleCss2Url("IBM Plex Mono", [400, 500, 600, 700]),
+  },
+  // Cascadia Code isn't a Google Fonts family we bundle; deliver its @font-face
+  // from the Fontsource CDN (latin subset, regular + bold).
+  {
+    id: "cascadia-code",
+    label: "Cascadia Code",
+    family: "Cascadia Code",
+    category: "code",
+    source: "self-hosted",
+    faces: [
+      { url: `${CASCADIA_FONTSOURCE}/latin-400-normal.woff2`, weight: "400", format: "woff2" },
+      { url: `${CASCADIA_FONTSOURCE}/latin-700-normal.woff2`, weight: "700", format: "woff2" },
+    ],
+  },
+  // Nerd Font variants: patched glyphs (powerline, icons) IDE/terminal users
+  // expect. Delivered as single-file Mono faces from the pinned Nerd Fonts CDN,
+  // lazily — never eagerly imported.
+  {
+    id: "jetbrainsmono-nerd-font-mono",
+    label: "JetBrainsMono Nerd Font Mono",
+    family: "JetBrainsMono Nerd Font Mono",
+    category: "code",
+    source: "self-hosted",
+    faces: nerdFace("JetBrainsMono/Ligatures/Regular/JetBrainsMonoNerdFontMono-Regular.ttf"),
+  },
+  {
+    id: "firacode-nerd-font-mono",
+    label: "FiraCode Nerd Font Mono",
+    family: "FiraCode Nerd Font Mono",
+    category: "code",
+    source: "self-hosted",
+    faces: nerdFace("FiraCode/Regular/FiraCodeNerdFontMono-Regular.ttf"),
+  },
+  {
+    id: "saucecodepro-nerd-font-mono",
+    label: "SauceCodePro Nerd Font Mono",
+    family: "SauceCodePro Nerd Font Mono",
+    category: "code",
+    source: "self-hosted",
+    faces: nerdFace("SourceCodePro/SauceCodeProNerdFontMono-Regular.ttf"),
+  },
+  {
+    id: "caskaydiacove-nerd-font-mono",
+    label: "CaskaydiaCove Nerd Font Mono",
+    family: "CaskaydiaCove Nerd Font Mono",
+    category: "code",
+    source: "self-hosted",
+    faces: nerdFace("CascadiaCode/CaskaydiaCoveNerdFontMono-Regular.ttf"),
+  },
+];
+
+/** Every catalog entry, in category then display order. */
+export const FONT_CATALOG: readonly FontCatalogEntry[] = [
+  ...SANS_FONTS,
+  ...FIXED_WIDTH_FONTS,
+  ...CODE_FONTS,
+];
+
+/** The catalog grouped by role, for the three Settings controls. */
+export const FONT_CATALOG_BY_CATEGORY: Readonly<Record<FontCategory, readonly FontCatalogEntry[]>> =
+  {
+    sans: SANS_FONTS,
+    fixedWidth: FIXED_WIDTH_FONTS,
+    code: CODE_FONTS,
+  };
+
+// id → entry, built once. Ids are unique across the catalog (asserted in tests).
+const BY_ID = new Map<string, FontCatalogEntry>(FONT_CATALOG.map((e) => [e.id, e]));
+
+/** Look up a catalog entry by its stable id. */
+export function getFontById(id: string): FontCatalogEntry | undefined {
+  return BY_ID.get(id);
+}
+
+// Lower-cased family → entry. A family (e.g. "IBM Plex Mono") can appear in more
+// than one category; the FIRST catalog occurrence wins, which is enough for the
+// loader — it only needs the delivery metadata, identical across duplicates.
+const BY_FAMILY = new Map<string, FontCatalogEntry>();
+for (const entry of FONT_CATALOG) {
+  const key = entry.family.trim().toLowerCase();
+  if (key && !BY_FAMILY.has(key)) BY_FAMILY.set(key, entry);
+}
+
+/**
+ * Resolve a typed/stored family NAME to its catalog entry, case-insensitively.
+ *
+ * This is the bridge from the existing free-text font inputs (which store a
+ * bare family string) to the loader: a typed name that matches a catalog family
+ * gets loaded; anything else (a locally-installed font, a partial name) resolves
+ * to `undefined` and the loader leaves it to the OS, unchanged. An empty name
+ * (System default) is never a catalog family, so it also returns `undefined`.
+ */
+export function getFontByFamily(family: string): FontCatalogEntry | undefined {
+  const key = family.trim().toLowerCase();
+  if (!key) return undefined;
+  return BY_FAMILY.get(key);
+}
diff --git a/web/src/lib/uiFontPreferences.ts b/web/src/lib/uiFontPreferences.ts
index c1c9b32fad..d333cc8b75 100644
--- a/web/src/lib/uiFontPreferences.ts
+++ b/web/src/lib/uiFontPreferences.ts
@@ -16,6 +16,8 @@
 // `var(--ui-font-family, var(--font-sans))`, so an unset family falls back to
 // the system stack and any value we set on documentElement wins.
 
+import { loadFontByFamily } from "./webFontLoader";
+
 const STORAGE_KEY = "omnigent:ui-font-size";
 
 /** Reference size that a scale of 1 corresponds to (Tailwind/browser default). */
@@ -166,5 +168,11 @@ export function applyUiFontFamily(name: string): void {
     document.documentElement.style.removeProperty("--ui-font-family");
     return;
   }
+  // Kick a webfont load when the name matches a catalog family so the glyphs
+  // actually arrive (fire-and-forget: the CSS var is set now and font-display:
+  // swap paints the face once it lands). A non-catalog name is left to the OS —
+  // the existing free-text behavior. The `, var(--font-sans)` fallback covers
+  // the gap before load and any name that never resolves.
+  void loadFontByFamily(normalized);
   document.documentElement.style.setProperty("--ui-font-family", `${normalized}, var(--font-sans)`);
 }
diff --git a/web/src/lib/webFontLoader.test.ts b/web/src/lib/webFontLoader.test.ts
new file mode 100644
index 0000000000..bce19fcada
--- /dev/null
+++ b/web/src/lib/webFontLoader.test.ts
@@ -0,0 +1,125 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { type FontCatalogEntry, getFontById } from "./fontCatalog";
+import { resetFontLoaderForTests, loadFont, loadFontByFamily } from "./webFontLoader";
+
+// jsdom has no FontFaceSet; stub document.fonts.load so readiness resolves and
+// we can count how often a given family was requested.
+let loadCalls: string[] = [];
+
+beforeEach(() => {
+  loadCalls = [];
+  Object.defineProperty(document, "fonts", {
+    configurable: true,
+    value: {
+      load: vi.fn((spec: string) => {
+        loadCalls.push(spec);
+        return Promise.resolve([]);
+      }),
+    },
+  });
+});
+
+afterEach(() => {
+  resetFontLoaderForTests();
+  for (const node of document.querySelectorAll("[data-omnigent-font]")) node.remove();
+  vi.restoreAllMocks();
+});
+
+function styleNodes(id: string): number {
+  return document.querySelectorAll(`[data-omnigent-font="${id}"]`).length;
+}
+
+describe("webFontLoader — google-css2", () => {
+  it("injects a stylesheet link once and awaits readiness", async () => {
+    const inter = getFontById("inter") as FontCatalogEntry;
+    await loadFont(inter);
+
+    const link = document.querySelector<HTMLLinkElement>(`link[data-omnigent-font="inter"]`);
+    expect(link).not.toBeNull();
+    expect(link?.rel).toBe("stylesheet");
+    expect(link?.href).toBe(inter.cssUrl);
+    // Readiness awaited via document.fonts.load('16px "<family>"').
+    expect(loadCalls).toContain(`16px "Inter"`);
+  });
+
+  it("never injects the same stylesheet twice", async () => {
+    const inter = getFontById("inter") as FontCatalogEntry;
+    await loadFont(inter);
+    await loadFont(inter);
+    expect(styleNodes("inter")).toBe(1);
+  });
+
+  it("shares one in-flight promise for concurrent loads", async () => {
+    const roboto = getFontById("roboto") as FontCatalogEntry;
+    const a = loadFont(roboto);
+    const b = loadFont(roboto);
+    expect(a).toBe(b);
+    await Promise.all([a, b]);
+    expect(styleNodes("roboto")).toBe(1);
+    // A single readiness await, not one per call.
+    expect(loadCalls.filter((s) => s === `16px "Roboto"`).length).toBe(1);
+  });
+});
+
+describe("webFontLoader — self-hosted", () => {
+  it("injects @font-face rules once for a Nerd Font", async () => {
+    const nerd = getFontById("jetbrainsmono-nerd-font-mono") as FontCatalogEntry;
+    await loadFont(nerd);
+
+    const style = document.querySelector<HTMLStyleElement>(
+      `style[data-omnigent-font="jetbrainsmono-nerd-font-mono"]`,
+    );
+    expect(style).not.toBeNull();
+    expect(style?.textContent).toContain("@font-face");
+    expect(style?.textContent).toContain(`font-family: 'JetBrainsMono Nerd Font Mono'`);
+    expect(style?.textContent).toContain(nerd.faces?.[0].url ?? "MISSING");
+    expect(loadCalls).toContain(`16px "JetBrainsMono Nerd Font Mono"`);
+  });
+
+  it("injects multiple faces for a multi-weight self-hosted font", async () => {
+    const cascadia = getFontById("cascadia-code") as FontCatalogEntry;
+    await loadFont(cascadia);
+    const style = document.querySelector(`style[data-omnigent-font="cascadia-code"]`);
+    const faceCount = style?.textContent?.match(/@font-face/g)?.length ?? 0;
+    expect(faceCount).toBe(cascadia.faces?.length);
+  });
+});
+
+describe("webFontLoader — no-ops", () => {
+  it("does not fetch a bundled font", async () => {
+    const geist = getFontById("geist-mono") as FontCatalogEntry;
+    await loadFont(geist);
+    expect(styleNodes("geist-mono")).toBe(0);
+    expect(loadCalls.length).toBe(0);
+  });
+
+  it("does not fetch the empty system-default family", async () => {
+    const system = getFontById("system-ui") as FontCatalogEntry;
+    await loadFont(system);
+    expect(loadCalls.length).toBe(0);
+  });
+});
+
+describe("webFontLoader — loadFontByFamily bridge", () => {
+  it("loads a catalog family typed as a bare name", async () => {
+    const { entry, ready } = loadFontByFamily("Fira Code");
+    expect(entry?.id).toBe("fira-code");
+    await ready;
+    expect(styleNodes("fira-code")).toBe(1);
+    expect(loadCalls).toContain(`16px "Fira Code"`);
+  });
+
+  it("resolves without loading for a non-catalog family", async () => {
+    const { entry, ready } = loadFontByFamily("Comic Sans MS");
+    expect(entry).toBeUndefined();
+    await ready;
+    expect(loadCalls.length).toBe(0);
+  });
+
+  it("resolves without loading for an empty family", async () => {
+    const { entry, ready } = loadFontByFamily("");
+    expect(entry).toBeUndefined();
+    await ready;
+    expect(loadCalls.length).toBe(0);
+  });
+});
diff --git a/web/src/lib/webFontLoader.ts b/web/src/lib/webFontLoader.ts
new file mode 100644
index 0000000000..dd6c7c487c
--- /dev/null
+++ b/web/src/lib/webFontLoader.ts
@@ -0,0 +1,126 @@
+// On-demand web font loader.
+//
+// Given a catalog entry (see lib/fontCatalog.ts), inject the stylesheet or
+// `@font-face` rules that fetch its face data, then await readiness so callers
+// know when glyphs are actually available (the moment to re-measure Monaco /
+// refit xterm). Deduplicated on every axis:
+//   - `bundled` fonts and empty families no-op (nothing to fetch).
+//   - each stylesheet/asset is injected AT MOST ONCE, keyed by entry id.
+//   - concurrent loads of the same font share one in-flight promise.
+//
+// SSR/no-DOM safe: with no `document`, load() resolves immediately (there's
+// nothing to paint), so boot-time restore on the server is a harmless no-op.
+
+import { type FontCatalogEntry, getFontByFamily } from "./fontCatalog";
+
+// Marker so injected nodes are recognizable in the DOM (and idempotent across
+// a hot reload that re-runs this module with a fresh Map).
+const DATA_ATTR = "data-omnigent-font";
+
+// entry.id → the load promise. Present = injection started; resolved = the
+// font's `document.fonts.load()` settled (or timed out / errored — see below).
+const loads = new Map<string, Promise<void>>();
+
+/**
+ * Await the browser actually having `family` ready to paint.
+ *
+ * `document.fonts.load('16px "Family"')` kicks the fetch for any matching
+ * unloaded `@font-face` and resolves when they finish. A short timeout guards a
+ * face that never resolves (offline, blocked CDN) so a caller awaiting readiness
+ * isn't wedged — the CSS fallback stack renders meanwhile, and the glyphs swap
+ * in if the fetch lands later (`font-display: swap`).
+ */
+async function awaitFontReady(family: string): Promise<void> {
+  const fonts = document.fonts;
+  if (!fonts?.load) return;
+  const spec = `16px "${family}"`;
+  const timeout = new Promise<void>((resolve) => window.setTimeout(resolve, 8000));
+  try {
+    await Promise.race([fonts.load(spec).then(() => undefined), timeout]);
+  } catch {
+    // A rejected load (e.g. malformed descriptor) must not reject the caller;
+    // the fallback stack still renders.
+  }
+}
+
+/** Inject a `<link rel="stylesheet">` for a Google CSS2 (or any CSS) href. */
+function injectStylesheet(entry: FontCatalogEntry): void {
+  if (!entry.cssUrl) return;
+  // Guard against a duplicate node if this module's Map was reset (hot reload).
+  if (document.querySelector(`link[${DATA_ATTR}="${entry.id}"]`)) return;
+  const link = document.createElement("link");
+  link.rel = "stylesheet";
+  link.href = entry.cssUrl;
+  link.setAttribute(DATA_ATTR, entry.id);
+  document.head.appendChild(link);
+}
+
+/** Inject a `<style>` holding the entry's explicit `@font-face` rules. */
+function injectFontFaces(entry: FontCatalogEntry): void {
+  if (!entry.faces?.length) return;
+  if (document.querySelector(`style[${DATA_ATTR}="${entry.id}"]`)) return;
+  const css = entry.faces
+    .map((face) => {
+      const src = face.format ? `url(${face.url}) format('${face.format}')` : `url(${face.url})`;
+      return [
+        "@font-face {",
+        `  font-family: '${entry.family}';`,
+        `  font-style: ${face.style ?? "normal"};`,
+        `  font-weight: ${face.weight ?? "400"};`,
+        "  font-display: swap;",
+        `  src: ${src};`,
+        "}",
+      ].join("\n");
+    })
+    .join("\n");
+  const style = document.createElement("style");
+  style.setAttribute(DATA_ATTR, entry.id);
+  style.textContent = css;
+  document.head.appendChild(style);
+}
+
+/**
+ * Load the font for a catalog entry, returning a promise that resolves when its
+ * glyphs are ready to paint. Deduplicated: repeat calls for the same entry share
+ * one promise and inject the stylesheet/faces at most once. A `bundled` entry
+ * (already in the app bundle) or an empty family resolves immediately.
+ */
+export function loadFont(entry: FontCatalogEntry): Promise<void> {
+  if (typeof document === "undefined") return Promise.resolve();
+  // Nothing to fetch: bundled faces are in the app CSS; an empty family is the
+  // system default. Either way the browser already has it.
+  if (entry.source === "bundled" || !entry.family) return Promise.resolve();
+
+  const existing = loads.get(entry.id);
+  if (existing) return existing;
+
+  const promise = (async () => {
+    if (entry.source === "google-css2") injectStylesheet(entry);
+    else if (entry.source === "self-hosted") injectFontFaces(entry);
+    await awaitFontReady(entry.family);
+  })();
+  loads.set(entry.id, promise);
+  return promise;
+}
+
+/**
+ * Load the font matching a typed/stored family NAME, if it's in the catalog.
+ *
+ * The bridge from the free-text font inputs: a name matching a catalog family
+ * is loaded and its promise returned; a non-catalog name (a locally-installed
+ * font, a partial name) resolves immediately and is left to the OS — the
+ * existing free-text behavior, unchanged. Returns whether an entry matched so
+ * callers can skip post-load work (Monaco re-measure) when nothing loaded.
+ */
+export function loadFontByFamily(family: string): {
+  entry: FontCatalogEntry | undefined;
+  ready: Promise<void>;
+} {
+  const entry = getFontByFamily(family);
+  return { entry, ready: entry ? loadFont(entry) : Promise.resolve() };
+}
+
+/** Test-only: clear the in-flight/loaded dedup cache. */
+export function resetFontLoaderForTests(): void {
+  loads.clear();
+}
diff --git a/web/src/main.tsx b/web/src/main.tsx
index 79e2c8a2d3..cbbc291577 100644
--- a/web/src/main.tsx
+++ b/web/src/main.tsx
@@ -21,6 +21,7 @@ import {
   readUiFontFamily,
   readUiFontSizePx,
 } from "./lib/uiFontPreferences";
+import { loadCodeFontFamily, readCodeFontFamily } from "./lib/codeFontPreferences";
 import { applyThemePalette, readThemePalette } from "./lib/themePalette";
 import { applyCustomTheme, readCustomTheme } from "./lib/customTheme";
 import { initChatStore } from "./store/chatStore";
@@ -58,9 +59,17 @@ void resolveIdentity();
 initNativeInsets();
 
 // Apply the saved UI font size and family before first paint so there's no flash.
+// applyUiFontFamily also kicks off the webfont load when the saved family is a
+// catalog font, so a chosen font is fetched on boot rather than only on the next
+// Settings change.
 applyUiFontScale(readUiFontSizePx());
 applyUiFontFamily(readUiFontFamily());
 
+// Restore the saved code font's webfont on boot too: the code font rides a
+// pub/sub (not a CSS var), so nothing loads it unless we ask. Editors/terminals
+// re-measure when it lands (see codeFontPreferences.loadCodeFontFamily).
+loadCodeFontFamily(readCodeFontFamily());
+
 // Apply the saved color palette (data-theme on <html>) before first paint too,
 // so the app renders in the chosen theme rather than flashing the brand default.
 applyCustomTheme(readCustomTheme());
diff --git a/web/src/shell/MonacoCodeEditor.tsx b/web/src/shell/MonacoCodeEditor.tsx
index 2c2911b35a..91a133e6d5 100644
--- a/web/src/shell/MonacoCodeEditor.tsx
+++ b/web/src/shell/MonacoCodeEditor.tsx
@@ -37,10 +37,10 @@ import { useEditorAutoSave } from "./useEditorAutoSave";
 import {
   ensureLanguage,
   ensureMonacoReady,
+  monaco,
   monacoLanguageId,
   resolvedThemeToMonaco,
 } from "./monacoSetup";
-import type { monaco } from "./monacoSetup";
 import { useMonacoCommentLayer, type CodeEditorInstance } from "./useMonacoCommentLayer";
 import "./monacoCodeEditor.css";
 
@@ -288,7 +288,7 @@ function MonacoCodeEditorInner({
   flushRef.current = autoSave.flush;
 
   const handleMount: OnMount = useCallback(
-    (editor, monaco) => {
+    (editor, monacoApi) => {
       editorInstanceRef.current = editor;
       baselineRef.current = editor.getValue();
       latestContentRef.current = editor.getValue();
@@ -299,14 +299,14 @@ function MonacoCodeEditorInner({
         .getModel()
         ?.setEOL(
           content.includes("\r\n")
-            ? monaco.editor.EndOfLineSequence.CRLF
-            : monaco.editor.EndOfLineSequence.LF,
+            ? monacoApi.editor.EndOfLineSequence.CRLF
+            : monacoApi.editor.EndOfLineSequence.LF,
         );
       // Route ⌘S through the same single-flight + trailing-save engine as
       // auto-save, so a manual save during an in-flight/debounced auto-save can't
       // start an overlapping PUT.
       // oxlint-disable-next-line eslint(no-bitwise) -- Monaco keybindings are bit-OR'd flags.
-      editor.addCommand(monaco.KeyMod.CtrlCmd | monaco.KeyCode.KeyS, () => {
+      editor.addCommand(monacoApi.KeyMod.CtrlCmd | monacoApi.KeyCode.KeyS, () => {
         flushRef.current();
       });
       // Flush a pending debounce when focus leaves the editor (snappier than
@@ -463,6 +463,11 @@ function MonacoCodeEditorInner({
         fontSize: font.sizePx,
         fontFamily: codeFontFamilyForEditor(font.family),
       });
+      // A newly-loaded webfont changes the glyph cell metrics after the family
+      // was set. Monaco caches font measurements, so tell it to re-measure or
+      // the editor keeps laying out against the fallback's cell size until the
+      // next reflow. Cheap and safe when nothing changed.
+      monaco.editor.remeasureFonts();
     });
   }, []);
 

From 71943ef20ecaff23f91a7d286613e2d44f2285c0 Mon Sep 17 00:00:00 2001
From: Bryan Li <15131870+btli@users.noreply.github.com>
Date: Mon, 20 Jul 2026 10:46:21 -0700
Subject: [PATCH 2/6] fix(web): close webfont loader race, dedup, and
 category-lookup gaps
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address cross-vendor review of the font loader/catalog:

1. Google readiness raced the stylesheet load: document.fonts.load() ran
   before the injected <link>'s @font-face rules were registered, so it
   could resolve empty and fire a premature remeasure. injectStylesheet
   now awaits the link's `load` event (rejects on `error`, removing the
   dead node) BEFORE querying document.fonts; an empty/failed FontFaceSet
   result is treated as not-ready (false), not success.

2. The 8s timeout reported success and left a dangling timer. Removed it:
   readiness is now signalled ONLY by genuine document.fonts.load
   settlement (itself bounded by spec), and neither consumer blocks on it
   (UI fires-and-forgets via font-display: swap; the code font chains a
   .then that re-emits only on a true result). So a slow font remeasures
   exactly when it truly arrives and a fast one leaves no timer.

3. Dedup was keyed by catalog id, so the two IBM Plex Mono entries (same
   URL, different ids) injected twice and returned different promises.
   Added fontLoadKey(entry) — the canonical resource URL / @font-face src
   — and keyed both the in-flight map and the DOM guard by it. A failed
   load evicts its cache entry so a later attempt retries.

4. getFontByFamily always returned the fixedWidth IBM Plex Mono entry.
   Added getFontsByFamily (all matches) and an optional category arg to
   getFontByFamily so a per-role lookup resolves the right entry; the
   code-font path now passes "code". Single-arg behavior is unchanged.

Tests: readiness ordering (no fonts query until <link> load; empty/errored
= not ready), cross-id IBM Plex Mono dedup (one injection, shared promise),
retry-after-failure, fontLoadKey resource identity, and category-aware
family resolution.

Co-authored-by: omnigent <noreply@omnigent.ai>
Signed-off-by: Bryan Li <bryan.li@gmail.com>
---
 web/src/lib/codeFontPreferences.ts |   8 +-
 web/src/lib/fontCatalog.test.ts    |  63 +++++++-
 web/src/lib/fontCatalog.ts         |  71 +++++++--
 web/src/lib/webFontLoader.test.ts  | 238 +++++++++++++++++++++--------
 web/src/lib/webFontLoader.ts       | 193 ++++++++++++++++-------
 5 files changed, 429 insertions(+), 144 deletions(-)

diff --git a/web/src/lib/codeFontPreferences.ts b/web/src/lib/codeFontPreferences.ts
index e809f02db2..154d83b7b0 100644
--- a/web/src/lib/codeFontPreferences.ts
+++ b/web/src/lib/codeFontPreferences.ts
@@ -163,9 +163,13 @@ export function writeCodeFontFamily(name: string): void {
  */
 export function loadCodeFontFamily(family: string): void {
   const normalized = normalizeCodeFontFamily(family);
-  const { entry, ready } = loadFontByFamily(normalized);
+  const { entry, ready } = loadFontByFamily(normalized, "code");
   if (!entry) return;
-  void ready.then(() => {
+  void ready.then((loaded) => {
+    // Only re-emit once the glyphs genuinely arrived — a failed/blocked load
+    // resolves `false`, and re-measuring then would just churn against the
+    // fallback cell.
+    if (!loaded) return;
     // Re-read live prefs at resolution time: if the user changed the family
     // again while this was loading, don't clobber the newer choice.
     emit(readCodeFont());
diff --git a/web/src/lib/fontCatalog.test.ts b/web/src/lib/fontCatalog.test.ts
index e5677b304b..84927fc3c9 100644
--- a/web/src/lib/fontCatalog.test.ts
+++ b/web/src/lib/fontCatalog.test.ts
@@ -3,8 +3,10 @@ import {
   FONT_CATALOG,
   FONT_CATALOG_BY_CATEGORY,
   type FontCategory,
+  fontLoadKey,
   getFontByFamily,
   getFontById,
+  getFontsByFamily,
 } from "./fontCatalog";
 
 const CATEGORIES: FontCategory[] = ["sans", "fixedWidth", "code"];
@@ -102,11 +104,66 @@ describe("fontCatalog — lookups", () => {
     expect(getFontByFamily("Comic Sans MS")).toBeUndefined();
   });
 
-  it("resolves a family shared across categories to a single entry", () => {
-    // IBM Plex Mono is offered in both fixedWidth and code; family lookup must
-    // still resolve deterministically (first catalog occurrence wins).
+  it("resolves a family shared across categories deterministically", () => {
+    // IBM Plex Mono is offered in both fixedWidth and code; the single-arg
+    // lookup resolves to the FIRST catalog occurrence (backward-compatible).
     const entry = getFontByFamily("IBM Plex Mono");
     expect(entry).toBeDefined();
     expect(entry?.family).toBe("IBM Plex Mono");
+    expect(entry?.category).toBe("fixedWidth");
+  });
+
+  it("returns every entry for a shared family via getFontsByFamily", () => {
+    const matches = getFontsByFamily("IBM Plex Mono");
+    expect(matches.length).toBe(2);
+    expect(new Set(matches.map((e) => e.category))).toEqual(new Set(["fixedWidth", "code"]));
+    // Distinct ids, so PR 2 can address each independently.
+    expect(new Set(matches.map((e) => e.id)).size).toBe(2);
+    expect(getFontsByFamily("Comic Sans MS")).toEqual([]);
+    expect(getFontsByFamily("")).toEqual([]);
+  });
+
+  it("resolves a shared family to the requested category", () => {
+    // The whole point of the category arg: the code control must get the code
+    // entry, the mono control the fixedWidth one — not always the first match.
+    expect(getFontByFamily("IBM Plex Mono", "code")?.category).toBe("code");
+    expect(getFontByFamily("IBM Plex Mono", "code")?.id).toBe("ibm-plex-mono-code");
+    expect(getFontByFamily("IBM Plex Mono", "fixedWidth")?.category).toBe("fixedWidth");
+    expect(getFontByFamily("IBM Plex Mono", "fixedWidth")?.id).toBe("ibm-plex-mono");
+  });
+
+  it("falls back to the first match when the family isn't in the asked category", () => {
+    // Fira Code is code-only; asking for it as sans still resolves (delivery
+    // metadata is identical across a family's entries, so it still loads).
+    const entry = getFontByFamily("Fira Code", "sans");
+    expect(entry?.id).toBe("fira-code");
+  });
+});
+
+describe("fontCatalog — fontLoadKey (resource identity)", () => {
+  it("keys google-css2 entries by their stylesheet URL", () => {
+    const inter = getFontById("inter");
+    expect(fontLoadKey(inter!)).toBe(inter!.cssUrl);
+  });
+
+  it("gives the two IBM Plex Mono entries the SAME load key", () => {
+    // Different ids, identical Google CSS2 URL → identical resource → one key,
+    // so the loader dedupes them (see webFontLoader dedup test).
+    const fixed = getFontById("ibm-plex-mono")!;
+    const code = getFontById("ibm-plex-mono-code")!;
+    expect(fixed.id).not.toBe(code.id);
+    expect(fontLoadKey(fixed)).toBe(fontLoadKey(code));
+  });
+
+  it("keys self-hosted entries by their face URLs", () => {
+    const nerd = getFontById("jetbrainsmono-nerd-font-mono")!;
+    expect(fontLoadKey(nerd)).toContain(nerd.faces![0].url);
+  });
+
+  it("gives distinct resources distinct keys", () => {
+    const keys = FONT_CATALOG.filter((e) => e.source !== "bundled").map(fontLoadKey);
+    // The only intentional collision is the shared IBM Plex Mono URL.
+    const dupes = keys.filter((k, i) => keys.indexOf(k) !== i);
+    expect(new Set(dupes).size).toBe(1);
   });
 });
diff --git a/web/src/lib/fontCatalog.ts b/web/src/lib/fontCatalog.ts
index 3e9f9830ab..0abe836f5c 100644
--- a/web/src/lib/fontCatalog.ts
+++ b/web/src/lib/fontCatalog.ts
@@ -291,26 +291,67 @@ export function getFontById(id: string): FontCatalogEntry | undefined {
   return BY_ID.get(id);
 }
 
-// Lower-cased family → entry. A family (e.g. "IBM Plex Mono") can appear in more
-// than one category; the FIRST catalog occurrence wins, which is enough for the
-// loader — it only needs the delivery metadata, identical across duplicates.
-const BY_FAMILY = new Map<string, FontCatalogEntry>();
+// Lower-cased family → ALL matching entries, in catalog order. A family (e.g.
+// "IBM Plex Mono") can appear in more than one category, so we keep every match
+// rather than the first — a category-aware lookup needs the right one.
+const BY_FAMILY = new Map<string, FontCatalogEntry[]>();
 for (const entry of FONT_CATALOG) {
   const key = entry.family.trim().toLowerCase();
-  if (key && !BY_FAMILY.has(key)) BY_FAMILY.set(key, entry);
+  if (!key) continue;
+  const list = BY_FAMILY.get(key);
+  if (list) list.push(entry);
+  else BY_FAMILY.set(key, [entry]);
 }
 
 /**
- * Resolve a typed/stored family NAME to its catalog entry, case-insensitively.
- *
- * This is the bridge from the existing free-text font inputs (which store a
- * bare family string) to the loader: a typed name that matches a catalog family
- * gets loaded; anything else (a locally-installed font, a partial name) resolves
- * to `undefined` and the loader leaves it to the OS, unchanged. An empty name
- * (System default) is never a catalog family, so it also returns `undefined`.
+ * All catalog entries offered under a family NAME, case-insensitively (empty
+ * for a non-catalog family or the empty/System-default name). A shared family
+ * like "IBM Plex Mono" returns one entry per category it appears in.
  */
-export function getFontByFamily(family: string): FontCatalogEntry | undefined {
+export function getFontsByFamily(family: string): readonly FontCatalogEntry[] {
   const key = family.trim().toLowerCase();
-  if (!key) return undefined;
-  return BY_FAMILY.get(key);
+  if (!key) return [];
+  return BY_FAMILY.get(key) ?? [];
+}
+
+/**
+ * Resolve a typed/stored family NAME to a catalog entry, case-insensitively.
+ *
+ * The bridge from the free-text font inputs (which store a bare family string)
+ * to the loader: a typed name matching a catalog family resolves to an entry to
+ * load; anything else (a locally-installed font, a partial name, the empty
+ * System-default name) resolves to `undefined` and is left to the OS.
+ *
+ * When `category` is given (e.g. PR 2's per-role dropdowns), the entry from that
+ * category wins — so a shared family like "IBM Plex Mono" resolves to its `code`
+ * entry for the code control and its `fixedWidth` entry for the mono control. If
+ * the family isn't offered in that category, the first match is returned anyway:
+ * the delivery metadata is identical across a family's entries, so the font
+ * still loads. With no `category`, the first catalog occurrence wins
+ * (backward-compatible).
+ */
+export function getFontByFamily(
+  family: string,
+  category?: FontCategory,
+): FontCatalogEntry | undefined {
+  const matches = getFontsByFamily(family);
+  if (matches.length === 0) return undefined;
+  if (category) return matches.find((e) => e.category === category) ?? matches[0];
+  return matches[0];
+}
+
+/**
+ * The canonical load key for an entry: its underlying resource identity, NOT its
+ * catalog id. Two entries with different ids but the same delivery resource (e.g.
+ * the `fixedWidth` and `code` IBM Plex Mono entries share one Google CSS2 URL)
+ * produce the same key, so the loader injects the stylesheet/faces once and
+ * shares a single in-flight load across them.
+ */
+export function fontLoadKey(entry: FontCatalogEntry): string {
+  if (entry.source === "google-css2") return entry.cssUrl ?? `id:${entry.id}`;
+  if (entry.source === "self-hosted") {
+    const urls = (entry.faces ?? []).map((f) => f.url).join("|");
+    return urls || `id:${entry.id}`;
+  }
+  return `bundled:${entry.id}`;
 }
diff --git a/web/src/lib/webFontLoader.test.ts b/web/src/lib/webFontLoader.test.ts
index bce19fcada..90cb5f4616 100644
--- a/web/src/lib/webFontLoader.test.ts
+++ b/web/src/lib/webFontLoader.test.ts
@@ -1,19 +1,33 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { type FontCatalogEntry, getFontById } from "./fontCatalog";
-import { resetFontLoaderForTests, loadFont, loadFontByFamily } from "./webFontLoader";
+import { loadFont, loadFontByFamily, resetFontLoaderForTests } from "./webFontLoader";
+
+// A resolvable promise handle for driving readiness/link ordering in tests.
+function deferred<T>() {
+  let resolve!: (v: T) => void;
+  let reject!: (e: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
 
-// jsdom has no FontFaceSet; stub document.fonts.load so readiness resolves and
-// we can count how often a given family was requested.
-let loadCalls: string[] = [];
+// Records each `document.fonts.load(spec)` call and hands back a deferred whose
+// resolution the test controls, so readiness ordering is observable rather than
+// resolving instantly.
+type FontsLoadCall = { spec: string; deferred: ReturnType<typeof deferred<unknown[]>> };
+let fontsLoadCalls: FontsLoadCall[] = [];
 
 beforeEach(() => {
-  loadCalls = [];
+  fontsLoadCalls = [];
   Object.defineProperty(document, "fonts", {
     configurable: true,
     value: {
       load: vi.fn((spec: string) => {
-        loadCalls.push(spec);
-        return Promise.resolve([]);
+        const d = deferred<unknown[]>();
+        fontsLoadCalls.push({ spec, deferred: d });
+        return d.promise;
       }),
     },
   });
@@ -25,78 +39,160 @@ afterEach(() => {
   vi.restoreAllMocks();
 });
 
-function styleNodes(id: string): number {
-  return document.querySelectorAll(`[data-omnigent-font="${id}"]`).length;
+/** Injected stylesheet <link> nodes (jsdom won't fire their load event itself). */
+function links(): HTMLLinkElement[] {
+  return [...document.querySelectorAll<HTMLLinkElement>(`link[data-omnigent-font]`)];
+}
+/** Injected @font-face <style> nodes. */
+function styles(): HTMLStyleElement[] {
+  return [...document.querySelectorAll<HTMLStyleElement>(`style[data-omnigent-font]`)];
+}
+/** Fire the `load` event on every injected link, as a browser would on parse. */
+function fireLinkLoads(): void {
+  for (const link of links()) link.dispatchEvent(new Event("load"));
 }
+/** Let queued microtasks/promise callbacks run. */
+const flush = () => new Promise<void>((r) => setTimeout(r, 0));
+
+const inter = () => getFontById("inter") as FontCatalogEntry;
+const roboto = () => getFontById("roboto") as FontCatalogEntry;
+const nerd = () => getFontById("jetbrainsmono-nerd-font-mono") as FontCatalogEntry;
+const cascadia = () => getFontById("cascadia-code") as FontCatalogEntry;
+
+describe("webFontLoader — google-css2 readiness ordering", () => {
+  it("does NOT query document.fonts until the stylesheet <link> has loaded", async () => {
+    const p = loadFont(inter());
+    await flush();
+    // Link is injected, but its `load` event hasn't fired — readiness must not
+    // have been queried yet (that's the race the fix closes).
+    expect(links().length).toBe(1);
+    expect(fontsLoadCalls.length).toBe(0);
+
+    // Now the stylesheet parses.
+    fireLinkLoads();
+    await flush();
+    expect(fontsLoadCalls.length).toBe(1);
+    expect(fontsLoadCalls[0].spec).toBe(`16px "Inter"`);
+
+    // Still pending until the FontFaceSet genuinely settles non-empty.
+    let settled = false;
+    void p.then(() => {
+      settled = true;
+    });
+    await flush();
+    expect(settled).toBe(false);
+
+    fontsLoadCalls[0].deferred.resolve([{}]); // one matched FontFace
+    await expect(p).resolves.toBe(true);
+  });
 
-describe("webFontLoader — google-css2", () => {
-  it("injects a stylesheet link once and awaits readiness", async () => {
-    const inter = getFontById("inter") as FontCatalogEntry;
-    await loadFont(inter);
+  it("resolves false when the FontFaceSet matches nothing (rules not registered)", async () => {
+    const p = loadFont(roboto());
+    await flush();
+    fireLinkLoads();
+    await flush();
+    // Empty array = not ready → false, so no premature remeasure fires.
+    fontsLoadCalls[0].deferred.resolve([]);
+    await expect(p).resolves.toBe(false);
+  });
 
-    const link = document.querySelector<HTMLLinkElement>(`link[data-omnigent-font="inter"]`);
-    expect(link).not.toBeNull();
-    expect(link?.rel).toBe("stylesheet");
-    expect(link?.href).toBe(inter.cssUrl);
-    // Readiness awaited via document.fonts.load('16px "<family>"').
-    expect(loadCalls).toContain(`16px "Inter"`);
+  it("resolves false and does NOT query fonts when the <link> errors", async () => {
+    const p = loadFont(inter());
+    await flush();
+    links()[0].dispatchEvent(new Event("error"));
+    await expect(p).resolves.toBe(false);
+    expect(fontsLoadCalls.length).toBe(0);
   });
 
   it("never injects the same stylesheet twice", async () => {
-    const inter = getFontById("inter") as FontCatalogEntry;
-    await loadFont(inter);
-    await loadFont(inter);
-    expect(styleNodes("inter")).toBe(1);
-  });
-
-  it("shares one in-flight promise for concurrent loads", async () => {
-    const roboto = getFontById("roboto") as FontCatalogEntry;
-    const a = loadFont(roboto);
-    const b = loadFont(roboto);
-    expect(a).toBe(b);
-    await Promise.all([a, b]);
-    expect(styleNodes("roboto")).toBe(1);
-    // A single readiness await, not one per call.
-    expect(loadCalls.filter((s) => s === `16px "Roboto"`).length).toBe(1);
+    const p1 = loadFont(inter());
+    const p2 = loadFont(inter());
+    expect(p1).toBe(p2); // shared in-flight promise
+    await flush();
+    fireLinkLoads();
+    await flush();
+    fontsLoadCalls.forEach((c) => c.deferred.resolve([{}]));
+    await Promise.all([p1, p2]);
+    expect(links().length).toBe(1);
+    expect(fontsLoadCalls.length).toBe(1);
+  });
+});
+
+describe("webFontLoader — dedup by resource identity, not id", () => {
+  it("dedupes two DIFFERENT ids that share one stylesheet URL", async () => {
+    // The two IBM Plex Mono entries have distinct ids but identical Google CSS2
+    // URLs — they must inject once and share one in-flight promise.
+    const fixed = getFontById("ibm-plex-mono") as FontCatalogEntry;
+    const code = getFontById("ibm-plex-mono-code") as FontCatalogEntry;
+    expect(fixed.id).not.toBe(code.id);
+
+    const pa = loadFont(fixed);
+    const pb = loadFont(code);
+    expect(pa).toBe(pb);
+    await flush();
+    expect(links().length).toBe(1);
+
+    fireLinkLoads();
+    await flush();
+    expect(fontsLoadCalls.length).toBe(1);
+    fontsLoadCalls[0].deferred.resolve([{}]);
+    await expect(pa).resolves.toBe(true);
+    await expect(pb).resolves.toBe(true);
+  });
+
+  it("retries after a failed load rather than caching the failure", async () => {
+    const p1 = loadFont(inter());
+    await flush();
+    links()[0].dispatchEvent(new Event("error"));
+    await expect(p1).resolves.toBe(false);
+    await flush();
+
+    // A fresh call must re-inject (previous promise resolved false → evicted).
+    const p2 = loadFont(inter());
+    expect(p2).not.toBe(p1);
+    await flush();
+    expect(links().length).toBe(1);
+    fireLinkLoads();
+    await flush();
+    fontsLoadCalls.at(-1)!.deferred.resolve([{}]);
+    await expect(p2).resolves.toBe(true);
   });
 });
 
 describe("webFontLoader — self-hosted", () => {
-  it("injects @font-face rules once for a Nerd Font", async () => {
-    const nerd = getFontById("jetbrainsmono-nerd-font-mono") as FontCatalogEntry;
-    await loadFont(nerd);
-
-    const style = document.querySelector<HTMLStyleElement>(
-      `style[data-omnigent-font="jetbrainsmono-nerd-font-mono"]`,
-    );
-    expect(style).not.toBeNull();
+  it("injects @font-face rules once for a Nerd Font and awaits readiness", async () => {
+    const p = loadFont(nerd());
+    await flush();
+    const style = styles()[0];
     expect(style?.textContent).toContain("@font-face");
     expect(style?.textContent).toContain(`font-family: 'JetBrainsMono Nerd Font Mono'`);
-    expect(style?.textContent).toContain(nerd.faces?.[0].url ?? "MISSING");
-    expect(loadCalls).toContain(`16px "JetBrainsMono Nerd Font Mono"`);
+    expect(style?.textContent).toContain(nerd().faces?.[0].url ?? "MISSING");
+    // Self-hosted has no <link> to await — readiness is queried straight away.
+    expect(fontsLoadCalls[0].spec).toBe(`16px "JetBrainsMono Nerd Font Mono"`);
+    fontsLoadCalls[0].deferred.resolve([{}]);
+    await expect(p).resolves.toBe(true);
   });
 
-  it("injects multiple faces for a multi-weight self-hosted font", async () => {
-    const cascadia = getFontById("cascadia-code") as FontCatalogEntry;
-    await loadFont(cascadia);
-    const style = document.querySelector(`style[data-omnigent-font="cascadia-code"]`);
-    const faceCount = style?.textContent?.match(/@font-face/g)?.length ?? 0;
-    expect(faceCount).toBe(cascadia.faces?.length);
+  it("injects one @font-face per declared face", async () => {
+    const p = loadFont(cascadia());
+    await flush();
+    const faceCount = styles()[0]?.textContent?.match(/@font-face/g)?.length ?? 0;
+    expect(faceCount).toBe(cascadia().faces?.length);
+    fontsLoadCalls[0].deferred.resolve([{}]);
+    await p;
   });
 });
 
 describe("webFontLoader — no-ops", () => {
-  it("does not fetch a bundled font", async () => {
-    const geist = getFontById("geist-mono") as FontCatalogEntry;
-    await loadFont(geist);
-    expect(styleNodes("geist-mono")).toBe(0);
-    expect(loadCalls.length).toBe(0);
+  it("does not fetch a bundled font (resolves ready)", async () => {
+    await expect(loadFont(getFontById("geist-mono") as FontCatalogEntry)).resolves.toBe(true);
+    expect(links().length + styles().length).toBe(0);
+    expect(fontsLoadCalls.length).toBe(0);
   });
 
   it("does not fetch the empty system-default family", async () => {
-    const system = getFontById("system-ui") as FontCatalogEntry;
-    await loadFont(system);
-    expect(loadCalls.length).toBe(0);
+    await expect(loadFont(getFontById("system-ui") as FontCatalogEntry)).resolves.toBe(true);
+    expect(fontsLoadCalls.length).toBe(0);
   });
 });
 
@@ -104,22 +200,30 @@ describe("webFontLoader — loadFontByFamily bridge", () => {
   it("loads a catalog family typed as a bare name", async () => {
     const { entry, ready } = loadFontByFamily("Fira Code");
     expect(entry?.id).toBe("fira-code");
-    await ready;
-    expect(styleNodes("fira-code")).toBe(1);
-    expect(loadCalls).toContain(`16px "Fira Code"`);
+    await flush();
+    fireLinkLoads();
+    await flush();
+    fontsLoadCalls.at(-1)!.deferred.resolve([{}]);
+    await expect(ready).resolves.toBe(true);
+  });
+
+  it("routes a shared family to the requested category", async () => {
+    const { entry } = loadFontByFamily("IBM Plex Mono", "code");
+    expect(entry?.id).toBe("ibm-plex-mono-code");
+    expect(entry?.category).toBe("code");
   });
 
-  it("resolves without loading for a non-catalog family", async () => {
+  it("resolves false without loading for a non-catalog family", async () => {
     const { entry, ready } = loadFontByFamily("Comic Sans MS");
     expect(entry).toBeUndefined();
-    await ready;
-    expect(loadCalls.length).toBe(0);
+    await expect(ready).resolves.toBe(false);
+    expect(fontsLoadCalls.length).toBe(0);
   });
 
-  it("resolves without loading for an empty family", async () => {
+  it("resolves false without loading for an empty family", async () => {
     const { entry, ready } = loadFontByFamily("");
     expect(entry).toBeUndefined();
-    await ready;
-    expect(loadCalls.length).toBe(0);
+    await expect(ready).resolves.toBe(false);
+    expect(fontsLoadCalls.length).toBe(0);
   });
 });
diff --git a/web/src/lib/webFontLoader.ts b/web/src/lib/webFontLoader.ts
index dd6c7c487c..77f0276e16 100644
--- a/web/src/lib/webFontLoader.ts
+++ b/web/src/lib/webFontLoader.ts
@@ -5,60 +5,84 @@
 // know when glyphs are actually available (the moment to re-measure Monaco /
 // refit xterm). Deduplicated on every axis:
 //   - `bundled` fonts and empty families no-op (nothing to fetch).
-//   - each stylesheet/asset is injected AT MOST ONCE, keyed by entry id.
-//   - concurrent loads of the same font share one in-flight promise.
+//   - each stylesheet/asset is injected AT MOST ONCE, keyed by its resource URL
+//     (NOT the catalog id) so two entries sharing one resource dedupe.
+//   - concurrent loads of the same resource share one in-flight promise.
+//
+// Readiness is signalled ONLY by genuine `document.fonts.load` settlement — no
+// timer resolves it. `document.fonts.load` is itself bounded (it settles when
+// the browser's font fetch finishes or fails, per spec — it doesn't hang), and
+// our two consumers never block on it: the UI font path fires-and-forgets (CSS
+// `font-display: swap` paints the swap), and the code font path chains `.then`
+// to re-emit only on a `true` result. So a wall-clock timeout would either fire
+// a premature remeasure against the fallback cell (if reported as ready) or
+// suppress the real late notification — the exact bugs it was meant to avoid.
+// We deliberately omit it.
 //
 // SSR/no-DOM safe: with no `document`, load() resolves immediately (there's
 // nothing to paint), so boot-time restore on the server is a harmless no-op.
 
-import { type FontCatalogEntry, getFontByFamily } from "./fontCatalog";
+import { type FontCatalogEntry, fontLoadKey, getFontByFamily } from "./fontCatalog";
 
-// Marker so injected nodes are recognizable in the DOM (and idempotent across
-// a hot reload that re-runs this module with a fresh Map).
+// Marker + load-key attribute on injected nodes: recognizable in the DOM and
+// idempotent across a hot reload that re-runs this module with a fresh Map. The
+// key is the resource URL (see fontLoadKey), so a shared resource maps to one
+// node regardless of which catalog entry triggered it.
 const DATA_ATTR = "data-omnigent-font";
 
-// entry.id → the load promise. Present = injection started; resolved = the
-// font's `document.fonts.load()` settled (or timed out / errored — see below).
-const loads = new Map<string, Promise<void>>();
+// load key → the load promise. Present = injection started; resolved(true) =
+// the font's glyphs are genuinely ready; resolved(false) = the load failed (bad
+// CDN, blocked). Keyed by resource identity so identical resources share one
+// load. The promise resolves ONLY on genuine `document.fonts.load` settlement —
+// never on a timer — so a consumer's remeasure/refit fires exactly when (and
+// only if) the glyphs actually arrive, however late, and never against the
+// fallback cell.
+const loads = new Map<string, Promise<boolean>>();
 
 /**
- * Await the browser actually having `family` ready to paint.
- *
- * `document.fonts.load('16px "Family"')` kicks the fetch for any matching
- * unloaded `@font-face` and resolves when they finish. A short timeout guards a
- * face that never resolves (offline, blocked CDN) so a caller awaiting readiness
- * isn't wedged — the CSS fallback stack renders meanwhile, and the glyphs swap
- * in if the fetch lands later (`font-display: swap`).
+ * Escape a value for use inside a quoted attribute selector (`[a="<here>"]`).
+ * Only `"` and `\` are special there — NOT `:`/`?`/`&` etc., so we must NOT use
+ * `CSS.escape` (which escapes identifier chars and would break the match).
  */
-async function awaitFontReady(family: string): Promise<void> {
-  const fonts = document.fonts;
-  if (!fonts?.load) return;
-  const spec = `16px "${family}"`;
-  const timeout = new Promise<void>((resolve) => window.setTimeout(resolve, 8000));
-  try {
-    await Promise.race([fonts.load(spec).then(() => undefined), timeout]);
-  } catch {
-    // A rejected load (e.g. malformed descriptor) must not reject the caller;
-    // the fallback stack still renders.
-  }
+function escapeAttr(value: string): string {
+  return value.replace(/["\\]/g, "\\$&");
 }
 
-/** Inject a `<link rel="stylesheet">` for a Google CSS2 (or any CSS) href. */
-function injectStylesheet(entry: FontCatalogEntry): void {
-  if (!entry.cssUrl) return;
-  // Guard against a duplicate node if this module's Map was reset (hot reload).
-  if (document.querySelector(`link[${DATA_ATTR}="${entry.id}"]`)) return;
-  const link = document.createElement("link");
-  link.rel = "stylesheet";
-  link.href = entry.cssUrl;
-  link.setAttribute(DATA_ATTR, entry.id);
-  document.head.appendChild(link);
+/**
+ * Inject a `<link rel="stylesheet">` for a Google CSS2 (or any CSS) href and
+ * resolve once the browser has parsed it (`load` event) — so the @font-face
+ * rules are registered before we ask `document.fonts` about them. Rejects on the
+ * link's `error` event. If a node for this key already exists (hot reload / a
+ * sibling entry sharing the URL), resolves immediately.
+ */
+function injectStylesheet(key: string, cssUrl: string): Promise<void> {
+  const selector = `link[${DATA_ATTR}="${escapeAttr(key)}"]`;
+  if (document.querySelector(selector)) return Promise.resolve();
+  return new Promise<void>((resolve, reject) => {
+    const link = document.createElement("link");
+    link.rel = "stylesheet";
+    link.href = cssUrl;
+    link.setAttribute(DATA_ATTR, key);
+    link.addEventListener("load", () => resolve(), { once: true });
+    link.addEventListener(
+      "error",
+      () => {
+        // Remove the failed node so a later retry (the promise is evicted on
+        // failure) genuinely re-injects instead of matching this dead link.
+        link.remove();
+        reject(new Error(`stylesheet failed: ${cssUrl}`));
+      },
+      { once: true },
+    );
+    document.head.appendChild(link);
+  });
 }
 
-/** Inject a `<style>` holding the entry's explicit `@font-face` rules. */
-function injectFontFaces(entry: FontCatalogEntry): void {
+/** Inject a `<style>` holding an entry's explicit `@font-face` rules (once). */
+function injectFontFaces(key: string, entry: FontCatalogEntry): void {
   if (!entry.faces?.length) return;
-  if (document.querySelector(`style[${DATA_ATTR}="${entry.id}"]`)) return;
+  const selector = `style[${DATA_ATTR}="${escapeAttr(key)}"]`;
+  if (document.querySelector(selector)) return;
   const css = entry.faces
     .map((face) => {
       const src = face.format ? `url(${face.url}) format('${face.format}')` : `url(${face.url})`;
@@ -74,32 +98,82 @@ function injectFontFaces(entry: FontCatalogEntry): void {
     })
     .join("\n");
   const style = document.createElement("style");
-  style.setAttribute(DATA_ATTR, entry.id);
+  style.setAttribute(DATA_ATTR, key);
   style.textContent = css;
   document.head.appendChild(style);
 }
 
 /**
- * Load the font for a catalog entry, returning a promise that resolves when its
- * glyphs are ready to paint. Deduplicated: repeat calls for the same entry share
- * one promise and inject the stylesheet/faces at most once. A `bundled` entry
- * (already in the app bundle) or an empty family resolves immediately.
+ * Resolve `true` once the browser genuinely has `family` ready to paint.
+ *
+ * `document.fonts.load('16px "Family"')` kicks the fetch for matching unloaded
+ * `@font-face`s and resolves with the FontFace objects it matched. An EMPTY
+ * match array (or a rejected load) is treated as NOT ready and resolves `false`
+ * — an empty result means the rules weren't registered, so reporting success
+ * would fire a premature remeasure against the fallback cell. Callers only await
+ * this once the stylesheet/faces are known-injected, so a genuine face resolves
+ * non-empty. Never rejects and never resolves on a timer, so a consumer chained
+ * off it remeasures exactly when the glyphs actually arrive, however late.
+ */
+async function fontsReady(family: string): Promise<boolean> {
+  const fonts = document.fonts;
+  if (!fonts?.load) return false;
+  try {
+    const faces = await fonts.load(`16px "${family}"`);
+    return Array.isArray(faces) ? faces.length > 0 : Boolean(faces);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Load the font for a catalog entry, returning a promise that resolves `true`
+ * when its glyphs are genuinely ready to paint (and `false` if the load fails).
+ * Deduplicated by RESOURCE identity (fontLoadKey), so two entries sharing one
+ * stylesheet/asset inject once and share one in-flight promise. A `bundled`
+ * entry (already in the app bundle) or an empty family resolves immediately.
+ *
+ * Resolution tracks genuine `document.fonts` settlement, never a timer: a slow
+ * font resolves whenever it truly arrives (so the remeasure/refit lands then,
+ * not before), and a fast font leaves no dangling timer. Callers that must not
+ * block on a stalled CDN should not `await` this directly — the UI font path
+ * fires-and-forgets (CSS `font-display: swap` paints the swap), and the code
+ * font path chains a `.then` that re-emits so widgets remeasure on genuine
+ * arrival.
  */
-export function loadFont(entry: FontCatalogEntry): Promise<void> {
-  if (typeof document === "undefined") return Promise.resolve();
+export function loadFont(entry: FontCatalogEntry): Promise<boolean> {
+  if (typeof document === "undefined") return Promise.resolve(false);
   // Nothing to fetch: bundled faces are in the app CSS; an empty family is the
-  // system default. Either way the browser already has it.
-  if (entry.source === "bundled" || !entry.family) return Promise.resolve();
+  // system default. Either way the browser already has it — treat as ready.
+  if (entry.source === "bundled" || !entry.family) return Promise.resolve(true);
 
-  const existing = loads.get(entry.id);
+  const key = fontLoadKey(entry);
+  const existing = loads.get(key);
   if (existing) return existing;
 
   const promise = (async () => {
-    if (entry.source === "google-css2") injectStylesheet(entry);
-    else if (entry.source === "self-hosted") injectFontFaces(entry);
-    await awaitFontReady(entry.family);
+    if (entry.source === "google-css2" && entry.cssUrl) {
+      // Wait for the stylesheet to parse so its @font-face rules are registered
+      // BEFORE we query document.fonts — otherwise fonts.load resolves empty and
+      // we'd report a premature ready with no later notification.
+      try {
+        await injectStylesheet(key, entry.cssUrl);
+      } catch {
+        // A blocked/failed stylesheet leaves the fallback stack; not ready.
+        return false;
+      }
+    } else if (entry.source === "self-hosted") {
+      injectFontFaces(key, entry);
+    }
+    return fontsReady(entry.family);
   })();
-  loads.set(entry.id, promise);
+  loads.set(key, promise);
+  // A load that resolves `false` (failed) must not poison the cache: a later
+  // attempt for the same resource should retry rather than get the stale
+  // failure. A genuine success stays cached (idempotent no-op re-injection).
+  void promise.then((ready) => {
+    if (!ready && loads.get(key) === promise) loads.delete(key);
+  });
   return promise;
 }
 
@@ -111,13 +185,18 @@ export function loadFont(entry: FontCatalogEntry): Promise<void> {
  * font, a partial name) resolves immediately and is left to the OS — the
  * existing free-text behavior, unchanged. Returns whether an entry matched so
  * callers can skip post-load work (Monaco re-measure) when nothing loaded.
+ * An optional `category` disambiguates a family offered in more than one role.
  */
-export function loadFontByFamily(family: string): {
+export function loadFontByFamily(
+  family: string,
+  category?: Parameters<typeof getFontByFamily>[1],
+): {
   entry: FontCatalogEntry | undefined;
-  ready: Promise<void>;
+  /** Resolves `true` when the matched font's glyphs genuinely arrive. */
+  ready: Promise<boolean>;
 } {
-  const entry = getFontByFamily(family);
-  return { entry, ready: entry ? loadFont(entry) : Promise.resolve() };
+  const entry = getFontByFamily(family, category);
+  return { entry, ready: entry ? loadFont(entry) : Promise.resolve(false) };
 }
 
 /** Test-only: clear the in-flight/loaded dedup cache. */

From 3f75237812abaef49b5da16ff0bd714fd0535e63 Mon Sep 17 00:00:00 2001
From: Bryan Li <15131870+btli@users.noreply.github.com>
Date: Mon, 20 Jul 2026 11:02:17 -0700
Subject: [PATCH 3/6] fix(web): remove injected node on retryable font-load
 failure
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round-2 regression from the dedup/retry fix: on a fontsReady() failure the
in-flight promise was evicted but the injected <link>/<style> stayed in the
DOM, so the injection guard matched the dead node and a retry never
re-fetched. For self-hosted faces the errored FontFace also lingered in
document.fonts, so document.fonts.load kept returning the rejected face.

- fontsReady now returns a three-way outcome: `ready` | `failed` |
  `unsupported`. `failed` (rejected load OR empty/not-ready result) is
  retryable; `unsupported` (no document.fonts API) is NOT, so we don't
  thrash reinjecting when the API is simply missing.
- On `failed`, removeInjected(key) drops this attempt's node(s) BEFORE
  evicting the cache entry, so a later call reinjects and re-fetches (and,
  for self-hosted, mints a fresh FontFace). On `unsupported` the node is
  left in place (CSS may still paint via font-display) and only the cache
  entry is evicted.
- Track injected nodes in a key→nodes Map instead of a quoted attribute
  selector: the key is a URL (`:?&;@`), and such attribute selectors match
  unreliably across engines (jsdom fails them), which would have silently
  broken the dedup/removal guards.

Tests: fonts.load rejection and empty/not-ready results both remove the
node and let a retry reinject + re-query (google-css2 and self-hosted),
genuine success after a prior failure, and the unsupported-API case
leaving the node untouched.

Co-authored-by: omnigent <noreply@omnigent.ai>
Signed-off-by: Bryan Li <bryan.li@gmail.com>
---
 web/src/lib/webFontLoader.test.ts | 100 ++++++++++++++++++++++++++-
 web/src/lib/webFontLoader.ts      | 111 ++++++++++++++++++++----------
 2 files changed, 174 insertions(+), 37 deletions(-)

diff --git a/web/src/lib/webFontLoader.test.ts b/web/src/lib/webFontLoader.test.ts
index 90cb5f4616..e4b380f898 100644
--- a/web/src/lib/webFontLoader.test.ts
+++ b/web/src/lib/webFontLoader.test.ts
@@ -140,7 +140,7 @@ describe("webFontLoader — dedup by resource identity, not id", () => {
     await expect(pb).resolves.toBe(true);
   });
 
-  it("retries after a failed load rather than caching the failure", async () => {
+  it("retries after a <link> error rather than caching the failure", async () => {
     const p1 = loadFont(inter());
     await flush();
     links()[0].dispatchEvent(new Event("error"));
@@ -159,6 +159,104 @@ describe("webFontLoader — dedup by resource identity, not id", () => {
   });
 });
 
+describe("webFontLoader — failure removes the injected node so retry re-fetches", () => {
+  it("google-css2: fonts.load REJECTS → <link> removed, next call reinjects and re-queries", async () => {
+    const p1 = loadFont(inter());
+    await flush();
+    fireLinkLoads();
+    await flush();
+    expect(links().length).toBe(1);
+    // The stylesheet parsed but document.fonts.load rejects (face errored).
+    fontsLoadCalls[0].deferred.reject(new Error("network"));
+    await expect(p1).resolves.toBe(false);
+    await flush();
+    // Regression guard: the dead <link> must be gone, or the DOM guard would
+    // skip reinjection forever.
+    expect(links().length).toBe(0);
+
+    // Retry: reinjects a fresh link AND issues a fresh document.fonts.load.
+    const p2 = loadFont(inter());
+    expect(p2).not.toBe(p1);
+    await flush();
+    expect(links().length).toBe(1);
+    fireLinkLoads();
+    await flush();
+    expect(fontsLoadCalls.length).toBe(2);
+    fontsLoadCalls[1].deferred.resolve([{}]);
+    await expect(p2).resolves.toBe(true);
+  });
+
+  it("google-css2: fonts.load resolves EMPTY → <link> removed, next call reinjects", async () => {
+    const p1 = loadFont(roboto());
+    await flush();
+    fireLinkLoads();
+    await flush();
+    fontsLoadCalls[0].deferred.resolve([]); // not-ready
+    await expect(p1).resolves.toBe(false);
+    await flush();
+    expect(links().length).toBe(0);
+
+    const p2 = loadFont(roboto());
+    expect(p2).not.toBe(p1);
+    await flush();
+    expect(links().length).toBe(1);
+    fireLinkLoads();
+    await flush();
+    fontsLoadCalls.at(-1)!.deferred.resolve([{}]);
+    await expect(p2).resolves.toBe(true);
+  });
+
+  it("self-hosted: not-ready → <style> removed, next call reinjects a fresh face", async () => {
+    const p1 = loadFont(nerd());
+    await flush();
+    expect(styles().length).toBe(1);
+    fontsLoadCalls[0].deferred.resolve([]); // errored/not-ready face
+    await expect(p1).resolves.toBe(false);
+    await flush();
+    // The errored @font-face <style> is dropped so a retry mints a fresh face
+    // instead of document.fonts.load reusing the rejected one.
+    expect(styles().length).toBe(0);
+
+    const p2 = loadFont(nerd());
+    expect(p2).not.toBe(p1);
+    await flush();
+    expect(styles().length).toBe(1);
+    fontsLoadCalls.at(-1)!.deferred.resolve([{}]);
+    await expect(p2).resolves.toBe(true);
+  });
+
+  it("genuine success after a prior failure works end-to-end", async () => {
+    const p1 = loadFont(inter());
+    await flush();
+    fireLinkLoads();
+    await flush();
+    fontsLoadCalls[0].deferred.resolve([]); // fail once
+    await expect(p1).resolves.toBe(false);
+    await flush();
+
+    const p2 = loadFont(inter());
+    await flush();
+    fireLinkLoads();
+    await flush();
+    fontsLoadCalls.at(-1)!.deferred.resolve([{}]); // succeed on retry
+    await expect(p2).resolves.toBe(true);
+    expect(links().length).toBe(1);
+  });
+
+  it("unsupported document.fonts API is NOT treated as retryable (no node thrash)", async () => {
+    // Simulate an environment without the FontFaceSet API.
+    Object.defineProperty(document, "fonts", { configurable: true, value: undefined });
+    const p1 = loadFont(nerd());
+    await flush();
+    // The @font-face was injected (CSS may still paint via font-display); it is
+    // NOT removed, because "API missing" isn't an asset failure.
+    expect(styles().length).toBe(1);
+    await expect(p1).resolves.toBe(false);
+    await flush();
+    expect(styles().length).toBe(1);
+  });
+});
+
 describe("webFontLoader — self-hosted", () => {
   it("injects @font-face rules once for a Nerd Font and awaits readiness", async () => {
     const p = loadFont(nerd());
diff --git a/web/src/lib/webFontLoader.ts b/web/src/lib/webFontLoader.ts
index 77f0276e16..863d15daf1 100644
--- a/web/src/lib/webFontLoader.ts
+++ b/web/src/lib/webFontLoader.ts
@@ -39,25 +39,34 @@ const DATA_ATTR = "data-omnigent-font";
 // fallback cell.
 const loads = new Map<string, Promise<boolean>>();
 
+// load key → the node(s) this loader injected for it. Tracked in a Map rather
+// than found via a DOM attribute selector: the key is a URL (with `:?&;@`) and a
+// quoted attribute selector over such a value is unreliable across engines. The
+// `DATA_ATTR` on each node stays only as a debugging marker.
+const injected = new Map<string, Element[]>();
+
 /**
- * Escape a value for use inside a quoted attribute selector (`[a="<here>"]`).
- * Only `"` and `\` are special there — NOT `:`/`?`/`&` etc., so we must NOT use
- * `CSS.escape` (which escapes identifier chars and would break the match).
+ * Remove every node this loader injected for `key` (the `<link>` and/or the
+ * `@font-face` `<style>`). Called on a retryable failure so a later attempt
+ * genuinely reinjects and re-fetches — and, for self-hosted faces, so the
+ * errored CSS-connected `FontFace` is dropped from `document.fonts` (a fresh
+ * `<style>` mints a fresh face rather than `document.fonts.load` returning the
+ * cached rejected one forever).
  */
-function escapeAttr(value: string): string {
-  return value.replace(/["\\]/g, "\\$&");
+function removeInjected(key: string): void {
+  for (const node of injected.get(key) ?? []) node.remove();
+  injected.delete(key);
 }
 
 /**
  * Inject a `<link rel="stylesheet">` for a Google CSS2 (or any CSS) href and
  * resolve once the browser has parsed it (`load` event) — so the @font-face
  * rules are registered before we ask `document.fonts` about them. Rejects on the
- * link's `error` event. If a node for this key already exists (hot reload / a
- * sibling entry sharing the URL), resolves immediately.
+ * link's `error` event (removing its own node). If a node for this key already
+ * exists (hot reload / a sibling entry sharing the URL), resolves immediately.
  */
 function injectStylesheet(key: string, cssUrl: string): Promise<void> {
-  const selector = `link[${DATA_ATTR}="${escapeAttr(key)}"]`;
-  if (document.querySelector(selector)) return Promise.resolve();
+  if (injected.has(key)) return Promise.resolve();
   return new Promise<void>((resolve, reject) => {
     const link = document.createElement("link");
     link.rel = "stylesheet";
@@ -67,22 +76,22 @@ function injectStylesheet(key: string, cssUrl: string): Promise<void> {
     link.addEventListener(
       "error",
       () => {
-        // Remove the failed node so a later retry (the promise is evicted on
-        // failure) genuinely re-injects instead of matching this dead link.
-        link.remove();
+        // Drop the failed node so a later retry (the promise is evicted on
+        // failure) genuinely re-injects instead of the has-guard skipping it.
+        removeInjected(key);
         reject(new Error(`stylesheet failed: ${cssUrl}`));
       },
       { once: true },
     );
     document.head.appendChild(link);
+    injected.set(key, [link]);
   });
 }
 
 /** Inject a `<style>` holding an entry's explicit `@font-face` rules (once). */
 function injectFontFaces(key: string, entry: FontCatalogEntry): void {
   if (!entry.faces?.length) return;
-  const selector = `style[${DATA_ATTR}="${escapeAttr(key)}"]`;
-  if (document.querySelector(selector)) return;
+  if (injected.has(key)) return;
   const css = entry.faces
     .map((face) => {
       const src = face.format ? `url(${face.url}) format('${face.format}')` : `url(${face.url})`;
@@ -101,28 +110,41 @@ function injectFontFaces(key: string, entry: FontCatalogEntry): void {
   style.setAttribute(DATA_ATTR, key);
   style.textContent = css;
   document.head.appendChild(style);
+  injected.set(key, [style]);
 }
 
 /**
- * Resolve `true` once the browser genuinely has `family` ready to paint.
+ * Outcome of a readiness probe:
+ *   - `ready`       — glyphs genuinely available; remeasure now.
+ *   - `failed`      — a real asset failure (rejected load, or empty/not-ready
+ *     result meaning the rules didn't take). RETRYABLE: the caller drops the
+ *     injected node so a later attempt re-fetches.
+ *   - `unsupported` — no `document.fonts` API (old browser / jsdom). NOT a load
+ *     failure, so NOT retryable — reinjecting would just thrash.
+ */
+type ReadyOutcome = "ready" | "failed" | "unsupported";
+
+/**
+ * Probe whether the browser genuinely has `family` ready to paint.
  *
  * `document.fonts.load('16px "Family"')` kicks the fetch for matching unloaded
  * `@font-face`s and resolves with the FontFace objects it matched. An EMPTY
- * match array (or a rejected load) is treated as NOT ready and resolves `false`
- * — an empty result means the rules weren't registered, so reporting success
- * would fire a premature remeasure against the fallback cell. Callers only await
- * this once the stylesheet/faces are known-injected, so a genuine face resolves
- * non-empty. Never rejects and never resolves on a timer, so a consumer chained
- * off it remeasures exactly when the glyphs actually arrive, however late.
+ * match array (or a rejected load) is `failed` — an empty result means the rules
+ * weren't registered / the face errored, so reporting success would fire a
+ * premature remeasure against the fallback cell. A missing API is `unsupported`,
+ * kept distinct so the caller doesn't treat it as a retryable asset failure.
+ * Never rejects and never resolves on a timer, so a consumer chained off it
+ * remeasures exactly when the glyphs actually arrive, however late.
  */
-async function fontsReady(family: string): Promise<boolean> {
+async function fontsReady(family: string): Promise<ReadyOutcome> {
   const fonts = document.fonts;
-  if (!fonts?.load) return false;
+  if (!fonts?.load) return "unsupported";
   try {
     const faces = await fonts.load(`16px "${family}"`);
-    return Array.isArray(faces) ? faces.length > 0 : Boolean(faces);
+    const ok = Array.isArray(faces) ? faces.length > 0 : Boolean(faces);
+    return ok ? "ready" : "failed";
   } catch {
-    return false;
+    return "failed";
   }
 }
 
@@ -151,29 +173,45 @@ export function loadFont(entry: FontCatalogEntry): Promise<boolean> {
   const existing = loads.get(key);
   if (existing) return existing;
 
-  const promise = (async () => {
+  // The inner load yields a ReadyOutcome; the outer `.then` maps it to the
+  // cached boolean AND handles retry eviction (where `promise` is in scope).
+  const outcome = (async (): Promise<ReadyOutcome> => {
     if (entry.source === "google-css2" && entry.cssUrl) {
       // Wait for the stylesheet to parse so its @font-face rules are registered
       // BEFORE we query document.fonts — otherwise fonts.load resolves empty and
-      // we'd report a premature ready with no later notification.
+      // we'd report a premature ready with no later notification. The link's own
+      // error handler removes its node, so a rejection here is a retryable
+      // failure with nothing left to reinject.
       try {
         await injectStylesheet(key, entry.cssUrl);
       } catch {
-        // A blocked/failed stylesheet leaves the fallback stack; not ready.
-        return false;
+        return "failed";
       }
     } else if (entry.source === "self-hosted") {
       injectFontFaces(key, entry);
     }
     return fontsReady(entry.family);
   })();
-  loads.set(key, promise);
-  // A load that resolves `false` (failed) must not poison the cache: a later
-  // attempt for the same resource should retry rather than get the stale
-  // failure. A genuine success stays cached (idempotent no-op re-injection).
-  void promise.then((ready) => {
-    if (!ready && loads.get(key) === promise) loads.delete(key);
+
+  const promise = outcome.then((result) => {
+    if (result === "failed") {
+      // A real asset failure: drop THIS attempt's injected node(s) so a retry
+      // reinjects and re-fetches (and, for self-hosted, mints a fresh FontFace
+      // instead of reusing the errored one), then evict so the next call re-runs.
+      // Guard against clobbering a newer in-flight load for the same key.
+      if (loads.get(key) === promise) {
+        removeInjected(key);
+        loads.delete(key);
+      }
+    } else if (result === "unsupported") {
+      // No document.fonts API (old browser / jsdom): NOT a load failure. Leave
+      // the injected node in place (CSS may still paint via font-display) and
+      // evict without node removal so we don't thrash reinjecting on retry.
+      if (loads.get(key) === promise) loads.delete(key);
+    }
+    return result === "ready";
   });
+  loads.set(key, promise);
   return promise;
 }
 
@@ -199,7 +237,8 @@ export function loadFontByFamily(
   return { entry, ready: entry ? loadFont(entry) : Promise.resolve(false) };
 }
 
-/** Test-only: clear the in-flight/loaded dedup cache. */
+/** Test-only: clear the in-flight/loaded dedup cache and injected-node index. */
 export function resetFontLoaderForTests(): void {
   loads.clear();
+  injected.clear();
 }

From 22c5462654863fab4d532cf64ecfefaf6ed07a8b Mon Sep 17 00:00:00 2001
From: Bryan Li <15131870+btli@users.noreply.github.com>
Date: Tue, 21 Jul 2026 06:55:18 -0700
Subject: [PATCH 4/6] refactor(web): extract shared font-family factory +
 catalog helper

PR-1 review follow-ups on the font loader/catalog work, shaping the
shared surface PR 2's font dropdowns will consume:

- Extract the CSS-var-backed font-family core into
  cssFontFamilyPreference.ts (normalizeFontFamily, readStoredFontFamily,
  writeStoredFontFamily, createCssFontFamilyPreference threading a loader
  category) and refactor uiFontPreferences onto it. codeFontPreferences
  keeps its specialized remeasure/refit pub/sub path.
- Add a googleFont() catalog helper and collapse the repeated Google
  CSS2 entries; family names unchanged.
- Export UI_FONT_FAMILY_FALLBACK so callers/tests stop repeating the
  var(--font-sans) literal (mirrors CODE_FONT_FAMILY_FALLBACK).
- resetFontLoaderForTests now removes the DOM nodes it injected.
- Centralize boot restore in restoreFontPreferences(), called from
  main.tsx and embed.tsx.

Co-authored-by: Isaac
Signed-off-by: Bryan Li <bryan.li@gmail.com>
---
 web/src/embed.tsx                           |  12 +-
 web/src/lib/cssFontFamilyPreference.test.ts | 115 ++++++++++++++++
 web/src/lib/cssFontFamilyPreference.ts      | 143 ++++++++++++++++++++
 web/src/lib/fontCatalog.ts                  | 140 +++++--------------
 web/src/lib/restoreFontPreferences.test.ts  |  30 ++++
 web/src/lib/restoreFontPreferences.ts       |  33 +++++
 web/src/lib/uiFontPreferences.test.ts       |   5 +-
 web/src/lib/uiFontPreferences.ts            |  78 ++++-------
 web/src/lib/webFontLoader.test.ts           |  22 ++-
 web/src/lib/webFontLoader.ts                |   9 +-
 web/src/main.tsx                            |  23 +---
 web/src/pages/SettingsPage.test.tsx         |   3 +-
 12 files changed, 421 insertions(+), 192 deletions(-)
 create mode 100644 web/src/lib/cssFontFamilyPreference.test.ts
 create mode 100644 web/src/lib/cssFontFamilyPreference.ts
 create mode 100644 web/src/lib/restoreFontPreferences.test.ts
 create mode 100644 web/src/lib/restoreFontPreferences.ts

diff --git a/web/src/embed.tsx b/web/src/embed.tsx
index 9f3c200fe4..06a6db765b 100644
--- a/web/src/embed.tsx
+++ b/web/src/embed.tsx
@@ -45,13 +45,7 @@ import { initChatStore } from "./store/chatStore";
 import "./index.css";
 import { QueueFlushProvider } from "./hooks/QueueFlushProvider";
 import { SessionUpdatesProvider } from "./hooks/SessionUpdatesProvider";
-import {
-  applyUiFontFamily,
-  applyUiFontScale,
-  readUiFontFamily,
-  readUiFontSizePx,
-} from "./lib/uiFontPreferences";
-import { loadCodeFontFamily, readCodeFontFamily } from "./lib/codeFontPreferences";
+import { restoreFontPreferences } from "./lib/restoreFontPreferences";
 
 // Restore the saved font preferences (and kick off any catalog webfont loads)
 // when the embed module loads. The UI/code font controls stay visible when
@@ -59,9 +53,7 @@ import { loadCodeFontFamily, readCodeFontFamily } from "./lib/codeFontPreference
 // so a chosen font must be applied + fetched here just as standalone does in
 // main.tsx — otherwise the selection would only take effect on the next Settings
 // change. Guarded for SSR by the apply/load helpers.
-applyUiFontScale(readUiFontSizePx());
-applyUiFontFamily(readUiFontFamily());
-loadCodeFontFamily(readCodeFontFamily());
+restoreFontPreferences();
 
 export type { OmnigentHostConfig } from "./lib/host";
 export type { RoutingApi } from "./lib/routing";
diff --git a/web/src/lib/cssFontFamilyPreference.test.ts b/web/src/lib/cssFontFamilyPreference.test.ts
new file mode 100644
index 0000000000..3453eafd16
--- /dev/null
+++ b/web/src/lib/cssFontFamilyPreference.test.ts
@@ -0,0 +1,115 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  createCssFontFamilyPreference,
+  FONT_FAMILY_DEFAULT,
+  normalizeFontFamily,
+  readStoredFontFamily,
+  writeStoredFontFamily,
+} from "./cssFontFamilyPreference";
+
+const KEY = "omnigent:test-font-family";
+const CSS_VAR = "--test-font-family";
+
+afterEach(() => {
+  localStorage.clear();
+  document.documentElement.style.removeProperty(CSS_VAR);
+});
+
+describe("cssFontFamilyPreference — normalizeFontFamily", () => {
+  it("returns the empty default for non-strings", () => {
+    expect(normalizeFontFamily(42)).toBe(FONT_FAMILY_DEFAULT);
+    expect(normalizeFontFamily(null)).toBe("");
+    expect(normalizeFontFamily(undefined)).toBe("");
+  });
+
+  it("trims surrounding whitespace", () => {
+    expect(normalizeFontFamily("  Georgia  ")).toBe("Georgia");
+  });
+
+  it("preserves the punctuation a font stack relies on", () => {
+    expect(normalizeFontFamily('"Times New Roman", serif')).toBe('"Times New Roman", serif');
+  });
+
+  it("strips characters that could break the CSS declaration", () => {
+    expect(normalizeFontFamily("Arial;}body{")).toBe("Arialbody");
+  });
+
+  it("collapses an over-long value to the default", () => {
+    expect(normalizeFontFamily("x".repeat(200))).toBe(FONT_FAMILY_DEFAULT);
+  });
+});
+
+describe("cssFontFamilyPreference — readStoredFontFamily / writeStoredFontFamily", () => {
+  it("round-trips a valid family name and returns the normalized write value", () => {
+    expect(writeStoredFontFamily(KEY, "Inter")).toBe("Inter");
+    expect(readStoredFontFamily(KEY)).toBe("Inter");
+    expect(localStorage.getItem(KEY)).toBe(JSON.stringify("Inter"));
+  });
+
+  it("clears the key when written empty or whitespace-only", () => {
+    writeStoredFontFamily(KEY, "Inter");
+    expect(localStorage.getItem(KEY)).not.toBeNull();
+    expect(writeStoredFontFamily(KEY, "   ")).toBe("");
+    expect(localStorage.getItem(KEY)).toBeNull();
+    expect(readStoredFontFamily(KEY)).toBe("");
+  });
+
+  it("returns the default when nothing is stored", () => {
+    expect(readStoredFontFamily(KEY)).toBe(FONT_FAMILY_DEFAULT);
+  });
+
+  it("falls back to the default on malformed JSON", () => {
+    localStorage.setItem(KEY, "}{not json");
+    expect(readStoredFontFamily(KEY)).toBe(FONT_FAMILY_DEFAULT);
+  });
+
+  it("falls back to the default on a non-string value", () => {
+    localStorage.setItem(KEY, JSON.stringify(42));
+    expect(readStoredFontFamily(KEY)).toBe(FONT_FAMILY_DEFAULT);
+  });
+});
+
+describe("cssFontFamilyPreference — createCssFontFamilyPreference", () => {
+  const pref = createCssFontFamilyPreference({
+    key: KEY,
+    cssVar: CSS_VAR,
+    fallback: "var(--font-sans)",
+    category: "sans",
+  });
+
+  it("read/write round-trip through the configured key", () => {
+    expect(pref.write("Inter")).toBe("Inter");
+    expect(pref.read()).toBe("Inter");
+    expect(localStorage.getItem(KEY)).toBe(JSON.stringify("Inter"));
+  });
+
+  it("applies the family with the fallback stack appended", () => {
+    pref.apply("Inter");
+    expect(document.documentElement.style.getPropertyValue(CSS_VAR)).toBe(
+      "Inter, var(--font-sans)",
+    );
+  });
+
+  it("removes the property when applied empty (default)", () => {
+    pref.apply("Inter");
+    expect(document.documentElement.style.getPropertyValue(CSS_VAR)).toBe(
+      "Inter, var(--font-sans)",
+    );
+    pref.apply("");
+    expect(document.documentElement.style.getPropertyValue(CSS_VAR)).toBe("");
+  });
+
+  it("uses each preference's own fallback stack", () => {
+    const mono = createCssFontFamilyPreference({
+      key: "omnigent:test-mono-family",
+      cssVar: "--test-mono-family",
+      fallback: "ui-monospace, monospace",
+      category: "fixedWidth",
+    });
+    mono.apply("Roboto Mono");
+    expect(document.documentElement.style.getPropertyValue("--test-mono-family")).toBe(
+      "Roboto Mono, ui-monospace, monospace",
+    );
+    document.documentElement.style.removeProperty("--test-mono-family");
+  });
+});
diff --git a/web/src/lib/cssFontFamilyPreference.ts b/web/src/lib/cssFontFamilyPreference.ts
new file mode 100644
index 0000000000..0f6f20b3ef
--- /dev/null
+++ b/web/src/lib/cssFontFamilyPreference.ts
@@ -0,0 +1,143 @@
+// Shared core for CSS-variable-backed font-family preferences.
+//
+// The chrome/UI font (uiFontPreferences.ts) and the general monospace font both
+// ride a CSS custom property on the document root: an unset property falls back
+// to a system stack, and a set value wins. The read/normalize/persist/apply
+// mechanics are identical across them — only the storage key, the CSS variable,
+// the appended fallback stack, and the loader category differ. This module
+// factors that common core out so each family is a thin config object.
+//
+// The code font (codeFontPreferences.ts) is deliberately NOT built on this: it
+// can't ride a CSS variable (Monaco/xterm are fixed-pixel widgets) and needs a
+// specialized immediate + post-load remeasure/refit pub/sub path.
+//
+// SSR/no-DOM safe: reads return the empty default with no `window`, and apply
+// no-ops with no `document`, so boot-time restore on the server is harmless.
+
+import { loadFontByFamily } from "./webFontLoader";
+import type { FontCategory } from "./fontCatalog";
+
+/** Empty string = the family's default: no override, falls back to the stack. */
+export const FONT_FAMILY_DEFAULT = "";
+
+/** Longest family name we'll accept — a guard against a corrupt/oversized entry. */
+const FONT_FAMILY_MAX_LENGTH = 100;
+
+/**
+ * Normalize a raw family name into a value safe to persist and to set as a CSS
+ * custom property (or hand a code widget): trimmed, with characters that could
+ * terminate the declaration or open a new one (`;{}` and control chars)
+ * stripped. Over-long input collapses to the default. Returns "" for anything
+ * that isn't a usable family, so callers treat empty as the family default.
+ */
+export function normalizeFontFamily(value: unknown): string {
+  if (typeof value !== "string") return FONT_FAMILY_DEFAULT;
+  // eslint-disable-next-line no-control-regex -- intentionally stripping control chars
+  const cleaned = value.replace(/[;{}\x00-\x1f\x7f]/g, "").trim();
+  if (!cleaned || cleaned.length > FONT_FAMILY_MAX_LENGTH) {
+    return FONT_FAMILY_DEFAULT;
+  }
+  return cleaned;
+}
+
+/**
+ * Read a persisted font family from `localStorage[key]`.
+ *
+ * Returns "" (the family default) when nothing is stored, on a server render (no
+ * `window`), or when the stored value is missing/malformed — never throws, so a
+ * corrupt entry can't break app boot.
+ */
+export function readStoredFontFamily(key: string): string {
+  if (typeof window === "undefined") return FONT_FAMILY_DEFAULT;
+  try {
+    const raw = window.localStorage.getItem(key);
+    if (!raw) return FONT_FAMILY_DEFAULT;
+    const parsed: unknown = JSON.parse(raw);
+    return normalizeFontFamily(parsed);
+  } catch {
+    return FONT_FAMILY_DEFAULT;
+  }
+}
+
+/**
+ * Persist a font family under `localStorage[key]`, returning the normalized name
+ * that was applied. An empty (or all-stripped) name clears the preference —
+ * reverting to the family default — rather than storing a blank. Swallows
+ * quota/access errors so a failed write can't break the app.
+ */
+export function writeStoredFontFamily(key: string, name: string): string {
+  const normalized = normalizeFontFamily(name);
+  if (typeof window === "undefined") return normalized;
+  try {
+    if (!normalized) {
+      window.localStorage.removeItem(key);
+    } else {
+      window.localStorage.setItem(key, JSON.stringify(normalized));
+    }
+  } catch {
+    // localStorage quota or access errors shouldn't break the app.
+  }
+  return normalized;
+}
+
+/** Config for a CSS-variable-backed font-family preference. */
+export interface CssFontFamilyPreferenceConfig {
+  /** localStorage key the value is persisted under. */
+  readonly key: string;
+  /** CSS custom property set on the document root, e.g. `--ui-font-family`. */
+  readonly cssVar: string;
+  /**
+   * Fallback stack appended after the chosen family in the CSS value, e.g.
+   * `var(--font-sans)`. So an uninstalled/partial name degrades to this rather
+   * than the browser's default serif. The `var(--x, …)` fallback in the CSS only
+   * fires when the property is UNSET, not when it holds an unusable name, so the
+   * fallback has to live inside the value too.
+   */
+  readonly fallback: string;
+  /** Loader category, so a family shared across roles loads the right entry. */
+  readonly category: FontCategory;
+}
+
+/** The read/write/apply trio for one CSS-variable-backed font family. */
+export interface CssFontFamilyPreference {
+  /** Read the persisted family ("" = default). Never throws. */
+  read(): string;
+  /** Persist the family; returns the normalized name written ("" cleared it). */
+  write(name: string): string;
+  /**
+   * Apply the family to the document root's CSS variable. An empty name removes
+   * the property (restoring the fallback stack); a catalog name also kicks a
+   * fire-and-forget webfont load so the glyphs arrive (font-display: swap paints
+   * the swap). This is the single source of the DOM side-effect.
+   */
+  apply(name: string): void;
+}
+
+/**
+ * Build the read/write/apply trio for a CSS-variable-backed font family (the
+ * UI and fixed-width shape). See {@link CssFontFamilyPreferenceConfig}.
+ */
+export function createCssFontFamilyPreference(
+  config: CssFontFamilyPreferenceConfig,
+): CssFontFamilyPreference {
+  const { key, cssVar, fallback, category } = config;
+  return {
+    read: () => readStoredFontFamily(key),
+    write: (name: string) => writeStoredFontFamily(key, name),
+    apply: (name: string) => {
+      if (typeof document === "undefined") return;
+      const normalized = normalizeFontFamily(name);
+      if (!normalized) {
+        document.documentElement.style.removeProperty(cssVar);
+        return;
+      }
+      // Kick a webfont load when the name matches a catalog family so the glyphs
+      // actually arrive (fire-and-forget: the CSS var is set now and
+      // font-display: swap paints the face once it lands). A non-catalog name is
+      // left to the OS — the existing free-text behavior. The `, <fallback>`
+      // covers the gap before load and any name that never resolves.
+      void loadFontByFamily(normalized, category);
+      document.documentElement.style.setProperty(cssVar, `${normalized}, ${fallback}`);
+    },
+  };
+}
diff --git a/web/src/lib/fontCatalog.ts b/web/src/lib/fontCatalog.ts
index 0abe836f5c..65d0f7b82b 100644
--- a/web/src/lib/fontCatalog.ts
+++ b/web/src/lib/fontCatalog.ts
@@ -90,59 +90,38 @@ function nerdFace(path: string): readonly FontFaceAsset[] {
   return [{ url: `${NERD_FONTS_BASE}/${path}`, weight: "400", format: "truetype" }];
 }
 
+/**
+ * A Google Fonts CSS2 catalog entry: label mirrors the family, `id` is the
+ * stable slug, and the stylesheet href is built from the family + weights. Keeps
+ * the ~13 Google entries from repeating the family name four times each.
+ */
+function googleFont(
+  category: FontCategory,
+  id: string,
+  family: string,
+  weights: readonly number[],
+): FontCatalogEntry {
+  return {
+    id,
+    label: family,
+    family,
+    category,
+    source: "google-css2",
+    cssUrl: googleCss2Url(family, weights),
+  };
+}
+
 // ---- Sans (UI/chrome) -----------------------------------------------------
 
 const SANS_FONTS: readonly FontCatalogEntry[] = [
   // System default: no face to load — the empty family maps to --font-sans.
   { id: "system-ui", label: "System default", family: "", category: "sans", source: "bundled" },
-  {
-    id: "inter",
-    label: "Inter",
-    family: "Inter",
-    category: "sans",
-    source: "google-css2",
-    cssUrl: googleCss2Url("Inter", [400, 500, 600, 700]),
-  },
-  {
-    id: "roboto",
-    label: "Roboto",
-    family: "Roboto",
-    category: "sans",
-    source: "google-css2",
-    cssUrl: googleCss2Url("Roboto", [400, 500, 700]),
-  },
-  {
-    id: "open-sans",
-    label: "Open Sans",
-    family: "Open Sans",
-    category: "sans",
-    source: "google-css2",
-    cssUrl: googleCss2Url("Open Sans", [400, 600, 700]),
-  },
-  {
-    id: "lato",
-    label: "Lato",
-    family: "Lato",
-    category: "sans",
-    source: "google-css2",
-    cssUrl: googleCss2Url("Lato", [400, 700]),
-  },
-  {
-    id: "source-sans-3",
-    label: "Source Sans 3",
-    family: "Source Sans 3",
-    category: "sans",
-    source: "google-css2",
-    cssUrl: googleCss2Url("Source Sans 3", [400, 600, 700]),
-  },
-  {
-    id: "geist",
-    label: "Geist",
-    family: "Geist",
-    category: "sans",
-    source: "google-css2",
-    cssUrl: googleCss2Url("Geist", [400, 500, 600, 700]),
-  },
+  googleFont("sans", "inter", "Inter", [400, 500, 600, 700]),
+  googleFont("sans", "roboto", "Roboto", [400, 500, 700]),
+  googleFont("sans", "open-sans", "Open Sans", [400, 600, 700]),
+  googleFont("sans", "lato", "Lato", [400, 700]),
+  googleFont("sans", "source-sans-3", "Source Sans 3", [400, 600, 700]),
+  googleFont("sans", "geist", "Geist", [400, 500, 600, 700]),
 ];
 
 // ---- Fixed width (general monospace UI) -----------------------------------
@@ -157,67 +136,20 @@ const FIXED_WIDTH_FONTS: readonly FontCatalogEntry[] = [
     category: "fixedWidth",
     source: "bundled",
   },
-  {
-    id: "ibm-plex-mono",
-    label: "IBM Plex Mono",
-    family: "IBM Plex Mono",
-    category: "fixedWidth",
-    source: "google-css2",
-    cssUrl: googleCss2Url("IBM Plex Mono", [400, 500, 600, 700]),
-  },
-  {
-    id: "roboto-mono",
-    label: "Roboto Mono",
-    family: "Roboto Mono",
-    category: "fixedWidth",
-    source: "google-css2",
-    cssUrl: googleCss2Url("Roboto Mono", [400, 500, 700]),
-  },
-  {
-    id: "space-mono",
-    label: "Space Mono",
-    family: "Space Mono",
-    category: "fixedWidth",
-    source: "google-css2",
-    cssUrl: googleCss2Url("Space Mono", [400, 700]),
-  },
+  googleFont("fixedWidth", "ibm-plex-mono", "IBM Plex Mono", [400, 500, 600, 700]),
+  googleFont("fixedWidth", "roboto-mono", "Roboto Mono", [400, 500, 700]),
+  googleFont("fixedWidth", "space-mono", "Space Mono", [400, 700]),
 ];
 
 // ---- Code (editor + terminal) ---------------------------------------------
 
 const CODE_FONTS: readonly FontCatalogEntry[] = [
-  {
-    id: "jetbrains-mono",
-    label: "JetBrains Mono",
-    family: "JetBrains Mono",
-    category: "code",
-    source: "google-css2",
-    cssUrl: googleCss2Url("JetBrains Mono", [400, 500, 700]),
-  },
-  {
-    id: "fira-code",
-    label: "Fira Code",
-    family: "Fira Code",
-    category: "code",
-    source: "google-css2",
-    cssUrl: googleCss2Url("Fira Code", [400, 500, 700]),
-  },
-  {
-    id: "source-code-pro",
-    label: "Source Code Pro",
-    family: "Source Code Pro",
-    category: "code",
-    source: "google-css2",
-    cssUrl: googleCss2Url("Source Code Pro", [400, 500, 700]),
-  },
-  {
-    id: "ibm-plex-mono-code",
-    label: "IBM Plex Mono",
-    family: "IBM Plex Mono",
-    category: "code",
-    source: "google-css2",
-    cssUrl: googleCss2Url("IBM Plex Mono", [400, 500, 600, 700]),
-  },
+  googleFont("code", "jetbrains-mono", "JetBrains Mono", [400, 500, 700]),
+  googleFont("code", "fira-code", "Fira Code", [400, 500, 700]),
+  googleFont("code", "source-code-pro", "Source Code Pro", [400, 500, 700]),
+  // Shares the fixedWidth IBM Plex Mono stylesheet URL (same family + weights),
+  // so the loader dedupes them by resource identity — distinct id, one fetch.
+  googleFont("code", "ibm-plex-mono-code", "IBM Plex Mono", [400, 500, 600, 700]),
   // Cascadia Code isn't a Google Fonts family we bundle; deliver its @font-face
   // from the Fontsource CDN (latin subset, regular + bold).
   {
diff --git a/web/src/lib/restoreFontPreferences.test.ts b/web/src/lib/restoreFontPreferences.test.ts
new file mode 100644
index 0000000000..7dea4cc52a
--- /dev/null
+++ b/web/src/lib/restoreFontPreferences.test.ts
@@ -0,0 +1,30 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { restoreFontPreferences } from "./restoreFontPreferences";
+
+afterEach(() => {
+  localStorage.clear();
+  document.documentElement.style.removeProperty("--ui-font-scale");
+  document.documentElement.style.removeProperty("--ui-font-family");
+});
+
+describe("restoreFontPreferences", () => {
+  it("applies the saved UI size + family to the document root on boot", () => {
+    localStorage.setItem("omnigent:ui-font-size", JSON.stringify(20));
+    localStorage.setItem("omnigent:ui-font-family", JSON.stringify("Inter"));
+
+    restoreFontPreferences();
+
+    // 20 / 16 base = 1.25.
+    expect(document.documentElement.style.getPropertyValue("--ui-font-scale")).toBe("1.25");
+    expect(document.documentElement.style.getPropertyValue("--ui-font-family")).toBe(
+      "Inter, var(--font-sans)",
+    );
+  });
+
+  it("applies defaults when nothing is stored (no throw)", () => {
+    expect(() => restoreFontPreferences()).not.toThrow();
+    // Default size 16 → scale 1; family unset → no override.
+    expect(document.documentElement.style.getPropertyValue("--ui-font-scale")).toBe("1");
+    expect(document.documentElement.style.getPropertyValue("--ui-font-family")).toBe("");
+  });
+});
diff --git a/web/src/lib/restoreFontPreferences.ts b/web/src/lib/restoreFontPreferences.ts
new file mode 100644
index 0000000000..c6cff25f58
--- /dev/null
+++ b/web/src/lib/restoreFontPreferences.ts
@@ -0,0 +1,33 @@
+// Boot-time font restoration, shared by the standalone (main.tsx) and embed
+// (embed.tsx) entry points.
+//
+// The saved font preferences must be applied before first paint so there's no
+// flash, and the catalog webfont loads kicked off so a chosen font is fetched on
+// boot rather than only on the next Settings change. Both entry points need the
+// exact same calls, so they live here once.
+//
+// SSR/no-DOM safe: every apply/load helper guards for a missing document.
+
+import {
+  applyUiFontFamily,
+  applyUiFontScale,
+  readUiFontFamily,
+  readUiFontSizePx,
+} from "./uiFontPreferences";
+import { loadCodeFontFamily, readCodeFontFamily } from "./codeFontPreferences";
+
+/**
+ * Restore the saved UI + code font preferences on boot.
+ *
+ * - UI font: applies the size (`--ui-font-scale`) and family (`--ui-font-family`)
+ *   to the document root; `applyUiFontFamily` also kicks the catalog webfont
+ *   load for the saved family.
+ * - Code font: rides a pub/sub (not a CSS var), so nothing loads it unless we
+ *   ask — `loadCodeFontFamily` fetches it and mounted editors/terminals
+ *   re-measure when it lands.
+ */
+export function restoreFontPreferences(): void {
+  applyUiFontScale(readUiFontSizePx());
+  applyUiFontFamily(readUiFontFamily());
+  loadCodeFontFamily(readCodeFontFamily());
+}
diff --git a/web/src/lib/uiFontPreferences.test.ts b/web/src/lib/uiFontPreferences.test.ts
index cf691f1dbb..fdb30f7935 100644
--- a/web/src/lib/uiFontPreferences.test.ts
+++ b/web/src/lib/uiFontPreferences.test.ts
@@ -5,6 +5,7 @@ import {
   readUiFontFamily,
   readUiFontSizePx,
   UI_FONT_FAMILY_DEFAULT,
+  UI_FONT_FAMILY_FALLBACK,
   UI_FONT_SIZE_DEFAULT,
   UI_FONT_SIZE_MAX,
   UI_FONT_SIZE_MIN,
@@ -134,14 +135,14 @@ describe("uiFontPreferences — family", () => {
     // the app's default sans, not the browser's default serif.
     applyUiFontFamily("Inter");
     expect(document.documentElement.style.getPropertyValue("--ui-font-family")).toBe(
-      "Inter, var(--font-sans)",
+      `Inter, ${UI_FONT_FAMILY_FALLBACK}`,
     );
   });
 
   it("removes the custom property when applied empty (System default)", () => {
     applyUiFontFamily("Inter");
     expect(document.documentElement.style.getPropertyValue("--ui-font-family")).toBe(
-      "Inter, var(--font-sans)",
+      `Inter, ${UI_FONT_FAMILY_FALLBACK}`,
     );
     applyUiFontFamily("");
     // Removing the property lets the html rule fall back to var(--font-sans).
diff --git a/web/src/lib/uiFontPreferences.ts b/web/src/lib/uiFontPreferences.ts
index d333cc8b75..f1810f4f95 100644
--- a/web/src/lib/uiFontPreferences.ts
+++ b/web/src/lib/uiFontPreferences.ts
@@ -16,7 +16,7 @@
 // `var(--ui-font-family, var(--font-sans))`, so an unset family falls back to
 // the system stack and any value we set on documentElement wins.
 
-import { loadFontByFamily } from "./webFontLoader";
+import { createCssFontFamilyPreference } from "./cssFontFamilyPreference";
 
 const STORAGE_KEY = "omnigent:ui-font-size";
 
@@ -90,25 +90,25 @@ const FONT_FAMILY_STORAGE_KEY = "omnigent:ui-font-family";
 /** Empty string = "System default": no override, falls back to `--font-sans`. */
 export const UI_FONT_FAMILY_DEFAULT = "";
 
-/** Longest family name we'll accept — a guard against a corrupt/oversized entry. */
-const UI_FONT_FAMILY_MAX_LENGTH = 100;
-
 /**
- * Normalize a raw family name into a value safe to persist and to set as a CSS
- * custom property: trimmed, with characters that could terminate the
- * declaration or open a new one (`;{}` and control chars) stripped. Over-long
- * input collapses to the default. Returns "" for anything that isn't a usable
- * family, so callers treat empty as "System default".
+ * The sans stack the UI font falls back to when no custom family is set (or an
+ * uninstalled name is chosen). It's the `--font-sans` variable rather than a
+ * literal so the CSS var and the appended fallback stay in lockstep, and so
+ * SettingsPage can name the fallback semantically instead of repeating the
+ * literal (mirrors {@link CODE_FONT_FAMILY_FALLBACK}).
  */
-function normalizeUiFontFamily(value: unknown): string {
-  if (typeof value !== "string") return UI_FONT_FAMILY_DEFAULT;
-  // eslint-disable-next-line no-control-regex -- intentionally stripping control chars
-  const cleaned = value.replace(/[;{}\x00-\x1f\x7f]/g, "").trim();
-  if (!cleaned || cleaned.length > UI_FONT_FAMILY_MAX_LENGTH) {
-    return UI_FONT_FAMILY_DEFAULT;
-  }
-  return cleaned;
-}
+export const UI_FONT_FAMILY_FALLBACK = "var(--font-sans)";
+
+// The whole UI font-family preference — read/normalize/persist/apply — is the
+// shared CSS-variable-backed shape. Setting `--ui-font-family` on the document
+// root drives the `html` rule in index.css; the `sans` category loads the right
+// catalog entry for a shared family.
+const uiFontFamilyPreference = createCssFontFamilyPreference({
+  key: FONT_FAMILY_STORAGE_KEY,
+  cssVar: "--ui-font-family",
+  fallback: UI_FONT_FAMILY_FALLBACK,
+  category: "sans",
+});
 
 /**
  * Read the persisted UI font family.
@@ -118,15 +118,7 @@ function normalizeUiFontFamily(value: unknown): string {
  * corrupt entry can't break app boot.
  */
 export function readUiFontFamily(): string {
-  if (typeof window === "undefined") return UI_FONT_FAMILY_DEFAULT;
-  try {
-    const raw = window.localStorage.getItem(FONT_FAMILY_STORAGE_KEY);
-    if (!raw) return UI_FONT_FAMILY_DEFAULT;
-    const parsed: unknown = JSON.parse(raw);
-    return normalizeUiFontFamily(parsed);
-  } catch {
-    return UI_FONT_FAMILY_DEFAULT;
-  }
+  return uiFontFamilyPreference.read();
 }
 
 /**
@@ -135,17 +127,7 @@ export function readUiFontFamily(): string {
  * quota/access errors so a failed write can't break the app.
  */
 export function writeUiFontFamily(name: string): void {
-  if (typeof window === "undefined") return;
-  try {
-    const normalized = normalizeUiFontFamily(name);
-    if (!normalized) {
-      window.localStorage.removeItem(FONT_FAMILY_STORAGE_KEY);
-      return;
-    }
-    window.localStorage.setItem(FONT_FAMILY_STORAGE_KEY, JSON.stringify(normalized));
-  } catch {
-    // localStorage quota or access errors shouldn't break the app.
-  }
+  uiFontFamilyPreference.write(name);
 }
 
 /**
@@ -156,23 +138,9 @@ export function writeUiFontFamily(name: string): void {
  * The chosen family is applied WITH the system stack appended
  * (`<name>, var(--font-sans)`) so a name that isn't installed — or a partial one
  * typed so far — degrades to the app's default sans rather than the browser's
- * default serif. (The `var(--ui-font-family, …)` fallback in the CSS only fires
- * when the property is unset, not when it holds an unusable name, so the
- * fallback has to live inside the value too.) This is the single source of the
- * DOM side-effect.
+ * default serif. Also kicks a fire-and-forget webfont load for a catalog family.
+ * This is the single source of the DOM side-effect.
  */
 export function applyUiFontFamily(name: string): void {
-  if (typeof document === "undefined") return;
-  const normalized = normalizeUiFontFamily(name);
-  if (!normalized) {
-    document.documentElement.style.removeProperty("--ui-font-family");
-    return;
-  }
-  // Kick a webfont load when the name matches a catalog family so the glyphs
-  // actually arrive (fire-and-forget: the CSS var is set now and font-display:
-  // swap paints the face once it lands). A non-catalog name is left to the OS —
-  // the existing free-text behavior. The `, var(--font-sans)` fallback covers
-  // the gap before load and any name that never resolves.
-  void loadFontByFamily(normalized);
-  document.documentElement.style.setProperty("--ui-font-family", `${normalized}, var(--font-sans)`);
+  uiFontFamilyPreference.apply(name);
 }
diff --git a/web/src/lib/webFontLoader.test.ts b/web/src/lib/webFontLoader.test.ts
index e4b380f898..190e183dc3 100644
--- a/web/src/lib/webFontLoader.test.ts
+++ b/web/src/lib/webFontLoader.test.ts
@@ -34,8 +34,8 @@ beforeEach(() => {
 });
 
 afterEach(() => {
+  // resetFontLoaderForTests removes the nodes it injected, so no hand-cleanup.
   resetFontLoaderForTests();
-  for (const node of document.querySelectorAll("[data-omnigent-font]")) node.remove();
   vi.restoreAllMocks();
 });
 
@@ -294,6 +294,26 @@ describe("webFontLoader — no-ops", () => {
   });
 });
 
+describe("webFontLoader — resetFontLoaderForTests cleans up the DOM", () => {
+  it("removes injected <link> and <style> nodes it owns", async () => {
+    const pLink = loadFont(inter()); // injects a <link>
+    const pStyle = loadFont(nerd()); // injects a <style>
+    await flush();
+    // Let the stylesheet parse + both readiness probes resolve so the loads
+    // settle before we reset (rather than leaving promises dangling).
+    fireLinkLoads();
+    await flush();
+    fontsLoadCalls.forEach((c) => c.deferred.resolve([{}]));
+    await Promise.all([pLink, pStyle]);
+    expect(links().length).toBe(1);
+    expect(styles().length).toBe(1);
+
+    resetFontLoaderForTests();
+    // The nodes the loader tracked are gone without any hand-removal.
+    expect(document.querySelectorAll("[data-omnigent-font]").length).toBe(0);
+  });
+});
+
 describe("webFontLoader — loadFontByFamily bridge", () => {
   it("loads a catalog family typed as a bare name", async () => {
     const { entry, ready } = loadFontByFamily("Fira Code");
diff --git a/web/src/lib/webFontLoader.ts b/web/src/lib/webFontLoader.ts
index 863d15daf1..fb3beb516a 100644
--- a/web/src/lib/webFontLoader.ts
+++ b/web/src/lib/webFontLoader.ts
@@ -237,8 +237,15 @@ export function loadFontByFamily(
   return { entry, ready: entry ? loadFont(entry) : Promise.resolve(false) };
 }
 
-/** Test-only: clear the in-flight/loaded dedup cache and injected-node index. */
+/**
+ * Test-only: clear the in-flight/loaded dedup cache and remove every node this
+ * loader injected, so a test starts from a clean DOM without hand-removing the
+ * `<link>`/`<style>` nodes itself.
+ */
 export function resetFontLoaderForTests(): void {
   loads.clear();
+  for (const nodes of injected.values()) {
+    for (const node of nodes) node.remove();
+  }
   injected.clear();
 }
diff --git a/web/src/main.tsx b/web/src/main.tsx
index cbbc291577..12e6911b37 100644
--- a/web/src/main.tsx
+++ b/web/src/main.tsx
@@ -15,13 +15,7 @@ import { CapabilitiesProvider } from "./lib/CapabilitiesContext";
 import { resolveIdentity } from "./lib/identity";
 import { initNativeInsets } from "./lib/nativeInsets";
 import { initBrowserTelemetry } from "./lib/telemetry";
-import {
-  applyUiFontFamily,
-  applyUiFontScale,
-  readUiFontFamily,
-  readUiFontSizePx,
-} from "./lib/uiFontPreferences";
-import { loadCodeFontFamily, readCodeFontFamily } from "./lib/codeFontPreferences";
+import { restoreFontPreferences } from "./lib/restoreFontPreferences";
 import { applyThemePalette, readThemePalette } from "./lib/themePalette";
 import { applyCustomTheme, readCustomTheme } from "./lib/customTheme";
 import { initChatStore } from "./store/chatStore";
@@ -58,17 +52,10 @@ void resolveIdentity();
 // No-op off the iOS shell (the inset vars stay at their env()-only defaults).
 initNativeInsets();
 
-// Apply the saved UI font size and family before first paint so there's no flash.
-// applyUiFontFamily also kicks off the webfont load when the saved family is a
-// catalog font, so a chosen font is fetched on boot rather than only on the next
-// Settings change.
-applyUiFontScale(readUiFontSizePx());
-applyUiFontFamily(readUiFontFamily());
-
-// Restore the saved code font's webfont on boot too: the code font rides a
-// pub/sub (not a CSS var), so nothing loads it unless we ask. Editors/terminals
-// re-measure when it lands (see codeFontPreferences.loadCodeFontFamily).
-loadCodeFontFamily(readCodeFontFamily());
+// Apply the saved UI + code font preferences before first paint so there's no
+// flash, and kick off the catalog webfont loads so a chosen font is fetched on
+// boot rather than only on the next Settings change.
+restoreFontPreferences();
 
 // Apply the saved color palette (data-theme on <html>) before first paint too,
 // so the app renders in the chosen theme rather than flashing the brand default.
diff --git a/web/src/pages/SettingsPage.test.tsx b/web/src/pages/SettingsPage.test.tsx
index 7439fd8e2f..ee6514e536 100644
--- a/web/src/pages/SettingsPage.test.tsx
+++ b/web/src/pages/SettingsPage.test.tsx
@@ -10,6 +10,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { TooltipProvider } from "@/components/ui/tooltip";
 import type { Conversation } from "@/hooks/useConversations";
 import type { ElectronUpdateBridge, UpdateConfig, UpdateStatus } from "@/lib/nativeBridge";
+import { UI_FONT_FAMILY_FALLBACK } from "@/lib/uiFontPreferences";
 
 const mocks = vi.hoisted(() => ({
   setTheme: vi.fn(),
@@ -412,7 +413,7 @@ describe("SettingsPage", () => {
     // ...and applied live to the document root, with the system stack appended
     // so an uninstalled/partial name degrades to the default sans, not serif.
     expect(document.documentElement.style.getPropertyValue("--ui-font-family")).toBe(
-      "Inter, var(--font-sans)",
+      `Inter, ${UI_FONT_FAMILY_FALLBACK}`,
     );
     expect(screen.getByTestId("ui-font-family-reset")).not.toBeDisabled();
   });

From d3dac7f52c526239b4005ae9c801cacfe37ccf45 Mon Sep 17 00:00:00 2001
From: Bryan Li <15131870+btli@users.noreply.github.com>
Date: Tue, 21 Jul 2026 09:19:34 -0700
Subject: [PATCH 5/6] fix(web): restore the fixed-width font preference on boot

restoreFontPreferences applied the UI and code font roles on boot but
omitted the fixed-width (monospace chrome) role, so a saved fixed-width
family was neither applied nor fetched until the next Settings change.

Add the CSS-variable-backed fixed-width preference module (shared
factory: --ui-mono-font-family, omnigent:fixed-width-font-family, the
fixedWidth catalog category) and its .font-mono rule, then wire it into
restoreFontPreferences alongside UI and code so all three roles restore
on boot. Extend the restore test to assert the fixed-width family is
read, its CSS var applied, and its webfont load kicked off.

Co-authored-by: Isaac
Signed-off-by: Bryan Li <bryan.li@gmail.com>
---
 web/src/index.css                             | 12 +++
 web/src/lib/fixedWidthFontPreferences.test.ts | 78 +++++++++++++++++++
 web/src/lib/fixedWidthFontPreferences.ts      | 75 ++++++++++++++++++
 web/src/lib/restoreFontPreferences.test.ts    | 31 +++++++-
 web/src/lib/restoreFontPreferences.ts         |  7 +-
 5 files changed, 200 insertions(+), 3 deletions(-)
 create mode 100644 web/src/lib/fixedWidthFontPreferences.test.ts
 create mode 100644 web/src/lib/fixedWidthFontPreferences.ts

diff --git a/web/src/index.css b/web/src/index.css
index a702d1391c..99a22b00b7 100644
--- a/web/src/index.css
+++ b/web/src/index.css
@@ -804,6 +804,18 @@
   }
 }
 
+/* User-controlled fixed-width (monospace chrome) font family. The `font-mono`
+ * utility inlines the literal `--font-mono` stack (Tailwind v4 `@theme inline`),
+ * so a runtime `--font-mono` override is a no-op; this unlayered rule — winning
+ * over the layered utility — swaps in `--ui-mono-font-family` when the Appearance
+ * setting sets it on documentElement (see lib/fixedWidthFontPreferences.ts), and
+ * falls back to the app mono stack when unset. Scoped to the `font-mono` utility
+ * only, so Monaco/xterm (which read `var(--font-mono)` directly) keep the code
+ * font, not this chrome one. */
+.font-mono {
+  font-family: var(--ui-mono-font-family, var(--font-mono));
+}
+
 /* Mobile typography bump.
  *
  * Push the root font-size from the browser default (16px) to 18px below
diff --git a/web/src/lib/fixedWidthFontPreferences.test.ts b/web/src/lib/fixedWidthFontPreferences.test.ts
new file mode 100644
index 0000000000..b6dabe6098
--- /dev/null
+++ b/web/src/lib/fixedWidthFontPreferences.test.ts
@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  applyFixedWidthFontFamily,
+  FIXED_WIDTH_FONT_FAMILY_DEFAULT,
+  FIXED_WIDTH_FONT_FAMILY_FALLBACK,
+  readFixedWidthFontFamily,
+  writeFixedWidthFontFamily,
+} from "./fixedWidthFontPreferences";
+
+const FAMILY_STORAGE_KEY = "omnigent:fixed-width-font-family";
+
+afterEach(() => {
+  localStorage.clear();
+  document.documentElement.style.removeProperty("--ui-mono-font-family");
+});
+
+describe("fixedWidthFontPreferences", () => {
+  it("returns the empty default when nothing is stored", () => {
+    expect(readFixedWidthFontFamily()).toBe(FIXED_WIDTH_FONT_FAMILY_DEFAULT);
+    expect(readFixedWidthFontFamily()).toBe("");
+  });
+
+  it("round-trips a valid family under the dedicated key", () => {
+    writeFixedWidthFontFamily("IBM Plex Mono");
+    expect(readFixedWidthFontFamily()).toBe("IBM Plex Mono");
+    expect(localStorage.getItem(FAMILY_STORAGE_KEY)).toBe(JSON.stringify("IBM Plex Mono"));
+  });
+
+  it("trims surrounding whitespace", () => {
+    writeFixedWidthFontFamily("  Roboto Mono  ");
+    expect(readFixedWidthFontFamily()).toBe("Roboto Mono");
+  });
+
+  it("clears the preference when written empty or whitespace-only", () => {
+    writeFixedWidthFontFamily("IBM Plex Mono");
+    expect(localStorage.getItem(FAMILY_STORAGE_KEY)).not.toBeNull();
+    writeFixedWidthFontFamily("   ");
+    // Empty input removes the key rather than storing a blank string.
+    expect(localStorage.getItem(FAMILY_STORAGE_KEY)).toBeNull();
+    expect(readFixedWidthFontFamily()).toBe("");
+  });
+
+  it("strips characters that could break the CSS declaration", () => {
+    writeFixedWidthFontFamily("Roboto Mono;}body{");
+    expect(readFixedWidthFontFamily()).toBe("Roboto Monobody");
+  });
+
+  it("falls back to the default on a value longer than the cap", () => {
+    writeFixedWidthFontFamily("x".repeat(200));
+    expect(readFixedWidthFontFamily()).toBe(FIXED_WIDTH_FONT_FAMILY_DEFAULT);
+    expect(localStorage.getItem(FAMILY_STORAGE_KEY)).toBeNull();
+  });
+
+  it("falls back to the default on malformed JSON", () => {
+    // Corrupt localStorage should not break app boot.
+    localStorage.setItem(FAMILY_STORAGE_KEY, "}{not json");
+    expect(readFixedWidthFontFamily()).toBe(FIXED_WIDTH_FONT_FAMILY_DEFAULT);
+  });
+
+  it("applies the family with the mono stack appended as a fallback", () => {
+    // The mono stack is appended so an uninstalled/partial name degrades to the
+    // app's default mono, not a browser default.
+    applyFixedWidthFontFamily("IBM Plex Mono");
+    expect(document.documentElement.style.getPropertyValue("--ui-mono-font-family")).toBe(
+      `IBM Plex Mono, ${FIXED_WIDTH_FONT_FAMILY_FALLBACK}`,
+    );
+  });
+
+  it("removes the custom property when applied empty (Default)", () => {
+    applyFixedWidthFontFamily("IBM Plex Mono");
+    expect(document.documentElement.style.getPropertyValue("--ui-mono-font-family")).toBe(
+      `IBM Plex Mono, ${FIXED_WIDTH_FONT_FAMILY_FALLBACK}`,
+    );
+    applyFixedWidthFontFamily("");
+    // Removing the property lets the .font-mono rule fall back to var(--font-mono).
+    expect(document.documentElement.style.getPropertyValue("--ui-mono-font-family")).toBe("");
+  });
+});
diff --git a/web/src/lib/fixedWidthFontPreferences.ts b/web/src/lib/fixedWidthFontPreferences.ts
new file mode 100644
index 0000000000..1c34062c0a
--- /dev/null
+++ b/web/src/lib/fixedWidthFontPreferences.ts
@@ -0,0 +1,75 @@
+// Persisted, app-global preference for the FIXED-WIDTH font — the family used
+// by general monospace UI chrome (the `font-mono` utility: file paths, hashes,
+// inline code chips, log rows, …). This is a distinct role from both the
+// chrome/UI sans font (see lib/uiFontPreferences.ts) and the code editor /
+// terminal font (see lib/codeFontPreferences.ts).
+//
+// Like the UI sans font it rides a CSS custom property, `--ui-mono-font-family`,
+// so it uses the shared CSS-variable-backed shape. It can't reuse `--font-mono`:
+// Tailwind v4's `@theme inline` block inlines the literal mono stack into the
+// `font-mono` utility rather than a `var()`, so setting `--font-mono` at runtime
+// is a no-op. An unlayered `.font-mono` rule in index.css reads
+// `var(--ui-mono-font-family, var(--font-mono))`, so an unset preference falls
+// back to the app mono stack and any value we set on documentElement wins.
+
+import { createCssFontFamilyPreference } from "./cssFontFamilyPreference";
+
+const FONT_FAMILY_STORAGE_KEY = "omnigent:fixed-width-font-family";
+
+/** Empty string = "Default": no override, falls back to the `--font-mono` stack. */
+export const FIXED_WIDTH_FONT_FAMILY_DEFAULT = "";
+
+/**
+ * The mono stack the fixed-width font falls back to when no custom family is set
+ * (or an uninstalled name is chosen). It's the `--font-mono` variable rather
+ * than a literal so the CSS var and the appended fallback stay in lockstep
+ * (mirrors {@link UI_FONT_FAMILY_FALLBACK}).
+ */
+export const FIXED_WIDTH_FONT_FAMILY_FALLBACK = "var(--font-mono)";
+
+// The whole fixed-width font-family preference — read/normalize/persist/apply —
+// is the shared CSS-variable-backed shape. Setting `--ui-mono-font-family` on
+// the document root drives the `.font-mono` rule in index.css; the `fixedWidth`
+// category loads the right catalog entry for a shared family.
+const fixedWidthFontFamilyPreference = createCssFontFamilyPreference({
+  key: FONT_FAMILY_STORAGE_KEY,
+  cssVar: "--ui-mono-font-family",
+  fallback: FIXED_WIDTH_FONT_FAMILY_FALLBACK,
+  category: "fixedWidth",
+});
+
+/**
+ * Read the persisted fixed-width font family.
+ *
+ * Returns "" (Default) when nothing is stored, on a server render (no `window`),
+ * or when the stored value is missing/malformed — never throws, so a corrupt
+ * entry can't break app boot.
+ */
+export function readFixedWidthFontFamily(): string {
+  return fixedWidthFontFamilyPreference.read();
+}
+
+/**
+ * Persist the fixed-width font family. An empty (or all-stripped) name clears
+ * the preference — reverting to Default — rather than storing a blank. Swallows
+ * quota/access errors so a failed write can't break the app.
+ */
+export function writeFixedWidthFontFamily(name: string): void {
+  fixedWidthFontFamilyPreference.write(name);
+}
+
+/**
+ * Apply the given family to the DOM by setting the `--ui-mono-font-family`
+ * variable on the document root; the `.font-mono` rule in index.css reads it as
+ * the monospace-chrome font. An empty name removes the property, restoring the
+ * `--font-mono` stack.
+ *
+ * The chosen family is applied WITH the mono stack appended
+ * (`<name>, var(--font-mono)`) so a name that isn't installed — or a partial one
+ * typed so far — degrades to the app mono rather than a browser default. Also
+ * kicks a fire-and-forget webfont load for a catalog family. This is the single
+ * source of the DOM side-effect.
+ */
+export function applyFixedWidthFontFamily(name: string): void {
+  fixedWidthFontFamilyPreference.apply(name);
+}
diff --git a/web/src/lib/restoreFontPreferences.test.ts b/web/src/lib/restoreFontPreferences.test.ts
index 7dea4cc52a..a7dd6645ea 100644
--- a/web/src/lib/restoreFontPreferences.test.ts
+++ b/web/src/lib/restoreFontPreferences.test.ts
@@ -1,10 +1,21 @@
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { restoreFontPreferences } from "./restoreFontPreferences";
+import { loadFontByFamily } from "./webFontLoader";
+
+// Spy on the loader so we can assert a saved family's webfont load is kicked off
+// on boot, per role, without depending on jsdom's font machinery.
+vi.mock("./webFontLoader", () => ({
+  loadFontByFamily: vi.fn(() => ({ entry: undefined, ready: Promise.resolve(false) })),
+}));
+
+const mockLoadFontByFamily = vi.mocked(loadFontByFamily);
 
 afterEach(() => {
   localStorage.clear();
   document.documentElement.style.removeProperty("--ui-font-scale");
   document.documentElement.style.removeProperty("--ui-font-family");
+  document.documentElement.style.removeProperty("--ui-mono-font-family");
+  vi.clearAllMocks();
 });
 
 describe("restoreFontPreferences", () => {
@@ -21,10 +32,26 @@ describe("restoreFontPreferences", () => {
     );
   });
 
+  it("restores the saved fixed-width family on boot: applies its CSS var and loads it", () => {
+    localStorage.setItem("omnigent:fixed-width-font-family", JSON.stringify("IBM Plex Mono"));
+
+    restoreFontPreferences();
+
+    // The fixed-width family lands on its own CSS var with the mono fallback
+    // appended — not cross-wired to the UI var.
+    expect(document.documentElement.style.getPropertyValue("--ui-mono-font-family")).toBe(
+      "IBM Plex Mono, var(--font-mono)",
+    );
+    // And its webfont load is kicked off under the fixedWidth category so a
+    // catalog family is fetched on boot, not only on the next Settings change.
+    expect(mockLoadFontByFamily).toHaveBeenCalledWith("IBM Plex Mono", "fixedWidth");
+  });
+
   it("applies defaults when nothing is stored (no throw)", () => {
     expect(() => restoreFontPreferences()).not.toThrow();
-    // Default size 16 → scale 1; family unset → no override.
+    // Default size 16 → scale 1; families unset → no overrides.
     expect(document.documentElement.style.getPropertyValue("--ui-font-scale")).toBe("1");
     expect(document.documentElement.style.getPropertyValue("--ui-font-family")).toBe("");
+    expect(document.documentElement.style.getPropertyValue("--ui-mono-font-family")).toBe("");
   });
 });
diff --git a/web/src/lib/restoreFontPreferences.ts b/web/src/lib/restoreFontPreferences.ts
index c6cff25f58..bcb912063e 100644
--- a/web/src/lib/restoreFontPreferences.ts
+++ b/web/src/lib/restoreFontPreferences.ts
@@ -14,14 +14,18 @@ import {
   readUiFontFamily,
   readUiFontSizePx,
 } from "./uiFontPreferences";
+import { applyFixedWidthFontFamily, readFixedWidthFontFamily } from "./fixedWidthFontPreferences";
 import { loadCodeFontFamily, readCodeFontFamily } from "./codeFontPreferences";
 
 /**
- * Restore the saved UI + code font preferences on boot.
+ * Restore the saved UI + fixed-width + code font preferences on boot.
  *
  * - UI font: applies the size (`--ui-font-scale`) and family (`--ui-font-family`)
  *   to the document root; `applyUiFontFamily` also kicks the catalog webfont
  *   load for the saved family.
+ * - Fixed-width font: rides `--ui-mono-font-family` like the UI font;
+ *   `applyFixedWidthFontFamily` sets the var and kicks the catalog webfont load
+ *   for the saved family.
  * - Code font: rides a pub/sub (not a CSS var), so nothing loads it unless we
  *   ask — `loadCodeFontFamily` fetches it and mounted editors/terminals
  *   re-measure when it lands.
@@ -29,5 +33,6 @@ import { loadCodeFontFamily, readCodeFontFamily } from "./codeFontPreferences";
 export function restoreFontPreferences(): void {
   applyUiFontScale(readUiFontSizePx());
   applyUiFontFamily(readUiFontFamily());
+  applyFixedWidthFontFamily(readFixedWidthFontFamily());
   loadCodeFontFamily(readCodeFontFamily());
 }

From 1aa568bf6832c93658a9f57ea884b8d5b3bfa177 Mon Sep 17 00:00:00 2001
From: Bryan Li <15131870+btli@users.noreply.github.com>
Date: Mon, 20 Jul 2026 10:54:06 -0700
Subject: [PATCH 6/6] feat(web): searchable font dropdowns for the three font
 roles
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Appearance font-family controls were free-text inputs that only set a
family name; nothing loaded the font, so picking one the OS lacked silently
fell back. Building on the PR-1 catalog + webfont loader, replace them with
searchable comboboxes — one per interface font role:

- Font family (sans / UI chrome) → catalog `sans`, --ui-font-family.
- Fixed width (monospace chrome) → catalog `fixedWidth`, new
  --ui-mono-font-family read by the `font-mono` utility.
- Code font (editor + terminal) → catalog `code` (incl. Nerd Fonts),
  code-font pub/sub.

Each control previews every option in its own face, loads the webfont on
selection so it renders without a local install, and keeps a free-text
escape hatch plus an out-of-catalog custom row so a previously-typed family
stays honored. localStorage keys are unchanged; a parallel
fixedWidthFontPreferences module mirrors the ui/code pattern and restores on
boot in main.tsx / embed.tsx.

Co-authored-by: omnigent <noreply@omnigent.ai>
Signed-off-by: Bryan Li <bryan.li@gmail.com>
---
 .../components/FontFamilyCombobox.test.tsx    | 119 ++++++++++
 web/src/components/FontFamilyCombobox.tsx     | 222 ++++++++++++++++++
 web/src/pages/SettingsPage.test.tsx           | 159 ++++++++++---
 web/src/pages/SettingsPage.tsx                | 156 ++++++------
 4 files changed, 547 insertions(+), 109 deletions(-)
 create mode 100644 web/src/components/FontFamilyCombobox.test.tsx
 create mode 100644 web/src/components/FontFamilyCombobox.tsx

diff --git a/web/src/components/FontFamilyCombobox.test.tsx b/web/src/components/FontFamilyCombobox.test.tsx
new file mode 100644
index 0000000000..8c69e77f40
--- /dev/null
+++ b/web/src/components/FontFamilyCombobox.test.tsx
@@ -0,0 +1,119 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { FontFamilyCombobox } from "./FontFamilyCombobox";
+import { FONT_CATALOG_BY_CATEGORY } from "@/lib/fontCatalog";
+import { resetFontLoaderForTests } from "@/lib/webFontLoader";
+
+// jsdom has no FontFaceSet; stub document.fonts.load so the loader (invoked when
+// the dropdown opens to render previews) doesn't throw.
+beforeEach(() => {
+  Object.defineProperty(document, "fonts", {
+    configurable: true,
+    value: { load: vi.fn(() => Promise.resolve([])) },
+  });
+});
+
+afterEach(() => {
+  cleanup();
+  // The loader dedups by resource across calls; clear it so each test's open
+  // re-injects rather than hitting a cached promise.
+  resetFontLoaderForTests();
+  for (const node of document.querySelectorAll("[data-omnigent-font]")) node.remove();
+  vi.restoreAllMocks();
+});
+
+function renderCombobox(props: Partial<Parameters<typeof FontFamilyCombobox>[0]> = {}) {
+  const onChange = vi.fn();
+  render(
+    <FontFamilyCombobox
+      category="sans"
+      value=""
+      onChange={onChange}
+      defaultLabel="System default"
+      ariaLabel="UI font family"
+      testId="test-font"
+      previewFallback="var(--font-sans)"
+      {...props}
+    />,
+  );
+  return { onChange };
+}
+
+describe("FontFamilyCombobox", () => {
+  it("renders every font in its category (plus the default row)", () => {
+    renderCombobox({ category: "sans" });
+    fireEvent.click(screen.getByTestId("test-font-trigger"));
+
+    expect(screen.getByTestId("test-font-option-default")).toBeInTheDocument();
+    for (const entry of FONT_CATALOG_BY_CATEGORY.sans) {
+      if (!entry.family) continue; // the empty "system default" entry is the default row
+      expect(screen.getByTestId(`test-font-option-${entry.family}`)).toBeInTheDocument();
+    }
+    // A code-only font must NOT leak into the sans list.
+    expect(screen.queryByTestId("test-font-option-JetBrains Mono")).toBeNull();
+  });
+
+  it("calls onChange with the selected catalog family and loads its webfont", () => {
+    const { onChange } = renderCombobox({ category: "sans" });
+    fireEvent.click(screen.getByTestId("test-font-trigger"));
+    // Opening the dropdown eagerly kicks the loader for each catalog face so
+    // its preview renders in-face — the google-css2 path injects a stylesheet.
+    expect(document.querySelector(`link[data-omnigent-font]`)).not.toBeNull();
+
+    fireEvent.click(screen.getByTestId("test-font-option-Inter"));
+    expect(onChange).toHaveBeenCalledWith("Inter");
+  });
+
+  it("calls onChange with an empty string for the default row", () => {
+    const { onChange } = renderCombobox({ category: "sans", value: "Inter" });
+    fireEvent.click(screen.getByTestId("test-font-trigger"));
+    fireEvent.click(screen.getByTestId("test-font-option-default"));
+    expect(onChange).toHaveBeenCalledWith("");
+  });
+
+  it("surfaces a stored non-catalog family as a selectable custom row", () => {
+    const { onChange } = renderCombobox({ category: "sans", value: "My Local Font" });
+    expect(screen.getByTestId("test-font-trigger")).toHaveTextContent("My Local Font");
+
+    fireEvent.click(screen.getByTestId("test-font-trigger"));
+    const custom = screen.getByTestId("test-font-option-custom-current");
+    expect(custom).toHaveTextContent("My Local Font");
+    fireEvent.click(custom);
+    expect(onChange).toHaveBeenCalledWith("My Local Font");
+  });
+
+  it("shows a cross-category catalog family as a custom row for this category", () => {
+    // "Fira Code" is a code-catalog family, absent from the sans list. Stored in
+    // the sans slot it must render as Custom — not be silently swallowed by a
+    // cross-category catalog match — so the user can see and keep their entry.
+    const { onChange } = renderCombobox({ category: "sans", value: "Fira Code" });
+    expect(screen.getByTestId("test-font-trigger")).toHaveTextContent("Fira Code");
+
+    fireEvent.click(screen.getByTestId("test-font-trigger"));
+    // It is NOT offered as a normal sans option…
+    expect(screen.queryByTestId("test-font-option-Fira Code")).toBeNull();
+    // …it is the custom row instead.
+    const custom = screen.getByTestId("test-font-option-custom-current");
+    expect(custom).toHaveTextContent("Fira Code");
+    expect(custom).toHaveTextContent("Custom");
+    fireEvent.click(custom);
+    expect(onChange).toHaveBeenCalledWith("Fira Code");
+  });
+
+  it("treats a same-category catalog family as a known option, not custom", () => {
+    // The mirror of the cross-category case: a fixedWidth family stored in the
+    // fixedWidth slot is a normal option, so no custom row appears for it.
+    renderCombobox({ category: "fixedWidth", value: "IBM Plex Mono" });
+    fireEvent.click(screen.getByTestId("test-font-trigger"));
+    expect(screen.getByTestId("test-font-option-IBM Plex Mono")).toBeInTheDocument();
+    expect(screen.queryByTestId("test-font-option-custom-current")).toBeNull();
+  });
+
+  it("applies a typed family the catalog doesn't list (free-text escape hatch)", () => {
+    const { onChange } = renderCombobox({ category: "code" });
+    fireEvent.click(screen.getByTestId("test-font-trigger"));
+    fireEvent.change(screen.getByTestId("test-font-input"), { target: { value: "Menlo" } });
+    fireEvent.click(screen.getByTestId("test-font-option-custom"));
+    expect(onChange).toHaveBeenCalledWith("Menlo");
+  });
+});
diff --git a/web/src/components/FontFamilyCombobox.tsx b/web/src/components/FontFamilyCombobox.tsx
new file mode 100644
index 0000000000..a67b9a2cc8
--- /dev/null
+++ b/web/src/components/FontFamilyCombobox.tsx
@@ -0,0 +1,222 @@
+// Searchable font picker for the Settings → Appearance font controls.
+//
+// Replaces the old free-text font inputs: lists a font-catalog category (see
+// lib/fontCatalog.ts) by label, each option previewed in its own face, with a
+// "Default" row and a free-text escape hatch so a custom family the catalog
+// doesn't know is still honored. Selecting a catalog option triggers the
+// webfont loader (via the caller's preference-apply, and eagerly on open here so
+// previews render) so the font actually loads without a local install.
+
+import { useEffect, useMemo, useState } from "react";
+import { ChevronsUpDownIcon } from "lucide-react";
+
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "@/components/ui/command";
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+import { type FontCategory, FONT_CATALOG_BY_CATEGORY } from "@/lib/fontCatalog";
+import { loadFontByFamily } from "@/lib/webFontLoader";
+import { cn } from "@/lib/utils";
+
+interface FontFamilyComboboxProps {
+  /** Which catalog category to list. */
+  category: FontCategory;
+  /** Current family; "" means the default (no override). */
+  value: string;
+  /** Fired with the chosen family ("" for default). */
+  onChange: (family: string) => void;
+  /** Label for the "no override" row, e.g. "System default" / "Editor default". */
+  defaultLabel: string;
+  /** Accessible name for the trigger + search. */
+  ariaLabel: string;
+  /** Base for the control's data-testids (`<testId>-trigger`, `-input`, …). */
+  testId: string;
+  /** Fallback CSS stack appended to a preview so an unloaded face degrades. */
+  previewFallback: string;
+}
+
+/** A resolved option row: the family to apply and how to display it. */
+interface FontOption {
+  /** Family to persist/apply; "" = default. */
+  family: string;
+  /** Human label shown in the trigger and list. */
+  label: string;
+}
+
+export function FontFamilyCombobox({
+  category,
+  value,
+  onChange,
+  defaultLabel,
+  ariaLabel,
+  testId,
+  previewFallback,
+}: FontFamilyComboboxProps) {
+  const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState("");
+
+  // Catalog entries for this role, deduped by family (a family can appear more
+  // than once — e.g. IBM Plex Mono in fixedWidth and code). The empty-family
+  // "system default" catalog entry is dropped: the Default row below covers it.
+  const options = useMemo<FontOption[]>(() => {
+    const seen = new Set<string>();
+    const rows: FontOption[] = [];
+    for (const entry of FONT_CATALOG_BY_CATEGORY[category]) {
+      if (!entry.family) continue;
+      const key = entry.family.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      rows.push({ family: entry.family, label: entry.label });
+    }
+    return rows;
+  }, [category]);
+
+  // A stored family this category's dropdown doesn't offer (a locally-installed
+  // or previously typed font, or a family that only lives in a DIFFERENT catalog
+  // category). Surface it as its own selectable row so the current choice is
+  // visible and re-selectable — the backward-compat escape hatch. Membership is
+  // decided against THIS category's options only: a cross-category catalog match
+  // (e.g. a sans slot holding "Fira Code", a code-only family) must still show
+  // as Custom, so we don't use getFontByFamily's cross-category fallback here.
+  const customOption = useMemo<FontOption | null>(() => {
+    if (!value) return null;
+    const key = value.toLowerCase();
+    if (options.some((option) => option.family.toLowerCase() === key)) return null;
+    return { family: value, label: value };
+  }, [value, options]);
+
+  // On open, eagerly load every listed catalog face so its preview renders in
+  // its own font rather than the fallback. Fire-and-forget; non-catalog and
+  // bundled entries no-op inside the loader.
+  useEffect(() => {
+    if (!open) return;
+    for (const option of options) loadFontByFamily(option.family, category);
+  }, [open, options, category]);
+
+  const selectedLabel = value
+    ? (customOption?.label ??
+      options.find((option) => option.family.toLowerCase() === value.toLowerCase())?.label ??
+      value)
+    : defaultLabel;
+
+  const select = (family: string) => {
+    onChange(family);
+    setOpen(false);
+    setSearch("");
+  };
+
+  // Let the user apply a typed family the list doesn't contain (custom fallback).
+  const trimmedSearch = search.trim();
+  const hasExactMatch = options.some(
+    (option) => option.label.toLowerCase() === trimmedSearch.toLowerCase(),
+  );
+  const showCustomEntry = trimmedSearch.length > 0 && !hasExactMatch;
+
+  const previewStyle = (family: string) => ({ fontFamily: `"${family}", ${previewFallback}` });
+
+  return (
+    <Popover
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (!next) setSearch("");
+      }}
+    >
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          role="combobox"
+          aria-expanded={open}
+          aria-label={ariaLabel}
+          data-testid={`${testId}-trigger`}
+          className={cn(
+            "flex h-9 w-56 items-center justify-between gap-2 rounded-md border border-input bg-background px-3 text-sm shadow-xs transition-colors outline-none dark:bg-input/30",
+            "hover:border-border-strong focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50",
+          )}
+        >
+          <span className="min-w-0 truncate" style={value ? previewStyle(value) : undefined}>
+            {selectedLabel}
+          </span>
+          <ChevronsUpDownIcon className="size-4 shrink-0 opacity-50" />
+        </button>
+      </PopoverTrigger>
+      <PopoverContent align="end" className="w-72 p-0" data-testid={`${testId}-popover`}>
+        <Command
+          // Search matches labels; keep the typed custom entry visible too.
+          filter={(itemValue, query) =>
+            itemValue.toLowerCase().includes(query.trim().toLowerCase()) ? 1 : 0
+          }
+        >
+          <CommandInput
+            placeholder={`Search ${ariaLabel.toLowerCase()}…`}
+            aria-label={ariaLabel}
+            data-testid={`${testId}-input`}
+            value={search}
+            onValueChange={setSearch}
+          />
+          <CommandList>
+            <CommandEmpty>No fonts found.</CommandEmpty>
+            <CommandGroup>
+              {/* Default (no override). */}
+              <CommandItem
+                value={defaultLabel}
+                data-testid={`${testId}-option-default`}
+                data-checked={value === ""}
+                onSelect={() => select("")}
+              >
+                <span className="truncate">{defaultLabel}</span>
+              </CommandItem>
+
+              {/* An out-of-catalog stored family, so the current custom value shows. */}
+              {customOption && (
+                <CommandItem
+                  value={customOption.label}
+                  data-testid={`${testId}-option-custom-current`}
+                  data-checked
+                  onSelect={() => select(customOption.family)}
+                >
+                  <span className="truncate" style={previewStyle(customOption.family)}>
+                    {customOption.label}
+                  </span>
+                  <span className="ml-2 shrink-0 text-xs text-muted-foreground">Custom</span>
+                </CommandItem>
+              )}
+
+              {options.map((option) => (
+                <CommandItem
+                  key={option.family}
+                  value={option.label}
+                  data-testid={`${testId}-option-${option.family}`}
+                  data-checked={option.family.toLowerCase() === value.toLowerCase()}
+                  onSelect={() => select(option.family)}
+                >
+                  <span className="truncate" style={previewStyle(option.family)}>
+                    {option.label}
+                  </span>
+                </CommandItem>
+              ))}
+
+              {/* Free-text escape hatch: apply whatever family was typed. */}
+              {showCustomEntry && (
+                <CommandItem
+                  value={`__custom__ ${trimmedSearch}`}
+                  data-testid={`${testId}-option-custom`}
+                  onSelect={() => select(trimmedSearch)}
+                >
+                  <span className="truncate" style={previewStyle(trimmedSearch)}>
+                    Use “{trimmedSearch}”
+                  </span>
+                </CommandItem>
+              )}
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  );
+}
diff --git a/web/src/pages/SettingsPage.test.tsx b/web/src/pages/SettingsPage.test.tsx
index ee6514e536..dd35a76430 100644
--- a/web/src/pages/SettingsPage.test.tsx
+++ b/web/src/pages/SettingsPage.test.tsx
@@ -196,6 +196,10 @@ afterEach(() => {
   // don't leak persisted state or the --ui-font-scale variable into each other.
   localStorage.clear();
   document.documentElement.style.removeProperty("--ui-font-scale");
+  // The font-family pickers set these on <html>; clear so one test's choice
+  // doesn't leak into the next.
+  document.documentElement.style.removeProperty("--ui-font-family");
+  document.documentElement.style.removeProperty("--ui-mono-font-family");
   // The palette picker sets data-theme on <html>; clear it so a palette
   // selected in one test doesn't leak into the next.
   document.documentElement.removeAttribute("data-theme");
@@ -394,20 +398,19 @@ describe("SettingsPage", () => {
     expect(screen.getByTestId("ui-font-size-inc")).not.toBeDisabled();
   });
 
-  it("shows the empty font family default and applies + persists a typed name", () => {
+  it("shows the system default and selecting a catalog sans font persists + applies it", () => {
     localStorage.clear();
     document.documentElement.style.removeProperty("--ui-font-family");
     renderPage("/settings/appearance");
-    const input = screen.getByTestId("ui-font-family-input") as HTMLInputElement;
-    // No stored preference → empty input, System-default placeholder, no override.
-    expect(input.value).toBe("");
-    expect(input.placeholder).toBe("System default");
+    const trigger = screen.getByTestId("ui-font-family-trigger");
+    // No stored preference → the trigger shows "System default", no override applied.
+    expect(trigger).toHaveTextContent("System default");
     expect(document.documentElement.style.getPropertyValue("--ui-font-family")).toBe("");
-    // Reset has nothing to do at the default.
-    expect(screen.getByTestId("ui-font-family-reset")).toBeDisabled();
 
-    fireEvent.change(input, { target: { value: "Inter" } });
-    expect(input.value).toBe("Inter");
+    // Open the dropdown and pick a catalog font.
+    fireEvent.click(trigger);
+    fireEvent.click(screen.getByTestId("ui-font-family-option-Inter"));
+
     // The choice is persisted so it survives a refresh...
     expect(localStorage.getItem("omnigent:ui-font-family")).toBe(JSON.stringify("Inter"));
     // ...and applied live to the document root, with the system stack appended
@@ -415,23 +418,105 @@ describe("SettingsPage", () => {
     expect(document.documentElement.style.getPropertyValue("--ui-font-family")).toBe(
       `Inter, ${UI_FONT_FAMILY_FALLBACK}`,
     );
-    expect(screen.getByTestId("ui-font-family-reset")).not.toBeDisabled();
+    expect(screen.getByTestId("ui-font-family-trigger")).toHaveTextContent("Inter");
   });
 
-  it("reset restores the system default font family", () => {
-    localStorage.setItem("omnigent:ui-font-family", JSON.stringify("Georgia"));
+  it("selecting System default restores the system font family", () => {
+    localStorage.setItem("omnigent:ui-font-family", JSON.stringify("Inter"));
     renderPage("/settings/appearance");
-    const input = screen.getByTestId("ui-font-family-input") as HTMLInputElement;
     // The control reflects the stored preference on mount.
-    expect(input.value).toBe("Georgia");
+    expect(screen.getByTestId("ui-font-family-trigger")).toHaveTextContent("Inter");
 
-    fireEvent.click(screen.getByTestId("ui-font-family-reset"));
-    // Reset clears the field, the applied property, and the stored key.
-    expect(input.value).toBe("");
+    fireEvent.click(screen.getByTestId("ui-font-family-trigger"));
+    fireEvent.click(screen.getByTestId("ui-font-family-option-default"));
+
+    // Choosing the default clears the applied property and the stored key.
+    expect(screen.getByTestId("ui-font-family-trigger")).toHaveTextContent("System default");
     expect(document.documentElement.style.getPropertyValue("--ui-font-family")).toBe("");
     expect(localStorage.getItem("omnigent:ui-font-family")).toBeNull();
   });
 
+  it("honors a previously-typed custom sans family the catalog doesn't know", () => {
+    // A family stored before the catalog existed (or a locally-installed font).
+    localStorage.setItem("omnigent:ui-font-family", JSON.stringify("Comic Sans MS"));
+    renderPage("/settings/appearance");
+    // The custom value is shown on the trigger and stays selectable as its own row.
+    expect(screen.getByTestId("ui-font-family-trigger")).toHaveTextContent("Comic Sans MS");
+    fireEvent.click(screen.getByTestId("ui-font-family-trigger"));
+    expect(screen.getByTestId("ui-font-family-option-custom-current")).toHaveTextContent(
+      "Comic Sans MS",
+    );
+  });
+
+  it("applies a typed family that isn't in the catalog (free-text fallback)", () => {
+    localStorage.clear();
+    renderPage("/settings/appearance");
+    fireEvent.click(screen.getByTestId("ui-font-family-trigger"));
+    // Type a family the catalog doesn't list; a "Use …" escape-hatch row appears.
+    fireEvent.change(screen.getByTestId("ui-font-family-input"), {
+      target: { value: "Papyrus" },
+    });
+    fireEvent.click(screen.getByTestId("ui-font-family-option-custom"));
+
+    expect(localStorage.getItem("omnigent:ui-font-family")).toBe(JSON.stringify("Papyrus"));
+    expect(document.documentElement.style.getPropertyValue("--ui-font-family")).toBe(
+      "Papyrus, var(--font-sans)",
+    );
+  });
+
+  it("shows the fixed-width font default and selecting a catalog font persists + applies it", () => {
+    localStorage.clear();
+    document.documentElement.style.removeProperty("--ui-mono-font-family");
+    renderPage("/settings/appearance");
+    const trigger = screen.getByTestId("fixed-width-font-family-trigger");
+    expect(trigger).toHaveTextContent("Default");
+    expect(document.documentElement.style.getPropertyValue("--ui-mono-font-family")).toBe("");
+
+    fireEvent.click(trigger);
+    fireEvent.click(screen.getByTestId("fixed-width-font-family-option-IBM Plex Mono"));
+
+    // Persisted under the dedicated fixed-width key and applied to its own CSS var.
+    expect(localStorage.getItem("omnigent:fixed-width-font-family")).toBe(
+      JSON.stringify("IBM Plex Mono"),
+    );
+    expect(document.documentElement.style.getPropertyValue("--ui-mono-font-family")).toBe(
+      "IBM Plex Mono, var(--font-mono)",
+    );
+    expect(screen.getByTestId("fixed-width-font-family-trigger")).toHaveTextContent(
+      "IBM Plex Mono",
+    );
+  });
+
+  it("keeps the fixed-width chrome font isolated from the code (Monaco/xterm) font", () => {
+    // The fixed-width control drives --ui-mono-font-family (chrome monospace,
+    // read by the `.font-mono` utility); Monaco/xterm read the code-font pref /
+    // --font-mono directly. Setting one role must not touch the other's storage.
+    localStorage.clear();
+    document.documentElement.style.removeProperty("--ui-mono-font-family");
+    renderPage("/settings/appearance");
+
+    // Pick a fixed-width font: it persists to the fixed-width key only — the code
+    // font pref stays untouched, so the editor/terminal font is unaffected.
+    fireEvent.click(screen.getByTestId("fixed-width-font-family-trigger"));
+    fireEvent.click(screen.getByTestId("fixed-width-font-family-option-IBM Plex Mono"));
+    expect(localStorage.getItem("omnigent:fixed-width-font-family")).toBe(
+      JSON.stringify("IBM Plex Mono"),
+    );
+    expect(localStorage.getItem("omnigent:code-font-family")).toBeNull();
+
+    // Pick a code font: it persists to the code-font key and leaves the
+    // fixed-width chrome var/key exactly as the fixed-width choice set them.
+    fireEvent.click(screen.getByTestId("code-font-family-trigger"));
+    fireEvent.click(screen.getByTestId("code-font-family-option-Fira Code"));
+    expect(localStorage.getItem("omnigent:code-font-family")).toBe(JSON.stringify("Fira Code"));
+    expect(localStorage.getItem("omnigent:fixed-width-font-family")).toBe(
+      JSON.stringify("IBM Plex Mono"),
+    );
+    expect(document.documentElement.style.getPropertyValue("--ui-mono-font-family")).toBe(
+      "IBM Plex Mono, var(--font-mono)",
+    );
+  });
+
   it("lets you clear and retype the font size without clamping mid-edit", () => {
     localStorage.setItem("omnigent:ui-font-size", "13");
     renderPage("/settings/appearance");
@@ -533,33 +618,41 @@ describe("SettingsPage", () => {
     expect(localStorage.getItem("omnigent:code-font-size")).toBe("10");
   });
 
-  it("shows the empty code font family default and applies + persists a typed name", () => {
+  it("shows the code font default and selecting a catalog code font persists it", () => {
     localStorage.clear();
     renderPage("/settings/appearance");
-    const input = screen.getByTestId("code-font-family-input") as HTMLInputElement;
-    // No stored preference → empty input, editor-default placeholder.
-    expect(input.value).toBe("");
-    expect(input.placeholder).toBe("Editor default");
-    // Reset has nothing to do at the default.
-    expect(screen.getByTestId("code-font-family-reset")).toBeDisabled();
+    const trigger = screen.getByTestId("code-font-family-trigger");
+    // No stored preference → the trigger shows the editor default.
+    expect(trigger).toHaveTextContent("Editor default");
+
+    fireEvent.click(trigger);
+    fireEvent.click(screen.getByTestId("code-font-family-option-Fira Code"));
 
-    fireEvent.change(input, { target: { value: "Fira Code" } });
-    expect(input.value).toBe("Fira Code");
     // The choice is persisted under the code-font family key so it survives a refresh.
     expect(localStorage.getItem("omnigent:code-font-family")).toBe(JSON.stringify("Fira Code"));
-    expect(screen.getByTestId("code-font-family-reset")).not.toBeDisabled();
+    expect(screen.getByTestId("code-font-family-trigger")).toHaveTextContent("Fira Code");
   });
 
-  it("reset restores the default code font family", () => {
+  it("lists Nerd Fonts in the code font dropdown", () => {
+    localStorage.clear();
+    renderPage("/settings/appearance");
+    fireEvent.click(screen.getByTestId("code-font-family-trigger"));
+    // A Nerd Font variant is offered for the editor/terminal role.
+    expect(
+      screen.getByTestId("code-font-family-option-JetBrainsMono Nerd Font Mono"),
+    ).toBeInTheDocument();
+  });
+
+  it("selecting Editor default restores the default code font family", () => {
     localStorage.setItem("omnigent:code-font-family", JSON.stringify("JetBrains Mono"));
     renderPage("/settings/appearance");
-    const input = screen.getByTestId("code-font-family-input") as HTMLInputElement;
     // The control reflects the stored preference on mount.
-    expect(input.value).toBe("JetBrains Mono");
+    expect(screen.getByTestId("code-font-family-trigger")).toHaveTextContent("JetBrains Mono");
 
-    fireEvent.click(screen.getByTestId("code-font-family-reset"));
-    // Reset clears the field and the stored key.
-    expect(input.value).toBe("");
+    fireEvent.click(screen.getByTestId("code-font-family-trigger"));
+    fireEvent.click(screen.getByTestId("code-font-family-option-default"));
+    // Choosing the default clears the stored key.
+    expect(screen.getByTestId("code-font-family-trigger")).toHaveTextContent("Editor default");
     expect(localStorage.getItem("omnigent:code-font-family")).toBeNull();
   });
 
diff --git a/web/src/pages/SettingsPage.tsx b/web/src/pages/SettingsPage.tsx
index bb6852540c..6c6f198f59 100644
--- a/web/src/pages/SettingsPage.tsx
+++ b/web/src/pages/SettingsPage.tsx
@@ -100,7 +100,6 @@ import {
   clampUiFontSizePx,
   readUiFontFamily,
   readUiFontSizePx,
-  UI_FONT_FAMILY_DEFAULT,
   UI_FONT_SIZE_MAX,
   UI_FONT_SIZE_MIN,
   UI_FONT_SIZE_STEP,
@@ -109,7 +108,7 @@ import {
 } from "@/lib/uiFontPreferences";
 import {
   clampCodeFontSizePx,
-  CODE_FONT_FAMILY_DEFAULT,
+  CODE_FONT_FAMILY_FALLBACK,
   CODE_FONT_SIZE_MAX,
   CODE_FONT_SIZE_MIN,
   CODE_FONT_SIZE_STEP,
@@ -118,6 +117,12 @@ import {
   writeCodeFontFamily,
   writeCodeFontSizePx,
 } from "@/lib/codeFontPreferences";
+import {
+  applyFixedWidthFontFamily,
+  readFixedWidthFontFamily,
+  writeFixedWidthFontFamily,
+} from "@/lib/fixedWidthFontPreferences";
+import { FontFamilyCombobox } from "@/components/FontFamilyCombobox";
 import {
   readTerminalThemeMode,
   writeTerminalThemeMode,
@@ -834,6 +839,8 @@ function AppearanceSection() {
 
         <UiFontFamilyControl />
 
+        <FixedWidthFontFamilyControl />
+
         {/* Code font (Monaco + xterm) sits as its own two rows — labelled in full
             ("Code font size" / "Code font family") rather than under a shared
             heading — so each control reads unambiguously next to the UI-font rows
@@ -1001,12 +1008,14 @@ function UiFontSizeControl() {
 }
 
 /**
- * UI font family picker. Free-text (Cursor-style): type any font installed on
- * this device; blank means "System default", which falls back to the existing
- * --font-sans stack. Applies live and persists on every change via the
- * --ui-font-family variable (see lib/uiFontPreferences.ts). Like the size
- * control it stays visible when embedded — a per-device readability pref that
- * doesn't conflict with host theming.
+ * UI font family picker. A searchable dropdown over the catalog's `sans` role
+ * (see lib/fontCatalog.ts); selecting an option loads the webfont so it renders
+ * without a local install and applies it live via the --ui-font-family variable
+ * (see lib/uiFontPreferences.ts). "System default" falls back to --font-sans; a
+ * previously-typed custom family the catalog doesn't know stays honored (shown
+ * as its own row) and any name can still be typed in the search as an escape
+ * hatch. Like the size control it stays visible when embedded — a per-device
+ * readability pref that doesn't conflict with host theming.
  */
 function UiFontFamilyControl() {
   const [family, setFamily] = useState(() => readUiFontFamily());
@@ -1017,47 +1026,62 @@ function UiFontFamilyControl() {
     applyUiFontFamily(next);
   }, []);
 
-  const isDefault = family.trim() === UI_FONT_FAMILY_DEFAULT;
-
   return (
     <div className="flex flex-wrap items-center justify-between gap-x-6 gap-y-3">
-      {/* Take the remaining width (and let the longer description wrap within
-          this column) so the input stays inline instead of dropping to its own
-          row — matches the font-size row's alignment. */}
       <div className="flex min-w-0 flex-1 flex-col">
         <span className="text-sm font-medium">Font family</span>
         <span className="text-sm text-muted-foreground">
-          Use any font installed on this device. Leave blank for the system default.
+          Interface text font. Pick from the catalog or type any font installed on this device.
         </span>
       </div>
-      {/* Reset sits left of the input so the input is the rightmost element and
-          its right edge lines up flush with the font-size stepper above.
-          `invisible` (not removed) at the default keeps the row from shifting. */}
-      <div role="group" aria-label="Font family" className="flex shrink-0 items-center gap-2">
-        <Button
-          type="button"
-          variant="ghost"
-          size="sm"
-          data-testid="ui-font-family-reset"
-          disabled={isDefault}
-          className={cn("h-9", isDefault && "invisible")}
-          onClick={() => update(UI_FONT_FAMILY_DEFAULT)}
-        >
-          Reset
-        </Button>
-        <Input
-          type="text"
-          aria-label="UI font family"
-          data-testid="ui-font-family-input"
-          placeholder="System default"
-          spellCheck={false}
-          autoCapitalize="off"
-          autoCorrect="off"
-          className="h-9 w-56"
-          value={family}
-          onChange={(e) => update(e.target.value)}
-        />
+      <FontFamilyCombobox
+        category="sans"
+        value={family}
+        onChange={update}
+        defaultLabel="System default"
+        ariaLabel="UI font family"
+        testId="ui-font-family"
+        previewFallback="var(--font-sans)"
+      />
+    </div>
+  );
+}
+
+/**
+ * Fixed-width (monospace chrome) font family picker. A searchable dropdown over
+ * the catalog's `fixedWidth` role; selecting an option loads the webfont and
+ * applies it live via the --ui-mono-font-family variable, which the `font-mono`
+ * utility reads (see lib/fixedWidthFontPreferences.ts) — file paths, hashes,
+ * inline code chips and log rows across the chrome. Distinct from the code
+ * editor/terminal font below. "Default" falls back to the --font-mono stack; a
+ * custom typed family stays honored.
+ */
+function FixedWidthFontFamilyControl() {
+  const [family, setFamily] = useState(() => readFixedWidthFontFamily());
+
+  const update = useCallback((next: string) => {
+    setFamily(next);
+    writeFixedWidthFontFamily(next);
+    applyFixedWidthFontFamily(next);
+  }, []);
+
+  return (
+    <div className="flex flex-wrap items-center justify-between gap-x-6 gap-y-3">
+      <div className="flex min-w-0 flex-1 flex-col">
+        <span className="text-sm font-medium">Fixed width font</span>
+        <span className="text-sm text-muted-foreground">
+          Monospace font for file paths, hashes, and inline code in the interface.
+        </span>
       </div>
+      <FontFamilyCombobox
+        category="fixedWidth"
+        value={family}
+        onChange={update}
+        defaultLabel="Default"
+        ariaLabel="Fixed width font family"
+        testId="fixed-width-font-family"
+        previewFallback="var(--font-mono)"
+      />
     </div>
   );
 }
@@ -1165,10 +1189,11 @@ function UiCodeFontSizeControl() {
 }
 
 /**
- * Code font family picker. Free-text (Cursor-style): type any monospace font
- * installed on this device; blank means the editor/terminal default (the shared
- * mono stack). Applies live and persists on every change via the code-font
- * pub/sub (see lib/codeFontPreferences.ts). Mirrors UiFontFamilyControl.
+ * Code font family picker. A searchable dropdown over the catalog's `code` role
+ * (IDE + Nerd Fonts); selecting an option loads the webfont and applies it live
+ * to the code editor (Monaco) and terminal (xterm) via the code-font pub/sub
+ * (see lib/codeFontPreferences.ts). "Editor default" falls back to the shared
+ * mono stack; a custom typed family stays honored. Mirrors UiFontFamilyControl.
  */
 function UiCodeFontFamilyControl() {
   const [family, setFamily] = useState(() => readCodeFontFamily());
@@ -1178,44 +1203,23 @@ function UiCodeFontFamilyControl() {
     writeCodeFontFamily(next);
   }, []);
 
-  const isDefault = family.trim() === CODE_FONT_FAMILY_DEFAULT;
-
   return (
     <div className="flex flex-wrap items-center justify-between gap-x-6 gap-y-3">
       <div className="flex min-w-0 flex-1 flex-col">
         <span className="text-sm font-medium">Code font family</span>
         <span className="text-sm text-muted-foreground">
-          Font for the code editor and terminal. Leave blank for the default.
+          Font for the code editor and terminal. Pick from the catalog or type any installed font.
         </span>
       </div>
-      {/* Reset sits left of the input so the input's right edge lines up flush
-          with the size stepper above. `invisible` (not removed) at the default
-          keeps the row from shifting. */}
-      <div role="group" aria-label="Code font family" className="flex shrink-0 items-center gap-2">
-        <Button
-          type="button"
-          variant="ghost"
-          size="sm"
-          data-testid="code-font-family-reset"
-          disabled={isDefault}
-          className={cn("h-9", isDefault && "invisible")}
-          onClick={() => update(CODE_FONT_FAMILY_DEFAULT)}
-        >
-          Reset
-        </Button>
-        <Input
-          type="text"
-          aria-label="Code font family"
-          data-testid="code-font-family-input"
-          placeholder="Editor default"
-          spellCheck={false}
-          autoCapitalize="off"
-          autoCorrect="off"
-          className="h-9 w-56"
-          value={family}
-          onChange={(e) => update(e.target.value)}
-        />
-      </div>
+      <FontFamilyCombobox
+        category="code"
+        value={family}
+        onChange={update}
+        defaultLabel="Editor default"
+        ariaLabel="Code font family"
+        testId="code-font-family"
+        previewFallback={CODE_FONT_FAMILY_FALLBACK}
+      />
     </div>
   );
 }