@vectoriox/iox-ui 5.19.0 → 5.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.19.0",
+  "version": "5.21.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/design-core/flavor-tokens.ts

@@ -1,5 +1,5 @@
 import { deriveAccentTokens } from './brand';
-import { cssString } from './fonts';
+import { fontStackWithout, formatFontFamily } from './fonts';
 import { SPEC_AXES } from './flavor-spec.generated';
 import {
     DesignChoices, DesignTokenRow, FlavorPackV2, FlavorSpecToken, flavorSourceStamp, USER_TOKEN_SOURCE,
@@ -38,9 +38,16 @@ export function defaultDesignChoices(pack: FlavorPackV2): DesignChoices {
     };
 }
 
-/** `'<Family>', system-ui, sans-serif` — the value a font role holds once the author picks a face. */
-export function userFontStack(family: string): string {
-    return `${cssString(family.trim())}, ${USER_FONT_FALLBACK}`;
+/**
+ * The value a font role holds once the author picks a face: `'<Family>', <the look's own stack>` —
+ * e.g. `'Rubik', 'Inter Tight', system-ui, -apple-system, 'Segoe UI', sans-serif`. The look's font
+ * follows the author's, so a family that later stops existing (deleted outside the delete guard, a
+ * bucket emptied by hand) renders in the pack's font — Board 8's promise — in every renderer, with no
+ * runtime check. With no look stack: `system-ui, sans-serif`.
+ */
+export function userFontStack(family: string, packStack?: string | null): string {
+    const fallback = fontStackWithout(packStack, family) || USER_FONT_FALLBACK;
+    return `${formatFontFamily(family)}, ${fallback}`;
 }
 
 const toRow = (t: FlavorSpecToken, source: string): DesignTokenRow => ({
@@ -81,7 +88,7 @@ export function buildFlavorTokens(pack: FlavorPackV2, choices: DesignChoices): D
     set(BUTTON_RADIUS, choices.pillButtons ? PILL_RADIUS : (buttonRadius?.overridden ? buttonRadius.value : CONTROL_RADIUS));
 
     for (const [role, family] of Object.entries(choices.fonts ?? {})) {
-        if (typeof family === 'string' && family.trim() !== '') set(role, userFontStack(family), USER_TOKEN_SOURCE);
+        if (typeof family === 'string' && family.trim() !== '') set(role, userFontStack(family, byName.get(role)?.value), USER_TOKEN_SOURCE);
     }
 
     if (choices.seed && choices.seed.toLowerCase() !== pack.seed.toLowerCase()) {

package/src/design-core/fonts.ts

@@ -12,28 +12,57 @@ export const FONT_CATALOG: Readonly<Record<string, string>> = SPEC_FONTS;
 export type FontFormat = 'woff2' | 'woff' | 'truetype' | 'opentype';
 export type FontStyle = 'normal' | 'italic';
 
+/**
+ * A face's weight (spec `fontDescriptor.weight`): 100–900 for a static cut (OS/2 `usWeightClass`), or
+ * the RANGE string `'<min> <max>'` a variable font's `fvar` wght axis covers — emitted as
+ * `font-weight: <min> <max>`, so every weight inside it renders from the one file.
+ */
+export type FontWeight = number | string;
+
 /** One uploaded font FILE (spec `fontDescriptor`) — a family is all descriptors sharing `family`. */
 export interface FontDescriptor {
     family: string;
-    /** 100–900, from the file's OS/2 `usWeightClass`. */
-    weight: number;
+    weight: FontWeight;
     style: FontStyle;
     url: string;
     format: FontFormat;
 }
 
+/**
+ * Why iox-cms refused a font upload. The server answers `{ code }` beside its message; the admin
+ * translates the code (`filebox.fontUpload.<code>`), so the author reads why in their language.
+ */
+export enum FontUploadError {
+    NotAFont = 'not_a_font',
+    Empty = 'empty',
+    Unreadable = 'unreadable',
+    TooLarge = 'too_large',
+}
+
+/**
+ * The largest font FILE a studio may upload: 10 MB. A full static or variable Latin/Hebrew/Arabic
+ * family is well under it (Inter's variable TTF is 0.9 MB); an unsubsetted CJK family is not, and
+ * must be subset first. iox-cms stops reading the request at this size; the admin checks it before
+ * sending.
+ */
+export const MAX_FONT_FILE_BYTES = 10 * 1024 * 1024;
+
 /** The token roles whose values name the families a page renders in. */
 export const FONT_FAMILY_TOKENS = ['font-display', 'font-body', 'font-label', 'font-mono'] as const;
 
 const DEFAULT_WEIGHT = 400;
 const MIN_WEIGHT = 100;
 const MAX_WEIGHT = 900;
+/** The bounds CSS gives `font-weight`; a variable font's axis may reach them (Roboto Flex: 100–1000). */
+const CSS_MIN_WEIGHT = 1;
+const CSS_MAX_WEIGHT = 1000;
 const FONT_FORMATS: ReadonlyArray<FontFormat> = ['woff2', 'woff', 'truetype', 'opentype'];
 
 /**
  * A CSS string literal, single-quoted: `\` and `'` escaped, line breaks and NUL dropped, and `<` /
  * `>` hex-escaped (`\3c `) — the face CSS is inlined into a `<style>` by the SSR engine, where an
- * uploaded family named `</style><script>` would otherwise close the element.
+ * uploaded family named `</style><script>` would otherwise close the element. `parseFontFamilies` is
+ * its exact inverse (escapes included), which is what keeps a family's name one value everywhere.
  */
 export function cssString(value: string): string {
     const body = String(value)
@@ -45,6 +74,174 @@ export function cssString(value: string): string {
     return `'${body}'`;
 }
 
+/** ONE family as a `font-family` entry — always quoted, so a family named `Acme, Serif` or `serif` is
+ *  that family, never a list or a generic. */
+export function formatFontFamily(family: string): string {
+    return cssString(String(family ?? '').trim());
+}
+
+/** Families → a `font-family` stack, each quoted (`formatFontFamily`); `parseFontFamilies` reverses it. */
+export function formatFontFamilies(families: ReadonlyArray<string>): string {
+    return (families ?? []).filter(f => String(f ?? '').trim() !== '').map(formatFontFamily).join(', ');
+}
+
+const HEX = /[0-9a-f]/i;
+const CSS_WS = /[ \t\n\r\f]/;
+const REPLACEMENT = '\uFFFD';
+
+/** A CSS escape at `s[at] === '\\'` → [the character it stands for, the index after it] (CSS Syntax §4.3.7). */
+function readEscape(s: string, at: number, inString: boolean): [string, number] {
+    let i = at + 1;
+    if (i >= s.length) return ['', i];
+    if (inString && /[\n\r\f]/.test(s[i])) return ['', s[i] === '\r' && s[i + 1] === '\n' ? i + 2 : i + 1];
+    if (HEX.test(s[i])) {
+        let hex = '';
+        while (i < s.length && hex.length < 6 && HEX.test(s[i])) hex += s[i++];
+        if (s[i] === '\r' && s[i + 1] === '\n') i += 2;
+        else if (i < s.length && CSS_WS.test(s[i])) i++;
+        const cp = parseInt(hex, 16);
+        const valid = cp > 0 && cp <= 0x10ffff && !(cp >= 0xd800 && cp <= 0xdfff);
+        return [valid ? String.fromCodePoint(cp) : REPLACEMENT, i];
+    }
+    const cp = s.codePointAt(i)!;
+    const ch = String.fromCodePoint(cp);
+    return [ch, i + ch.length];
+}
+
+/** A stack's entries, each as the family it names and the exact text that named it. */
+function splitFontStack(stack: string | null | undefined): Array<{ family: string; raw: string }> {
+    const s = String(stack ?? '');
+    const out: Array<{ family: string; raw: string }> = [];
+    let i = 0;
+    while (i < s.length) {
+        while (i < s.length && CSS_WS.test(s[i])) i++;
+        if (i >= s.length) break;
+        const start = i;
+        let family = '';
+        const quote = s[i];
+        if (quote === '"' || quote === "'") {
+            i++;
+            while (i < s.length && s[i] !== quote) {
+                if (s[i] === '\\') {
+                    const [ch, next] = readEscape(s, i, true);
+                    family += ch;
+                    i = next;
+                } else family += s[i++];
+            }
+            i++;
+            while (i < s.length && s[i] !== ',') i++;
+        } else {
+            const words: string[] = [];
+            let word = '';
+            while (i < s.length && s[i] !== ',') {
+                if (s[i] === '\\') {
+                    const [ch, next] = readEscape(s, i, false);
+                    word += ch;
+                    i = next;
+                } else if (CSS_WS.test(s[i])) {
+                    if (word) words.push(word);
+                    word = '';
+                    i++;
+                } else word += s[i++];
+            }
+            if (word) words.push(word);
+            family = words.join(' ');
+        }
+        const raw = s.slice(start, Math.min(i, s.length)).trim();
+        if (family.trim() !== '') out.push({ family, raw });
+        if (s[i] === ',') i++;
+    }
+    return out;
+}
+
+/** The entries of `stack` that do NOT name `family`, as written — what a fallback list keeps. */
+export function fontStackWithout(stack: string | null | undefined, family: string | null | undefined): string {
+    const key = fontFamilyKey(family);
+    return splitFontStack(stack).filter(e => fontFamilyKey(e.family) !== key).map(e => e.raw).join(', ');
+}
+
+/** A weight as a closed range — a static cut is `{ min: w, max: w }`. */
+export interface FontWeightRange {
+    min: number;
+    max: number;
+}
+
+const WEIGHT_NUMBER = /^\d+(?:\.\d+)?$/;
+const WEIGHT_RANGE = /^(\d+(?:\.\d+)?)(?:\s*[-\u2013\u2014]\s*|\s+)(\d+(?:\.\d+)?)$/;
+const clampWeight = (n: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, Math.round(n)));
+
+/**
+ * Anything a file, a descriptor or an author may hold as a weight → its range, or null when it is
+ * not one: `700`, `'700'`, `'100 900'`, `'100-900'`, `'100–900'` (the tile's own spelling). A static
+ * weight clamps to 100–900 (as before); range ends clamp to CSS's 1–1000.
+ */
+export function parseFontWeight(value: unknown): FontWeightRange | null {
+    const text = typeof value === 'number' ? String(value) : typeof value === 'string' ? value.trim() : '';
+    if (WEIGHT_NUMBER.test(text)) {
+        const n = Number(text);
+        if (!(n > 0)) return null;
+        const w = clampWeight(n, MIN_WEIGHT, MAX_WEIGHT);
+        return { min: w, max: w };
+    }
+    const m = WEIGHT_RANGE.exec(text);
+    if (!m) return null;
+    const a = clampWeight(Number(m[1]), CSS_MIN_WEIGHT, CSS_MAX_WEIGHT);
+    const b = clampWeight(Number(m[2]), CSS_MIN_WEIGHT, CSS_MAX_WEIGHT);
+    if (!(a > 0) || !(b > 0)) return null;
+    return a === b ? { min: a, max: a } : { min: Math.min(a, b), max: Math.max(a, b) };
+}
+
+/** A range in the stored / descriptor / CSS form: a number for one weight, `'<min> <max>'` for a span. */
+export function fontWeightValue(range: FontWeightRange): FontWeight {
+    return range.min === range.max ? range.min : `${range.min} ${range.max}`;
+}
+
+/** Any weight → the stored form; a bad value → 400 (as `normalizeFontWeight`). */
+export function normalizeFontWeightValue(value: unknown): FontWeight {
+    return fontWeightValue(parseFontWeight(value) ?? { min: DEFAULT_WEIGHT, max: DEFAULT_WEIGHT });
+}
+
+/** Any weight → its range; a bad value → 400–400. */
+export function fontWeightRange(value: unknown): FontWeightRange {
+    return parseFontWeight(value) ?? { min: DEFAULT_WEIGHT, max: DEFAULT_WEIGHT };
+}
+
+/** True when the weight spans more than one value (a variable font's wght axis). */
+export function isFontWeightRange(value: unknown): boolean {
+    const r = parseFontWeight(value);
+    return !!r && r.min !== r.max;
+}
+
+/** How a weight reads on screen: `700`, or `100–900` for a range. */
+export function formatFontWeight(value: unknown): string {
+    const r = fontWeightRange(value);
+    return r.min === r.max ? String(r.min) : `${r.min}\u2013${r.max}`;
+}
+
+/**
+ * A weight an author or a client SENT, held to what a face can be — or null: a whole number 100–900,
+ * or a range of whole numbers 1 ≤ min < max ≤ 1000. Nothing is clamped or rounded here; a value that
+ * would need it is refused (the PUT correction's rule).
+ */
+export function checkFontWeight(value: unknown): FontWeight | null {
+    const text = typeof value === 'number' ? String(value) : typeof value === 'string' ? value.trim() : '';
+    if (/^\d+$/.test(text)) {
+        const n = Number(text);
+        return n >= MIN_WEIGHT && n <= MAX_WEIGHT ? n : null;
+    }
+    const m = /^(\d+)(?:\s*[-\u2013\u2014]\s*|\s+)(\d+)$/.exec(text);
+    if (!m) return null;
+    const min = Number(m[1]);
+    const max = Number(m[2]);
+    return min >= CSS_MIN_WEIGHT && max <= CSS_MAX_WEIGHT && min < max ? `${min} ${max}` : null;
+}
+
+/** True when a face of `weight` renders `wanted` from its own file (inside its range). */
+export function fontWeightCovers(weight: unknown, wanted: number): boolean {
+    const r = fontWeightRange(weight);
+    return wanted >= r.min && wanted <= r.max;
+}
+
 /** The file extensions a studio may upload as a font, and the descriptor format each one IS (§5b). */
 export const FONT_FILE_FORMATS: Readonly<Record<string, FontFormat>> = Object.freeze({
     woff2: 'woff2', woff: 'woff', ttf: 'truetype', otf: 'opentype',
@@ -78,7 +275,8 @@ export function fontFileStem(key: string | null | undefined): string {
     return fontFileName(key).replace(/\.[^.]+$/, '');
 }
 
-/** A weight as CSS can use it: 100–900, a bad value → 400. */
+/** A single weight as CSS can use it: 100–900, a bad value → 400. A range is not a single weight —
+ *  use `normalizeFontWeightValue` for a face. */
 export function normalizeFontWeight(w: unknown): number {
     const n = Math.round(Number(w));
     return Number.isFinite(n) && n > 0 ? Math.min(MAX_WEIGHT, Math.max(MIN_WEIGHT, n)) : DEFAULT_WEIGHT;
@@ -107,10 +305,10 @@ const preference = (format: FontFormat) => {
  * whose `src` lists them best format first, which is what the two retired forks did per file stem.
  */
 export function buildFontFaceCss(descriptors: ReadonlyArray<FontDescriptor> | null | undefined): string {
-    const faces = new Map<string, { family: string; weight: number; style: FontStyle; files: FontDescriptor[] }>();
+    const faces = new Map<string, { family: string; weight: FontWeight; style: FontStyle; files: FontDescriptor[] }>();
     for (const d of (descriptors ?? []).filter(usableDescriptor)) {
         const family = d.family.trim();
-        const weight = normalizeFontWeight(d.weight);
+        const weight = normalizeFontWeightValue(d.weight);
         const style = normalizeFontStyle(d.style);
         const id = `${fontFamilyKey(family)}|${weight}|${style}`;
         const face = faces.get(id) ?? { family, weight, style, files: [] };
@@ -125,7 +323,7 @@ export function buildFontFaceCss(descriptors: ReadonlyArray<FontDescriptor> | nu
                 .join(', ');
             return [
                 '@font-face {',
-                `  font-family: ${cssString(face.family)};`,
+                `  font-family: ${formatFontFamily(face.family)};`,
                 `  src: ${src};`,
                 `  font-weight: ${face.weight};`,
                 `  font-style: ${face.style};`,
@@ -139,13 +337,26 @@ export function buildFontFaceCss(descriptors: ReadonlyArray<FontDescriptor> | nu
 /** An uploaded family: every file sharing a family name (case-insensitively), with its real cuts. */
 export interface FontFamilyGroup {
     family: string;
-    /** Distinct weights, ascending. */
-    weights: number[];
+    /** Distinct weights, ascending by their lower end — a variable file's is its `'<min> <max>'` range. */
+    weights: FontWeight[];
     styles: FontStyle[];
     /** Every file of the family, lightest first. */
     faces: FontDescriptor[];
 }
 
+/** Lighter first: by the range's lower end, then its upper end (a static 100 before a 100–900 file). */
+export function compareFontWeights(a: unknown, b: unknown): number {
+    const ra = fontWeightRange(a);
+    const rb = fontWeightRange(b);
+    return ra.min - rb.min || ra.max - rb.max;
+}
+
+/** The weight a family's preview renders at: 400 when a face covers it, else its lightest. */
+export function previewFontWeight(weights: ReadonlyArray<FontWeight>): number {
+    if (!weights?.length || weights.some(w => fontWeightCovers(w, DEFAULT_WEIGHT))) return DEFAULT_WEIGHT;
+    return fontWeightRange([...weights].sort(compareFontWeights)[0]).min;
+}
+
 /** Files → families (§5b "Group into families"): the Files tile, the typeface dropdown and Design ▸ Type. */
 export function groupFontFamilies(descriptors: ReadonlyArray<FontDescriptor> | null | undefined): FontFamilyGroup[] {
     const groups = new Map<string, FontFamilyGroup>();
@@ -157,11 +368,16 @@ export function groupFontFamilies(descriptors: ReadonlyArray<FontDescriptor> | n
     }
     return [...groups.values()]
         .map(g => {
-            const faces = [...g.faces].sort((a, b) => normalizeFontWeight(a.weight) - normalizeFontWeight(b.weight)
+            const faces = [...g.faces].sort((a, b) => compareFontWeights(a.weight, b.weight)
                 || normalizeFontStyle(a.style).localeCompare(normalizeFontStyle(b.style)));
+            const weights = new Map<string, FontWeight>();
+            for (const f of faces) {
+                const w = normalizeFontWeightValue(f.weight);
+                weights.set(String(w), w);
+            }
             return {
                 family: g.family,
-                weights: [...new Set(faces.map(f => normalizeFontWeight(f.weight)))].sort((a, b) => a - b),
+                weights: [...weights.values()].sort(compareFontWeights),
                 styles: FONT_STYLES.filter(s => faces.some(f => normalizeFontStyle(f.style) === s)),
                 faces,
             };
@@ -169,12 +385,14 @@ export function groupFontFamilies(descriptors: ReadonlyArray<FontDescriptor> | n
         .sort((a, b) => a.family.localeCompare(b.family));
 }
 
-/** The family names in a CSS `font-family` stack, unquoted, in order. */
-export function parseFontFamilies(stack: string): string[] {
-    return String(stack ?? '')
-        .split(',')
-        .map(f => f.trim().replace(/^(['"])(.*)\1$/, '$2').trim())
-        .filter(Boolean);
+/**
+ * The family names in a CSS `font-family` stack, in order — the exact inverse of `formatFontFamily` /
+ * `formatFontFamilies`: quotes removed, CSS escapes decoded (`\'`, `\\`, `\3c `), a comma INSIDE
+ * quotes kept, an unquoted name's words joined by one space. Every reader of a font token goes
+ * through this; a naive split on `,` is how `O'Neil Sans` stopped matching its own token.
+ */
+export function parseFontFamilies(stack: string | null | undefined): string[] {
+    return splitFontStack(stack).map(e => e.family);
 }
 
 /** Where Google serves the stylesheets, and the origin the font FILES come from (preconnect). */
@@ -204,6 +422,13 @@ export interface FontsForTokensOptions {
      * would otherwise download a monospace face for a site with no code on it.
      */
     usedCss?: string;
+    /**
+     * The families the org UPLOADED. An uploaded family renders from the org's own files, so it is
+     * never fetched from Google — even when the catalog has a family of that name (an org that uploads
+     * Inter's variable file means THAT Inter: linking Google's too put its static cuts beside the
+     * upload, and the browser picked Google's — DS5.1).
+     */
+    uploaded?: ReadonlyArray<string>;
 }
 
 /**
@@ -219,16 +444,24 @@ export function fontsForTokens(
     const monoRead = MONO_REFERENCE.test(opts.usedCss ?? '')
         || rows.some(t => t.name !== MONO_ROLE && MONO_REFERENCE.test(`${t.value ?? ''} ${t.values?.dark ?? ''}`));
     const roles = monoRead ? FONT_FAMILY_TOKENS : ALWAYS_LOADED_ROLES;
+    const uploaded = new Set((opts.uploaded ?? []).map(fontFamilyKey));
     const seen = new Set<string>();
     const ids: string[] = [];
     for (const role of roles) {
         const row = rows.find(t => t.name === role);
+        // The role's FIRST family that renders decides: an uploaded one needs nothing from Google; the
+        // first catalog one is linked (it renders, or stands in for an uploaded family that is missing
+        // — `userFontStack` puts the look's font right after the author's). Nothing further down is
+        // ever reached, so nothing further down is loaded.
+        let id: string | null = null;
         for (const family of parseFontFamilies(row?.value ?? '')) {
-            const id = catalogFontId(family);
-            if (id && !seen.has(id)) {
-                seen.add(id);
-                ids.push(id);
-            }
+            if (uploaded.has(fontFamilyKey(family))) break;
+            id = catalogFontId(family);
+            if (id) break;
+        }
+        if (id && !seen.has(id)) {
+            seen.add(id);
+            ids.push(id);
         }
     }
     return ids;
@@ -243,28 +476,38 @@ export function stackNamesFamily(stack: string | null | undefined, family: strin
 }
 
 /**
- * The font tokens whose value names `family` — what the delete guard asks before an uploaded family's
- * last file goes (§5b): deleting it would silently drop those roles to their fallback.
+ * The font tokens that render in `family` — their stack LEADS with it — what the delete guard asks
+ * before an uploaded family's last file goes (§5b): deleting it would drop those roles to their
+ * fallback. A role naming it further down (the look's font behind the author's, `userFontStack`) does
+ * not render in it, and rewriting that role would throw the author's own choice away.
  */
 export function fontRoleReferences(
     tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
     family: string | null | undefined,
 ): FontFamilyToken[] {
+    const key = fontFamilyKey(family);
+    if (!key) return [];
     const rows = (tokens ?? []).filter(t => !!t && typeof t.name === 'string');
-    return FONT_FAMILY_TOKENS.filter(role => rows.some(t => t.name === role && stackNamesFamily(t.value, family)));
+    return FONT_FAMILY_TOKENS.filter(role => rows.some(t => t.name === role
+        && fontFamilyKey(parseFontFamilies(t.value ?? '')[0]) === key));
 }
 
 /**
- * The face CSS font matching picks for `weight` from `faces` (CSS Fonts §5.2): 400 tries 500 next,
- * 500 tries 400; lighter weights look down first, heavier ones up. So an `h1` at 600 over a family
- * uploaded at 400 + 700 renders the real 700 cut — the one worth preloading.
+ * The face CSS font matching picks for `weight` from `faces` (CSS Fonts §5.2): a face whose range
+ * holds the weight is exact (a variable file covers every weight on its axis); otherwise 400 tries
+ * 500 next, 500 tries 400; lighter weights look down first, heavier ones up — each face measured at
+ * its nearest end. So an `h1` at 600 over a family uploaded at 400 + 700 renders the real 700 cut —
+ * the one worth preloading.
  */
-export function matchFontWeight<T extends { weight: number }>(faces: ReadonlyArray<T>, weight: number): T | null {
+export function matchFontWeight<T extends { weight: FontWeight }>(faces: ReadonlyArray<T>, weight: number): T | null {
     if (!faces?.length) return null;
     const want = normalizeFontWeight(weight);
-    const exact = faces.find(f => normalizeFontWeight(f.weight) === want);
+    const exact = faces.find(f => fontWeightCovers(f.weight, want));
     if (exact) return exact;
-    const w = (f: T) => normalizeFontWeight(f.weight);
+    const w = (f: T) => {
+        const r = fontWeightRange(f.weight);
+        return r.max < want ? r.max : r.min;
+    };
     const below = (max: number) => [...faces].filter(f => w(f) < max).sort((a, b) => w(b) - w(a))[0] ?? null;
     const above = (min: number) => [...faces].filter(f => w(f) > min).sort((a, b) => w(a) - w(b))[0] ?? null;
     if (want >= 400 && want <= 500) {
@@ -306,3 +549,46 @@ export function fontPreloads(
     }
     return [...out.values()];
 }
+
+/** CSS generic families and the faces every visitor's system already has — never "missing". */
+const ALWAYS_AVAILABLE_FAMILIES: ReadonlySet<string> = new Set([
+    'serif', 'sans-serif', 'monospace', 'cursive', 'fantasy', 'system-ui', 'ui-serif', 'ui-sans-serif',
+    'ui-monospace', 'ui-rounded', 'emoji', 'math', 'fangsong', '-apple-system', 'blinkmacsystemfont',
+    'arial', 'helvetica', 'helvetica neue', 'georgia', 'times new roman', 'times', 'courier new', 'courier',
+    'verdana', 'tahoma', 'trebuchet ms', 'segoe ui', 'roboto', 'menlo', 'monaco', 'consolas',
+]);
+
+/** A font role naming a family that is neither uploaded nor in the catalog, and what renders instead. */
+export interface MissingFontRole {
+    role: FontFamilyToken;
+    /** The family the role names first, which no file and no catalog entry serves. */
+    family: string;
+    /** The next family in the role's stack that does render — the look's own font for a stack written
+     *  by `userFontStack`, `system-ui` for an older one. */
+    fallback: string;
+}
+
+/**
+ * Board 8's "the same check runs when a font token points at a missing family": the font roles whose
+ * FIRST family is not uploaded (`uploaded` — the org's families), not in the catalog and not a system
+ * face. Only meaningful over a listing that SUCCEEDED — an empty bucket because storage is down would
+ * otherwise report every uploaded family missing.
+ */
+export function missingFontRoles(
+    tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
+    uploaded: ReadonlyArray<string> | null | undefined,
+): MissingFontRole[] {
+    const have = new Set((uploaded ?? []).map(fontFamilyKey));
+    const available = (family: string) => {
+        const key = fontFamilyKey(family);
+        return have.has(key) || ALWAYS_AVAILABLE_FAMILIES.has(key) || catalogFontId(family) !== null;
+    };
+    const resolved = resolveTokenValues(tokens);
+    const out: MissingFontRole[] = [];
+    for (const role of FONT_FAMILY_TOKENS) {
+        const families = parseFontFamilies(resolved[role] ?? '');
+        if (!families.length || /^var\(/i.test(families[0]) || available(families[0])) continue;
+        out.push({ role, family: families[0], fallback: families.slice(1).find(available) ?? '' });
+    }
+    return out;
+}