@miragon/mcp-toolkit-ui 2.5.0 → 2.7.0

package/src/theme/create-theme.ts

@@ -1,29 +1,40 @@
 import type { CSSProperties } from "react"
 
 /**
- * A curated, brand-relevant subset of the toolkit's CSS-variable theming
- * surface (the full set lives in `packages/ui/src/globals.css`). These are the
- * tokens a white-label client almost always wants to change — the brand colour
- * pair, the surface/accent colours, the border/ring, and the shape/typography
- * knobs — expressed in plain, design-system terms.
+ * The toolkit's theming surface in plain, design-system terms: one optional
+ * field per ROLE variable defined in `packages/ui/src/theme.css` (the role-token
+ * contract, see {@link ROLE_TOKENS}), plus the legacy shadcn knobs it always had.
  *
- * Every field is **optional**: a theme overrides only the tokens it cares about
- * and inherits the rest from the toolkit defaults (`:root` / `.dark`). Colour
- * values are any valid CSS colour string (`oklch(...)`, `#rrggbb`, `hsl(...)`),
- * `radius` is any CSS length (e.g. `"0.5rem"`), and the font fields are CSS
- * `font-family` lists.
+ * The defaults are the Miragon theme — every role points at a vendored
+ * `--cd-*` corporate-design token, in light and in dark. A brand overrides
+ * only the roles it cares about and inherits the rest. Colour values are any
+ * CSS colour string (`#rrggbb`, `oklch(...)`, `color-mix(...)`), lengths any
+ * CSS length, fonts `font-family` lists, durations CSS times.
  *
- * Unlisted CSS variables (`--popover`, `--chart-*`, `--sidebar-*`, …) are
- * intentionally out of scope here: they are part of the theming surface but not
- * the brand essentials, so a client tunes them by hand in CSS when needed. See
- * {@link TOKEN_TO_CSS_VAR} for the exact field → variable mapping.
+ * Roles a component must never take from a host's palette — primary, link,
+ * focus, the status tones and the input border — are brand decisions; a host
+ * maps only the neutral roles (background, card, foreground, border, …).
+ *
+ * Unlisted variables (`--chart-*`, `--sidebar-*`, `--popover-foreground`, …)
+ * stay themeable in CSS. See {@link TOKEN_TO_CSS_VAR} for the exact mapping.
  */
 export interface ThemeTokens {
-  /** Brand colour. Maps to `--primary`. */
+  /** Brand colour: primary button fill, selection. Maps to `--primary`. */
   primary?: string
   /** Text/icon colour on a `primary` surface. Maps to `--primary-foreground`. */
   primaryForeground?: string
-  /** Accent colour for subtle highlights. Maps to `--accent`. */
+  /**
+   * Primary button fill on hover. Maps to `--primary-hover`. A theme that sets
+   * `primary` but never `primaryHover` gets `primary` at 90 % (the pre-role
+   * hover) from {@link resolveThemeVars}.
+   */
+  primaryHover?: string
+  /**
+   * Link and interactive text. Maps to `--link`. A theme that sets `primary`
+   * but never `link` gets links in `primary` (the pre-role link colour).
+   */
+  link?: string
+  /** Hover/selection highlight surface. Maps to `--accent`. */
   accent?: string
   /** Text colour on an `accent` surface. Maps to `--accent-foreground`. */
   accentForeground?: string
@@ -35,14 +46,92 @@ export interface ThemeTokens {
   card?: string
   /** Text colour on a `card` surface. Maps to `--card-foreground`. */
   cardForeground?: string
-  /** Border colour for dividers/outlines. Maps to `--border`. */
+  /** Menu, select and dialog surface. Maps to `--popover`. */
+  popover?: string
+  /** Quiet surface (table heads, skeletons, tab rails). Maps to `--muted`. */
+  muted?: string
+  /** Secondary text — must keep 4.5:1 on `muted`. Maps to `--muted-foreground`. */
+  mutedForeground?: string
+  /** Secondary button / badge surface. Maps to `--secondary`. */
+  secondary?: string
+  /** Decorative dividers and outlines (no contrast claim). Maps to `--border`. */
   border?: string
-  /** Focus-ring colour. Maps to `--ring`. */
+  /** Input border — must keep 3:1 on its surface. Maps to `--input`. */
+  input?: string
+  /** Legacy focus-ring colour (shadcn). Maps to `--ring`. */
   ring?: string
-  /** Base corner radius (a CSS length). Maps to `--radius`. */
+  /**
+   * Focus ring and focused-input border, opaque, 3:1. Maps to `--focus`. A
+   * theme that sets `ring` but never `focus` gets its focus ring in `ring`.
+   */
+  focus?: string
+  /** Destructive action fill. Maps to `--destructive`. */
+  destructive?: string
+  /**
+   * Text/icon colour on a `destructive` fill (white by default; keep 4.5:1).
+   * Maps to `--destructive-foreground`.
+   */
+  destructiveForeground?: string
+  /** Success colour — fill, dot, border, icon (never text on light). Maps to `--success`. */
+  success?: string
+  /** Success tint surface. Maps to `--success-soft`. */
+  successSoft?: string
+  /** Text colour of the success tone. Maps to `--success-ink`. */
+  successInk?: string
+  /** Warning colour — fill, dot, border, icon (never text on light). Maps to `--warning`. */
+  warning?: string
+  /** Warning tint surface. Maps to `--warning-soft`. */
+  warningSoft?: string
+  /** Text colour of the warning tone. Maps to `--warning-ink`. */
+  warningInk?: string
+  /** Danger colour — fill, dot, border, icon. Maps to `--danger`. */
+  danger?: string
+  /** Danger tint surface. Maps to `--danger-soft`. */
+  dangerSoft?: string
+  /** Text colour of the danger tone. Maps to `--danger-ink`. */
+  dangerInk?: string
+  /** Info colour — fill, dot, border, icon. Maps to `--info`. */
+  info?: string
+  /** Info tint surface. Maps to `--info-soft`. */
+  infoSoft?: string
+  /** Text colour of the info tone. Maps to `--info-ink`. */
+  infoInk?: string
+  /**
+   * Base corner radius (the legacy shadcn knob). Drives `rounded-xl` and up;
+   * applied through a theme ({@link ThemeProvider}, {@link resolveThemeVars}
+   * or `toStyle()`) it also derives `radiusSm`/`radiusMd`/`radiusLg` when those
+   * are not set. In plain CSS `--radius` no longer reshapes `rounded-sm/md/lg`:
+   * set `--radius-sm`/`--radius-md`/`--radius-lg` there. Maps to `--radius`.
+   */
   radius?: string
+  /** Badges and chips. Maps to `--radius-sm` (`rounded-sm`). */
+  radiusSm?: string
+  /** The standard: buttons, inputs, cards, dialogs. Maps to `--radius-md` (`rounded-md`). */
+  radiusMd?: string
+  /** Large panels and tiles. Maps to `--radius-lg` (`rounded-lg`). */
+  radiusLg?: string
+  /** Pills and avatars. Maps to `--radius-pill` (`rounded-pill`). */
+  radiusPill?: string
+  /** Subtle elevation. Maps to `--shadow-1` (`shadow-1`). */
+  shadow1?: string
+  /** Cards, hovered primary buttons. Maps to `--shadow-2` (`shadow-2`). */
+  shadow2?: string
+  /** Popovers and dialogs. Maps to `--shadow-3` (`shadow-3`). */
+  shadow3?: string
+  /** Dialog/sheet backdrop. Maps to `--scrim` (`bg-scrim`). */
+  scrim?: string
+  /** Hover-speed transitions. Maps to `--motion-fast` (the default duration). */
+  motionFast?: string
+  /** Standard transitions. Maps to `--motion-base`. */
+  motionBase?: string
+  /** Large enter/leave transitions. Maps to `--motion-slow`. */
+  motionSlow?: string
+  /** Easing curve. Maps to `--ease` (the default timing function). */
+  ease?: string
   /** Body font-family list. Maps to `--font-sans`. */
   fontSans?: string
+  /** Code, ids and stack traces. Maps to `--font-mono`. */
+  fontMono?: string
   /** Heading font-family list. Maps to `--font-heading`. */
   fontHeading?: string
 }
@@ -51,27 +140,147 @@ export interface ThemeTokens {
 type CssVarName = `--${string}`
 
 /**
- * The single source of truth mapping each curated {@link ThemeTokens} field to
- * its real CSS variable name from `globals.css`. `tokensToVars` walks this map,
- * so adding a field here (and to {@link ThemeTokens}) is all that is needed to
- * extend the public theming surface.
+ * The single source of truth mapping each {@link ThemeTokens} field to its real
+ * CSS variable name in `theme.css`. `tokensToVars` walks this map, so adding a
+ * field here (and to {@link ThemeTokens}) is all that is needed to extend the
+ * public theming surface.
  */
 export const TOKEN_TO_CSS_VAR = {
   primary: "--primary",
   primaryForeground: "--primary-foreground",
+  primaryHover: "--primary-hover",
+  link: "--link",
   accent: "--accent",
   accentForeground: "--accent-foreground",
   background: "--background",
   foreground: "--foreground",
   card: "--card",
   cardForeground: "--card-foreground",
+  popover: "--popover",
+  muted: "--muted",
+  mutedForeground: "--muted-foreground",
+  secondary: "--secondary",
   border: "--border",
+  input: "--input",
   ring: "--ring",
+  focus: "--focus",
+  destructive: "--destructive",
+  destructiveForeground: "--destructive-foreground",
+  success: "--success",
+  successSoft: "--success-soft",
+  successInk: "--success-ink",
+  warning: "--warning",
+  warningSoft: "--warning-soft",
+  warningInk: "--warning-ink",
+  danger: "--danger",
+  dangerSoft: "--danger-soft",
+  dangerInk: "--danger-ink",
+  info: "--info",
+  infoSoft: "--info-soft",
+  infoInk: "--info-ink",
   radius: "--radius",
+  radiusSm: "--radius-sm",
+  radiusMd: "--radius-md",
+  radiusLg: "--radius-lg",
+  radiusPill: "--radius-pill",
+  shadow1: "--shadow-1",
+  shadow2: "--shadow-2",
+  shadow3: "--shadow-3",
+  scrim: "--scrim",
+  motionFast: "--motion-fast",
+  motionBase: "--motion-base",
+  motionSlow: "--motion-slow",
+  ease: "--ease",
   fontSans: "--font-sans",
+  fontMono: "--font-mono",
   fontHeading: "--font-heading",
 } as const satisfies Record<keyof ThemeTokens, CssVarName>
 
+/**
+ * The role-token contract: every variable the toolkit defines for components
+ * to use (`theme.css`), in light and — for colours — dark. Components in this
+ * package, and in apps built on it, style through these names only, never
+ * through raw colours or Tailwind palette classes.
+ */
+export const ROLE_TOKENS = [
+  "--background",
+  "--card",
+  "--popover",
+  "--muted",
+  "--secondary",
+  "--foreground",
+  "--muted-foreground",
+  "--border",
+  "--input",
+  "--primary",
+  "--primary-foreground",
+  "--primary-hover",
+  "--link",
+  "--ring",
+  "--focus",
+  "--success",
+  "--warning",
+  "--danger",
+  "--info",
+  "--success-soft",
+  "--warning-soft",
+  "--danger-soft",
+  "--info-soft",
+  "--success-ink",
+  "--warning-ink",
+  "--danger-ink",
+  "--info-ink",
+  "--destructive",
+  "--radius-sm",
+  "--radius-md",
+  "--radius-lg",
+  "--radius-pill",
+  "--shadow-1",
+  "--shadow-2",
+  "--shadow-3",
+  "--scrim",
+  "--motion-fast",
+  "--motion-base",
+  "--motion-slow",
+  "--ease",
+  "--font-sans",
+  "--font-mono",
+] as const satisfies readonly CssVarName[]
+
+/**
+ * Variables whose toolkit value is the same in light and dark (theme.css
+ * declares them once, or identically in both modes). A theme's LIGHT value for
+ * one of these also applies in dark mode — a brand's button colour, radius or
+ * font does not change with the mode. Every other variable (surfaces, text,
+ * links, focus, status tones) takes its dark value from the theme's `dark`
+ * tokens or, failing that, from the toolkit's dark defaults — never from the
+ * light value, which would put light surfaces into a dark scope.
+ * Pinned against theme.css by `theme-css.test.ts`.
+ */
+export const MODE_INVARIANT_VARS: ReadonlySet<CssVarName> = new Set<CssVarName>([
+  "--primary",
+  "--primary-foreground",
+  "--primary-hover",
+  "--destructive",
+  "--destructive-foreground",
+  "--input",
+  "--radius",
+  "--radius-sm",
+  "--radius-md",
+  "--radius-lg",
+  "--radius-pill",
+  "--shadow-1",
+  "--shadow-2",
+  "--shadow-3",
+  "--motion-fast",
+  "--motion-base",
+  "--motion-slow",
+  "--ease",
+  "--font-sans",
+  "--font-mono",
+  "--font-heading",
+])
+
 /** A serializable map of CSS custom properties (`--primary` → value). */
 export type ThemeVars = Record<CssVarName, string>
 
@@ -85,14 +294,18 @@ export type ThemeVars = Record<CssVarName, string>
  * logged, or persisted and rehydrated.
  */
 export interface ThemeDefinition {
-  /** CSS variables applied at the theme scope (overrides `:root`). */
+  /** CSS variables applied at the theme scope in light mode (overrides `:root`). */
   vars: ThemeVars
-  /** Dark-mode CSS variables, applied under `.dark` at the theme scope. */
+  /** Dark-mode CSS variables, applied at the theme scope in dark mode. */
   darkVars?: ThemeVars
   /**
-   * The light {@link vars} as a React `style` object (CSS custom properties are
-   * valid `CSSProperties` keys). Handy for inlining onto a wrapper element
-   * without the {@link ThemeProvider}.
+   * The theme's light-mode variables as a React `style` object (CSS custom
+   * properties are valid `CSSProperties` keys): exactly what
+   * {@link ThemeProvider} applies in light mode, i.e.
+   * {@link resolveThemeVars}`(theme, "light")` — {@link vars} plus the values
+   * derived from the legacy knobs (sm/md/lg from `radius`, …). Handy for
+   * inlining onto a wrapper element without the provider; for dark mode use
+   * {@link resolveThemeVars}`(theme, "dark")`.
    */
   toStyle(): CSSProperties
 }
@@ -119,29 +332,30 @@ export function tokensToVars(tokens: ThemeTokens): ThemeVars {
 /** Options for {@link createTheme}. */
 export interface CreateThemeOptions {
   /**
-   * Dark-mode token overrides. Applied on top of the toolkit's `.dark` defaults
-   * when the active mode is dark (see {@link ThemeProvider}). Provide only the
-   * tokens that differ from light — typically a darker `background`/`card` and a
-   * brighter `primary`.
+   * Dark-mode token overrides. In dark mode a theme scope gets the toolkit's
+   * dark defaults, the theme's mode-invariant light tokens (brand button
+   * colour, radii, fonts — see {@link MODE_INVARIANT_VARS}) and these. Provide
+   * what differs in dark — typically `background`, `card`, `link`.
    */
   dark?: ThemeTokens
 }
 
 /**
- * Build a serializable {@link ThemeDefinition} from a curated set of brand
+ * Build a serializable {@link ThemeDefinition} from a set of brand
  * {@link ThemeTokens}. This is the one switch a white-label client flips: pass
- * your brand's primary colour, radius, and (optionally) dark overrides, and
- * every toolkit primitive that reads the design tokens — `Card`, `Button`,
- * `Badge`, `bg-card`, `text-primary`, `rounded-lg` — re-skins to match.
+ * the brand's roles (and, optionally, dark overrides), and every toolkit
+ * primitive that reads the role tokens — `Card`, `Button`, `Badge`, `bg-card`,
+ * `text-link`, `rounded-md` — re-skins to match. Without a theme the toolkit
+ * renders in the Miragon theme.
  *
  * Pure and side-effect-free: it only maps fields to CSS-variable names. Apply
  * the result with {@link ThemeProvider} (recommended) or by spreading
- * `theme.toStyle()` onto a wrapper element.
+ * {@link resolveThemeVars}`(theme, mode)` onto a wrapper element.
  *
  * @example
  * const brand = createTheme(
- *   { primary: "oklch(0.55 0.2 264)", radius: "0.5rem" },
- *   { dark: { primary: "oklch(0.7 0.18 264)" } },
+ *   { primary: "#0f766e", link: "#0f766e", focus: "#0f766e", radiusMd: "6px" },
+ *   { dark: { link: "#5eead4", focus: "#5eead4" } },
  * )
  * // <ThemeProvider theme={brand}>…</ThemeProvider>
  */
@@ -150,9 +364,67 @@ export function createTheme(tokens: ThemeTokens, opts?: CreateThemeOptions): The
   const darkTokens = opts?.dark
   const darkVars = darkTokens ? tokensToVars(darkTokens) : undefined
 
-  return {
+  const theme: ThemeDefinition = {
     vars,
     ...(darkVars && Object.keys(darkVars).length > 0 ? { darkVars } : {}),
-    toStyle: () => vars,
+    toStyle: () => resolveThemeVars(theme, "light"),
+  }
+  return theme
+}
+
+/** Whether the theme sets `name` itself, in light or in dark. */
+function declares(theme: ThemeDefinition, name: CssVarName): boolean {
+  return name in theme.vars || (theme.darkVars !== undefined && name in theme.darkVars)
+}
+
+/**
+ * Fill the roles a theme written against the pre-role API leaves unset, from
+ * the knobs it does set, so it keeps ONE brand instead of half Miragon:
+ *
+ * - the base `--radius` reshapes the sm/md/lg steps (CI ratio 6 : 12 : 16);
+ * - `--primary` gives `--primary-hover` (90 %, the old `bg-primary/90`) and
+ *   `--link` (the old link button was `text-primary`);
+ * - `--ring` gives `--focus` (the old focus ring).
+ *
+ * A role the theme sets itself — in either mode — is never derived, and an
+ * explicit value always wins.
+ */
+function withDerivedVars(vars: ThemeVars, theme: ThemeDefinition): ThemeVars {
+  const derived: ThemeVars = {}
+  const radius = vars["--radius"]
+  if (radius) {
+    derived["--radius-sm"] = `calc(${radius} * 0.5)`
+    derived["--radius-md"] = radius
+    derived["--radius-lg"] = `calc(${radius} * 4 / 3)`
+  }
+  const primary = vars["--primary"]
+  if (primary && !declares(theme, "--primary-hover")) {
+    derived["--primary-hover"] = `color-mix(in srgb, ${primary} 90%, transparent)`
+  }
+  if (primary && !declares(theme, "--link")) derived["--link"] = primary
+  const ring = vars["--ring"]
+  if (ring && !declares(theme, "--focus")) derived["--focus"] = ring
+  return { ...derived, ...vars }
+}
+
+/**
+ * The CSS variables a theme applies at its scope in `mode`. Light mode: the
+ * theme's `vars`. Dark mode: its mode-invariant light vars plus its `darkVars`
+ * — never the other light vars, which would beat the toolkit's dark defaults
+ * (mcp-toolkit#178 N35). Both modes add what the legacy knobs derive (a base
+ * `--radius` → sm/md/lg; `--primary` → hover and link; `--ring` → focus)
+ * where the theme does not set those roles itself.
+ * `null`/`undefined` yields `{}` (the toolkit defaults apply).
+ */
+export function resolveThemeVars(
+  theme: ThemeDefinition | null | undefined,
+  mode: "light" | "dark",
+): ThemeVars {
+  if (!theme) return {}
+  if (mode === "light") return withDerivedVars(theme.vars, theme)
+  const carried: ThemeVars = {}
+  for (const [name, value] of Object.entries(theme.vars) as [CssVarName, string][]) {
+    if (MODE_INVARIANT_VARS.has(name)) carried[name] = value
   }
+  return withDerivedVars({ ...carried, ...theme.darkVars }, theme)
 }

package/src/theme/fonts.test.ts

@@ -0,0 +1,85 @@
+/// <reference types="node" />
+import { readFileSync } from "node:fs"
+import { describe, expect, it } from "vitest"
+import { GEIST_FONT_FILES, fontFaces } from "./fonts.js"
+
+describe("fontFaces (opt-in Geist by URL)", () => {
+  // Built inside each test: a describe-scope value is computed once at
+  // collection, outside any mutant Stryker activates.
+  const css = () => fontFaces({ baseUrl: "https://mcp.example.com/fonts" })
+
+  it("declares Geist and Geist Mono — the families the font tokens name first", () => {
+    expect(css()).toContain('font-family: "Geist";')
+    expect(css()).toContain('font-family: "Geist Mono";')
+    expect(css().match(/@font-face \{/g)).toHaveLength(2)
+  })
+
+  it("points at the latin variable woff2 files under the base URL", () => {
+    expect(css()).toContain(
+      'src: url("https://mcp.example.com/fonts/geist-latin-wght-normal.woff2") format("woff2");',
+    )
+    expect(css()).toContain(
+      'src: url("https://mcp.example.com/fonts/geist-mono-latin-wght-normal.woff2") format("woff2");',
+    )
+  })
+
+  it("covers the whole weight axis, swaps by default and limits itself to latin", () => {
+    expect(css().match(/font-weight: 100 900;/g)).toHaveLength(2)
+    expect(css().match(/font-display: swap;/g)).toHaveLength(2)
+    expect(css().match(/font-style: normal;/g)).toHaveLength(2)
+    expect(css().match(/unicode-range: U\+0000-00FF,/g)).toHaveLength(2)
+  })
+
+  it("renders two complete @font-face rules, one declaration per line", () => {
+    const range =
+      "U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD"
+    const rule = (family: string, file: string) =>
+      [
+        "@font-face {",
+        `  font-family: "${family}";`,
+        "  font-style: normal;",
+        "  font-display: swap;",
+        "  font-weight: 100 900;",
+        `  src: url("/f/${file}") format("woff2");`,
+        `  unicode-range: ${range};`,
+        "}",
+      ].join("\n")
+    expect(fontFaces({ baseUrl: "/f" })).toBe(
+      `${rule("Geist", "geist-latin-wght-normal.woff2")}\n${rule("Geist Mono", "geist-mono-latin-wght-normal.woff2")}`,
+    )
+  })
+
+  it("strips every leading slash of a file name but keeps its inner path", () => {
+    const out = fontFaces({ baseUrl: "/f", files: { sans: "//a.woff2", mono: "sub/b.woff2" } })
+    expect(out).toContain('url("/f/a.woff2")')
+    expect(out).toContain('url("/f/sub/b.woff2")')
+  })
+
+  it("joins base URL and file name with exactly one slash", () => {
+    const out = fontFaces({ baseUrl: "/fonts///", files: { sans: "/a.woff2", mono: "b.woff2" } })
+    expect(out).toContain('url("/fonts/a.woff2")')
+    expect(out).toContain('url("/fonts/b.woff2")')
+  })
+
+  it("honours a custom font-display strategy", () => {
+    expect(fontFaces({ baseUrl: "/f", display: "optional" })).toContain("font-display: optional;")
+  })
+
+  it('refuses URLs that could break out of url("…")', () => {
+    for (const baseUrl of ['/f")}body{', "/f'x", "/f x", "/f(", "/f\\", "/f<x>"]) {
+      expect(() => fontFaces({ baseUrl }), baseUrl).toThrow(/refusing a font URL/)
+    }
+  })
+
+  it("names the files @fontsource-variable ships, so a server can copy them as-is", () => {
+    for (const [pkg, file] of [
+      ["@fontsource-variable/geist", GEIST_FONT_FILES.sans],
+      ["@fontsource-variable/geist-mono", GEIST_FONT_FILES.mono],
+    ] as const) {
+      const shipped = readFileSync(
+        new URL(`../../node_modules/${pkg}/files/${file}`, import.meta.url),
+      )
+      expect(shipped.byteLength, `${pkg}/files/${file}`).toBeGreaterThan(1000)
+    }
+  })
+})

package/src/theme/fonts.ts

@@ -0,0 +1,72 @@
+/**
+ * Opt-in Geist delivery by URL. The toolkit's font tokens name "Geist" and
+ * "Geist Mono" first but load no font: an app either imports
+ * `@miragon/mcp-toolkit-ui/fonts.css` (bundled by the build) or serves the
+ * woff2 files itself and declares them with {@link fontFaces}. The second path
+ * keeps MCP App views small — the files are fetched once and cached instead of
+ * inlined as base64 into every view; allow their origin in the view's CSP
+ * `resourceDomains`. Where the fonts never load, the host's font renders (if
+ * the host sends one, see `adoptHostFontVariables`), else the system stack.
+ */
+
+/** The latin variable woff2 files, as `@fontsource-variable/geist(-mono)` ship them. */
+export const GEIST_FONT_FILES = {
+  sans: "geist-latin-wght-normal.woff2",
+  mono: "geist-mono-latin-wght-normal.woff2",
+} as const
+
+/** The latin subset both files cover (identical to fontsource's `latin` range). */
+const LATIN_UNICODE_RANGE =
+  "U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD"
+
+/** Options for {@link fontFaces}. */
+export interface FontFacesOptions {
+  /** Where the woff2 files are served from, e.g. `https://mcp.example.com/fonts`. */
+  baseUrl: string
+  /** File names under `baseUrl`. Defaults to {@link GEIST_FONT_FILES}. */
+  files?: { sans?: string; mono?: string }
+  /** `font-display` strategy. Default `"swap"`: text renders at once in the fallback. */
+  display?: "auto" | "block" | "swap" | "fallback" | "optional"
+}
+
+/** Characters that could break out of the CSS `url("…")` the helper writes. */
+const UNSAFE_URL_CHARS = /["'\\()\s<>]/
+
+function fontUrl(baseUrl: string, file: string): string {
+  const url = `${baseUrl.replace(/\/+$/, "")}/${file.replace(/^\/+/, "")}`
+  if (UNSAFE_URL_CHARS.test(url)) {
+    throw new Error(`fontFaces: refusing a font URL with quote, bracket or whitespace: ${url}`)
+  }
+  return url
+}
+
+function face(family: string, url: string, display: string): string {
+  return [
+    "@font-face {",
+    `  font-family: "${family}";`,
+    "  font-style: normal;",
+    `  font-display: ${display};`,
+    "  font-weight: 100 900;",
+    `  src: url("${url}") format("woff2");`,
+    `  unicode-range: ${LATIN_UNICODE_RANGE};`,
+    "}",
+  ].join("\n")
+}
+
+/**
+ * The `@font-face` rules for Geist and Geist Mono (latin, variable weight
+ * 100–900) served from `baseUrl`. Pure — inject the string where your app
+ * builds its document, e.g. `<style>{fontFaces({ baseUrl })}</style>`.
+ *
+ * @example
+ * fontFaces({ baseUrl: "https://mcp.example.com/fonts" })
+ * // @font-face { font-family: "Geist"; … src: url("https://mcp.example.com/fonts/geist-latin-wght-normal.woff2") … }
+ */
+export function fontFaces({ baseUrl, files, display = "swap" }: FontFacesOptions): string {
+  const sans = files?.sans ?? GEIST_FONT_FILES.sans
+  const mono = files?.mono ?? GEIST_FONT_FILES.mono
+  return [
+    face("Geist", fontUrl(baseUrl, sans), display),
+    face("Geist Mono", fontUrl(baseUrl, mono), display),
+  ].join("\n")
+}