@superdoc-dev/fonts 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@superdoc-dev/fonts",
+  "version": "0.1.0",
+  "description": "Optional bundled metric-compatible font substitutes for SuperDoc, shipped as bundler-resolvable assets.",
+  "type": "module",
+  "license": "SEE LICENSE IN assets/LICENSES.md",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "assets"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "sync": "node scripts/sync-assets.mjs",
+    "generate": "node scripts/generate-asset-urls.mjs && pnpm exec tsx scripts/generate-bundled-families.ts",
+    "check:families": "pnpm exec tsx scripts/check-bundled-families.ts",
+    "build": "node scripts/sync-assets.mjs && node scripts/generate-asset-urls.mjs && tsc --project tsconfig.json",
+    "prepare": "node scripts/sync-assets.mjs && node scripts/generate-asset-urls.mjs && tsc --project tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "typescript": "catalog:"
+  }
+}

package/src/asset-urls.ts

@@ -0,0 +1,76 @@
+/**
+ * GENERATED by scripts/generate-asset-urls.mjs - do not edit by hand.
+ *
+ * Each value is a static `new URL('../assets/<file>', import.meta.url)`, the cross-bundler
+ * pattern for "emit this asset and give me its final URL". Bundlers rewrite these at build
+ * time; under plain Node ESM they resolve to the file:// path inside the package.
+ */
+export const BUNDLED_FONT_ASSET_URLS: Readonly<Record<string, string>> = Object.freeze({
+  'ArchivoBlack-Regular.woff2': new URL('../assets/ArchivoBlack-Regular.woff2', import.meta.url).href,
+  'BacasimeAntique-Regular.woff2': new URL('../assets/BacasimeAntique-Regular.woff2', import.meta.url).href,
+  'C059-BdIta.woff2': new URL('../assets/C059-BdIta.woff2', import.meta.url).href,
+  'C059-Bold.woff2': new URL('../assets/C059-Bold.woff2', import.meta.url).href,
+  'C059-Italic.woff2': new URL('../assets/C059-Italic.woff2', import.meta.url).href,
+  'C059-Roman.woff2': new URL('../assets/C059-Roman.woff2', import.meta.url).href,
+  'Caladea-Bold.woff2': new URL('../assets/Caladea-Bold.woff2', import.meta.url).href,
+  'Caladea-BoldItalic.woff2': new URL('../assets/Caladea-BoldItalic.woff2', import.meta.url).href,
+  'Caladea-Italic.woff2': new URL('../assets/Caladea-Italic.woff2', import.meta.url).href,
+  'Caladea-Regular.woff2': new URL('../assets/Caladea-Regular.woff2', import.meta.url).href,
+  'Caprasimo-Regular.woff2': new URL('../assets/Caprasimo-Regular.woff2', import.meta.url).href,
+  'Cardo-Bold.woff2': new URL('../assets/Cardo-Bold.woff2', import.meta.url).href,
+  'Cardo-Italic.woff2': new URL('../assets/Cardo-Italic.woff2', import.meta.url).href,
+  'Cardo-Regular.woff2': new URL('../assets/Cardo-Regular.woff2', import.meta.url).href,
+  'Carlito-Bold.woff2': new URL('../assets/Carlito-Bold.woff2', import.meta.url).href,
+  'Carlito-BoldItalic.woff2': new URL('../assets/Carlito-BoldItalic.woff2', import.meta.url).href,
+  'Carlito-Italic.woff2': new URL('../assets/Carlito-Italic.woff2', import.meta.url).href,
+  'Carlito-Regular.woff2': new URL('../assets/Carlito-Regular.woff2', import.meta.url).href,
+  'ComicRelief-Bold.woff2': new URL('../assets/ComicRelief-Bold.woff2', import.meta.url).href,
+  'ComicRelief-Regular.woff2': new URL('../assets/ComicRelief-Regular.woff2', import.meta.url).href,
+  'Gelasio-Bold.woff2': new URL('../assets/Gelasio-Bold.woff2', import.meta.url).href,
+  'Gelasio-BoldItalic.woff2': new URL('../assets/Gelasio-BoldItalic.woff2', import.meta.url).href,
+  'Gelasio-Italic.woff2': new URL('../assets/Gelasio-Italic.woff2', import.meta.url).href,
+  'Gelasio-Regular.woff2': new URL('../assets/Gelasio-Regular.woff2', import.meta.url).href,
+  'InconsolataSemiExpanded-Bold.woff2': new URL('../assets/InconsolataSemiExpanded-Bold.woff2', import.meta.url).href,
+  'InconsolataSemiExpanded-Regular.woff2': new URL('../assets/InconsolataSemiExpanded-Regular.woff2', import.meta.url)
+    .href,
+  'LiberationMono-Bold.woff2': new URL('../assets/LiberationMono-Bold.woff2', import.meta.url).href,
+  'LiberationMono-BoldItalic.woff2': new URL('../assets/LiberationMono-BoldItalic.woff2', import.meta.url).href,
+  'LiberationMono-Italic.woff2': new URL('../assets/LiberationMono-Italic.woff2', import.meta.url).href,
+  'LiberationMono-Regular.woff2': new URL('../assets/LiberationMono-Regular.woff2', import.meta.url).href,
+  'LiberationSans-Bold.woff2': new URL('../assets/LiberationSans-Bold.woff2', import.meta.url).href,
+  'LiberationSans-BoldItalic.woff2': new URL('../assets/LiberationSans-BoldItalic.woff2', import.meta.url).href,
+  'LiberationSans-Italic.woff2': new URL('../assets/LiberationSans-Italic.woff2', import.meta.url).href,
+  'LiberationSans-Regular.woff2': new URL('../assets/LiberationSans-Regular.woff2', import.meta.url).href,
+  'LiberationSansNarrow-Bold.woff2': new URL('../assets/LiberationSansNarrow-Bold.woff2', import.meta.url).href,
+  'LiberationSansNarrow-BoldItalic.woff2': new URL('../assets/LiberationSansNarrow-BoldItalic.woff2', import.meta.url)
+    .href,
+  'LiberationSansNarrow-Italic.woff2': new URL('../assets/LiberationSansNarrow-Italic.woff2', import.meta.url).href,
+  'LiberationSansNarrow-Regular.woff2': new URL('../assets/LiberationSansNarrow-Regular.woff2', import.meta.url).href,
+  'LiberationSerif-Bold.woff2': new URL('../assets/LiberationSerif-Bold.woff2', import.meta.url).href,
+  'LiberationSerif-BoldItalic.woff2': new URL('../assets/LiberationSerif-BoldItalic.woff2', import.meta.url).href,
+  'LiberationSerif-Italic.woff2': new URL('../assets/LiberationSerif-Italic.woff2', import.meta.url).href,
+  'LiberationSerif-Regular.woff2': new URL('../assets/LiberationSerif-Regular.woff2', import.meta.url).href,
+  'NotoSans-Bold.woff2': new URL('../assets/NotoSans-Bold.woff2', import.meta.url).href,
+  'NotoSans-BoldItalic.woff2': new URL('../assets/NotoSans-BoldItalic.woff2', import.meta.url).href,
+  'NotoSans-Italic.woff2': new URL('../assets/NotoSans-Italic.woff2', import.meta.url).href,
+  'NotoSans-Regular.woff2': new URL('../assets/NotoSans-Regular.woff2', import.meta.url).href,
+  'NotoSansMono-Bold.woff2': new URL('../assets/NotoSansMono-Bold.woff2', import.meta.url).href,
+  'NotoSansMono-Regular.woff2': new URL('../assets/NotoSansMono-Regular.woff2', import.meta.url).href,
+  'OreganoItalic-Regular.woff2': new URL('../assets/OreganoItalic-Regular.woff2', import.meta.url).href,
+  'PTSans-Bold.woff2': new URL('../assets/PTSans-Bold.woff2', import.meta.url).href,
+  'PTSans-BoldItalic.woff2': new URL('../assets/PTSans-BoldItalic.woff2', import.meta.url).href,
+  'PTSans-Italic.woff2': new URL('../assets/PTSans-Italic.woff2', import.meta.url).href,
+  'PTSans-Regular.woff2': new URL('../assets/PTSans-Regular.woff2', import.meta.url).href,
+  'PTSansNarrow-Bold.woff2': new URL('../assets/PTSansNarrow-Bold.woff2', import.meta.url).href,
+  'PTSansNarrow-Regular.woff2': new URL('../assets/PTSansNarrow-Regular.woff2', import.meta.url).href,
+  'Selawik-Bold.woff2': new URL('../assets/Selawik-Bold.woff2', import.meta.url).href,
+  'Selawik-Regular.woff2': new URL('../assets/Selawik-Regular.woff2', import.meta.url).href,
+  'TeXGyreBonum-Bold.woff2': new URL('../assets/TeXGyreBonum-Bold.woff2', import.meta.url).href,
+  'TeXGyreBonum-BoldItalic.woff2': new URL('../assets/TeXGyreBonum-BoldItalic.woff2', import.meta.url).href,
+  'TeXGyreBonum-Italic.woff2': new URL('../assets/TeXGyreBonum-Italic.woff2', import.meta.url).href,
+  'TeXGyreBonum-Regular.woff2': new URL('../assets/TeXGyreBonum-Regular.woff2', import.meta.url).href,
+  'URWGothic-Book.woff2': new URL('../assets/URWGothic-Book.woff2', import.meta.url).href,
+  'URWGothic-BookOblique.woff2': new URL('../assets/URWGothic-BookOblique.woff2', import.meta.url).href,
+  'URWGothic-Demi.woff2': new URL('../assets/URWGothic-Demi.woff2', import.meta.url).href,
+  'URWGothic-DemiOblique.woff2': new URL('../assets/URWGothic-DemiOblique.woff2', import.meta.url).href,
+});

