@glossarist/concept-browser 0.7.107 → 0.7.108

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.107",
+  "version": "0.7.108",
   "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,124 @@
+import { describe, it, expect } from 'vitest';
+import { buildDefaultFaviconLinks, renderFaviconLinkTag } from '../../utils/favicon-links';
+
+/**
+ * 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 (favicon-base.ts) and
+ * emit links with the resolved prefix.
+ *
+ * This test exercises the full link-emission path: config in →
+ * resolved base → link tags with correct hrefs.
+ */
+describe('buildDefaultFaviconLinks — BASE_PATH regression', () => {
+  it('emits /-prefixed hrefs for root deployment', () => {
+    const links = buildDefaultFaviconLinks({ 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.
+   *
+   * Reproduction: cie-eilv deployment at /cie-eilv/. The 0.7.106/0.7.107
+   * build emitted href="/favicon-32x32.png" — wrong. The fix must emit
+   * href="/cie-eilv/favicon-32x32.png".
+   */
+  it('emits /cie-eilv/-prefixed hrefs for sub-path deployment', () => {
+    const links = buildDefaultFaviconLinks({
+      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 = buildDefaultFaviconLinks({
+      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 = buildDefaultFaviconLinks({
+      siteConfigBasePath: '/cie-eilv', // no trailing slash
+    });
+    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', () => {
+    // Regression guard: a future bug that drops the filename would leave
+    // just the prefix. This test fails loudly if that happens.
+    const scenarios = [
+      { astroBaseUrl: '/' },
+      { astroBaseUrl: '/vocab/' },
+      { siteConfigBasePath: '/cie-eilv/' },
+      { brandingFaviconBasePath: '/custom/' },
+    ];
+    for (const input of scenarios) {
+      const links = buildDefaultFaviconLinks(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 = buildDefaultFaviconLinks({ astroBaseUrl: '/' });
+    // 5 icons (ico + svg + 3 PNG sizes) + 11 apple-touch-icon sizes = 16
+    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('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', () => {
+    // Build a complete link tag and verify the href attribute has content.
+    const links = buildDefaultFaviconLinks({ 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

package/src/config/types.ts

@@ -1,10 +1,22 @@
 // === Branding ===
 
+export type FontCategory = 'serif' | 'sans-serif' | 'monospace';
+
 export interface FontConfig {
   family: string;
   source: 'google' | 'url' | 'local';
   weights?: number[];
   url?: string;
+  /** Font category — controls the fallback chain when the primary family
+   *  fails to load. Defaults preserve prior behavior: `'serif'` for header,
+   *  `'sans-serif'` for body, `'monospace'` for mono.
+   *
+   *  Set explicitly when the consumer's chosen family doesn't match the
+   *  slot's default category — e.g. set `header: { family: 'Inter',
+   *  category: 'sans-serif' }` so the fallback chain is
+   *  `'Inter', system-ui, sans-serif` instead of `'Inter', Georgia, serif`.
+   */
+  category?: FontCategory;
 }
 
 export interface LogoConfig {
@@ -38,8 +50,18 @@ export interface SiteBranding {
   primaryColor?: string;
   darkColor?: string;
   fonts?: {
+    /** Most prominent display text on each page — home hero, concept name
+     *  on the detail page, group/dataset title. No category is dictated;
+     *  pick `serif`, `sans-serif`, or `monospace` for any slot. */
+    title?: FontConfig;
+    /** Section headings (h2–h6). */
+    heading?: FontConfig;
+    /** Backward-compat alias for `heading` (deprecated). */
     header?: FontConfig;
+    /** Paragraph text, lists, table cells. */
     body?: FontConfig;
+    /** Code blocks, inline code, kbd. */
+    mono?: FontConfig;
   };
   logo?: LogoConfig;
   footerLogo?: LogoConfig;

package/src/config/use-site-config.ts

@@ -3,6 +3,7 @@ import type { PageConfig, SiteColors } from './types';
 import type { DatasetGroup } from './types';
 import { synthesizePages } from './page-types';
 import { locale } from '../i18n';
+import { fontStack, DEFAULT_FONTS, DEFAULT_CATEGORY } from '../utils/font-stack';
 
 export interface RuntimeSiteConfig {
   id: string;
@@ -21,8 +22,11 @@ export interface RuntimeSiteConfig {
     primaryColor?: string;
     darkColor?: string;
     fonts?: {
-      header?: { family: string; source: string; weights?: number[]; url?: string };
-      body?: { family: string; source: string; weights?: number[]; url?: string };
+      title?: { family: string; source: string; weights?: number[]; url?: string; category?: 'serif' | 'sans-serif' | 'monospace' };
+      heading?: { family: string; source: string; weights?: number[]; url?: string; category?: 'serif' | 'sans-serif' | 'monospace' };
+      header?: { family: string; source: string; weights?: number[]; url?: string; category?: 'serif' | 'sans-serif' | 'monospace' }; // deprecated alias for heading
+      body?: { family: string; source: string; weights?: number[]; url?: string; category?: 'serif' | 'sans-serif' | 'monospace' };
+      mono?: { family: string; source: string; weights?: number[]; url?: string; category?: 'serif' | 'sans-serif' | 'monospace' };
     };
     logo?: { path: string; alt: string; url?: string; light?: string; dark?: string };
     footerLogo?: { path: string; alt: string; url?: string; light?: string; dark?: string };
@@ -95,13 +99,25 @@ function applyBranding(config: RuntimeSiteConfig) {
     root.style.setProperty('--brand-dark', b.darkColor);
   }
 
-  if (b.fonts?.header) {
-    loadFont(b.fonts.header);
-    root.style.setProperty('--font-header', `'${b.fonts.header.family}', Georgia, serif`);
+  if (b.fonts?.title) {
+    loadFont(b.fonts.title);
+    root.style.setProperty('--font-title', fontStack(b.fonts.title, DEFAULT_CATEGORY.title) ?? DEFAULT_FONTS.title);
+  }
+  // heading is the new slot name; header is the backward-compat alias.
+  const headingFont = b.fonts?.heading ?? b.fonts?.header;
+  if (headingFont) {
+    loadFont(headingFont);
+    const stack = fontStack(headingFont, DEFAULT_CATEGORY.heading) ?? DEFAULT_FONTS.heading;
+    root.style.setProperty('--font-heading', stack);
+    root.style.setProperty('--font-header', stack);
   }
   if (b.fonts?.body) {
     loadFont(b.fonts.body);
-    root.style.setProperty('--font-body', `'${b.fonts.body.family}', system-ui, sans-serif`);
+    root.style.setProperty('--font-body', fontStack(b.fonts.body, DEFAULT_CATEGORY.body) ?? DEFAULT_FONTS.body);
+  }
+  if (b.fonts?.mono) {
+    loadFont(b.fonts.mono);
+    root.style.setProperty('--font-mono', fontStack(b.fonts.mono, DEFAULT_CATEGORY.mono) ?? DEFAULT_FONTS.mono);
   }
 }
 

package/src/layouts/Default.astro

@@ -2,6 +2,14 @@
 import '@/styles/tailwind.css';
 import AppIsland from '../islands/AppIsland.vue';
 import { getSiteConfig } from '../lib/site-config';
+import {
+  fontStack,
+  DEFAULT_FONTS,
+  DEFAULT_CATEGORY,
+  type FontConfigLike,
+} from '../utils/font-stack';
+import { resolveFaviconBase } from '../utils/favicon-base';
+import { buildDefaultFaviconLinks, renderFaviconLinkTag } from '../utils/favicon-links';
 
 interface Props {
   title: string;
@@ -14,28 +22,35 @@ const { title, description = '', conceptTerm, conceptDefinition } = Astro.props;
 const siteConfig = await getSiteConfig();
 
 // Derive Google Fonts URL from siteConfig branding (build-time SSG).
-// Falls back to the default DM Sans / DM Serif Display / JetBrains Mono
-// when no branding.fonts is declared.
+// Includes every slot the consumer declared (title / heading / body / mono,
+// plus the deprecated `header` alias). Falls back to the default
+// DM Sans / DM Serif Display / JetBrains Mono when nothing is declared.
 const brandingFonts = siteConfig?.branding?.fonts;
+const headingFont = brandingFonts?.heading ?? brandingFonts?.header; // header = deprecated alias
+const fontSlots = [
+  brandingFonts?.title,
+  headingFont,
+  brandingFonts?.body,
+  brandingFonts?.mono,
+];
 const fontParts: string[] = [];
-if (brandingFonts?.header?.source === 'google' && brandingFonts.header.family) {
-  const w = (brandingFonts.header.weights || [400, 700]).join(';');
-  fontParts.push(`family=${brandingFonts.header.family.replace(/ /g, '+')}:wght@${w}`);
-}
-if (brandingFonts?.body?.source === 'google' && brandingFonts.body.family) {
-  const w = (brandingFonts.body.weights || [400, 700]).join(';');
-  fontParts.push(`family=${brandingFonts.body.family.replace(/ /g, '+')}:wght@${w}`);
+for (const f of fontSlots) {
+  if (f && (f as FontConfigLike).source === 'google' && (f as FontConfigLike).family) {
+    const w = (f.weights || [400, 700]).join(';');
+    fontParts.push(`family=${(f as FontConfigLike).family.replace(/ /g, '+')}:wght@${w}`);
+  }
 }
 const fontsUrl = fontParts.length > 0
   ? `https://fonts.googleapis.com/css2?${fontParts.join('&')}&display=swap`
   : 'https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700;1,9..40,400&family=DM+Serif+Display:ital@0;1&family=JetBrains+Mono:wght@400;500&display=swap';
 
-const fontHeader = brandingFonts?.header?.family
-  ? `'${brandingFonts.header.family}', Georgia, serif`
-  : `'DM Serif Display', Georgia, serif`;
-const fontBody = brandingFonts?.body?.family
-  ? `'${brandingFonts.body.family}', system-ui, sans-serif`
-  : `'DM Sans', system-ui, sans-serif`;
+// Build CSS font-family stacks via the shared SSOT. Consumers can pick
+// any category for any slot — e.g. sans-serif title + serif heading —
+// and the fallback chain follows the declared category.
+const fontTitle = fontStack(brandingFonts?.title, DEFAULT_CATEGORY.title) ?? DEFAULT_FONTS.title;
+const fontHeading = fontStack(headingFont, DEFAULT_CATEGORY.heading) ?? DEFAULT_FONTS.heading;
+const fontBody = fontStack(brandingFonts?.body, DEFAULT_CATEGORY.body) ?? DEFAULT_FONTS.body;
+const fontMono = fontStack(brandingFonts?.mono, DEFAULT_CATEGORY.mono) ?? DEFAULT_FONTS.mono;
 
 // Favicon configuration (issue #173).
 //
@@ -55,7 +70,20 @@ const fontBody = brandingFonts?.body?.family
 const faviconCfg = siteConfig?.branding?.favicon ?? {};
 const skipDefaultFaviconLinks = faviconCfg.skip_default_links === true;
 const customFaviconLinks: string = faviconCfg.links_html ?? '';
-const faviconBase = faviconCfg.base_path ?? '/';
+
+// BASE_PATH-aware favicon URL prefix. Walks the configuration cascade:
+// branding.favicon.base_path → siteConfig.basePath → import.meta.env.BASE_URL → '/'.
+// Always ends with '/' so `${faviconBase}favicon.ico` resolves correctly
+// whether the deployment is at '/' or '/cie-eilv/'.
+//
+// See src/utils/favicon-base.ts for the shared resolver + regression tests.
+const faviconBaseInput = {
+  brandingFaviconBasePath: typeof faviconCfg === 'object' ? faviconCfg.base_path : undefined,
+  siteConfigBasePath: siteConfig?.basePath,
+  astroBaseUrl: import.meta.env.BASE_URL,
+};
+const faviconBase = resolveFaviconBase(faviconBaseInput);
+const faviconLinks = buildDefaultFaviconLinks(faviconBaseInput).map(renderFaviconLinkTag);
 ---
 
 <!DOCTYPE html>
@@ -63,24 +91,7 @@ const faviconBase = faviconCfg.base_path ?? '/';
   <head>
     <meta charset="utf-8" />
     {!skipDefaultFaviconLinks && (
-      <>
-        <link rel="icon" type="image/x-icon" href={`${faviconBase}favicon.ico`} />
-        <link rel="icon" type="image/svg+xml" href={`${faviconBase}favicon.svg`} />
-        <link rel="icon" type="image/png" sizes="16x16" href={`${faviconBase}favicon-16x16.png`} />
-        <link rel="icon" type="image/png" sizes="32x32" href={`${faviconBase}favicon-32x32.png`} />
-        <link rel="icon" type="image/png" sizes="48x48" href={`${faviconBase}favicon-48x48.png`} />
-        <link rel="apple-touch-icon" sizes="57x57" href={`${faviconBase}apple-touch-icon-57x57.png`} />
-        <link rel="apple-touch-icon" sizes="60x60" href={`${faviconBase}apple-touch-icon-60x60.png`} />
-        <link rel="apple-touch-icon" sizes="72x72" href={`${faviconBase}apple-touch-icon-72x72.png`} />
-        <link rel="apple-touch-icon" sizes="76x76" href={`${faviconBase}apple-touch-icon-76x76.png`} />
-        <link rel="apple-touch-icon" sizes="114x114" href={`${faviconBase}apple-touch-icon-114x114.png`} />
-        <link rel="apple-touch-icon" sizes="120x120" href={`${faviconBase}apple-touch-icon-120x120.png`} />
-        <link rel="apple-touch-icon" sizes="144x144" href={`${faviconBase}apple-touch-icon-144x144.png`} />
-        <link rel="apple-touch-icon" sizes="152x152" href={`${faviconBase}apple-touch-icon-152x152.png`} />
-        <link rel="apple-touch-icon" sizes="167x167" href={`${faviconBase}apple-touch-icon-167x167.png`} />
-        <link rel="apple-touch-icon" sizes="180x180" href={`${faviconBase}apple-touch-icon-180x180.png`} />
-        <link rel="apple-touch-icon" sizes="1024x1024" href={`${faviconBase}apple-touch-icon-1024x1024.png`} />
-      </>
+      <Fragment set:html={faviconLinks.join('\n    ')} />
     )}
     {customFaviconLinks && <Fragment set:html={customFaviconLinks} />}
     <meta name="apple-mobile-web-app-capable" content="yes" />
@@ -93,7 +104,7 @@ const faviconBase = faviconCfg.base_path ?? '/';
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link rel="preload" as="style" href={fontsUrl} onload="this.rel='stylesheet'">
     <noscript><link href={fontsUrl} rel="stylesheet"></noscript>
-    <Fragment set:html={`<style>:root{--font-header:${fontHeader};--font-body:${fontBody}}</style>`} />
+    <Fragment set:html={`<style>:root{--font-title:${fontTitle};--font-heading:${fontHeading};--font-header:${fontHeading};--font-body:${fontBody};--font-mono:${fontMono}}</style>`} />
     <script is:inline>
       (function() {
         const c = document.cookie.split(';').map(s => s.trim()).find(s => s.startsWith('theme='));

package/src/styles/tailwind.css

@@ -60,6 +60,8 @@
   --brand-primary: #2563eb;
   --brand-primary-rgb: 37, 99, 235;
   --brand-dark: #1e293b;
+  --font-title: "DM Serif Display", Georgia, serif;
+  --font-heading: "DM Serif Display", Georgia, serif;
   --font-header: "DM Serif Display", Georgia, serif;
   --font-body: "DM Sans", system-ui, sans-serif;
   --gold-accent: #B8935A;
@@ -73,6 +75,9 @@
     -webkit-font-smoothing: antialiased;
     -moz-osx-font-smoothing: grayscale;
   }
+  .font-title {
+    font-family: var(--font-title);
+  }
   h1, h2, h3, .font-serif {
     font-family: var(--font-header);
   }

package/src/utils/favicon-base.ts

@@ -0,0 +1,45 @@
+/**
+ * Favicon base path resolver — shared SSOT for the URL prefix that
+ * goes in front of every favicon `<link href="...">`.
+ *
+ * Used by:
+ *   - `src/layouts/Default.astro`     (build-time SSG <link> emission)
+ *   - `cli/index.mjs` / `cli/index.ts` (runtime <link> rewriting)
+ *
+ * Why this exists: a deployment at `/cie-eilv/` has its favicon files
+ * at `/cie-eilv/favicon.ico`, NOT `/favicon.ico`. Hardcoding `/` as
+ * the URL prefix (which 0.7.106 did) caused 404s on every sub-path
+ * deployment. This resolver walks the configuration cascade to find
+ * the right prefix.
+ */
+
+export interface FaviconBaseInput {
+  /** Explicit consumer override via `branding.favicon.base_path`. */
+  brandingFaviconBasePath?: string;
+  /** Consumer's declared sub-path via `site-config.yml:basePath`. */
+  siteConfigBasePath?: string;
+  /** Build-time BASE_PATH from Astro/Vite (`import.meta.env.BASE_URL`). */
+  astroBaseUrl?: string;
+}
+
+/**
+ * Resolve the URL prefix for favicon links. Always returns a string
+ * ending with `/` so callers can do `${base}favicon.ico` without
+ * worrying about the separator.
+ *
+ * Cascade (first non-empty wins):
+ *   1. branding.favicon.base_path (explicit per-deployment override)
+ *   2. siteConfig.basePath        (consumer's declared sub-path)
+ *   3. import.meta.env.BASE_URL   (build-time BASE_PATH)
+ *   4. '/'                        (last resort — root deployment)
+ */
+export function resolveFaviconBase(input: FaviconBaseInput): string {
+  const candidates = [
+    input.brandingFaviconBasePath,
+    input.siteConfigBasePath,
+    input.astroBaseUrl,
+    '/',
+  ];
+  const raw = candidates.find(c => c != null && c.length > 0) ?? '/';
+  return raw.endsWith('/') ? raw : `${raw}/`;
+}

package/src/utils/favicon-links.ts

@@ -0,0 +1,79 @@
+/**
+ * Favicon link-tag builder — shared SSOT for the `<link rel="icon">`
+ * block emitted in `<head>`.
+ *
+ * Used by:
+ *   - `src/layouts/Default.astro` (build-time SSG)
+ *
+ * Why this exists: a deployment at `/cie-eilv/` has its favicon files
+ * at `/cie-eilv/favicon.ico`, NOT `/favicon.ico`. Hardcoding `/` as
+ * the URL prefix (which 0.7.106 did) caused 404s on every sub-path
+ * deployment. This builder walks the configuration cascade via
+ * `resolveFaviconBase` and emits correctly-prefixed link tags.
+ */
+
+import { resolveFaviconBase } from './favicon-base';
+
+export interface FaviconLinkTag {
+  rel: string;
+  type?: string;
+  sizes?: string;
+  href: string;
+}
+
+/** Default favicon file set emitted by the CLI's `favicons` pipeline. */
+const DEFAULT_FAVICON_FILES: readonly FaviconLinkTag[] = [
+  { rel: 'icon',       type: 'image/x-icon',  href: 'favicon.ico' },
+  { rel: 'icon',       type: 'image/svg+xml', href: 'favicon.svg' },
+  { rel: 'icon',       type: 'image/png',     sizes: '16x16',  href: 'favicon-16x16.png' },
+  { rel: 'icon',       type: 'image/png',     sizes: '32x32',  href: 'favicon-32x32.png' },
+  { rel: 'icon',       type: 'image/png',     sizes: '48x48',  href: 'favicon-48x48.png' },
+  { rel: 'apple-touch-icon', sizes: '57x57',  href: 'apple-touch-icon-57x57.png' },
+  { rel: 'apple-touch-icon', sizes: '60x60',  href: 'apple-touch-icon-60x60.png' },
+  { rel: 'apple-touch-icon', sizes: '72x72',  href: 'apple-touch-icon-72x72.png' },
+  { rel: 'apple-touch-icon', sizes: '76x76',  href: 'apple-touch-icon-76x76.png' },
+  { rel: 'apple-touch-icon', sizes: '114x114',href: 'apple-touch-icon-114x114.png' },
+  { rel: 'apple-touch-icon', sizes: '120x120',href: 'apple-touch-icon-120x120.png' },
+  { rel: 'apple-touch-icon', sizes: '144x144',href: 'apple-touch-icon-144x144.png' },
+  { rel: 'apple-touch-icon', sizes: '152x152',href: 'apple-touch-icon-152x152.png' },
+  { rel: 'apple-touch-icon', sizes: '167x167',href: 'apple-touch-icon-167x167.png' },
+  { rel: 'apple-touch-icon', sizes: '180x180',href: 'apple-touch-icon-180x180.png' },
+  { rel: 'apple-touch-icon', sizes: '1024x1024',href: 'apple-touch-icon-1024x1024.png' },
+];
+
+export interface BuildFaviconLinksInput {
+  /** Explicit consumer override via `branding.favicon.base_path`. */
+  brandingFaviconBasePath?: string;
+  /** Consumer's declared sub-path via `site-config.yml:basePath`. */
+  siteConfigBasePath?: string;
+  /** Build-time BASE_PATH from Astro/Vite (`import.meta.env.BASE_URL`). */
+  astroBaseUrl?: string;
+}
+
+/**
+ * Build the list of default favicon link tags with BASE_PATH-aware URLs.
+ *
+ * Returns the tag descriptors; the caller (Default.astro) renders them
+ * into <link> elements.
+ */
+export function buildDefaultFaviconLinks(input: BuildFaviconLinksInput): FaviconLinkTag[] {
+  const base = resolveFaviconBase(input);
+  return DEFAULT_FAVICON_FILES.map(tag => ({
+    ...tag,
+    href: `${base}${tag.href}`,
+  }));
+}
+
+/**
+ * Render a single FaviconLinkTag to an HTML <link> string.
+ *
+ * Attribute order: rel, type (if present), sizes (if present), href.
+ * Deterministic for snapshot testing.
+ */
+export function renderFaviconLinkTag(tag: FaviconLinkTag): string {
+  const attrs: string[] = [`rel="${tag.rel}"`];
+  if (tag.type) attrs.push(`type="${tag.type}"`);
+  if (tag.sizes) attrs.push(`sizes="${tag.sizes}"`);
+  attrs.push(`href="${tag.href}"`);
+  return `<link ${attrs.join(' ')} />`;
+}

package/src/utils/font-stack.ts

@@ -0,0 +1,77 @@
+/**
+ * Font stack builder — shared SSOT for `branding.fonts.*` fallback chains.
+ *
+ * Used by:
+ *   - `src/layouts/Default.astro`     (build-time SSG CSS variables)
+ *   - `src/config/use-site-config.ts` (runtime CSS variable overrides)
+ *
+ * Design principle: NO slot dictates a font category. The consumer picks
+ * `serif`, `sans-serif`, or `monospace` for each slot independently. The
+ * defaults below preserve the Glossarist visual identity (serif title +
+ * serif heading + sans-serif body + monospace code) but every slot can
+ * be overridden to any category.
+ *
+ * Slot semantics:
+ *   - title   : single most-prominent display text on the page
+ *               (home hero h1, concept name on detail page, group title)
+ *   - heading : h2–h6 section headings
+ *   - body    : paragraph text, lists, table cells
+ *   - mono    : code blocks, inline code, kbd
+ *
+ * Backward compat:
+ *   - `branding.fonts.header` is accepted as a deprecated alias for
+ *     `branding.fonts.heading` (both write to `--font-heading`, which
+ *     also surfaces as `--font-header` for legacy CSS).
+ */
+
+export type FontCategory = 'serif' | 'sans-serif' | 'monospace';
+
+export interface FontConfigLike {
+  family: string;
+  category?: FontCategory;
+}
+
+const FALLBACKS: Readonly<Record<FontCategory, string>> = {
+  serif: 'Georgia, serif',
+  'sans-serif': 'system-ui, sans-serif',
+  monospace: 'ui-monospace, "JetBrains Mono", Menlo, Monaco, monospace',
+};
+
+/**
+ * Build a CSS font-family stack from a FontConfig-like object.
+ *
+ * - If `font` is null/undefined or has no family, returns `undefined`
+ *   and the caller applies its slot-specific default.
+ * - If `font.category` is omitted, falls back to `defaultCategory`
+ *   so existing configs preserve prior behavior.
+ */
+export function fontStack(
+  font: FontConfigLike | null | undefined,
+  defaultCategory: FontCategory,
+): string | undefined {
+  if (!font?.family) return undefined;
+  const category: FontCategory = font.category ?? defaultCategory;
+  const fallback = FALLBACKS[category];
+  return `'${font.family}', ${fallback}`;
+}
+
+/** Default font stacks (used when the consumer declares nothing).
+ *  Preserves the Glossarist visual identity. NOT a dictate — every
+ *  slot can be overridden to any category via branding.fonts.*. */
+export const DEFAULT_FONTS = {
+  title: `'DM Serif Display', ${FALLBACKS.serif}`,
+  heading: `'DM Serif Display', ${FALLBACKS.serif}`,
+  body: `'DM Sans', ${FALLBACKS['sans-serif']}`,
+  mono: `'JetBrains Mono', ${FALLBACKS.monospace}`,
+} as const;
+
+/** Slot → default category, used when the consumer omits `category`.
+ *  These defaults preserve prior behavior and are NOT a constraint —
+ *  consumers can pick any category for any slot. */
+export const DEFAULT_CATEGORY = {
+  title: 'serif' as FontCategory,
+  heading: 'serif' as FontCategory,
+  body: 'sans-serif' as FontCategory,
+  mono: 'monospace' as FontCategory,
+} as const;
+

package/src/views/DatasetView.vue

@@ -321,7 +321,7 @@ function clearSection() {
 
     <!-- Header -->
     <div v-if="manifest" class="mb-8">
-      <h1 class="font-serif text-3xl text-ink-800 mb-2">{{ localizedTitle }}</h1>
+      <h1 class="font-title text-3xl text-ink-800 mb-2">{{ localizedTitle }}</h1>
       <p class="text-ink-400 leading-relaxed max-w-2xl">{{ localizedDescription }}</p>
       <div class="flex flex-wrap gap-2 mt-4">
         <span class="badge" :style="conceptCountBadgeStyle">{{ manifest.conceptCount.toLocaleString() }} {{ t('dataset.concepts') }}</span>

package/src/views/GroupView.vue

@@ -96,7 +96,7 @@ function openDataset(id: string) {
     <template v-else-if="group">
       <div class="flex items-baseline gap-3 mb-2">
         <span class="text-2xl">{{ groupMeta.glyph }}</span>
-        <h1 class="font-serif text-3xl text-ink-800 dark:text-ink-50">
+        <h1 class="font-title text-3xl text-ink-800 dark:text-ink-50">
           {{ group.label }}
         </h1>
       </div>

package/src/views/HomeView.vue

@@ -77,7 +77,7 @@ function goToGraph() { router.push({ name: 'graph' }); }
           <span class="text-[11px] font-semibold uppercase tracking-[0.2em] text-ink-300 hidden sm:inline">{{ localizedSubtitle }}</span>
         </template>
       </div>
-      <h1 class="font-serif text-[2rem] sm:text-[2.75rem] text-ink-800 leading-[1.1] mb-4 tracking-tight">
+      <h1 class="font-title text-[2rem] sm:text-[2.75rem] text-ink-800 leading-[1.1] mb-4 tracking-tight">
         {{ localizedTitle }}
         <template v-if="localizedSubtitle"><br class="hidden sm:block" /> {{ localizedSubtitle }}</template>
       </h1>

package/tailwind.config.js

@@ -13,9 +13,11 @@ export default {
   theme: {
     extend: {
       fontFamily: {
+        title: ['var(--font-title, "DM Serif Display")', 'Georgia', 'serif'],
+        heading: ['var(--font-heading, "DM Serif Display")', 'Georgia', 'serif'],
         serif: ['var(--font-header, "DM Serif Display")', 'Georgia', 'serif'],
         sans: ['var(--font-body, "DM Sans")', 'system-ui', 'sans-serif'],
-        mono: ['"JetBrains Mono"', 'monospace'],
+        mono: ['var(--font-mono, "JetBrains Mono")', 'ui-monospace', 'monospace'],
       },
       colors: {
         ink: {