@glossarist/concept-browser 0.7.107 → 0.7.109

package/README.md

@@ -109,6 +109,93 @@ branding:
 
 If no logo is configured, the Glossarist logo is shown by default. The footer always shows the Glossarist logo ("Powered by Glossarist").
 
+### Fonts
+
+Brand typography is fully slot-based and category-agnostic. There are **four slots** — `title`, `heading`, `body`, `mono` — and each slot accepts **any category** (`serif`, `sans-serif`, `monospace`). Nothing dictates that "headings must be serif" or "body must be sans-serif". Pick whatever combination matches your brand.
+
+#### Slots
+
+| Slot | Applies to | Default family | Default category |
+|---|---|---|---|
+| `title` | The single most-prominent text on each page (home hero, concept name on detail page, dataset/group title) | DM Serif Display | serif |
+| `heading` | h2–h6 section headings | DM Serif Display | serif |
+| `body` | Paragraph text, lists, table cells | DM Sans | sans-serif |
+| `mono` | Code blocks, inline code, kbd | JetBrains Mono | monospace |
+
+The defaults preserve the Glossarist visual identity — override any of them to match your brand.
+
+#### Per-slot category override
+
+Set `category` on any slot to control the fallback chain (the browser uses it when the primary family fails to load or is still loading):
+
+```yaml
+branding:
+  fonts:
+    title:
+      family: Inter
+      source: google
+      category: sans-serif           # sans-serif title (was serif by default)
+      weights: [400, 600, 700]
+    heading:
+      family: Inter
+      source: google
+      category: sans-serif
+      weights: [600, 700]
+    body:
+      family: Merriweather
+      source: google
+      category: serif                # serif body (was sans-serif by default)
+      weights: [400, 700]
+    mono:
+      family: Fira Code
+      source: google
+      category: monospace
+      weights: [400, 500]
+```
+
+This produces:
+
+| Slot | CSS variable | Stack |
+|---|---|---|
+| title | `--font-title` | `'Inter', system-ui, sans-serif` |
+| heading | `--font-heading` (and `--font-header` for backward compat) | `'Inter', system-ui, sans-serif` |
+| body | `--font-body` | `'Merriweather', Georgia, serif` |
+| mono | `--font-mono` | `'Fira Code', ui-monospace, "JetBrains Mono", Menlo, Monaco, monospace` |
+
+#### Source options
+
+| `source` | Behavior |
+|---|---|
+| `google` | Build emits a Google Fonts CSS `@import` for the declared `family` + `weights`. |
+| `url` | Build emits a `@font-face` block loading from `url`. |
+| `local` | Consumer ships the font files in `public/`; no build-time fetch. |
+
+#### Backward compatibility
+
+The legacy `branding.fonts.header` slot still works — it's a deprecated alias for `branding.fonts.heading`. Existing configs don't break. The CSS variable `--font-header` is still emitted (as an alias for `--font-heading`) so existing stylesheets that reference it continue to work.
+
+#### Mixed-category example: all sans-serif
+
+```yaml
+branding:
+  fonts:
+    title:   { family: Inter,        source: google, category: sans-serif }
+    heading: { family: Inter,        source: google, category: sans-serif }
+    body:    { family: Inter,        source: google, category: sans-serif }
+    mono:    { family: JetBrains Mono, source: google, category: monospace }
+```
+
+#### Mixed-category example: traditional serif
+
+```yaml
+branding:
+  fonts:
+    title:   { family: Playfair Display, source: google, category: serif }
+    heading: { family: Lora,             source: google, category: serif }
+    body:    { family: Source Sans Pro,  source: google, category: sans-serif }
+    mono:    { family: Source Code Pro,  source: google, category: monospace }
+```
+
 ### Favicons
 
 `branding.favicon` accepts two shapes — a legacy **string** form and an **object** form that lets consumers provide their own canonical favicon set without writing a post-build script.
@@ -148,22 +235,33 @@ Then in `site-config.yml`:
 branding:
   favicon:
     base_path: /                              # URL prefix (BASE_PATH-aware; default '/')
