@glossarist/concept-browser 0.7.111 → 0.7.113

package/package.json

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

package/src/__tests__/composables/cite-resolver.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { computed, ref } from 'vue';
+import { useConceptEdges } from '../../composables/use-concept-edges';
+import { useVocabularyStore } from '../../stores/vocabulary';
+import type { Manifest, GraphEdge } from '../../adapters/types';
+import { makeManifest, setupPinia } from '../test-helpers';
+import { getFactory, resetFactory } from '../../adapters/factory';
+import { useRenderOptions } from '../../composables/use-render-options';
+import type { Router } from 'vue-router';
+
+/**
+ * citeResolver contract — pins the {{cite:sourceId}} resolution cascade.
+ *
+ * The citeResolver must:
+ * 1. Look up the concept's own sources[] for a matching id
+ * 2. Delegate to ReferenceResolver.resolveCite() which walks the
+ *    deployment's cascade
+ * 3. Render based on classification (internal → navigable link,
+ *    self-contained → external link with origin.link, unresolved → span)
+ *
+ * Bug history: citeResolver was dead code (never wired). Every
+ * {{cite:foo}} mention fell through to a plain <span> with no resolution.
+ * This spec pins the wiring.
+ */
+
+describe('citeResolver — {{cite:sourceId}} resolution', () => {
+  const noopRouter = { push() {} } as unknown as Router;
+  let store: ReturnType<typeof useVocabularyStore>;
+  const manifest: Manifest = makeManifest({
+    id: 'test',
+    datasetUri: 'urn:test:dataset',
+    uriBase: 'https://example.org',
+  });
+
+  beforeEach(() => {
+    setupPinia();
+    resetFactory();
+    store = useVocabularyStore();
+    store.manifests.set(manifest.id, manifest);
+
+    const factory = getFactory();
+    factory.resolveRelatedRef = vi.fn((ref: { source: string | null; id: string | null } | null) =>
+      ref?.source === 'urn:test:dataset' && ref.id
+        ? { registerId: manifest.id, conceptId: ref.id }
+        : null,
+    );
+  });
+
+  it('returns cite-ref span when no sources are provided', () => {
+    const { citeResolver } = useRenderOptions(() => 'test', () => undefined);
+    const html = citeResolver('foo', null);
+    expect(html).toContain('cite-ref');
+    expect(html).toContain('foo');
+  });
+
+  it('returns cite-unresolved when source id not found in sources', () => {
+    const sources = [{ id: 'bar', origin: { ref: { source: 'Test', id: '42' } } }];
+    const { citeResolver } = useRenderOptions(() => 'test', () => sources);
+    const html = citeResolver('foo', null);
+    expect(html).toContain('cite-unresolved');
+    expect(html).toContain('foo');
+  });
+
+  it('renders the label when provided', () => {
+    const sources = [{ id: 'foo', origin: { ref: { source: 'Test', id: '42' } } }];
+    const { citeResolver } = useRenderOptions(() => 'test', () => sources);
+    const html = citeResolver('foo', 'custom label');
+    // The resolver runs the cascade. Without a registered sourceRef, it
+    // falls through to unresolved or self-contained. Either way, the label
+    // or the source info should be in the output.
+    expect(html).toMatch(/custom label|Test|42/);
+  });
+
+  it('renders origin.link as external link for self-contained citation', () => {
+    const link = 'https://example.org/external/page';
+    const sources = [{
+      id: 'foo',
+      origin: { ref: { source: 'External', id: 'X1' }, link },
+    }];
+    const { citeResolver } = useRenderOptions(() => 'test', () => sources);
+    const html = citeResolver('foo', null);
+    // Without a registered sourceRef matching "External", the cascade
+    // falls through to self-contained or external. The link should appear.
+    expect(html).toContain('href');
+    expect(html).toContain(link);
+  });
+
+  it('does NOT crash when source.origin is null', () => {
+    const sources = [{ id: 'foo', origin: null }];
+    const { citeResolver } = useRenderOptions(() => 'test', () => sources);
+    expect(() => citeResolver('foo', null)).not.toThrow();
+  });
+
+  it('does NOT crash when sources is empty array', () => {
+    const { citeResolver } = useRenderOptions(() => 'test', () => []);
+    expect(() => citeResolver('foo', null)).not.toThrow();
+  });
+
+  it('does NOT crash when registerId returns empty string', () => {
+    const sources = [{ id: 'foo', origin: { ref: { source: 'X', id: '1' } } }];
+    const { citeResolver } = useRenderOptions(() => '', () => sources);
+    expect(() => citeResolver('foo', null)).not.toThrow();
+  });
+});
+
+describe('RenderOptions — urnRefResolver removed', () => {
+  it('content-renderer no longer exports UrnRefResolver type', async () => {
+    // RenderOptions is a TypeScript interface (no runtime export).
+    // Verify the UrnRefResolver type is gone by checking the source.
+    const fs = await import('fs');
+    const path = await import('path');
+    const source = fs.readFileSync(
+      path.resolve(process.cwd(), 'src/utils/content-renderer.ts'),
+      'utf-8',
+    );
+    expect(source).not.toMatch(/UrnRefResolver/);
+    expect(source).not.toMatch(/urnRefResolver/);
+  });
+});

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

