feat(fonts): config-gated bundled font availability and curation (SD-3441)

Without a configured pack SuperDoc advertises and renders only a safe baseline (one font per CSS generic), so an unconfigured app never fetches a bundled substitute it cannot serve. Configuring the pack (@superdoc/fonts, fonts.assetBaseUrl/resolveAssetUrl, or the CDN build) lights up the full reviewed set, gated by config presence rather than a runtime probe.

createSuperDocFonts({ include / exclude }) curates the pack by Word family name, validated against the offerings so a typo fails fast at setup time. Activation is document-scoped in the resolver and offerings and folded into the resolver signature, so a no-pack or curated document never reuses a full-pack document's measures. A CI drift check keeps the generated curatable list in sync with the offerings.

Author: caio-pizzol

.github/workflows/ci-superdoc.yml

@@ -39,6 +39,7 @@ jobs:
               - 'packages/document-api/**'
               - 'packages/collaboration-yjs/**'
               - 'packages/docx-evidence-contracts/**'
+              - 'packages/fonts/**'
               - 'shared/**'
               - 'tests/**'
               - 'scripts/**'
@@ -131,6 +132,13 @@ jobs:
         # Local equivalent: `pnpm check:public:superdoc` (with build).
         run: pnpm check:public:superdoc --skip-build
 
+      - name: Font curation list drift check
+        # Fails if the committed packages/fonts/src/bundled-families.ts no longer matches the
+        # font-system curation set, so a font-offerings change that is not regenerated cannot merge
+        # stale (guards the Verdana-bug class). Runs here because the job's path filter covers both
+        # the font offerings (shared/**) and the fonts package (packages/fonts/**).
+        run: pnpm --filter @superdoc/fonts run check:families
+
   unit-tests:
     needs: build
     runs-on: ubuntu-latest

apps/docs/advanced/headless-toolbar.mdx

@@ -329,7 +329,7 @@ Snapshot values match the format you pass to `execute()`. What you read is what
 
 For a font dropdown that also includes fonts used by the active document, use `useSuperDocFontOptions()` from `superdoc/ui/react` or `ui.fonts` from `superdoc/ui`.
 
-`DEFAULT_FONT_FAMILY_OPTIONS` mirrors the built-in picker list. It can include bundled font choices beyond the core defaults; use the font report when you need per-font rendering details.
+`DEFAULT_FONT_FAMILY_OPTIONS` is the conservative no-pack baseline - one Word font per CSS generic (Arial, Times New Roman, Courier New). For the full pack plus any curation and the active document's fonts, use `useSuperDocFontOptions()` from `superdoc/ui/react` or `ui.fonts` from `superdoc/ui`; they reflect the configured pack at runtime, which a static constant cannot.
 
 For font family, font size, and other commands that apply to selected text, prefer a button menu or popover that prevents `mousedown` from moving focus out of the editor. Native selects can visually clear the editor selection while their menu is open.
 