-    skip_default_links: true                  # suppress the default <link> block
     source_dir: assets/favicons               # canonical files (all of them, in one directory)
-    links_html: |-                            # raw HTML emitted verbatim in <head>
-      <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96" />
-      <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-      <link rel="shortcut icon" href="/favicon.ico" />
-      <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
-      <link rel="manifest" href="/site.webmanifest" />
+    icons:                                    # DATA — declare each icon, not HTML
+      - rel: icon
+        type: image/svg+xml
+        href: favicon.svg
+      - rel: icon
+        type: image/png
+        sizes: 96x96
+        href: favicon-96x96.png
+      - rel: shortcut icon
+        href: favicon.ico
+      - rel: apple-touch-icon
+        sizes: 180x180
+        href: apple-touch-icon.png
+      - rel: manifest
+        href: site.webmanifest
 ```
 
+The CLI copies every file from `source_dir/` into `public/` (also removing the default cruft), then renders one `<link>` tag per icon entry. The `href` is a **filename** — the system applies the correct `base_path` prefix automatically. Absolute URLs (`https://cdn.example.com/x.png`) and root-relative paths (`/x.png`) are emitted unchanged.
+
 | Field | Type | Effect |
 |---|---|---|
 | `source_dir` | string | Path (relative to cwd) to a directory containing **all** canonical favicon files. The CLI copies every file in this directory into `public/`, overriding any defaults. Also removes the default-generated cruft (`apple-touch-icon-57x57.png`, `favicon-16x16.png`, etc.) so it doesn't linger. |
-| `links_html` | string | Raw HTML (one or more `<link>` tags) emitted verbatim in `<head>`. Use this to declare which of the source_dir files the browser should load, with what `sizes`/`type`. |
-| `skip_default_links` | boolean | When true, the CLI does NOT call the `favicons` package and does NOT emit the default `<link>` tags. Pair with `links_html` and `source_dir` for fully custom branding. |
+| `icons` | `FaviconIcon[]` | **DATA — recommended.** Array of `{ rel, href, type?, sizes? }` entries. Each renders to one `<link>` tag with BASE_PATH-aware href. Replaces the default 16-link set. |
+| `skip_default_links` | boolean | When true, the CLI does NOT call the `favicons` package and does NOT emit the default `<link>` tags. Pair with `icons` and `source_dir` for fully custom branding. |
 | `base_path` | string | URL prefix prepended to every emitted link. Useful for BASE_PATH-scoped deployments (e.g. `/vocab/`). |
+| ~~`links_html`~~ | string | **@deprecated** — use `icons` instead. Raw HTML emitted verbatim. Impossible to validate or safely BASE_PATH-rewrite; kept for backward compat with a console warning. |
 
 The object form exists so consumers with a RealFaviconGenerator favicon set (or any other canonical brand favicon bundle) can install it without a post-build script. Previously this required workarounds like `glossarist/cie-eilv/scripts/install-favicons.mjs` (149 lines) and `glossarist/iala-vocab/scripts/install-favicons.mjs` (175 lines) — both are now unnecessary.
 

package/cli/index.mjs

@@ -97,9 +97,12 @@ Environment:
     //      package generates the full variant set from it.
     //
     //   2. Object — `{ source_dir?, links_html?, skip_default_links?, base_path? }`.
-    //      - `links_html`: raw HTML (one or more <link> tags) emitted verbatim.
-    //        Skips the `favicons` package entirely; consumer is responsible
-    //        for providing the actual icon files in public/.
+    //      - `icons`: DATA — array of { rel, href, type?, sizes? } entries.
+    //        The hrefs are filenames; the CLI applies BASE_PATH and renders
+    //        well-formed <link> tags. Recommended over `links_html`.
+    //      - `links_html` (deprecated): raw HTML emitted verbatim.
+    //        Skips the `favicons` package entirely; impossible to validate
+    //        or safely BASE_PATH-rewrite. Use `icons` instead.
     //      - `source_dir`: directory of canonical favicon files copied as-is
     //        into public/ (overriding any defaults). Useful when the consumer
     //        already has a RealFaviconGenerator output set.