@@ -0,0 +1,202 @@
+import { describe, it, expect } from 'vitest';
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+import {
+  buildFontVariables,
+  renderFontVariablesInline,
+  FONT_SLOTS,
+  type BrandingFontsLike,
+} from '../../utils/font-variables';
+
+/**
+ * Single-source-of-truth contract for branding-driven CSS font variables.
+ *
+ * Bug history (2026-08-01):
+ *   - 0.7.106–0.7.110: brand fonts were silently clobbered for
+ *     `--font-serif`/`--font-sans`/`--font-mono` because the tailwind.css
+ *     `@theme` block emitted `:root, :host { ... }` declarations into the
+ *     CSS bundle, which loaded AFTER Default.astro's inline `<style>` and
+ *     overrode the brand values per CSS cascade (equal specificity, later
+ *     source order wins).
+ *   - 0.7.111 contributor patch fixed `:root` block but missed `@theme`.
+ *
+ * Post-refactor: `buildFontVariables()` is the only emitter. Both
+ * `Default.astro` (build-time inline) and `use-site-config.ts` (runtime
+ * overrides) call it. The output is the canonical slot-named shape —
+ * no `--font-serif`/`--font-sans` category-named variables that bake in
+ * serif↔heading / sans↔body assumptions.
+ */
+
+describe('buildFontVariables — shape contract', () => {
+  it('returns exactly the four slot-named variables', () => {
+    const vars = buildFontVariables(null);
+    expect(Object.keys(vars).sort()).toEqual(
+      ['--font-body', '--font-heading', '--font-mono', '--font-title'],
+    );
+  });
+
+  it('FONT_SLOTS constant is the canonical slot list', () => {
+    expect(FONT_SLOTS).toEqual(['title', 'heading', 'body', 'mono']);
+  });
+
+  it('never emits --font-serif or --font-sans (category-named variables are forbidden)', () => {
+    const vars = buildFontVariables({
+      title: { family: 'Raleway', category: 'sans-serif' },
+    });
+    expect(vars).not.toHaveProperty('--font-serif');
+    expect(vars).not.toHaveProperty('--font-sans');
+  });
+
+  it('never emits --font-header as a separate variable (legacy alias handled by CSS, not JS)', () => {
+    const vars = buildFontVariables({ header: { family: 'Raleway' } });
+    expect(vars).not.toHaveProperty('--font-header');
+  });
+});
+
+describe('buildFontVariables — defaults preserve Glossarist visual identity', () => {
+  it('falls back to DM Serif Display + DM Sans + JetBrains Mono when no branding', () => {
+    const vars = buildFontVariables(null);
+    expect(vars['--font-title']).toContain('DM Serif Display');
+    expect(vars['--font-heading']).toContain('DM Serif Display');
+    expect(vars['--font-body']).toContain('DM Sans');
+    expect(vars['--font-mono']).toContain('JetBrains Mono');
+  });
+
+  it('keeps working when individual slots are missing', () => {
+    const vars = buildFontVariables({ title: { family: 'Raleway' } });
+    expect(vars['--font-title']).toContain('Raleway');
+    expect(vars['--font-heading']).toContain('DM Serif Display');
+    expect(vars['--font-body']).toContain('DM Sans');
+  });
+});
+
+describe('buildFontVariables — brand overrides', () => {
+  const raleway: BrandingFontsLike = {
+    title:   { family: 'Raleway', category: 'sans-serif' },
+    heading: { family: 'Raleway', category: 'sans-serif' },
+    body:    { family: 'Raleway', category: 'sans-serif' },
+    mono:    { family: 'Fira Code', category: 'monospace' },
+  };
+
+  it('produces Raleway stacks for every text slot when consumer sets all four', () => {
+    const vars = buildFontVariables(raleway);
+    expect(vars['--font-title']).toBe("'Raleway', system-ui, sans-serif");
+    expect(vars['--font-heading']).toBe("'Raleway', system-ui, sans-serif");
+    expect(vars['--font-body']).toBe("'Raleway', system-ui, sans-serif");
+    expect(vars['--font-mono']).toBe("'Fira Code', ui-monospace, \"JetBrains Mono\", Menlo, Monaco, monospace");
+  });
+
+  it('honors `header` legacy alias as input for the heading slot', () => {
+    const vars = buildFontVariables({ header: { family: 'Inter', category: 'sans-serif' } });
+    expect(vars['--font-heading']).toBe("'Inter', system-ui, sans-serif");
+  });
+
+  it('`heading` slot wins over legacy `header` alias when both are set', () => {
+    const vars = buildFontVariables({
+      heading: { family: 'Heading', category: 'sans-serif' },
+      header:  { family: 'Header',  category: 'sans-serif' },
+    });
+    expect(vars['--font-heading']).toContain('Heading');
+    expect(vars['--font-heading']).not.toContain('Header');
+  });
+});
+
+describe('renderFontVariablesInline — serialization', () => {
+  it('produces a `:root { ... }` block with every slot variable', () => {
+    const css = renderFontVariablesInline({ title: { family: 'Raleway', category: 'sans-serif' } });
+    expect(css.startsWith(':root{')).toBe(true);
+    expect(css.endsWith('}')).toBe(true);
+    expect(css).toContain('--font-title:');
+    expect(css).toContain('--font-heading:');
+    expect(css).toContain('--font-body:');
+    expect(css).toContain('--font-mono:');
+    expect(css).toContain("'Raleway'");
+  });
+
+  it('separates declarations with semicolons (no trailing junk)', () => {
+    const css = renderFontVariablesInline(null);
+    // Each declaration is `--font-X: value`, separated by `;`.
+    const declCount = css.match(/--font-[a-z]+:/g)!.length;
+    const sepCount = css.match(/;/g)!.length;
+    expect(declCount).toBe(4);
+    expect(sepCount).toBe(3); // 4 declarations = 3 separators (no trailing)
+    expect(css).not.toMatch(/;;/);
+  });
+
+  it('emits only slot-named variables — never --font-serif / --font-sans', () => {
+    const css = renderFontVariablesInline(null);
+    expect(css).not.toMatch(/--font-serif/);
+    expect(css).not.toMatch(/--font-sans/);
+    expect(css).not.toMatch(/--font-header/);
+  });
+});
+
+/**
+ * THE LOAD-BEARING REGRESSION TEST.
+ *
+ * The bundled CSS must NOT contain `:root, :host { --font-... }` declarations
+ * for any slot variable. If it does, the bundle loads after the inline
+ * `<style>` and clobbers the brand values per CSS cascade.
+ *
+ * This test scans the built Default.*.css artifact (produced by
+ * `npm run build:astro`) and asserts no font variable appears in a
+ * `:root` selector. Skipped when dist/ doesn't exist (fresh clone,
+ * before first build).
+ */
+function findBundleDefaultCss(): string | null {
+  const astroDir = resolve(process.cwd(), 'dist/_astro');
+  if (!existsSync(astroDir)) return null;
+  for (const f of readdirSync(astroDir)) {
+    if (f.startsWith('Default.') && f.endsWith('.css')) {
+      return readFileSync(resolve(astroDir, f), 'utf-8');
+    }
+  }
+  return null;
+}
+
+describe('bundle drift regression — Default.*.css must not clobber brand font vars', () => {
+  it('bundle has no `:root,:host{...--font-X: <literal>}` declarations', () => {
+    // The bundle's `:root, :host { ... }` block (from @theme) is allowed
+    // to define font variables as `var()` references to the slot variables
+    // — that's an alias, not a literal. A literal value (e.g.,
+    // `--font-serif: "DM Serif Display"`) would clobber the inline <style>.
+    const css = findBundleDefaultCss();
+    if (css == null) {
+      console.warn('Skipping bundle drift test — dist/_astro/Default.*.css not found.');
+      return;
+    }
+    // Find any `--font-X: <value>` declaration in a `:root,:host{...}` block.
+    // Reject if the value is a literal (not a var() reference).
+    // NOTE: --font-weight-* is a Tailwind font-WEIGHT scale, not a
+    // font-family variable — excluded from this drift check.
+    const rootBlocks = css.match(/:root[^{]*\{([^}]*)\}/g) ?? [];
+    const offenders: string[] = [];
+    for (const block of rootBlocks) {
+      const fontDecls = block.matchAll(/--font-(title|heading|header|body|mono|serif|sans)\s*:\s*([^;}]+)/g);
+      for (const m of fontDecls) {
+        const name = m[1];
+        const value = m[2].trim();
+        if (value.startsWith('var(')) continue; // alias — OK
+        if (value === 'initial') continue; // explicit disable — OK
+        offenders.push(`--font-${name}: ${value}`);
+      }
+    }
+    expect(
+      offenders,
+      'bundle must not emit literal font-family values at :root (they clobber inline style)',
+    ).toEqual([]);
+  });
+
+  it('bundle aliases map to slot variables (no category-named sources)', () => {
+    const css = findBundleDefaultCss();
+    if (css == null) {
+      console.warn('Skipping bundle drift test — dist/_astro/Default.*.css not found.');
+      return;
+    }
+    // Verify the alias wiring is in place: --font-serif → --font-heading,
+    // --font-sans → --font-body. These ensure Tailwind's default utility
+    // names still work in templates that haven't migrated to slot names.
+    expect(css).toMatch(/--font-serif:\s*var\(--font-heading\)/);
+    expect(css).toMatch(/--font-sans:\s*var\(--font-body\)/);
+  });
+});