package/src/bundled-families.ts

@@ -0,0 +1,40 @@
+/**
+ * GENERATED by scripts/generate-bundled-families.ts - do not edit by hand.
+ *
+ * The Word family names a document can curate via createSuperDocFonts({ include / exclude }), mirrored
+ * from @superdoc/font-system's runtime curation set (every logical family the resolver substitutes to a
+ * bundled face, including category fallbacks like Verdana). A name outside this set is a typo or an
+ * unbundled font, so createSuperDocFonts rejects it instead of silently dropping the intended fonts.
+ */
+export const BUNDLED_FAMILY_NAMES: readonly string[] = Object.freeze([
+  'Arial',
+  'Arial Black',
+  'Arial MT',
+  'Arial Narrow',
+  'Baskerville Old Face',
+  'Bookman Old Style',
+  'Brush Script MT',
+  'Calibri',
+  'Calibri Light',
+  'Cambria',
+  'Century',
+  'Century Gothic',
+  'Century Schoolbook',
+  'Comic Sans MS',
+  'Consolas',
+  'Cooper Black',
+  'Courier',
+  'Courier New',
+  'Garamond',
+  'Georgia',
+  'Gill Sans MT Condensed',
+  'Helvetica',
+  'ITC Bookman',
+  'Lucida Console',
+  'Segoe UI',
+  'Tahoma',
+  'Times',
+  'Times New Roman',
+  'Trebuchet MS',
+  'Verdana',
+]);

