@astryxdesign/cli 0.4.1 → 0.4.2-canary.464a445

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @xds/cli
 
+# 0.4.2
+
+#### New Features
+
+- `astryx theme build` warns when a theme names fonts it does not load. The resolved `--font-family-*` tokens and component-override `fontFamily` values are checked against CSS generics and known system families; anything else gets one warning per family in the receipt and, after the install instructions, the `<link>`/`@font-face` snippet to add. `astryx docs typography` gains a Loading Custom Fonts section (Google Fonts and self-hosted recipes, `font-display: swap`, real fallback stacks), and the theme docs' production-build section points at it (#5015).
+- `astryx theme template` writes an annotated theme template into your project (#5048).
+  New sibling of `theme add`: where `add` starts you from a theme we ship, `template` starts you from a blank annotated one. `astryx init --features theme` calls the same leaf, so project setup writes it too — it previously printed a one-line hint and wrote nothing, which is the weakest form of the help a theme author needs, since the first problem is not knowing the command but not knowing what the theme surface contains. The file is `theme.template.ts`: every `defineTheme` field with a note on when to reach for it, the token families, the component override syntax, and the consumption steps (providing the theme, loading the fonts you name, building for SSR), each section naming the CLI command that prints its authoritative reference. An existing file is never clobbered.
+
+  This came out of a vibe test (#5047): agents given an annotated template reached twice as far into the theme surface as agents given only the docs (17 component targets vs 8, and the only arm to use interaction states, custom variants and `onDark`), and shipped a third of the contrast defects.
+
+  A template that lies is worse than no template, so its claims are machine-checked against live sources rather than trusted: `scripts/check-theme-template.test.mjs` fails when a `defineTheme` field is added and left undocumented, when a token family is missing from the inventory, when a CSS variable or component key it names does not exist, when it cites a docs topic that does not, or when a theme source drops its SYNC reference. `theme build` compiles it warning-free in CI, and the CLI typecheck now covers it.
+
+#### Fixes
+
+- Heading's `type` is a documented theming target, and the docs stop teaching a CSS variable that does not exist (#5016).
+  `Heading` reflects `type` as a theme selector — `typography.scale` generates `heading: {'type:display-1' …}` rules for it — but `theming.targets` listed only `level` and `color`, so `astryx theme build` warned `Unknown prop "type" on component "heading"` on every theme that sets a type scale, including the shipped `neutralTheme`. The drift guard missed it twice over: it read a conditional spread (`{level, color, ...(type && {type})}`) as an unknown bag, and it only checked a component against a doc file in its own directory, so `Heading/` — documented from `Text/Text.doc.mjs` — was never checked at all. Both are fixed, which brings three more previously unchecked directories under the guard.
+
+  Separately, the theme docs' component-override example set `--button-press-scale`, which no component defines: copying it produces CSS that silently never applies. It now sets a real public var, and the example no longer declares the same `button` key twice.
+
+- Two guards left failing on `main` by their own landings, so every PR since has been red through no fault of its own. #4963 gave Thumbnail's remove button a coarse-pointer hit-area var and did not document it, which the derived-var guard reads as an undocumented private var; the var is an `inset` on a `::after` overlay, so it is documented as private and listed alongside the other vars no standard CSS property maps onto. #5026 moved `borderDefaults` into `CoreTokenName` — the landing the theme-template guard was explicitly waiting for (its comment says "when #5017 lands, this guard starts requiring the template to cover it") — so the template's token inventory now names `--border-width`.
+
+#### Documentation
+
+- MobileNavToggle preview simulates a mobile AppShell instead of an empty stage: new playground.appShellMobile for components that render nothing without AppShell mobile context (#4983)
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @AKnassa
+- @cixzhang
+
+---
+
 # 0.4.1
 
 #### Fixes

package/README.md

@@ -416,6 +416,7 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `theme.build.check`         | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing.                                                                 |
 | `theme.list`                | Every bundled theme as a ThemeListEntry[]: each with slug, displayName, description, and a maintained flag.                                                                                                                          |
 | `theme.add`                 | A scaffold receipt: resolved slug, displayName, maintained flag, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.                                                                           |
+| `theme.template`            | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not — `exists` when a file was already there, which is a success.                                        |
 | `upgrade.list`              | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.                                                                                                           |
 | `upgrade.status`            | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.                                                                                                     |
 | `upgrade.run`               | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                          |

package/api/init/init.doc.mjs

@@ -30,7 +30,7 @@ export const doc = {
       name: 'options.features',
       type: 'string',
       description:
-        'Comma-separated features to install: agents, theme, template.',
+        'Comma-separated features to install: agents (agent docs), theme (writes the annotated theme.template.ts), template (page-template guidance).',
     },
     {
       name: 'options.all',
@@ -64,7 +64,7 @@ export const doc = {
     {
       type: 'init.run',
       description:
-        'The install receipt: the `mode` (`default` | `features`), the features run, agent-doc files written, any soft docsError, whether theme guidance was emitted, the template outcome (`workflow` | `created` | `skipped`) plus its path, and whether the next-steps were emitted.',
+        'The install receipt: the `mode` (`default` | `features`), the features run, agent-doc files written, any soft docsError, the theme-template outcome (`created` | `skipped` | `failed`) plus its path, the page-template outcome (`workflow` | `created` | `skipped`) plus its path, and whether the next-steps were emitted.',
     },
     {
       type: 'init.remove',

package/api/init/init.test.mjs

@@ -57,13 +57,30 @@ describe('init() — receipts + side effects', () => {
     expect(res.type === 'init.run' && res.data.docsWritten).toContain('AGENTS.md');
   });
 
-  it('--features theme emits guidance, writes no files, and flags theme', async () => {
+  it('--features theme writes the annotated template and reports it on the receipt', async () => {
     const res = await init({features: 'theme'}, {cwd: tmpDir});
     expect(res.type).toBe('init.run');
     if (res.type !== 'init.run') return;
     expect(res.data.theme).toBe(true);
+    expect(res.data.themeTemplate).toBe('created');
+    expect(res.data.themeTemplatePath).toBe('theme.template.ts');
     expect(res.data.docsWritten).toEqual([]);
-    expect(fs.readdirSync(tmpDir)).toEqual([]);
+    expect(fs.readdirSync(tmpDir)).toEqual(['theme.template.ts']);
+    // The consumer's copy is their file: it must not carry our repo header,
+    // which their own lint would flag.
+    const written = fs.readFileSync(path.join(tmpDir, 'theme.template.ts'), 'utf-8');
+    expect(written).not.toMatch(/Copyright \(c\) Meta Platforms/);
+    expect(written.startsWith('/**')).toBe(true);
+  });
+
+  it('--features theme reports `skipped` rather than overwriting an existing template', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'theme.template.ts'), '// mine\n');
+    const res = await init({features: 'theme'}, {cwd: tmpDir});
+    expect(res.type).toBe('init.run');
+    if (res.type !== 'init.run') return;
+    expect(res.data.themeTemplate).toBe('skipped');
+    expect(res.data.themeTemplatePath).toBe(null);
+    expect(fs.readFileSync(path.join(tmpDir, 'theme.template.ts'), 'utf-8')).toBe('// mine\n');
   });
 
   it('--features template returns the workflow (or skipped) outcome, no crash', async () => {

package/api/init/init.type.d.mts

@@ -22,9 +22,17 @@ export type InitRunData = {
         message?: string;
     } | null;
     /**
-     * Whether theme guidance was emitted.
+     * Whether the theme feature ran.
      */
     theme: boolean;
+    /**
+     * Outcome of writing the annotated theme template (`skipped` = a file was already there).
+     */
+    themeTemplate: "created" | "skipped" | "failed" | null;
+    /**
+     * Relative output path when `themeTemplate === 'created'`.
+     */
+    themeTemplatePath: string | null;
     /**
      * Template outcome (`workflow` is the CLI default; `created`/`skipped` are programmatic).
      */

package/api/init/init.type.mjs

@@ -12,7 +12,9 @@
  * @property {string[]} features Features that were run, in order.
  * @property {string[]} docsWritten Agent-doc files written (empty if agents weren't run or install failed).
  * @property {{kind: 'path-safety' | 'install-failed', message?: string} | null} docsError Soft agent-docs failure, if any. `path-safety` also implies a non-zero exit.
- * @property {boolean} theme Whether theme guidance was emitted.
+ * @property {boolean} theme Whether the theme feature ran.
+ * @property {'created' | 'skipped' | 'failed' | null} themeTemplate Outcome of writing the annotated theme template (`skipped` = a file was already there).
+ * @property {string | null} themeTemplatePath Relative output path when `themeTemplate === 'created'`.
  * @property {'workflow' | 'created' | 'skipped' | null} template Template outcome (`workflow` is the CLI default; `created`/`skipped` are programmatic).
  * @property {string | null} templatePath Relative output path when `template === 'created'`.
  * @property {boolean} nextSteps Whether the getting-started "Next steps" were emitted (default mode).

package/api/init/run/run.mjs

@@ -20,6 +20,7 @@ import {CLI_ROOT} from '../../../foundation/fs/paths.mjs';
 import {PathSafetyError} from '../../../foundation/fs/path-safety.mjs';
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 import {installAgentDocs} from '../../../foundation/agent-docs/agent-docs.mjs';
+import {themeTemplate} from '../../theme/template/template.mjs';
 import {listTemplates} from '../../template/template.mjs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
@@ -106,6 +107,36 @@ function applyAgents(cwd, options, invocation, data) {
   }
 }
 
+/**
+ * Write the annotated theme template, via the same leaf `astryx theme template`
+ * uses — init is a convenience wrapper over the theme command, not a second
+ * implementation of it.
+ *
+ * @param {string} cwd
+ * @param {string} invocation
+ * @param {import('../init.type.mjs').InitRunData} data
+ */
+function applyTheme(cwd, invocation, data) {
+  data.theme = true;
+  try {
+    const {path: written, written: didWrite} = themeTemplate({cwd}).data;
+    data.themeTemplate = didWrite ? 'created' : 'skipped';
+    data.themeTemplatePath = didWrite ? written : null;
+    logger.log(
+      didWrite
+        ? `✓ Theme template written → ${written}`
+        : `• ${written} already exists — left as is.`,
+    );
+  } catch {
+    // Soft failure, like agent docs: the guidance below is still useful.
+    data.themeTemplate = 'failed';
+    logger.error('Could not write the theme template.');
+  }
+  logger.log(
+    `  Copy it to your theme file and edit, or run \`${invocation} theme add <slug>\` to start from a shipped theme (\`${invocation} theme list\` to browse).`,
+  );
+}
+
 /**
  * Emit the template guidance, or (programmatic-only) scaffold a named template.
  * The CLI never passes `templateName`, so from the CLI this always emits the
@@ -210,18 +241,15 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
       docsWritten: [],
       docsError: null,
       theme: false,
+      themeTemplate: null,
+      themeTemplatePath: null,
       template: null,
       templatePath: null,
       nextSteps: false,
     };
     for (const feature of features) {
       if (feature === 'agents') applyAgents(cwd, options, invocation, data);
-      if (feature === 'theme') {
-        logger.log(
-          `✓ For a custom theme, run \`${invocation} theme\` (browse) or \`${invocation} theme add <slug>\` (scaffold).`,
-        );
-        data.theme = true;
-      }
+      if (feature === 'theme') applyTheme(cwd, invocation, data);
       if (feature === 'template') {
         applyTemplate(cwd, {templateName: options.templateName}, invocation, data);
       }
@@ -238,6 +266,8 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
     docsWritten: [],
     docsError: null,
     theme: false,
+    themeTemplate: null,
+    themeTemplatePath: null,
     template: null,
     templatePath: null,
     nextSteps: true,

package/api/theme/add/add.mjs

@@ -13,19 +13,8 @@ import {assertWithin, PathSafetyError} from '../../../foundation/fs/path-safety.
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {THEMES_DIR, listThemes, findTheme} from '../_adapter.mjs';
-
-// Stripped from scaffolded files so the consumer's copy doesn't carry our
-// repo boilerplate (mirrors the docsite). Preserves a leading BOM/shebang.
-const META_COPYRIGHT_HEADER_RE =
-  /^(\uFEFF?(?:#![^\r\n]*(?:\r?\n))?)\/\/ Copyright \(c\) Meta Platforms, Inc\. and affiliates\.\r?\n(?:\r?\n)*/;
-
-/**
- * @param {string} source
- * @returns {string}
- */
-function stripCopyrightHeader(source) {
-  return source.replace(META_COPYRIGHT_HEADER_RE, '$1');
-}
+// Scaffolded files must not carry our repo boilerplate into a consumer's tree.
+import {stripCopyrightHeader} from '../../../foundation/text/copyright-header.mjs';
 
 /**
  * @param {string} slug

package/api/theme/build/build.font-warning.test.mjs

@@ -0,0 +1,161 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * API-contract tests for the font-loading warning in `themeBuild()` (#5015):
+ * a theme that names font families it does not load gets one entry per family
+ * in the `theme.build` receipt's `warnings` array, on BOTH load paths — a raw
+ * typography config (resolved through core's defineTheme) and an
+ * already-resolved theme that sets `--font-family-*` tokens directly. Themes
+ * that only name generics or known system families warn about nothing, and
+ * the warning never breaks the API's silence contract (default noopLogger).
+ *
+ * Needs a built core — the `node` project's globalSetup
+ * (vitest.global-setup.node.mjs) builds it once before workers fork.
+ */
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {themeBuild} from './build.mjs';
+
+vi.setConfig({testTimeout: 30000});
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-theme-fonts-api-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('themeBuild() — font-loading warnings in the receipt', () => {
+  it('warns once per unloaded family for a typography config (heading inherits body without duplicating)', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'fonty.mjs'),
+      `export default {
+  name: 'fonty',
+  typography: {
+    body: {family: 'Space Grotesk', fallbacks: 'Arial, sans-serif'},
+    code: {family: 'JetBrains Mono'},
+  },
+};\n`,
+    );
+
+    const result = await themeBuild('fonty.mjs', {}, {cwd: tmpDir});
+
+    expect(result?.type).toBe('theme.build');
+    const warnings = result?.data.warnings ?? [];
+    expect(warnings).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining('Font "Space Grotesk"'),
+        expect.stringContaining('Font "JetBrains Mono"'),
+      ]),
+    );
+    // Heading inherits body's family; the shared family warns exactly once.
+    expect(warnings.filter(w => w.includes('Space Grotesk'))).toHaveLength(1);
+  });
+
+  it('warns for an already-resolved theme: font-family tokens and component overrides, nothing else', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'raw.mjs'),
+      `export default {
+  name: 'raw',
+  tokens: {
+    '--font-family-body': '"Bungee", cursive',
+    '--font-size-base': '1rem',
+  },
+  components: {button: {base: {fontFamily: 'Orbitron'}}},
+};\n`,
+    );
+
+    const result = await themeBuild('raw.mjs', {}, {cwd: tmpDir});
+
+    // Exactly the two named families — a non-family --font-* token must not
+    // produce a bogus "Font \\"1rem\\"" entry, and the components half of the
+    // feature must survive the real themeBuild path, not just the unit helper.
+    const fontWarnings = (result?.data.warnings ?? []).filter(w =>
+      w.startsWith('Font "'),
+    );
+    expect(fontWarnings).toEqual([
+      expect.stringContaining('Font "Bungee"'),
+      expect.stringContaining('Font "Orbitron"'),
+    ]);
+  });
+
+  it('warns for a family named only inside a pseudo-class component override (defineTheme path)', async () => {
+    // ':hover' blocks are legal override values (generateThemeRules), and the
+    // typography path deep-merges author components with generated ones — a
+    // webfont hiding at that depth must survive the merge and still warn.
+    fs.writeFileSync(
+      path.join(tmpDir, 'pseudo.mjs'),
+      `export default {
+  name: 'pseudo',
+  typography: {
+    body: {family: 'Helvetica', fallbacks: 'Arial, sans-serif'},
+  },
+  components: {
+    button: {base: {':hover': {fontFamily: '"Rubik Doodle", cursive'}}},
+  },
+};\n`,
+    );
+
+    const result = await themeBuild('pseudo.mjs', {}, {cwd: tmpDir});
+
+    const fontWarnings = (result?.data.warnings ?? []).filter(w =>
+      w.startsWith('Font "'),
+    );
+    // Exactly the hidden family — Helvetica/Arial are system fonts.
+    expect(fontWarnings).toEqual([
+      expect.stringContaining('Font "Rubik Doodle"'),
+    ]);
+  });
+
+  it('warns about nothing when every named family is a generic or known system font', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'sys.mjs'),
+      `export default {
+  name: 'sys',
+  tokens: {
+    '--color-bg': '#fff',
+    '--font-family-body': 'Helvetica, Arial, sans-serif',
+  },
+};\n`,
+    );
+
+    const result = await themeBuild('sys.mjs', {}, {cwd: tmpDir});
+
+    expect(result?.type).toBe('theme.build');
+    expect(result?.data.warnings).toEqual([]);
+  });
+
+  it('stays silent under the default noopLogger even when font warnings fire', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'loud.mjs'),
+      `export default { name: 'loud', tokens: { '--font-family-body': '"Orbitron", sans-serif' } };\n`,
+    );
+
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const outSpy = vi
+      .spyOn(process.stdout, 'write')
+      .mockImplementation(() => true);
+
+    try {
+      const result = await themeBuild('loud.mjs', {}, {cwd: tmpDir});
+      expect(result?.data.warnings).toEqual(
+        expect.arrayContaining([expect.stringContaining('Font "Orbitron"')]),
+      );
+      expect(logSpy).not.toHaveBeenCalled();
+      expect(warnSpy).not.toHaveBeenCalled();
+      expect(errSpy).not.toHaveBeenCalled();
+      expect(outSpy).not.toHaveBeenCalled();
+    } finally {
+      logSpy.mockRestore();
+      warnSpy.mockRestore();
+      errSpy.mockRestore();
+      outSpy.mockRestore();
+    }
+  });
+});