package/src/components/ConceptDetail.vue

@@ -117,9 +117,14 @@ const conceptSources = computed(() => props.concept?.sources ?? []);
 const conceptTags = computed(() => props.concept?.tags ?? []);
 
 const factory = getFactory();
-const { ensureBibLoaded, bibResolver, nonVerbalRefResolver } = useRenderOptions(() => props.registerId);
+const { ready: bibReady, ensureBibLoaded, bibResolver, citeResolver, nonVerbalRefResolver } = useRenderOptions(
+  () => props.registerId,
+  () => props.concept?.sources,
+);
 
-const renderOpts = computed<RenderOptions>(() => ({
+const renderOpts = computed<RenderOptions>(() => {
+  bibReady.value;
+  return {
   xrefResolver: (uri, term) => {
     const resolution = factory.resolve(uri, props.registerId);
     if (resolution.type === 'internal') {
@@ -139,8 +144,10 @@ const renderOpts = computed<RenderOptions>(() => ({
     return `<a href="#" class="xref-link" data-register="${escapeAttr(props.registerId)}" data-concept="${escapeAttr(resolvedId)}">${escapeAttr(term)}</a>`;
   },
   bibResolver,
+  citeResolver,
   nonVerbalRefResolver,
-}));
+};
+});
 
 watch(() => props.registerId, () => { ensureBibLoaded(); }, { immediate: true });
 
@@ -152,7 +159,7 @@ const structuralEntityRefs = useConceptEntities(
 useNonVerbalCrossRef();
 
 function handleContentClick(e: MouseEvent) {
-  const target = (e.target as HTMLElement).closest('.xref-link') as HTMLElement | null;
+  const target = (e.target as HTMLElement).closest('.xref-link, .cite-link') as HTMLElement | null;
   if (!target) return;
   e.preventDefault();
   const registerId = target.dataset.register;

package/src/composables/use-render-options.ts

@@ -1,11 +1,34 @@
-import { ref } from 'vue';
-import type { RenderOptions, BibResolver, NonVerbalRefResolver } from '../utils/content-renderer';
+/**
+ * Render-options composable — builds resolvers for the content renderer.
+ *
+ * The citeResolver is the load-bearing addition: it connects inline
+ * {{cite:sourceId}} mentions to the existing ReferenceResolver cascade
+ * (factory.resolver.resolveCite). This closes the data/deployment
+ * boundary: the data author writes {{cite:iev_702-02-07}}, the resolver
+ * walks the deployment's sourceRefs → routing → link cascade, and the
+ * renderer emits the correct HTML based on classification.
+ */
+import { ref, type Ref } from 'vue';
+import type { RenderOptions, BibResolver, CiteResolver, NonVerbalRefResolver } from '../utils/content-renderer';
 import type { NonVerbalKind } from '../adapters/non-verbal/types';
 import { getFactory } from '../adapters/factory';
 import { anchorId } from '../utils/non-verbal-anchor';
-import { escapeAttr } from '../utils/escape';
+import { escapeAttr, escapeHtml } from '../utils/escape';
 
-export function useRenderOptions(registerId: () => string) {
+/** Minimal shape of a ConceptSource that citeResolver needs. */
+interface ConceptSourceLike {
+  id?: string | null;
+  origin?: {
+    ref?: { source?: string | null; id?: string | null; version?: string | null } | null;
+    locality?: { type?: string | null; reference_from?: string | null; referenceTo?: string | null; reference_to?: string | null; referenceFrom?: string | null } | null;
+    link?: string | null;
+  } | null;
+}
+
+export function useRenderOptions(
+  registerId: () => string,
+  getSources?: () => readonly ConceptSourceLike[] | undefined,
+) {
   const ready = ref(false);
 
   async function ensureBibLoaded() {
@@ -19,28 +42,80 @@ export function useRenderOptions(registerId: () => string) {
     const id = registerId();
     const entry = id ? getFactory().bibliography(id).findById(refId) : null;
     if (!entry) {
-      return `<span class="bib-ref">${escapeAttr(title)}</span>`;
+      return `<span class="bib-ref">${escapeHtml(title)}</span>`;
     }
     const display = title || entry.reference || refId;
     if (entry.link) {
-      return `<a href="${escapeAttr(entry.link)}" target="_blank" rel="noopener" class="bib-link" title="${escapeAttr(entry.title ?? '')}">${escapeAttr(display)}</a>`;
+      return `<a href="${escapeAttr(entry.link)}" target="_blank" rel="noopener" class="bib-link" title="${escapeAttr(entry.reference ?? '')}">${escapeHtml(display)}</a>`;
+    }
+    return `<span class="bib-ref" title="${escapeAttr(entry.reference ?? '')}">${escapeHtml(display)}</span>`;
+  };
+
+  /**
+   * citeResolver — the canonical path for {{cite:sourceId}} mentions.
+   *
+   * Looks up the concept's own sources[] for a matching id, then
+   * delegates to ReferenceResolver.resolveCite() which walks the
+   * deployment's cascade (sourceRefs → routing → link → unresolved).
+   */
+  const citeResolver: CiteResolver = (key, label) => {
+    const rid = registerId();
+    const sources = getSources?.();
+    if (!sources || !rid) {
+      return `<span class="cite-ref">${escapeHtml(label ?? key)}</span>`;
+    }
+
+    const source = sources.find(s => s.id === key);
+    if (!source?.origin) {
+      return `<span class="cite-unresolved">${escapeHtml(label ?? key)}</span>`;
+    }
+
+    const factory = getFactory();
+    const resolution = factory.resolver.resolveCite(source.origin, rid);
+    const refId = source.origin.ref?.id ?? key;
+    const refSource = source.origin.ref?.source ?? '';
+    const display = label ?? refId;
+
+    switch (resolution.classification) {
+      case 'internal-citation': {
+        if (!resolution.resolved) break;
+        const { registerId: targetReg, conceptId } = resolution.resolved;
+        const isCross = targetReg !== rid;
+        const crossBadge = isCross ? '<span class="text-[9px] opacity-60">↗</span>' : '';
+        return `<a href="#" class="cite-link" data-register="${escapeAttr(targetReg)}" data-concept="${escapeAttr(conceptId)}">${escapeHtml(display)} ${crossBadge}</a>`;
+      }
+      case 'self-contained-citation': {
+        const link = source.origin.link;
+        if (link) {
+          return `<a href="${escapeAttr(link)}" target="_blank" rel="noopener" class="cite-link cite-external">${escapeHtml(refSource || display)} <span class="text-[9px] opacity-60">↗</span></a>`;
+        }
+        return `<span class="cite-ref">${escapeHtml(refSource || display)}</span>`;
+      }
+      case 'external-citation': {
+        const link = source.origin.link;
+        if (link) {
+          return `<a href="${escapeAttr(link)}" target="_blank" rel="noopener" class="cite-link cite-external">${escapeHtml(refSource || display)} <span class="text-[9px] opacity-60">↗</span></a>`;
+        }
+        return `<span class="cite-ref">${escapeHtml(refSource || display)}</span>`;
+      }
     }
-    return `<span class="bib-ref" title="${escapeAttr(entry.title ?? '')}">${escapeAttr(display)}</span>`;
+
+    return `<span class="cite-unresolved">${escapeHtml(display)}</span>`;
   };
 
   const nonVerbalRefResolver: NonVerbalRefResolver = (kind: NonVerbalKind, entityId, display) => {
     const id = registerId();
     if (!id) {
       const label = display ?? entityId;
-      return `<span class="nv-ref nv-ref--${kind}">${escapeAttr(label)}</span>`;
+      return `<span class="nv-ref nv-ref--${kind}">${escapeHtml(label)}</span>`;
     }
     const href = `#${anchorId(kind, id, entityId)}`;
     const label = display ?? defaultLabelForKind(kind, entityId);
     const cls = `nv-ref nv-ref--${kind}`;
-    return `<a href="${href}" class="${cls}" data-nv-kind="${escapeAttr(kind)}" data-nv-dataset="${escapeAttr(id)}" data-nv-entity="${escapeAttr(entityId)}">${escapeAttr(label)}</a>`;
+    return `<a href="${href}" class="${cls}" data-nv-kind="${escapeAttr(kind)}" data-nv-dataset="${escapeAttr(id)}" data-nv-entity="${escapeAttr(entityId)}">${escapeHtml(label)}</a>`;
   };
 
-  return { ready, ensureBibLoaded, bibResolver, nonVerbalRefResolver };
+  return { ready, ensureBibLoaded, bibResolver, citeResolver, nonVerbalRefResolver };
 }
 
 function defaultLabelForKind(kind: NonVerbalKind, entityId: string): string {
@@ -50,3 +125,6 @@ function defaultLabelForKind(kind: NonVerbalKind, entityId: string): string {
     case 'formula': return `Formula ${entityId}`;
   }
 }
+
+/** Ensure `ready` is tracked as a Ref for consumers that read `.value`. */
+export type RenderOptionsReady = Ref<boolean>;

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

@@ -3,7 +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';
+import { buildFontVariables, type BrandingFontsLike } from '../utils/font-variables';
 
 export interface RuntimeSiteConfig {
   id: string;
@@ -99,25 +99,20 @@ function applyBranding(config: RuntimeSiteConfig) {
     root.style.setProperty('--brand-dark', b.darkColor);
   }
 
-  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', 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);
+  if (b.fonts && (b.fonts.title || b.fonts.heading || b.fonts.header || b.fonts.body || b.fonts.mono)) {
+    // Load declared Google Fonts first so the brand stack resolves
+    // without flashing the fallback.
+    if (b.fonts.title) loadFont(b.fonts.title);
+    const headingFont = b.fonts.heading ?? b.fonts.header;
+    if (headingFont) loadFont(headingFont);
+    if (b.fonts.body) loadFont(b.fonts.body);
+    if (b.fonts.mono) loadFont(b.fonts.mono);
+
+    // Single SSOT — same shape as Default.astro's inline <style>.
+    const vars = buildFontVariables(b.fonts as BrandingFontsLike);
+    for (const [k, v] of Object.entries(vars)) {
+      root.style.setProperty(k, v);
+    }
   }
 }
 

package/src/layouts/Default.astro

@@ -2,12 +2,8 @@
 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 { type FontConfigLike } from '../utils/font-stack';
+import { renderFontVariablesInline } from '../utils/font-variables';
 import { resolveFaviconBase } from '../utils/favicon-base';
 import { buildFaviconLinks, renderFaviconLinkTag } from '../utils/favicon-links';
 
@@ -44,13 +40,11 @@ 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';
 
-// 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;
+// Single source of truth for the inline font-variable block.
+// renderFontVariablesInline() is shared with use-site-config.ts so the
+// build-time SSG and runtime override paths can never drift.
+// See src/utils/font-variables.ts for the contract + regression tests.
+const fontVarsCss = renderFontVariablesInline(brandingFonts);
 
 // Favicon configuration (issues #173, #177, and the data-driven refactor).
 //
@@ -137,7 +131,7 @@ const faviconLinks = buildFaviconLinks({
     <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-title:${fontTitle};--font-heading:${fontHeading};--font-header:${fontHeading};--font-body:${fontBody};--font-mono:${fontMono}}</style>`} />
+    <Fragment set:html={`<style>${fontVarsCss}</style>`} />
     <script is:inline>
       (function() {
         const c = document.cookie.split(';').map(s => s.trim()).find(s => s.startsWith('theme='));

package/src/styles/tailwind.css

@@ -38,9 +38,19 @@
   --color-group-family: #6366f1;
   --color-group-collection: #0891b2;
 
-  --font-serif: "DM Serif Display", Georgia, serif;
-  --font-sans: "DM Sans", system-ui, sans-serif;
-  --font-mono: "JetBrains Mono", monospace;
+  /* Tailwind font utilities. Defined as `var()` references to the slot
+     variables so the utilities exist (templates still reference
+     `.font-serif`, `.font-sans`, `.font-mono`) but the bundle's
+     `:root, :host { ... }` block emits ALIASES, not literal values —
+     meaning it cannot clobber whatever the inline `<style>` sets.
+
+     The inline style (Default.astro) emits ONLY slot-named variables
+     (--font-title, --font-heading, --font-body, --font-mono) via
+     buildFontVariables() in src/utils/font-variables.ts. The aliases
+     here resolve to those slot variables through the cascade. */
+  --font-serif: var(--font-heading);
+  --font-sans: var(--font-body);
+  --font-mono: var(--font-mono);
 }
 
 :root {
@@ -60,10 +70,6 @@
   --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;
   --gold-accent-deep: #8C6A3A;
 }
@@ -75,11 +81,23 @@
     -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);
+  /* Slot-named utilities — the canonical API. Each maps to a CSS variable
+     emitted by buildFontVariables() in src/utils/font-variables.ts. */
+  .font-title   { font-family: var(--font-title); }
+  .font-heading { font-family: var(--font-heading); }
+  .font-body    { font-family: var(--font-body); }
+  /* Backward-compat aliases. Existing templates use `.font-serif` and
+     `.font-sans`; map them to slot variables so brand fonts propagate
+     without forcing every consumer to rewrite markup. These do NOT
+     bake in serif↔heading / sans↔body — the slot variable holds
+     whatever category the consumer declared. */
+  .font-serif   { font-family: var(--font-heading); }
+  .font-sans    { font-family: var(--font-body); }
+  /* Legacy alias for `.font-header` (renamed to `.font-heading`). */
+  .font-header  { font-family: var(--font-heading); }
+  /* Default heading typography — applies unless overridden by a slot class. */
+  h1, h2, h3, h4, h5, h6 {
+    font-family: var(--font-heading);
   }
   code, pre, .font-mono {
     font-family: var(--font-mono);

package/src/utils/content-renderer.ts

@@ -10,7 +10,7 @@
  *   - {{table:id}} / {{table:id, display}}  → nonVerbalRefResolver (table)
  *   - {{formula:id}} / {{formula:id, display}}  → nonVerbalRefResolver (formula)
  *   - {{cite:key[, render term]}}  → citeResolver
- *   - {{urn:...[, render term]}}  → urnRefResolver / xrefResolver
+ *   - {{urn:...[, render term]}}  → xrefResolver
  *   - {{concept_id[, render term]}}  → conceptRefResolver
  *   - {{designation[, render term]}}  → conceptRefResolver
  *
@@ -28,7 +28,6 @@ export type XrefResolver = (uri: string, term: string) => string;
 export type BibResolver = (refId: string, title: string) => string;
 export type CiteResolver = (key: string, label: string | null) => string;
 export type ConceptRefResolver = (conceptId: string, term: string) => string;
-export type UrnRefResolver = (uri: string, term: string) => string;
 export type NonVerbalRefResolver = (kind: NonVerbalKind, entityId: string, display?: string) => string;
 
 export interface RenderOptions {
@@ -36,7 +35,6 @@ export interface RenderOptions {
   bibResolver?: BibResolver;
   conceptRefResolver?: ConceptRefResolver;
   citeResolver?: CiteResolver;
-  urnRefResolver?: UrnRefResolver;
   nonVerbalRefResolver?: NonVerbalRefResolver;
 }
 
@@ -209,7 +207,6 @@ function resolveMentions(text: string, opts: RenderOptions): string {
       case 'urn-ref': {
         const uri = p.uri as string;
         const label = (p.label as string) ?? uri;
-        if (opts.urnRefResolver) return opts.urnRefResolver(uri, label);
         if (opts.xrefResolver) return opts.xrefResolver(uri, label);
         return escapeHtml(label);
       }

package/src/utils/font-variables.ts

@@ -0,0 +1,97 @@
+/**
+ * Single source of truth for branding-driven CSS font variables.
+ *
+ * WHY THIS EXISTS
+ *
+ * Pre-refactor (0.7.106–0.7.111), font variables came from FOUR places:
+ *   1. `src/utils/font-stack.ts` (DEFAULT_FONTS)
+ *   2. `src/styles/tailwind.css` `:root { ... }` block
+ *   3. `src/styles/tailwind.css` `@theme { ... }` block (generated
+ *      `:root, :host { ... }` in the CSS bundle)
+ *   4. `tailwind.config.js` `fontFamily.*` utility fallback strings
+ *
+ * The @theme block was the load-bearing bug. Its `:root, :host { ... }`
+ * declaration in the CSS bundle loaded AFTER `Default.astro`'s inline
+ * `<style>`, so by CSS cascade (equal specificity, later source order
+ * wins) the brand values were silently clobbered for `--font-serif`,
+ * `--font-sans`, `--font-mono`.
+ *
+ * Post-refactor: this module is the ONLY place that decides which CSS
+ * font variables exist and what their values are. Both
+ * `Default.astro` (build-time SSG inline `<style>`) and
+ * `use-site-config.ts` (runtime `root.style.setProperty` overrides)
+ * call `buildFontVariables()` and emit the same shape.
+ *
+ * DESIGN
+ *
+ * Slot-named variables only. No category-named variables
+ * (`--font-serif`, `--font-sans`) — those bake in "serif↔heading,
+ * sans↔body" assumptions that break when a consumer picks a different
+ * category for a slot. The Tailwind utilities `.font-serif` and
+ * `.font-sans` are kept as backward-compat aliases defined in
+ * `@layer base`, mapped to slot variables.
+ *
+ * Output keys:
+ *   --font-title   — most prominent display text
+ *   --font-heading — h2–h6 section headings
+ *   --font-body    — paragraph text
+ *   --font-mono    — code, pre, kbd
+ */
+
+import { fontStack, DEFAULT_FONTS, DEFAULT_CATEGORY, type FontConfigLike } from './font-stack';
+
+/** Canonical slot names. Any CSS variable not in this list is a bug. */
+export const FONT_SLOTS = ['title', 'heading', 'body', 'mono'] as const;
+export type FontSlot = (typeof FONT_SLOTS)[number];
+
+/** Branding fonts shape — accepts both `header` (legacy alias) and `heading`. */
+export interface BrandingFontsLike {
+  title?: FontConfigLike;
+  heading?: FontConfigLike;
+  /** @deprecated Legacy alias for `heading`. */
+  header?: FontConfigLike;
+  body?: FontConfigLike;
+  mono?: FontConfigLike;
+}
+
+/**
+ * Build the canonical `:root` CSS font-variable map from a branding
+ * config. Every variable the system relies on is present in the output
+ * — no need for fallback definitions elsewhere.
+ *
+ * Values are pre-formed CSS font-family stacks (e.g.
+ * `'Raleway', system-ui, sans-serif`). The caller is responsible for
+ * serializing into a CSS `:root { ... }` block.
+ *
+ * `header` (legacy alias) is read but not emitted as a separate
+ * variable. Its value flows into `--font-heading`. Consumers that
+ * still reference `--font-header` in their CSS get the heading value
+ * via the alias declaration in `@layer base` of tailwind.css.
+ */
+export function buildFontVariables(
+  fonts: BrandingFontsLike | null | undefined,
+): Record<`--font-${FontSlot}`, string> {
+  const f = fonts ?? {};
+  const heading = f.heading ?? f.header;
+  return {
+    '--font-title': fontStack(f.title, DEFAULT_CATEGORY.title) ?? DEFAULT_FONTS.title,
+    '--font-heading': fontStack(heading, DEFAULT_CATEGORY.heading) ?? DEFAULT_FONTS.heading,
+    '--font-body': fontStack(f.body, DEFAULT_CATEGORY.body) ?? DEFAULT_FONTS.body,
+    '--font-mono': fontStack(f.mono, DEFAULT_CATEGORY.mono) ?? DEFAULT_FONTS.mono,
+  };
+}
+
+/**
+ * Serialize the variable map to an inline `:root { ... }` CSS string,
+ * safe to drop into a `<style>` tag.
+ *
+ * Escapes nothing (font stacks come from a controlled source) but
+ * joins with proper CSS syntax. Use this from Default.astro.
+ */
+export function renderFontVariablesInline(
+  fonts: BrandingFontsLike | null | undefined,
+): string {
+  const vars = buildFontVariables(fonts);
+  const body = FONT_SLOTS.map(slot => `--font-${slot}:${vars[`--font-${slot}`]}`).join(';');
+  return `:root{${body}}`;
+}

package/tailwind.config.js

@@ -12,13 +12,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: ['var(--font-mono, "JetBrains Mono")', 'ui-monospace', 'monospace'],
-      },
+      // Font utilities are defined in src/styles/tailwind.css @layer base.
+      // They reference slot CSS variables (--font-title, --font-heading,
+      // --font-body, --font-mono) emitted by buildFontVariables() in
+      // src/utils/font-variables.ts. Configuring them here would create
+      // a second source of truth that can drift.
       colors: {
         ink: {
           DEFAULT: '#1a1b2e',
@@ -39,11 +37,6 @@ export default {
           raised: '#ffffff',
         },
       },
-      typography: {
-        serif: {
-          'font-family': 'var(--font-header, "DM Serif Display"), Georgia, serif',
-        },
-      },
     },
   },
   plugins: [],