package/src/index.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+import { BUNDLED_FONT_ASSET_URLS, createSuperDocFonts, resolveBundledFontAssetUrl, superdocFonts } from './index';
+
+describe('superdocFonts / resolveBundledFontAssetUrl', () => {
+  it('superdocFonts is a ready-made resolveAssetUrl config', () => {
+    expect(typeof superdocFonts.resolveAssetUrl).toBe('function');
+  });
+
+  it('resolves a known bundled face to its emitted URL', () => {
+    const file = Object.keys(BUNDLED_FONT_ASSET_URLS)[0];
+    expect(file).toBeTruthy();
+    expect(superdocFonts.resolveAssetUrl({ file })).toBe(BUNDLED_FONT_ASSET_URLS[file]);
+  });
+
+  it('throws on an unknown file so a version mismatch surfaces immediately', () => {
+    expect(() => resolveBundledFontAssetUrl({ file: 'NotAFont.woff2' })).toThrow(/no bundled asset/);
+  });
+});
+
+describe('createSuperDocFonts', () => {
+  it('with no options is the full pack: resolver only, no curation', () => {
+    const config = createSuperDocFonts();
+    expect(typeof config.resolveAssetUrl).toBe('function');
+    expect(config.bundled).toBeUndefined();
+  });
+
+  it('include sets an allow-list', () => {
+    expect(createSuperDocFonts({ include: ['Calibri', 'Cambria'] }).bundled).toEqual({
+      include: ['Calibri', 'Cambria'],
+    });
+  });
+
+  it('exclude sets a block-list', () => {
+    expect(createSuperDocFonts({ exclude: ['Cooper Black'] }).bundled).toEqual({ exclude: ['Cooper Black'] });
+  });
+
+  it('trims entries and drops empty lists', () => {
+    expect(createSuperDocFonts({ include: ['  Calibri  '] }).bundled).toEqual({ include: ['Calibri'] });
+    expect(createSuperDocFonts({ include: [] }).bundled).toBeUndefined();
+    expect(createSuperDocFonts({ exclude: [] }).bundled).toBeUndefined();
+  });
+
+  it('throws when include and exclude are both given (mutually exclusive intents)', () => {
+    expect(() => createSuperDocFonts({ include: ['Calibri'], exclude: ['Cambria'] })).toThrow(/not both/);
+  });
+
+  it('throws on a non-array list or non-string entries', () => {
+    expect(() => createSuperDocFonts({ include: 'Calibri' as unknown as string[] })).toThrow(/must be an array/);
+    expect(() => createSuperDocFonts({ exclude: ['Calibri', 42 as unknown as string] })).toThrow(
+      /non-empty font name strings/,
+    );
+  });
+
+  it('throws on a font name SuperDoc does not bundle, suggesting the closest match for a typo', () => {
+    expect(() => createSuperDocFonts({ include: ['Calbri'] })).toThrow(/does not bundle/);
+    expect(() => createSuperDocFonts({ include: ['Calbri'] })).toThrow(/did you mean "Calibri"\?/);
+    // A real Word font with no bundled clone is also rejected (curating it would be a no-op).
+    expect(() => createSuperDocFonts({ exclude: ['Aptos'] })).toThrow(/does not bundle/);
+  });
+
+  it('accepts every family the toolbar advertises, including category fallbacks like Verdana', () => {
+    // Regression: the curatable list must mirror the resolver/offerings, not the manifest's narrower
+    // metric-clone `replaces` (which omits Verdana). A font shown in the toolbar must be curatable.
+    expect(() => createSuperDocFonts({ exclude: ['Verdana'] })).not.toThrow();
+    expect(() => createSuperDocFonts({ include: ['Verdana', 'Calibri'] })).not.toThrow();
+    expect(createSuperDocFonts({ exclude: ['Verdana'] }).bundled).toEqual({ exclude: ['Verdana'] });
+  });
+
+  it('accepts case- and quote-variant spellings of bundled families (matched normalized)', () => {
+    expect(() => createSuperDocFonts({ include: ['  calibri  ', '"Cambria"'] })).not.toThrow();
+  });
+});