@@ -114,8 +117,34 @@ Environment:
 
     if (faviconCfgIsObject) {
       // Object form — honor each declared field.
+      if (faviconCfg.icons && Array.isArray(faviconCfg.icons) && faviconCfg.icons.length > 0) {
+        // Data-driven: build <link> tags from the icons array.
+        const basePathForIcons =
+          faviconCfg.base_path ||
+          process.env.BASE_PATH?.replace(/\/+$/, '') ||
+          '';
+        faviconHtml = faviconCfg.icons.map((icon) => {
+          const attrs = [`rel="${icon.rel || 'icon'}"`];
+          if (icon.type) attrs.push(`type="${icon.type}"`);
+          if (icon.sizes) attrs.push(`sizes="${icon.sizes}"`);
+          // Bare filenames get BASE_PATH-prefixed; absolute URLs / root-relative
+          // paths are emitted as-is.
+          let href = icon.href || '';
+          if (href && !/^[a-z][a-z0-9+.-]*:/i.test(href) && !href.startsWith('//') && !href.startsWith('/')) {
+            href = basePathForIcons ? `${basePathForIcons}/${href}` : `/${href}`;
+          }
+          attrs.push(`href="${href}"`);
+          return `<link ${attrs.join(' ')} />`;
+        }).join('\n    ');
+        skipDefaultGeneration = true;
+      }
       if (faviconCfg.links_html) {
-        faviconHtml = String(faviconCfg.links_html);
+        if (faviconHtml) {
+          console.warn('  Warning: branding.favicon.icons and links_html are both set; using icons (data form).');
+        } else {
+          console.warn('  Warning: branding.favicon.links_html is deprecated. Use branding.favicon.icons (data) instead.');
+          faviconHtml = String(faviconCfg.links_html);
+        }
         skipDefaultGeneration = true;
       }
       if (faviconCfg.source_dir) {

package/cli/index.ts

@@ -66,19 +66,23 @@ interface BrandingFonts {
   weights?: number[];
 }
 
+interface FaviconIcon {
+  rel?: string;
+  href: string;
+  type?: string;
+  sizes?: string;
+}
+
 interface FaviconConfig {
-  /** Path prefix for all favicon URLs. Defaults to '/', set to a sub-path
-   *  when deploying under BASE_PATH != '/'. */
+  /** Path prefix for all favicon URLs. Defaults to BASE_PATH-aware '/'. */
   base_path?: string;
-  /** Skip emitting the default <link rel="icon"> and <link rel="apple-touch-icon">
-   *  tags. Use when the consumer provides their own RFG-compatible markup via
-   *  `links_html`. Default: false (emit default tags). */
+  /** Skip emitting the default <link> block. */
   skip_default_links?: boolean;
-  /** Raw HTML string (one or more <link> tags) to emit in <head> instead of
-   *  the default favicon block. RealFaviconGenerator output goes here. */
+  /** Consumer-declared icons (DATA, not HTML). Replaces the default set. */
+  icons?: FaviconIcon[];
+  /** @deprecated Use `icons` instead. Raw HTML — kept for backward compat. */
   links_html?: string;
-  /** Consumer-side directory (relative to cwd) holding canonical favicon files.
-   *  The CLI copies these into public/, overriding defaults. */
+  /** Consumer-side directory of canonical favicon files. */
   source_dir?: string;
 }
 
@@ -133,8 +137,32 @@ async function runBuildPipeline(config: SiteConfig | null): Promise<void> {
 
   if (faviconCfgObject) {
     const cfg: FaviconConfig = faviconCfgObject;
+    if (cfg.icons && cfg.icons.length > 0) {
+      // Data-driven: build <link> tags from the icons array.
+      const basePathForIcons: string =
+        cfg.base_path ||
+        process.env.BASE_PATH?.replace(/\/+$/, '') ||
+        '';
+      faviconHtml = cfg.icons.map((icon: FaviconIcon): string => {
+        const attrs: string[] = [`rel="${icon.rel || 'icon'}"`];
+        if (icon.type) attrs.push(`type="${icon.type}"`);
+        if (icon.sizes) attrs.push(`sizes="${icon.sizes}"`);
+        let href: string = icon.href || '';
+        if (href && !/^[a-z][a-z0-9+.-]*:/i.test(href) && !href.startsWith('//') && !href.startsWith('/')) {
+          href = basePathForIcons ? `${basePathForIcons}/${href}` : `/${href}`;
+        }
+        attrs.push(`href="${href}"`);
+        return `<link ${attrs.join(' ')} />`;
+      }).join('\n    ');
+      skipDefaultGeneration = true;
+    }
     if (cfg.links_html) {
-      faviconHtml = String(cfg.links_html);
+      if (faviconHtml) {
+        console.warn('  Warning: branding.favicon.icons and links_html are both set; using icons (data form).');
+      } else {
+        console.warn('  Warning: branding.favicon.links_html is deprecated. Use branding.favicon.icons (data) instead.');
+        faviconHtml = String(cfg.links_html);
+      }
       skipDefaultGeneration = true;
     }
     if (cfg.source_dir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.107",
+  "version": "0.7.109",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {

package/src/__tests__/utils/favicon-base.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+import { resolveFaviconBase } from '../../utils/favicon-base';
+
+/**
+ * Regression test for the sub-path deployment 404 bug.
+ *
+ * Bug (filed by user, 2026-08-01): deployments at sub-paths
+ * (e.g. `/cie-eilv/`) saw console 404s for `favicon-32x32.png`,
+ * `favicon-16x16.png`, `favicon-48x48.png` because the emitted
+ * `<link href>` pointed at the ROOT (`/favicon-32x32.png`) instead
+ * of the deployment sub-path (`/cie-eilv/favicon-32x32.png`).
+ *
+ * Root cause: `Default.astro` hardcoded `const faviconBase = '/'`.
+ * Fix: cascade through configuration sources to find the right prefix.
+ */
+describe('resolveFaviconBase', () => {
+  it('returns / when nothing is configured (root deployment)', () => {
+    expect(resolveFaviconBase({})).toBe('/');
+  });
+
+  it('returns / when all candidates are empty', () => {
+    expect(resolveFaviconBase({
+      brandingFaviconBasePath: '',
+      siteConfigBasePath: '',
+      astroBaseUrl: '',
+    })).toBe('/');
+  });
+
+  it('uses branding.favicon.base_path when set (highest priority)', () => {
+    expect(resolveFaviconBase({
+      brandingFaviconBasePath: '/my-brand/',
+      siteConfigBasePath: '/should-be-ignored/',
+      astroBaseUrl: '/should-be-ignored/',
+    })).toBe('/my-brand/');
+  });
+
+  it('uses siteConfig.basePath when branding.favicon.base_path is absent', () => {
+    expect(resolveFaviconBase({
+      siteConfigBasePath: '/cie-eilv/',
+      astroBaseUrl: '/',
+    })).toBe('/cie-eilv/');
+  });
+
+  it('uses import.meta.env.BASE_URL when siteConfig.basePath is absent', () => {
+    expect(resolveFaviconBase({
+      astroBaseUrl: '/vocab/',
+    })).toBe('/vocab/');
+  });
+
+  /**
+   * THE LOAD-BEARING REGRESSION TEST.
+   *
+   * Reproduction of the bug: cie-eilv is deployed at /cie-eilv/, but
+   * the live site emitted <link href="/favicon-32x32.png">. The fix
+   * must produce /cie-eilv/favicon-32x32.png.
+   */
+  it('regression: resolves /cie-eilv/ when that is the configured basePath', () => {
+    const base = resolveFaviconBase({
+      siteConfigBasePath: '/cie-eilv/',
+      astroBaseUrl: '/',
+    });
+    expect(base).toBe('/cie-eilv/');
+    // Pin the full URL construction so a future regression that breaks
+    // the trailing slash also fails this test.
+    expect(`${base}favicon-32x32.png`).toBe('/cie-eilv/favicon-32x32.png');
+    expect(`${base}favicon-16x16.png`).toBe('/cie-eilv/favicon-16x16.png');
+    expect(`${base}favicon-48x48.png`).toBe('/cie-eilv/favicon-48x48.png');
+  });
+
+  it('appends trailing slash if consumer omitted it', () => {
+    expect(resolveFaviconBase({
+      siteConfigBasePath: '/cie-eilv', // no trailing slash
+    })).toBe('/cie-eilv/');
+  });
+
+  it('does not double-slash if consumer includes trailing slash', () => {
+    expect(resolveFaviconBase({
+      siteConfigBasePath: '/cie-eilv/',
+    })).toBe('/cie-eilv/');
+  });
+
+  it('handles deep sub-path deployments', () => {
+    expect(resolveFaviconBase({
+      siteConfigBasePath: '/vocab/iala/',
+    })).toBe('/vocab/iala/');
+    expect(`${resolveFaviconBase({ siteConfigBasePath: '/vocab/iala/' })}favicon.ico`)
+      .toBe('/vocab/iala/favicon.ico');
+  });
+});

package/src/__tests__/utils/favicon-links.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect } from 'vitest';
+import { buildFaviconLinks, renderFaviconLinkTag, type FaviconIcon } from '../../utils/favicon-links';
+
+/**
+ * Regression test for the sub-path deployment 404 bug + the
+ * data-driven icons API.
+ *
+ * Bug 1 (filed by user, 2026-08-01): deployments at sub-paths
+ * (e.g. `/cie-eilv/`) saw console 404s for `favicon-32x32.png`,
+ * `favicon-16x16.png`, `favicon-48x48.png` because the emitted
+ * `<link href>` pointed at the ROOT instead of the deployment sub-path.
+ *
+ * Bug 2 (filed by user, 2026-08-01): the `links_html` field required
+ * consumers to inject raw HTML — impossible to validate, can't be safely
+ * BASE_PATH-rewritten. Refactored to DATA: `icons: [{ rel, href, type?,
+ * sizes? }]` — href is a filename, system applies the correct prefix.
+ */
+describe('buildFaviconLinks — BASE_PATH regression', () => {
+  it('emits /-prefixed hrefs for root deployment', () => {
+    const links = buildFaviconLinks({ astroBaseUrl: '/' });
+    const png16 = links.find(l => l.sizes === '16x16');
+    const png32 = links.find(l => l.sizes === '32x32');
+    const png48 = links.find(l => l.sizes === '48x48');
+    expect(png16?.href).toBe('/favicon-16x16.png');
+    expect(png32?.href).toBe('/favicon-32x32.png');
+    expect(png48?.href).toBe('/favicon-48x48.png');
+  });
+
+  /**
+   * THE LOAD-BEARING TEST — pins the exact bug the user reported.
+   */
+  it('emits /cie-eilv/-prefixed hrefs for sub-path deployment', () => {
+    const links = buildFaviconLinks({
+      siteConfigBasePath: '/cie-eilv/',
+      astroBaseUrl: '/',
+    });
+    const png16 = links.find(l => l.sizes === '16x16');
+    const png32 = links.find(l => l.sizes === '32x32');
+    const png48 = links.find(l => l.sizes === '48x48');
+    expect(png16?.href).toBe('/cie-eilv/favicon-16x16.png');
+    expect(png32?.href).toBe('/cie-eilv/favicon-32x32.png');
+    expect(png48?.href).toBe('/cie-eilv/favicon-48x48.png');
+  });
+
+  it('handles deep sub-paths', () => {
+    const links = buildFaviconLinks({ siteConfigBasePath: '/vocab/iala/' });
+    const icon = links.find(l => l.rel === 'icon' && l.type === 'image/x-icon');
+    expect(icon?.href).toBe('/vocab/iala/favicon.ico');
+  });
+
+  it('handles basePath without trailing slash', () => {
+    const links = buildFaviconLinks({ siteConfigBasePath: '/cie-eilv' });
+    const icon = links.find(l => l.rel === 'icon' && l.type === 'image/x-icon');
+    expect(icon?.href).toBe('/cie-eilv/favicon.ico');
+  });
+
+  it('never produces a bare "/" href', () => {
+    const scenarios = [
+      { astroBaseUrl: '/' },
+      { astroBaseUrl: '/vocab/' },
+      { siteConfigBasePath: '/cie-eilv/' },
+      { brandingFaviconBasePath: '/custom/' },
+    ];
+    for (const input of scenarios) {
+      const links = buildFaviconLinks(input);
+      for (const link of links) {
+        expect(link.href, `bare href for input ${JSON.stringify(input)}`).not.toBe('/');
+        expect(link.href.length, `empty href for input ${JSON.stringify(input)}`).toBeGreaterThan(1);
+      }
+    }
+  });
+
+  it('emits the canonical 16 default favicon tags', () => {
+    const links = buildFaviconLinks({ astroBaseUrl: '/' });
+    expect(links.length).toBe(16);
+    expect(links.filter(l => l.rel === 'icon').length).toBe(5);
+    expect(links.filter(l => l.rel === 'apple-touch-icon').length).toBe(11);
+  });
+});
+
+describe('buildFaviconLinks — consumer-declared icons (data form)', () => {
+  const consumerIcons: FaviconIcon[] = [
+    { rel: 'icon',          type: 'image/svg+xml', href: 'favicon.svg' },
+    { rel: 'icon',          type: 'image/png',     sizes: '96x96', href: 'favicon-96x96.png' },
+    { rel: 'shortcut icon', href: 'favicon.ico' },
+    { rel: 'apple-touch-icon', sizes: '180x180',  href: 'apple-touch-icon.png' },
+    { rel: 'manifest',      href: 'site.webmanifest' },
+  ];
+
+  it('replaces the default set when icons is non-empty', () => {
+    const links = buildFaviconLinks({ astroBaseUrl: '/', icons: consumerIcons });
+    expect(links.length).toBe(consumerIcons.length);
+    // Should NOT contain any of the default 16 links.
+    expect(links.find(l => l.sizes === '16x16')).toBeUndefined();
+    expect(links.find(l => l.sizes === '32x32')).toBeUndefined();
+  });
+
+  it('prefixes bare filenames with the resolved base path', () => {
+    const links = buildFaviconLinks({
+      siteConfigBasePath: '/cie-eilv/',
+      icons: consumerIcons,
+    });
+    const svg = links.find(l => l.type === 'image/svg+xml');
+    const png96 = links.find(l => l.sizes === '96x96');
+    const ico = links.find(l => l.rel === 'shortcut icon');
+    const manifest = links.find(l => l.rel === 'manifest');
+    expect(svg?.href).toBe('/cie-eilv/favicon.svg');
+    expect(png96?.href).toBe('/cie-eilv/favicon-96x96.png');
+    expect(ico?.href).toBe('/cie-eilv/favicon.ico');
+    expect(manifest?.href).toBe('/cie-eilv/site.webmanifest');
+  });
+
+  it('emits absolute URLs as-is (no prefix)', () => {
+    const links = buildFaviconLinks({
+      astroBaseUrl: '/vocab/',
+      icons: [
+        { rel: 'icon', type: 'image/svg+xml', href: 'https://cdn.example.com/favicon.svg' },
+        { rel: 'icon', href: 'favicon.ico' },
+      ],
+    });
+    const cdn = links.find(l => l.href.startsWith('https://'));
+    const local = links.find(l => l.href.endsWith('favicon.ico') && !l.href.startsWith('https://'));
+    expect(cdn?.href).toBe('https://cdn.example.com/favicon.svg');
+    expect(local?.href).toBe('/vocab/favicon.ico');
+  });
+
+  it('emits root-relative paths as-is', () => {
+    const links = buildFaviconLinks({
+      astroBaseUrl: '/vocab/',
+      icons: [{ rel: 'icon', href: '/absolute-path.png' }],
+    });
+    expect(links[0].href).toBe('/absolute-path.png');
+  });
+
+  it('preserves type and sizes attributes from the data', () => {
+    const links = buildFaviconLinks({ astroBaseUrl: '/', icons: consumerIcons });
+    const svg = links.find(l => l.type === 'image/svg+xml');
+    const png96 = links.find(l => l.sizes === '96x96');
+    const touch = links.find(l => l.rel === 'apple-touch-icon');
+    expect(svg?.type).toBe('image/svg+xml');
+    expect(png96?.sizes).toBe('96x96');
+    expect(touch?.sizes).toBe('180x180');
+  });
+
+  it('falls back to default set when icons is empty array', () => {
+    const links = buildFaviconLinks({ astroBaseUrl: '/', icons: [] });
+    expect(links.length).toBe(16);
+  });
+
+  it('falls back to default set when icons is undefined', () => {
+    const links = buildFaviconLinks({ astroBaseUrl: '/' });
+    expect(links.length).toBe(16);
+  });
+});
+
+describe('renderFaviconLinkTag', () => {
+  it('renders all attributes in deterministic order', () => {
+    const html = renderFaviconLinkTag({
+      rel: 'icon',
+      type: 'image/png',
+      sizes: '32x32',
+      href: '/favicon-32x32.png',
+    });
+    expect(html).toBe('<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />');
+  });
+
+  it('omits optional attributes when not set', () => {
+    const html = renderFaviconLinkTag({
+      rel: 'apple-touch-icon',
+      sizes: '180x180',
+      href: '/apple-touch-icon.png',
+    });
+    expect(html).toBe('<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />');
+  });
+
+  it('never emits an empty href', () => {
+    const links = buildFaviconLinks({ siteConfigBasePath: '/sub-path/' });
+    for (const link of links) {
+      const html = renderFaviconLinkTag(link);
+      const hrefMatch = html.match(/href="([^"]+)"/);
+      expect(hrefMatch, `no href in: ${html}`).not.toBeNull();
+      expect(hrefMatch![1].length, `empty href in: ${html}`).toBeGreaterThan(0);
+    }
+  });
+});

package/src/__tests__/utils/font-stack.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect } from 'vitest';
+import {
+  fontStack,
+  DEFAULT_FONTS,
+  DEFAULT_CATEGORY,
+  type FontConfigLike,
+} from '../../utils/font-stack';
+
+/**
+ * Font stack builder — guarantees that NO slot dictates a category.
+ * Consumers can pick serif, sans-serif, or monospace for title, heading,
+ * body, or mono independently.
+ */
+describe('font-stack', () => {
+  describe('fontStack', () => {
+    it('returns undefined when font is null/undefined/empty', () => {
+      expect(fontStack(null, 'serif')).toBeUndefined();
+      expect(fontStack(undefined, 'serif')).toBeUndefined();
+      expect(fontStack({ family: '' }, 'serif')).toBeUndefined();
+    });
+
+    it('uses declared category for the fallback chain', () => {
+      const font: FontConfigLike = { family: 'Inter', category: 'sans-serif' };
+      expect(fontStack(font, 'serif')).toBe("'Inter', system-ui, sans-serif");
+    });
+
+    it('falls back to defaultCategory when category is omitted (backward compat)', () => {
+      const font: FontConfigLike = { family: 'Inter' };
+      // Default category is serif (header slot's prior behavior).
+      expect(fontStack(font, 'serif')).toBe("'Inter', Georgia, serif");
+    });
+
+    it('lets a sans-serif font be installed in the title slot', () => {
+      // The whole point of the redesign: titles don't have to be serif.
+      const font: FontConfigLike = { family: 'Inter', category: 'sans-serif' };
+      expect(fontStack(font, DEFAULT_CATEGORY.title)).toBe("'Inter', system-ui, sans-serif");
+    });
+
+    it('lets a serif font be installed in the body slot', () => {
+      const font: FontConfigLike = { family: 'Merriweather', category: 'serif' };
+      expect(fontStack(font, DEFAULT_CATEGORY.body)).toBe("'Merriweather', Georgia, serif");
+    });
+
+    it('supports monospace category for any slot', () => {
+      const font: FontConfigLike = { family: 'JetBrains Mono', category: 'monospace' };
+      expect(fontStack(font, DEFAULT_CATEGORY.mono)).toBe(
+        "'JetBrains Mono', ui-monospace, \"JetBrains Mono\", Menlo, Monaco, monospace",
+      );
+    });
+  });
+
+  describe('DEFAULT_FONTS', () => {
+    it('preserves the Glossarist visual identity (serif title + serif heading + sans body + mono)', () => {
+      // These defaults are NOT a dictate — consumers can override any slot
+      // to any category. They exist so existing deployments don't change
+      // appearance on upgrade.
+      expect(DEFAULT_FONTS.title).toContain('DM Serif Display');
+      expect(DEFAULT_FONTS.heading).toContain('DM Serif Display');
+      expect(DEFAULT_FONTS.body).toContain('DM Sans');
+      expect(DEFAULT_FONTS.mono).toContain('JetBrains Mono');
+    });
+
+    it('every default stack includes the appropriate fallback category', () => {
+      expect(DEFAULT_FONTS.title).toMatch(/Georgia, serif/);
+      expect(DEFAULT_FONTS.heading).toMatch(/Georgia, serif/);
+      expect(DEFAULT_FONTS.body).toMatch(/system-ui, sans-serif/);
+      expect(DEFAULT_FONTS.mono).toMatch(/monospace/);
+    });
+  });
+
+  describe('DEFAULT_CATEGORY', () => {
+    it('does NOT force title to be serif — it is only the default', () => {
+      // The default for title IS serif (visual identity), but consumers
+      // can override to any category. The default is just a fallback
+      // when `category` is omitted on the FontConfig.
+      expect(DEFAULT_CATEGORY.title).toBe('serif');
+      expect(DEFAULT_CATEGORY.heading).toBe('serif');
+      expect(DEFAULT_CATEGORY.body).toBe('sans-serif');
+      expect(DEFAULT_CATEGORY.mono).toBe('monospace');
+    });
+  });
+
+  describe('regression — every slot can be every category', () => {
+    // Pin the contract: the consumer can install any category in any slot.
+    // This is the answer to "What do you have to dictate that headers must
+    // be serif?" — nothing, anymore.
+    const categories: Array<['serif' | 'sans-serif' | 'monospace', RegExp]> = [
+      ['serif', /Georgia, serif/],
+      ['sans-serif', /system-ui, sans-serif/],
+      ['monospace', /monospace/],
+    ];
+    const slots = ['title', 'heading', 'body', 'mono'] as const;
+
+    for (const slot of slots) {
+      for (const [category, expectedFallback] of categories) {
+        it(`slot=${slot} with category=${category} → fallback matches`, () => {
+          const font: FontConfigLike = { family: 'TestFont', category };
+          const stack = fontStack(font, DEFAULT_CATEGORY[slot])!;
+          expect(stack).toContain("'TestFont'");
+          expect(stack).toMatch(expectedFallback);
+        });
+      }
+    }
+  });
+});

package/src/components/ConceptDetail.vue

@@ -297,7 +297,7 @@ const nonVerbalReps = computed(() => {
           </button>
         </div>
       </div>
-      <h1 class="font-serif text-2xl sm:text-3xl text-ink-800 leading-snug mb-3" v-html="renderedPrimaryTerm"></h1>
+      <h1 class="font-title text-2xl sm:text-3xl text-ink-800 leading-snug mb-3" v-html="renderedPrimaryTerm"></h1>
       <div class="flex gap-2 overflow-x-auto pb-1 -mx-4 px-4 sm:flex-wrap sm:overflow-visible sm:mx-0 sm:pb-0 scrollbar-none">
         <span class="badge badge-blue font-mono">{{ conceptId }}</span>
         <span