package/api/theme/build/build.mjs

@@ -11,8 +11,10 @@
  * - A JS module that re-exports the built theme (+ icon registry)
  * - A .d.ts (plus an optional .variants.d.ts for custom prop values)
  *
- * It performs the writes and returns a `theme.build` receipt, or `null` when
- * the theme produced no CSS (nothing to build). Errors throw AstryxError (with
+ * It performs the writes and returns a `theme.build` receipt — its `warnings`
+ * carry override problems and any fonts the theme names but does not load
+ * (font-warning.mjs) — or `null` when the theme produced no CSS (nothing to
+ * build). Errors throw AstryxError (with
  * a stable code). Human progress is emitted through the shared `logger`
  * (silent by default), so the CLI keeps its exact output while a programmatic
  * caller stays quiet.
@@ -41,6 +43,10 @@ import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {AstryxError} from '../../error.mjs';
 import {logger} from '../../logger.mjs';
 import {loadComponentDoc} from '../../../foundation/discovery/component-loader.mjs';
+import {
+  collectUnloadedFonts,
+  formatFontLoadingHelp,
+} from './font-warning.mjs';
 
 // Import shared theme processing from core. `astryx theme build` MUST produce the
 // exact same CSS as the `<Theme>` runtime, so it has exactly one generation
@@ -1341,16 +1347,17 @@ Or with a <link> tag:
   </Theme>
 `);
 
-  // Print font declaration warnings (derived from typography roles)
-  if (resolvedTheme && resolvedTheme.fonts && resolvedTheme.fonts.length > 0) {
-    logger.log(
-      `\n⚠ Theme "${themeDef.name}" requires fonts not included in the build:`,
-    );
-    for (const font of resolvedTheme.fonts) {
-      logger.log(`  ${font.family} — add to your document <head>:`);
-      logger.log(`  <link rel="stylesheet" href="${font.url}" />`);
-    }
-    logger.log('');
+  // Fonts the theme names but nothing loads (#5015). Resolved tokens and
+  // component overrides carry the final font-family values on both load
+  // paths, so this sees jiti-resolved and legacy themes alike.
+  const unloadedFonts = collectUnloadedFonts(resolvedTheme);
+  for (const family of unloadedFonts) {
+    const msg = `Font "${family}" is named by this theme but not loaded — add a <link> or @font-face in your app (recipe: astryx docs typography)`;
+    warningMessages.push(msg);
+    logger.warn(`  ⚠ ${msg}`);
+  }
+  if (unloadedFonts.length > 0) {
+    logger.log(formatFontLoadingHelp(themeDef.name, unloadedFonts));
   }
 
   return {

package/api/theme/build/build.test.mjs

@@ -254,6 +254,28 @@ describe('themeBuild() — component override validation', () => {
     expect(result?.data.warnings).toEqual([]);
   });
 
+  it('accepts the heading type rules a type scale generates', async () => {
+    // `typography.scale` makes defineTheme emit `heading: {'type:display-1' …}`
+    // (Heading renders a `type:` class alongside `level:`), so any theme with a
+    // type scale carried override keys the validator called unknown — including
+    // the shipped neutralTheme.
+    const themeFile = path.join(tmpDir, 'typescale.mjs');
+    fs.writeFileSync(
+      themeFile,
+      `export default {
+        name: 'typescale',
+        tokens: {'--color-bg': '#0a0a0a'},
+        components: {
+          heading: {'type:display-1': {letterSpacing: '0.01em'}},
+        },
+      };\n`,
+    );
+
+    const result = await themeBuild('typescale.mjs', {}, {cwd: tmpDir});
+
+    expect(result?.data.warnings).toEqual([]);
+  });
+
   it('still warns on a key that is neither a visual prop nor a state', async () => {
     // Widening the known set to states must not turn the guard off.
     const themeFile = path.join(tmpDir, 'bogus.mjs');
@@ -273,3 +295,34 @@ describe('themeBuild() — component override validation', () => {
     ]);
   });
 });
+
+describe('themeBuild() — the shipped theme template', () => {
+  // `assets/theme.template.ts` is what `astryx theme template` puts in a
+  // consumer's project. It is the one theme file we hand out, so it has to
+  // compile as shipped — and cleanly apart from the font warnings it earns on
+  // purpose: a template that greets its first reader with warnings teaches them
+  // to ignore warnings. The claims its comments make are checked separately by
+  // scripts/check-theme-template.test.mjs.
+  it('compiles as shipped, warning only about the fonts it deliberately names', async () => {
+    const src = path.resolve(
+      import.meta.dirname,
+      '../../../assets/theme.template.ts',
+    );
+    fs.copyFileSync(src, path.join(tmpDir, 'theme.template.ts'));
+
+    const result = await themeBuild('theme.template.ts', {}, {cwd: tmpDir});
+
+    // The template names Inter and Geist Mono to teach "SHIP THE FONTS YOU
+    // NAME", and loads neither — so the unloaded-font warning firing here is
+    // the lesson landing, not a defect. Any OTHER warning still fails.
+    const unexpected = (result?.data.warnings ?? []).filter(
+      w => !/^Font "(Inter|Geist Mono)" is named by this theme but not loaded/.test(w),
+    );
+    expect(unexpected).toEqual([]);
+    expect(result?.data.warnings).toHaveLength(2);
+    expect(fs.existsSync(path.join(tmpDir, 'my-theme.css'))).toBe(true);
+    // The template teaches custom variants; the augmentation it promises the
+    // reader has to actually be generated.
+    expect(fs.existsSync(path.join(tmpDir, 'my-theme.variants.d.ts'))).toBe(true);
+  });
+});

package/api/theme/build/font-warning.d.mts

@@ -0,0 +1,26 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Collect the font families a resolved theme names but does not load —
+ * every `--font-family-*` token plus every component-override `fontFamily`,
+ * minus generics, CSS-wide keywords, `var()` references, and known system
+ * families. Source order, first-seen casing, deduped case-insensitively.
+ *
+ * @param {{tokens?: Record<string, string>, components?: object}} resolvedTheme
+ * @returns {string[]}
+ */
+export function collectUnloadedFonts(resolvedTheme: {
+    tokens?: Record<string, string>;
+    components?: object;
+}): string[];
+/**
+ * Render the human fix printed after the install instructions: which fonts
+ * the theme names but does not load, the Google Fonts `<link>` recipe, and
+ * the self-hosted `@font-face` alternative.
+ *
+ * @param {string} themeName
+ * @param {string[]} families
+ * @returns {string}
+ */
+export function formatFontLoadingHelp(themeName: string, families: string[]): string;