package/src/index.ts

@@ -0,0 +1,209 @@
+/**
+ * `@superdoc-dev/fonts` - the reviewed metric-compatible font substitutes SuperDoc renders for
+ * proprietary Word fonts (Carlito for Calibri, Liberation Serif for Times New Roman, etc.).
+ *
+ * Optional: install it to make the bundled fallbacks load automatically in any bundler app, with
+ * no copy step and no `assetBaseUrl`. The asset URLs are written as
+ * `new URL('../assets/<file>', import.meta.url)`, which Vite, Webpack 5, Next, Nuxt, esbuild, and
+ * Parcel detect, emit, and rewrite to the final hashed path.
+ *
+ * @beta This package is in preview; its surface may change before 1.0.
+ */
+import { BUNDLED_FONT_ASSET_URLS } from './asset-urls';
+import { BUNDLED_FAMILY_NAMES } from './bundled-families';
+
+/**
+ * The full filename -> bundler-emitted URL map for every bundled face. Most consumers use
+ * {@link superdocFonts} or {@link resolveBundledFontAssetUrl} instead of reading this directly.
+ *
+ * @beta
+ */
+export { BUNDLED_FONT_ASSET_URLS };
+
+/**
+ * Minimal structural shape of SuperDoc's bundled-font asset context. Kept LOCAL so this
+ * package has no dependency on `@superdoc/font-system`; only `file` is read. Assignable to
+ * SuperDoc's `FontAssetUrlResolver` by structural typing.
+ *
+ * @beta
+ */
+export interface BundledFontAssetContext {
+  /** Asset filename, e.g. `Carlito-Regular.woff2`. */
+  file: string;
+  family?: string;
+  weight?: string;
+  style?: 'normal' | 'italic';
+  source?: string;
+}
+
+/**
+ * Resolve a bundled substitute face filename to a bundler-emitted URL.
+ *
+ * Pass as SuperDoc's `fonts.resolveAssetUrl` so the reviewed fallback pack loads from THIS
+ * package's emitted assets, with no manual copy step and no `assetBaseUrl`:
+ *
+ *     import { resolveBundledFontAssetUrl } from '@superdoc-dev/fonts';
+ *     new SuperDoc({ selector: '#editor', document, fonts: { resolveAssetUrl: resolveBundledFontAssetUrl } });
+ *
+ * Throws on an unknown file, which signals a version mismatch between `@superdoc-dev/fonts` and
+ * the `superdoc` core manifest rather than silently degrading to the logical font name.
+ *
+ * @beta
+ */
+export function resolveBundledFontAssetUrl(context: BundledFontAssetContext): string {
+  const url = BUNDLED_FONT_ASSET_URLS[context.file];
+  if (!url) {
+    throw new Error(
+      `[@superdoc-dev/fonts] no bundled asset for "${context.file}". This pack ships ` +
+        `${Object.keys(BUNDLED_FONT_ASSET_URLS).length} faces; the file is unknown, so ` +
+        `@superdoc-dev/fonts and superdoc are likely version-mismatched. Align their versions.`,
+    );
+  }
+  return url;
+}
+
+/**
+ * Drop-in value for SuperDoc's `fonts` config: `new SuperDoc({ fonts: superdocFonts })`.
+ * Equivalent to `{ resolveAssetUrl: resolveBundledFontAssetUrl }`.
+ *
+ * @beta
+ */
+export const superdocFonts: { resolveAssetUrl: (context: BundledFontAssetContext) => string } = {
+  resolveAssetUrl: resolveBundledFontAssetUrl,
+};
+
+/**
+ * Choose which bundled families SuperDoc advertises and renders, by LOGICAL Word family name
+ * (`"Calibri"`, never the physical `"Carlito"`).
+ *
+ * @beta
+ */
+export interface SuperDocFontsOptions {
+  /** Allow-list: ONLY these logical families are active, e.g. `['Calibri', 'Cambria']`. */
+  include?: string[];
+  /** Block-list: every bundled family EXCEPT these, e.g. `['Cooper Black', 'Brush Script MT']`. */
+  exclude?: string[];
+}
+
+/**
+ * The `fonts` config {@link createSuperDocFonts} returns: the bundled-asset resolver plus the
+ * curation. Structurally assignable to SuperDoc's `fonts` option.
+ *
+ * @beta
+ */
+export interface SuperDocFontsConfig {
+  resolveAssetUrl: (context: BundledFontAssetContext) => string;
+  bundled?: { include?: string[]; exclude?: string[] };
+}
+
+/**
+ * Build a curated `fonts` config: the bundled pack, narrowed to the families you choose.
+ *
+ *     import { createSuperDocFonts } from '@superdoc-dev/fonts';
+ *     new SuperDoc({
+ *       selector: '#editor',
+ *       document,
+ *       fonts: createSuperDocFonts({ exclude: ['Cooper Black', 'Brush Script MT'] }),
+ *     });
+ *
+ * Names are Word logical families. Pass neither `include` nor `exclude` for the full pack - that is
+ * exactly {@link superdocFonts}. Curation governs the BUNDLED pack only; your own licensed fonts stay
+ * separate (`fonts.families` / `fonts.map`).
+ *
+ * @beta
+ */
+export function createSuperDocFonts(options: SuperDocFontsOptions = {}): SuperDocFontsConfig {
+  const include = normalizeNameList(options.include, 'include');
+  const exclude = normalizeNameList(options.exclude, 'exclude');
+  // include and exclude are mutually exclusive intents; accepting both silently would hide which one
+  // wins. Reject at the API boundary (this runs in the consumer's setup code, so it fails fast and
+  // clearly) rather than picking one arbitrarily.
+  if (include && exclude) {
+    throw new Error(
+      '[@superdoc-dev/fonts] createSuperDocFonts: pass `include` OR `exclude`, not both. ' +
+        '`include` is an allow-list (only those families resolve and appear in the toolbar); ' +
+        '`exclude` keeps everything but the named families.',
+    );
+  }
+  // Reject names SuperDoc does not bundle. This runs in the consumer's setup code, so it fails fast
+  // and clearly - especially for `include`, where a typo would otherwise silently hide the fonts the
+  // consumer meant to keep. (Raw `fonts.bundled` set directly stays lenient and only warns.)
+  if (include) assertKnownFamilies(include, 'include');
+  if (exclude) assertKnownFamilies(exclude, 'exclude');
+  const config: SuperDocFontsConfig = { resolveAssetUrl: resolveBundledFontAssetUrl };
+  if (include) config.bundled = { include };
+  else if (exclude) config.bundled = { exclude };
+  return config;
+}
+
+/** Validate and clean a curation list: an array of non-empty strings, or omitted. Throws on misuse. */
+function normalizeNameList(value: string[] | undefined, field: 'include' | 'exclude'): string[] | undefined {
+  if (value == null) return undefined;
+  if (!Array.isArray(value)) {
+    throw new Error(`[@superdoc-dev/fonts] createSuperDocFonts: \`${field}\` must be an array of Word font names.`);
+  }
+  const names = value.map((name) => (typeof name === 'string' ? name.trim() : '')).filter(Boolean);
+  if (names.length !== value.length) {
+    throw new Error(
+      `[@superdoc-dev/fonts] createSuperDocFonts: \`${field}\` must contain only non-empty font name strings ` +
+        `(e.g. ["Calibri", "Cambria"]).`,
+    );
+  }
+  return names.length ? names : undefined;
+}
+
+/** Normalize a family name for matching: trim, strip surrounding quotes, lowercase. */
+function normalizeKey(name: string): string {
+  return name
+    .trim()
+    .replace(/^["']|["']$/g, '')
+    .toLowerCase();
+}
+
+const KNOWN_FAMILY_KEYS: ReadonlySet<string> = new Set(BUNDLED_FAMILY_NAMES.map(normalizeKey));
+
+/** Bounded Levenshtein distance between two short strings, for a "did you mean" hint on a typo. */
+function editDistance(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  if (Math.abs(m - n) > 2) return 3;
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  for (let i = 1; i <= m; i += 1) {
+    const curr = [i];
+    for (let j = 1; j <= n; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    prev = curr;
+  }
+  return prev[n];
+}
+
+/** The closest bundled family within edit distance 2, or null - so a typo gets a concrete suggestion. */
+function closestKnownFamily(name: string): string | null {
+  const key = normalizeKey(name);
+  let best: string | null = null;
+  let bestDist = 3;
+  for (const family of BUNDLED_FAMILY_NAMES) {
+    const dist = editDistance(key, normalizeKey(family));
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = family;
+    }
+  }
+  return best;
+}
+
+/** Throw on any curation name SuperDoc does not bundle, with a suggestion and the full valid list. */
+function assertKnownFamilies(names: readonly string[], field: 'include' | 'exclude'): void {
+  const unknown = names.filter((name) => !KNOWN_FAMILY_KEYS.has(normalizeKey(name)));
+  if (unknown.length === 0) return;
+  const hints = unknown.map((name) => {
+    const suggestion = closestKnownFamily(name);
+    return suggestion ? `"${name}" (did you mean "${suggestion}"?)` : `"${name}"`;
+  });
+  throw new Error(
+    `[@superdoc-dev/fonts] createSuperDocFonts: \`${field}\` names a font SuperDoc does not bundle: ${hints.join(', ')}. ` +
+      `Curate by Word family name. Bundled families: ${BUNDLED_FAMILY_NAMES.join(', ')}.`,
+  );
+}