@@ -361,7 +361,7 @@ const {
 
 | Constant | Contents |
 |----------|----------|
-| `DEFAULT_FONT_FAMILY_OPTIONS` | Built-in picker list. Includes strict defaults plus explicitly advertised bundled fallback choices. |
+| `DEFAULT_FONT_FAMILY_OPTIONS` | Conservative no-pack baseline: one font per CSS generic (Arial, Times New Roman, Courier New). Configure the pack for the full list, or use `useSuperDocFontOptions()` / `ui.fonts`. |
 | `DEFAULT_FONT_SIZE_OPTIONS` | 8pt through 96pt (14 sizes) |
 | `DEFAULT_TEXT_ALIGN_OPTIONS` | left, center, right, justify |
 | `DEFAULT_LINE_HEIGHT_OPTIONS` | 1.00, 1.15, 1.50, 2.00, 2.50, 3.00 |

apps/docs/editor/custom-ui/toolbar-and-commands.mdx

@@ -101,7 +101,7 @@ function FontSizePicker() {
 
 ## Font family picker
 
-Use `useSuperDocFontOptions()` for a custom font dropdown. It returns the built-in defaults plus fonts used by the active document, sorted alphabetically.
+Use `useSuperDocFontOptions()` for a custom font dropdown. It returns the fonts SuperDoc can render plus fonts used by the active document, sorted alphabetically. Without a configured font pack that is the conservative baseline; configure the pack (`@superdoc/fonts`, or `fonts.assetBaseUrl`) and it returns the full set, minus anything curated with `createSuperDocFonts`.
 
 `label` is what you show. `value` is what you pass to the `font-family` command. `previewFamily` is only for rendering the option row.
 

apps/docs/getting-started/fonts.mdx

@@ -10,6 +10,8 @@ SuperDoc keeps the font name from the Word document. When SuperDoc ships an appr
 
 A Word document asks for fonts like Calibri, Cambria, and Times New Roman. Most are proprietary, or not installed on every machine. SuperDoc renders them with reviewed open substitutes that match the metrics: Carlito for Calibri, Liberation Serif for Times New Roman, and more. The original name is kept for export.
 
+Without the pack, the toolbar lists one widely available font per CSS generic: Arial for sans-serif, Times New Roman for serif, Courier New for monospace. Each is applied with that generic as a fallback, so it renders acceptably even where the exact font is absent - a readable floor, not an exact-typography guarantee. Wire the pack and the toolbar lists the full reviewed set, and SuperDoc renders the substitutes everywhere. Either way, the Word font name is kept for export.
+
 These substitutes are real `.woff2` files. The browser fetches them from a URL. Installing SuperDoc from npm puts them in `node_modules`, which does not serve them to the browser. So you tell your app where they live. Pick one path.
 
 ### Recommended: the `@superdoc/fonts` package
@@ -31,6 +33,30 @@ new SuperDoc({
 });
 ```
 
+### Choose which bundled fonts
+
+By default the pack enables every reviewed font. To narrow it, use `createSuperDocFonts` and name the families. Think in Word names (`Calibri`, not the substitute `Carlito`).
+
+Drop a few:
+
+```js
+import { createSuperDocFonts } from '@superdoc/fonts';
+
+new SuperDoc({
+  selector: '#editor',
+  document: 'contract.docx',
+  fonts: createSuperDocFonts({ exclude: ['Cooper Black', 'Brush Script MT'] }),
+});
+```
+
+Or allow only a set:
+
+```js
+fonts: createSuperDocFonts({ include: ['Calibri', 'Cambria', 'Arial'] }),
+```
+
+Curation changes the toolbar list and which families SuperDoc substitutes. It does not touch your own licensed fonts (see [Load your own fonts](#load-your-own-fonts)). A curated-out family a document still uses keeps its Word name for export and renders with a system font.
+
 ### Alternative: host the files yourself
 
 Serve the `.woff2` from your own path or a CDN, then point SuperDoc at them. The files ship in the package at `node_modules/superdoc/dist/fonts/`.
@@ -51,7 +77,7 @@ The CDN build loads the fonts from a path relative to the script. Loading from a
 
 ### Skipping the pack
 
-The pack is optional. Skip it if you load your own fonts for every family, or only need fonts the user's OS already has. When the bundled `.woff2` cannot be fetched, SuperDoc logs a one-time warning and falls back to the original font name. On a machine without that font, the text renders in a system fallback, so it can look unchanged.
+The pack is optional. Skip it if you load your own fonts for every family, or only need fonts the user's OS already has. With no pack configured the toolbar shows the baseline and documents render with system fonts, quietly. If you do wire the pack but the `.woff2` cannot be fetched, SuperDoc logs a one-time warning that names the fix; until then text falls back to the original font name, so it can look unchanged on a machine that lacks it.
 
 ## Load your own fonts
 
@@ -69,7 +95,7 @@ SuperDoc's built-in fallbacks cover only the fonts it ships and verifies. For ev
 
 ## Toolbar font list
 
-The built-in toolbar lists SuperDoc's defaults plus fonts used by the active document, sorted alphabetically. If you pass `modules.toolbar.fonts`, that custom list replaces the default list.
+The built-in toolbar lists the fonts SuperDoc can render, plus the fonts the active document uses, sorted alphabetically. With no pack configured that is the baseline of one font per CSS generic (Arial, Times New Roman, Courier New); with the pack it is the full reviewed set, minus anything you curated out with `createSuperDocFonts`. If you pass `modules.toolbar.fonts`, that custom list replaces it entirely.
 
 Each custom entry is a `{ label, key }` pair where `key` is the CSS `font-family` value:
 
@@ -108,6 +134,7 @@ editor.doc.format.apply({
 
 - **Font name preserved, browser falls back.** SuperDoc keeps the DOCX font name. If no bundled fallback or loaded real font exists, the browser chooses its own fallback.
 - **Custom toolbar list hides document fonts.** Passing `modules.toolbar.fonts` replaces the built-in list. Include every option you want users to pick.
+- **Not every bundled family ships every weight and style.** A few substitutes are a single face. For a bold or italic run the substitute lacks, SuperDoc renders the faces it has and leaves the missing ones to the browser's fallback rather than synthesizing a face, so spacing stays predictable.
 - **Office font licensing.** Calibri, Cambria, and Aptos are licensed Microsoft fonts. Self-hosting the real files requires a license.
 
 ## Where to next

packages/fonts/README.md

@@ -40,6 +40,25 @@ That is the whole setup. No copying files into `public/`, no `assetBaseUrl`. The
 written as `new URL('../assets/<file>', import.meta.url)`, which Vite, Webpack 5, Next, Nuxt,
 esbuild, and Parcel all detect, emit, and rewrite to the final hashed path.
 
+### Choosing which fonts
+
+`superdocFonts` enables every reviewed family. To narrow the set, use `createSuperDocFonts` and name
+the families by their Word name (`Calibri`, not the substitute `Carlito`):
+
+```js
+import { createSuperDocFonts } from '@superdoc/fonts';
+
+// Everything except a couple:
+new SuperDoc({ selector: '#editor', document, fonts: createSuperDocFonts({ exclude: ['Cooper Black'] }) });
+
+// Or only an explicit set:
+new SuperDoc({ selector: '#editor', document, fonts: createSuperDocFonts({ include: ['Calibri', 'Cambria'] }) });
+```
+
+`include` is an allow-list; `exclude` keeps everything but the named families. Curation drives the
+toolbar list and which families SuperDoc substitutes. Your own licensed fonts stay separate
+(`fonts.families`).
+
 ### Hosting the assets another way
 
 If you serve the fonts from a CDN or a signed path instead, you do not need this package's

packages/fonts/package.json

@@ -27,10 +27,12 @@
   "sideEffects": false,
   "scripts": {
     "sync": "node scripts/sync-assets.mjs",
-    "generate": "node scripts/generate-asset-urls.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"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest"
   },
   "devDependencies": {
     "@types/node": "catalog:",

packages/fonts/scripts/check-bundled-families.ts

@@ -0,0 +1,39 @@
+// Non-mutating drift check (CI-safe): fails if the committed src/bundled-families.ts no longer
+// matches @superdoc/font-system's runtime curation set (getBundledFamilyNames). Guards the
+// Verdana-bug class - a font-offerings change that regenerates the list in a CI working tree but
+// merges without the committed update, so the published list silently drifts.
+//
+// Skips when the font-system source is absent (a standalone install cannot recompute the set); in the
+// monorepo it runs and a real import error fails loudly. Run via
+// `pnpm --filter @superdoc/fonts check:families`.
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BUNDLED_FAMILY_NAMES } from '../src/bundled-families';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const fontSystemSource = resolve(here, '../../../shared/font-system/src/font-offerings.ts');
+
+if (!existsSync(fontSystemSource)) {
+  console.log('[@superdoc/fonts] font-system source not present (standalone install); skipping curation-drift check');
+  process.exit(0);
+}
+
+// eslint-disable-next-line import-x/no-relative-packages -- build-only script (not shipped); @superdoc/fonts stays a dependency-free runtime package and font-system exposes no /src export, so reading its source relatively here is intentional
+const { getBundledFamilyNames } = await import('../../../shared/font-system/src/font-offerings');
+const expected = [...getBundledFamilyNames()].sort();
+const committed = [...BUNDLED_FAMILY_NAMES].sort();
+
+if (JSON.stringify(expected) !== JSON.stringify(committed)) {
+  const missing = expected.filter((name) => !committed.includes(name));
+  const extra = committed.filter((name) => !expected.includes(name));
+  console.error(
+    '[@superdoc/fonts] src/bundled-families.ts is STALE: it no longer matches the font-system curation set.',
+  );
+  if (missing.length) console.error(`  missing (in offerings, not committed): ${missing.join(', ')}`);
+  if (extra.length) console.error(`  extra (committed, not in offerings):    ${extra.join(', ')}`);
+  console.error('  Fix: run `pnpm --filter @superdoc/fonts generate` and commit src/bundled-families.ts');
+  process.exit(1);
+}
+
+console.log(`[@superdoc/fonts] curation list in sync with font-system (${committed.length} families)`);

packages/fonts/scripts/generate-asset-urls.mjs

@@ -17,6 +17,17 @@ const local = resolve(here, '../assets');
 const sourceDir = existsSync(canonical) ? canonical : local;
 const outFile = resolve(here, '../src/asset-urls.ts');
 
+/** Format with the repo Prettier when available so committed output is stable; tolerate its absence. */
+async function formatTs(content, filepath) {
+  try {
+    const prettier = await import('prettier');
+    const config = (await prettier.resolveConfig(filepath)) ?? {};
+    return await prettier.format(content, { ...config, filepath });
+  } catch {
+    return content;
+  }
+}
+
 const files = readdirSync(sourceDir)
   .filter((f) => f.endsWith('.woff2'))
   .sort();
@@ -44,16 +55,11 @@ ${entries}
 // generator produces byte-identical output and the format hook never rewrites it. Prettier is
 // optional - in a consumer git-install it may be absent, and the unformatted output is still
 // valid TypeScript - so a missing prettier is not an error.
-let output = content;
-try {
-  const prettier = await import('prettier');
-  const config = (await prettier.resolveConfig(outFile)) ?? {};
-  output = await prettier.format(content, { ...config, filepath: outFile });
-} catch {
-  // Prettier not resolvable here; write the unformatted (still valid) output.
-}
-
-writeFileSync(outFile, output);
+writeFileSync(outFile, await formatTs(content, outFile));
 console.log(
   `[@superdoc/fonts] wrote ${files.length} asset URLs -> src/asset-urls.ts (source: ${sourceDir.includes('shared') ? 'canonical' : 'local'})`,
 );
+
+// The curatable family-name list (src/bundled-families.ts) is generated SEPARATELY by
+// scripts/generate-bundled-families.ts: it must mirror the runtime resolver/offerings curation set
+// (which includes category fallbacks like Verdana), not the asset manifest's metric-clone `replaces`.

packages/fonts/scripts/generate-bundled-families.ts

@@ -0,0 +1,55 @@
+// Generates src/bundled-families.ts: 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) - NOT the asset manifest's narrower metric-clone `replaces`.
+//
+// Skips when the font-system source is absent (a rare standalone install), leaving the committed file;
+// in the monorepo a real import error fails loudly. Committed so npm consumers get the list without
+// re-generating. Re-run via `pnpm --filter @superdoc/fonts generate` when the curation set changes.
+import { existsSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const outFile = resolve(here, '../src/bundled-families.ts');
+const fontSystemSource = resolve(here, '../../../shared/font-system/src/font-offerings.ts');
+
+if (!existsSync(fontSystemSource)) {
+  console.log(
+    '[@superdoc/fonts] font-system source not present (standalone install); kept committed src/bundled-families.ts',
+  );
+  process.exit(0);
+}
+
+// eslint-disable-next-line import-x/no-relative-packages -- build-only script (not shipped); @superdoc/fonts stays a dependency-free runtime package and font-system exposes no /src export, so reading its source relatively here is intentional
+const { getBundledFamilyNames } = await import('../../../shared/font-system/src/font-offerings');
+const names = getBundledFamilyNames();
+if (names.length === 0) {
+  console.error('[@superdoc/fonts] font-system returned no curatable families');
+  process.exit(1);
+}
+
+const content = `/**
+ * 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([
+${names.map((name) => `  ${JSON.stringify(name)},`).join('\n')}
+]);
+`;
+
+let output = content;
+try {
+  const prettier = await import('prettier');
+  const config = (await prettier.resolveConfig(outFile)) ?? {};
+  output = await prettier.format(content, { ...config, filepath: outFile });
+} catch {
+  // Prettier optional; the unformatted output is still valid TypeScript.
+}
+
+writeFileSync(outFile, output);
+console.log(`[@superdoc/fonts] wrote ${names.length} curatable family names -> src/bundled-families.ts`);

packages/fonts/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',
+]);