@glossarist/concept-browser 0.7.44 → 0.7.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.44",
+  "version": "0.7.46",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
     "autoprefixer": "^10.4.21",
     "d3": "^7.9.0",
     "favicons": "^7.2.0",
-    "glossarist": "^0.3.7",
+    "glossarist": "^0.4.0",
     "js-yaml": "^4.1.0",
     "jszip": "^3.10.1",
     "pinia": "^2.3.1",

package/scripts/generate-data.mjs

@@ -4,6 +4,8 @@ import yaml from 'js-yaml';
 import { naturalSort, Register, parseMention } from 'glossarist';
 import { loadSiteConfig } from './load-site-config.mjs';
 import { getGroups } from './lib/concept-groups.mjs';
+import { consumeDatasetEntities } from './lib/build/non-verbal-consumer.mjs';
+import { copyImageAssets } from './lib/build/image-assets.mjs';
 const __dirname = path.dirname(new URL(import.meta.url).pathname);
 const ROOT = process.cwd();
 const PUBLIC = path.join(ROOT, 'public');
@@ -781,7 +783,7 @@ ${bodyEntries}
 `;
 }
 
-function processDataset(dir, register, opts) {
+async function processDataset(dir, register, opts) {
   const files = fs.readdirSync(dir).filter(f => f.endsWith('.yaml')).sort((a, b) => naturalSort(a.replace('.yaml', ''), b.replace('.yaml', '')));
 
   console.log(`Processing ${register}: ${files.length} files`);
@@ -1010,23 +1012,30 @@ function processDataset(dir, register, opts) {
   if (fs.existsSync(bibPath)) {
     const bibData = readYaml(bibPath);
     writeJson(path.join(DATA, register, 'bibliography.json'), bibData);
-    console.log(`  Copied bibliography (${Object.keys(bibData).length} entries)`);
+    const bibCount = Array.isArray(bibData?.bibliography) ? bibData.bibliography.length : 0;
+    console.log(`  Copied bibliography (${bibCount} entries)`);
   }
 
-  // Copy images/
+  // Copy images/ with magic-byte validation + manifest emission.
   const imagesSrcDir = path.join(sourceRoot, 'images');
   if (fs.existsSync(imagesSrcDir) && fs.statSync(imagesSrcDir).isDirectory()) {
     const imagesDestDir = path.join(DATA, register, 'images');
-    fs.mkdirSync(imagesDestDir, { recursive: true });
-    let imgCount = 0;
-    for (const file of fs.readdirSync(imagesSrcDir)) {
-      const src = path.join(imagesSrcDir, file);
-      if (fs.statSync(src).isFile()) {
-        fs.copyFileSync(src, path.join(imagesDestDir, file));
-        imgCount++;
-      }
+    const result = await copyImageAssets(imagesSrcDir, imagesDestDir);
+    console.log(`  Copied ${result.count} images (skipped ${result.skipped.length})`);
+    for (const w of result.skipped) {
+      console.warn(`    Warning: skipped image ${w}`);
+    }
+  }
+
+  // Consume non-verbal entities (figures/tables/formulas) — JSON-LD preferred,
+  // YAML fallback. Writes per-entity JSON + indexes.
+  const nvResult = await consumeDatasetEntities(sourceRoot, path.join(DATA, register));
+  const nvTotal = nvResult.figures + nvResult.tables + nvResult.formulas;
+  if (nvTotal > 0) {
+    console.log(`  Consumed ${nvResult.figures} figures, ${nvResult.tables} tables, ${nvResult.formulas} formulas`);
+    for (const w of nvResult.warnings) {
+      console.warn(`    Warning: ${w}`);
     }
-    console.log(`  Copied ${imgCount} images`);
   }
 
   console.log(`  Generated ${concepts.length} concepts, manifest, ${chunks.length} index chunks`);
@@ -1086,7 +1095,7 @@ for (let i = 0; i < config.datasets.length; i++) {
   // Resolve title: site-config override, then ref from register
   const resolvedTitle = ds.title || reg?.ref || ds.id;
 
-  counts[ds.id] = processDataset(dir, ds.id, {
+  counts[ds.id] = await processDataset(dir, ds.id, {
     title: resolvedTitle,
     description: resolvedDescription,
     owner: ds.owner || reg?.owner,

package/scripts/lib/build/image-assets.mjs

@@ -0,0 +1,190 @@
+/**
+ * Image asset pipeline — pure Node, no shell commands.
+ *
+ * Copies image bytes from the source directory to the runtime data
+ * directory, validates magic bytes for known formats, parses intrinsic
+ * dimensions for raster formats, and emits `images-manifest.json` with
+ * SHA-256 hashes + dimensions.
+ *
+ * If the source directory contains its own `manifest.json`, that file is
+ * reused as the SSOT (single source of truth) and only missing entries
+ * are computed. This lets glossarist-ruby ship a manifest if it wants to.
+ */
+
+import { createHash } from 'node:crypto';
+import { readFile, writeFile, mkdir, readdir, stat, copyFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/** @typedef {{ src: string, format: string, sha256: string, width?: number, height?: number, bytes: number }} ImageManifestEntry */
+
+export const SUPPORTED_FORMATS = new Set(['svg', 'png', 'jpg', 'jpeg', 'gif', 'webp', 'avif']);
+
+const MAGIC_BYTES = {
+  png:  [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A],
+  jpg:  [0xFF, 0xD8, 0xFF],
+  gif:  [0x47, 0x49, 0x46, 0x38],
+  webp: [0x52, 0x49, 0x46, 0x46], // "RIFF" — full match needs bytes 8-11 = "WEBP"
+};
+
+const FILENAME_RE = /^[a-z0-9._-]+$/i;
+
+/**
+ * Validate the file's magic bytes against its declared extension.
+ * Returns the canonical format (e.g. "jpg" for ".jpeg"), or null if
+ * validation fails.
+ *
+ * @param {Buffer} buf
+ * @param {string} ext
+ * @returns {string | null}
+ */
+export function detectFormat(buf, ext) {
+  const e = ext.toLowerCase();
+  if (e === 'svg') return buf.includes('<svg') || buf.includes('<SVG') ? 'svg' : null;
+  if (e === 'png' || e === 'jpg' || e === 'jpeg' || e === 'gif' || e === 'webp') {
+    const png = MAGIC_BYTES.png;
+    if (e === 'png' && buf.length >= png.length && png.every((b, i) => buf[i] === b)) return 'png';
+    const jpg = MAGIC_BYTES.jpg;
+    if ((e === 'jpg' || e === 'jpeg') && buf.length >= jpg.length && jpg.every((b, i) => buf[i] === b)) return 'jpg';
+    const gif = MAGIC_BYTES.gif;
+    if (e === 'gif' && buf.length >= gif.length && gif.every((b, i) => buf[i] === b)) return 'gif';
+    if (e === 'webp' && buf.length >= 12 && buf.toString('ascii', 0, 4) === 'RIFF' && buf.toString('ascii', 8, 12) === 'WEBP') return 'webp';
+  }
+  // Unknown formats (avif, etc.) — accept on trust; authors are responsible.
+  if (SUPPORTED_FORMATS.has(e)) return e;
+  return null;
+}
+
+/**
+ * Parse intrinsic dimensions for PNG/JPEG. Returns null for unknown formats.
+ * WebP/AVIF parsing is intentionally V1-light — authors declare via YAML.
+ *
+ * @param {Buffer} buf
+ * @param {string} format
+ * @returns {{ width?: number, height?: number }}
+ */
+export function readIntrinsicDimensions(buf, format) {
+  if (format === 'png' && buf.length >= 24) {
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+  }
+  if (format === 'jpg' || format === 'jpeg') {
+    return readJpegDimensions(buf);
+  }
+  return {};
+}
+
+function readJpegDimensions(buf) {
+  // Scan JPEG markers for SOFn (0xFFC0–0xFFCF, excluding 0xFFC4, 0xFFC8, 0xFFCC).
+  let i = 2;
+  while (i < buf.length - 9) {
+    if (buf[i] !== 0xFF) { i++; continue; }
+    const marker = buf[i + 1];
+    if (marker >= 0xC0 && marker <= 0xCF &&
+        marker !== 0xC4 && marker !== 0xC8 && marker !== 0xCC) {
+      const height = buf.readUInt16BE(i + 5);
+      const width = buf.readUInt16BE(i + 7);
+      return { width, height };
+    }
+    const segLen = buf.readUInt16BE(i + 2);
+    i += 2 + segLen;
+  }
+  return {};
+}
+
+/**
+ * Sanitize an image filename per the wire-format rule
+ * `[a-z0-9._-]+`. Returns the sanitized name (lowercased, with unsafe
+ * characters replaced by `-`).
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function sanitizeImageFilename(name) {
+  const lowered = name.toLowerCase();
+  const sanitized = lowered.replace(/[^a-z0-9._-]/g, '-').replace(/-+/g, '-');
+  return sanitized.replace(/^-+|-+$/g, '');
+}
+
+function sha256(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * Copy image assets from srcDir into destDir, validate, and emit
+ * images-manifest.json. Reuses upstream manifest if present.
+ *
+ * @param {string} srcDir   Absolute path to source images/
+ * @param {string} destDir  Absolute path to public/data/{ds}/images/
+ * @returns {Promise<{ count: number, manifest: Record<string, ImageManifestEntry>, skipped: string[] }>}
+ */
+export async function copyImageAssets(srcDir, destDir) {
+  await mkdir(destDir, { recursive: true });
+  const entries = await readdir(srcDir, { withFileTypes: true });
+
+  // Reuse upstream manifest if present (SSOT).
+  const upstreamManifestPath = path.join(srcDir, 'manifest.json');
+  let upstream = null;
+  try {
+    const st = await stat(upstreamManifestPath);
+    if (st.isFile()) {
+      upstream = JSON.parse(await readFile(upstreamManifestPath, 'utf8'));
+    }
+  } catch { /* no upstream manifest — compute fresh */ }
+
+  /** @type {Record<string, ImageManifestEntry>} */
+  const manifest = {};
+  const skipped = [];
+  let count = 0;
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (entry.name === 'manifest.json') continue;
+
+    const safeName = sanitizeImageFilename(entry.name);
+    if (!FILENAME_RE.test(safeName)) {
+      skipped.push(entry.name);
+      continue;
+    }
+    const ext = path.extname(safeName).slice(1);
+    if (!ext || !SUPPORTED_FORMATS.has(ext)) {
+      skipped.push(entry.name);
+      continue;
+    }
+
+    const src = path.join(srcDir, entry.name);
+    const dest = path.join(destDir, safeName);
+    const buf = await readFile(src);
+
+    const format = detectFormat(buf, ext);
+    if (!format) {
+      skipped.push(`${entry.name} (format mismatch)`);
+      continue;
+    }
+
+    await copyFile(src, dest);
+
+    /** @type {ImageManifestEntry} */
+    let entry_record;
+    if (upstream && upstream[safeName]) {
+      entry_record = { ...upstream[safeName], src: safeName, format };
+    } else {
+      const dims = readIntrinsicDimensions(buf, format);
+      entry_record = {
+        src: safeName,
+        format,
+        sha256: sha256(buf),
+        bytes: buf.length,
+        ...dims,
+      };
+    }
+    manifest[safeName] = entry_record;
+    count++;
+  }
+
+  await mkdir(destDir, { recursive: true });
+  await writeFile(
+    path.join(destDir, '..', 'images-manifest.json'),
+    JSON.stringify(manifest, null, 2),
+  );
+
+  return { count, manifest, skipped };
+}

package/scripts/lib/build/non-verbal-consumer.mjs

@@ -0,0 +1,221 @@
+/**
+ * Non-verbal entity consumer — reads source entities (JSON-LD preferred,
+ * YAML fallback) and writes per-entity JSON + indexes to public/data/{ds}/.
+ *
+ * Source layout (preferred — produced by `glossarist export`):
+ *   {sourceRoot}/figures/{id}.json
+ *   {sourceRoot}/tables/{id}.json
+ *   {sourceRoot}/formulas/{id}.json
+ *
+ * Fallback layout (raw glossarist YAML — converted minimally until
+ * glossarist-ruby publishes export support for these entities):
+ *   {sourceRoot}/figures/{id}.yaml
+ *   {sourceRoot}/tables/{id}.yaml
+ *   {sourceRoot}/formulas/{id}.yaml
+ *
+ * Output layout:
+ *   public/data/{ds}/figures/{id}.json
+ *   public/data/{ds}/tables/{id}.json
+ *   public/data/{ds}/formulas/{id}.json
+ *   public/data/{ds}/figures-index.json   { id: filename }
+ *   public/data/{ds}/tables-index.json
+ *   public/data/{ds}/formulas-index.json
+ */
+
+import { readFile, writeFile, mkdir, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import yaml from 'js-yaml';
+
+/** @typedef {'figure' | 'table' | 'formula'} NonVerbalKind */
+
+/** @type {Record<NonVerbalKind, { dir: string, type: string }>} */
+const KIND_META = {
+  figure:  { dir: 'figures',  type: 'Figure'  },
+  table:   { dir: 'tables',   type: 'Table'   },
+  formula: { dir: 'formulas', type: 'Formula' },
+};
+
+/**
+ * Convert a raw glossarist YAML entity to a JSON-LD-style document.
+ * This is a temporary consumer-side bridge until glossarist-ruby's
+ * `glossarist export` ships entity JSON-LD output natively.
+ *
+ * The output matches the wire format documented in TODO.figures/11-round-trip-spec.md.
+ *
+ * @param {Record<string, any>} yaml  Parsed YAML entity.
+ * @param {NonVerbalKind} kind
+ * @returns {Record<string, any>}     JSON-LD-style document.
+ */
+function yamlEntityToJsonLd(yaml, kind) {
+  const meta = KIND_META[kind];
+  const doc = {
+    '@type': `gl:${meta.type}`,
+    'gl:id': yaml.id,
+  };
+  if (yaml.identifier) doc['gl:identifier'] = yaml.identifier;
+  if (yaml.caption) doc['gl:caption'] = yaml.caption;
+  if (yaml.alt) doc['gl:altText'] = yaml.alt;
+  if (yaml.description) doc['gl:description'] = yaml.description;
+  if (Array.isArray(yaml.sources) && yaml.sources.length) {
+    doc['gl:source'] = yaml.sources.map(s => yamlSourceToJsonLd(s));
+  }
+
+  if (kind === 'figure') {
+    if (Array.isArray(yaml.images)) {
+      doc['gl:image'] = yaml.images.map(img => ({
+        'gl:src': img.src,
+        'gl:format': img.format,
+        ...(img.role ? { 'gl:role': img.role } : {}),
+        ...(img.width != null ? { 'gl:width': img.width } : {}),
+        ...(img.height != null ? { 'gl:height': img.height } : {}),
+        ...(img.scale != null ? { 'gl:scale': img.scale } : {}),
+      }));
+    }
+    if (Array.isArray(yaml.subfigures) && yaml.subfigures.length) {
+      doc['gl:subfigure'] = yaml.subfigures.map(sub => yamlEntityToJsonLd(sub, 'figure'));
+    }
+  } else if (kind === 'table') {
+    if (yaml.content) {
+      const c = { ...yaml.content };
+      if (c.type) {
+        c['gl:type'] = c.type;
+        delete c.type;
+      }
+      doc['gl:content'] = c;
+    }
+    if (yaml.format) doc['gl:format'] = yaml.format;
+  } else if (kind === 'formula') {
+    if (yaml.expression) doc['gl:expression'] = yaml.expression;
+    if (yaml.notation) doc['gl:notation'] = yaml.notation;
+  }
+
+  return doc;
+}
+
+function yamlSourceToJsonLd(s) {
+  const out = {};
+  if (s.id) out['gl:id'] = s.id;
+  if (s.type) out['gl:sourceType'] = s.type;
+  if (s.status) out['gl:sourceStatus'] = s.status;
+  if (s.modification) out['gl:modification'] = s.modification;
+  if (s.origin) {
+    const o = {};
+    if (s.origin.ref) {
+      o['gl:ref'] = typeof s.origin.ref === 'string'
+        ? s.origin.ref
+        : {
+            ...(s.origin.ref.source ? { 'gl:source': s.origin.ref.source } : {}),
+            ...(s.origin.ref.id ? { 'gl:id': s.origin.ref.id } : {}),
+            ...(s.origin.ref.version ? { 'gl:version': s.origin.ref.version } : {}),
+            ...(s.origin.ref.text ? { 'gl:text': s.origin.ref.text } : {}),
+          };
+    }
+    if (s.origin.locality) {
+      const l = s.origin.locality;
+      o['gl:locality'] = {
+        ...(l.type ? { 'gl:localityType': l.type } : {}),
+        ...(l.reference_from ? { 'gl:referenceFrom': l.reference_from } : {}),
+        ...(l.reference_to ? { 'gl:referenceTo': l.reference_to } : {}),
+      };
+    }
+    if (s.origin.link) o['gl:link'] = s.origin.link;
+    if (Object.keys(o).length) out['gl:origin'] = o;
+  }
+  return out;
+}
+
+/**
+ * Read entities of one kind from sourceDir. Tries JSON first, falls back to YAML.
+ *
+ * @param {string} sourceDir
+ * @param {NonVerbalKind} kind
+ * @returns {Promise<Array<{ id: string, doc: Record<string, any> }>>}
+ */
+async function readEntitiesForKind(sourceDir, kind) {
+  const meta = KIND_META[kind];
+  const dir = path.join(sourceDir, meta.dir);
+  let files;
+  try {
+    files = await readdir(dir);
+  } catch {
+    return [];
+  }
+
+  const out = [];
+  for (const file of files) {
+    const full = path.join(dir, file);
+    const st = await stat(full);
+    if (!st.isFile()) continue;
+    const ext = path.extname(file).toLowerCase();
+    const id = path.basename(file, ext);
+    if (ext === '.json') {
+      try {
+        const doc = JSON.parse(await readFile(full, 'utf8'));
+        out.push({ id, doc });
+      } catch (e) {
+        console.warn(`  Warning: failed to parse ${full}: ${e.message}`);
+      }
+    } else if (ext === '.yaml' || ext === '.yml') {
+      try {
+        const raw = yaml.load(await readFile(full, 'utf8'));
+        if (!raw || typeof raw !== 'object') continue;
+        out.push({ id, doc: yamlEntityToJsonLd(raw, kind) });
+      } catch (e) {
+        console.warn(`  Warning: failed to parse ${full}: ${e.message}`);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Consume non-verbal entities from sourceDir and write to public/data/{ds}/.
+ *
+ * @param {string} sourceRoot  Absolute path to the dataset source root.
+ * @param {string} destRoot    Absolute path to public/data/{ds}/.
+ * @returns {Promise<{ figures: number, tables: number, formulas: number, warnings: string[] }>}
+ */
+export async function consumeDatasetEntities(sourceRoot, destRoot) {
+  const counts = { figures: 0, tables: 0, formulas: 0 };
+  const warnings = [];
+
+  for (const kind of /** @type {NonVerbalKind[]} */ (['figure', 'table', 'formula'])) {
+    const meta = KIND_META[kind];
+    const entities = await readEntitiesForKind(sourceRoot, kind);
+    if (entities.length === 0) continue;
+
+    const outDir = path.join(destRoot, meta.dir);
+    await mkdir(outDir, { recursive: true });
+
+    const index = {};
+    for (const { id, doc } of entities) {
+      const docId = doc['gl:id'] ?? doc['gloss:id'] ?? id;
+      if (docId !== id) {
+        warnings.push(`${meta.dir}/${id}: gl:id (${docId}) does not match filename`);
+      }
+      const dest = path.join(outDir, `${id}.json`);
+      await writeFile(dest, JSON.stringify(doc, null, 2));
+      index[id] = `${meta.dir}/${id}.json`;
+
+      // Basic validation warnings — non-fatal, surface to authors.
+      if (!doc[`gl:${kind === 'figure' ? 'altText' : ''}`] && kind === 'figure') {
+        warnings.push(`${meta.dir}/${id}: missing gl:altText (accessibility)`);
+      }
+      if (!doc['gl:caption']) {
+        warnings.push(`${meta.dir}/${id}: missing gl:caption`);
+      }
+    }
+
+    const indexDest = path.join(destRoot, `${meta.dir}-index.json`);
+    await writeFile(indexDest, JSON.stringify(index, null, 2));
+
+    counts[meta.dir] = entities.length;
+  }
+
+  return {
+    figures: counts.figures,
+    tables: counts.tables,
+    formulas: counts.formulas,
+    warnings,
+  };
+}

package/src/__tests__/bibliography-adapter.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { BibliographyAdapter } from '../adapters/bibliography-adapter';
+
+function makeResponse(status: number, body: unknown): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  } as Response;
+}
+
+describe('BibliographyAdapter', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns null for findById before load', () => {
+    const a = new BibliographyAdapter('iso', {
+      basePath: '/',
+      fetcher: async () => makeResponse(200, { bibliography: [] }),
+    });
+    expect(a.findById('ref-1')).toBeNull();
+    expect(a.all()).toEqual([]);
+  });
+
+  it('loads bibliography once and deduplicates subsequent calls', async () => {
+    let calls = 0;
+    const fetcher = vi.fn(async () => {
+      calls++;
+      return makeResponse(200, {
+        bibliography: [
+          { id: 'ref-1', title: 'ISO Standard', type: 'misc' },
+        ],
+      });
+    });
+    const a = new BibliographyAdapter('iso', { basePath: '/', fetcher });
+    await a.load();
+    await a.load();
+    expect(calls).toBe(1);
+    expect(a.findById('ref-1')?.id).toBe('ref-1');
+  });
+
+  it('treats 404 as missing bibliography — no throw, findById returns null', async () => {
+    const fetcher = vi.fn(async () => makeResponse(404, {}));
+    const a = new BibliographyAdapter('iso', { basePath: '/', fetcher });
+    await expect(a.load()).resolves.toBeUndefined();
+    expect(a.findById('ref-1')).toBeNull();
+  });
+
+  it('swallows network errors — loaded becomes true to prevent retry storms', async () => {
+    const fetcher = vi.fn(async () => { throw new Error('boom'); });
+    const a = new BibliographyAdapter('iso', { basePath: '/', fetcher });
+    await a.load();
+    expect(a.all()).toEqual([]);
+    await a.load();
+    expect(fetcher).toHaveBeenCalledTimes(1);
+  });
+
+  it('clear() resets state so the next load() refetches', async () => {
+    let calls = 0;
+    const fetcher = vi.fn(async () => {
+      calls++;
+      return makeResponse(200, { bibliography: [{ id: 'x' }] });
+    });
+    const a = new BibliographyAdapter('iso', { basePath: '/', fetcher });
+    await a.load();
+    a.clear();
+    expect(a.findById('x')).toBeNull();
+    await a.load();
+    expect(calls).toBe(2);
+  });
+
+  it('builds URLs from basePath + datasetId', async () => {
+    const fetcher = vi.fn(async () => makeResponse(200, { bibliography: [] }));
+    const a = new BibliographyAdapter('isotc204', { basePath: '/cb/', fetcher });
+    await a.load();
+    expect(fetcher).toHaveBeenCalledWith('/cb/data/isotc204/bibliography.json');
+  });
+});

package/src/__tests__/content-renderer-nvr-mentions.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { renderContent } from '../utils/content-renderer';
+import type { RenderOptions } from '../utils/content-renderer';
+import type { NonVerbalKind } from '../adapters/non-verbal/types';
+
+type NvResolver = (kind: NonVerbalKind, id: string, display?: string) => string;
+
+function makeOpts(nonVerbalRefResolver?: NvResolver): RenderOptions {
+  return { nonVerbalRefResolver };
+}
+
+describe('content-renderer — non-verbal mentions', () => {
+  it('dispatches {{fig:id}} to nonVerbalRefResolver as figure', () => {
+    const calls: Array<[NonVerbalKind, string, string | undefined]> = [];
+    const resolver: NvResolver = (kind, id, display) => {
+      calls.push([kind, id, display]);
+      return `<a href="#figure-ds-${id}">${id}</a>`;
+    };
+    const out = renderContent('See {{fig:mixed-reflection}} in the diagram.', makeOpts(resolver));
+    expect(calls).toEqual([['figure', 'mixed-reflection', undefined]]);
+    expect(out).toContain('href="#figure-ds-mixed-reflection"');
+  });
+
+  it('dispatches {{table:id}} to nonVerbalRefResolver as table', () => {
+    const resolver: NvResolver = (kind) => `<a href="#${kind}-ds-x">x</a>`;
+    const out = renderContent('See {{table:wavelengths}}.', makeOpts(resolver));
+    expect(out).toContain('href="#table-ds-x"');
+  });
+
+  it('dispatches {{formula:id}} to nonVerbalRefResolver as formula', () => {
+    const resolver: NvResolver = (kind) => `<a href="#${kind}-ds-x">x</a>`;
+    const out = renderContent('Use {{formula:e-mc2}}.', makeOpts(resolver));
+    expect(out).toContain('href="#formula-ds-x"');
+  });
+
+  it('passes the display override as the third resolver arg', () => {
+    const calls: Array<[NonVerbalKind, string, string | undefined]> = [];
+    const resolver: NvResolver = (kind, id, display) => {
+      calls.push([kind, id, display]);
+      return '<span/>';
+    };
+    renderContent('{{fig:foo, Figure 3}}', makeOpts(resolver));
+    expect(calls[0]).toEqual(['figure', 'foo', 'Figure 3']);
+  });
+
+  it('falls back to a typed span when no resolver is configured', () => {
+    const out = renderContent('{{fig:foo}}', makeOpts(undefined));
+    expect(out).toContain('nv-ref nv-ref--figure');
+    expect(out).toContain('foo');
+  });
+
+  it('falls back to entityId as label when display override is absent and no resolver', () => {
+    const out = renderContent('{{table:wavelengths}}', makeOpts(undefined));
+    expect(out).toContain('wavelengths');
+    expect(out).toContain('nv-ref--table');
+  });
+});

package/src/__tests__/locale.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { pickLocaleText, pickLocaleMap } from '../utils/locale';
+
+describe('locale — fetchLocalizedString-backed resolution', () => {
+  it('returns the requested locale when present', () => {
+    const map = { eng: 'hello', fra: 'bonjour' };
+    expect(pickLocaleText(map, 'fra')).toBe('bonjour');
+  });
+
+  it('falls back through the chain when the requested locale is missing', () => {
+    const map = { eng: 'hello' };
+    expect(pickLocaleText(map, 'fra', ['eng'])).toBe('hello');
+  });
+
+  it('falls back to the first available locale when nothing in the chain matches', () => {
+    // Per the i18n-first invariant: never show nothing. If the user asks
+    // for a locale that is missing AND the chain misses too, return the
+    // first available locale's text rather than empty.
+    expect(pickLocaleText({ deu: 'hallo' }, 'fra', ['eng'])).toBe('hallo');
+  });
+
+  it('returns "" when the map is empty', () => {
+    expect(pickLocaleText({}, 'fra', ['eng'])).toBe('');
+  });
+
+  it('returns null from pickLocaleMap when the map is empty', () => {
+    expect(pickLocaleMap({}, 'fra', ['eng'])).toBeNull();
+  });
+
+  it('returns the resolved locale alongside the text', () => {
+    const r = pickLocaleMap({ eng: 'hi', fra: 'salut' }, 'fra', ['eng']);
+    expect(r).toEqual({ locale: 'fra', text: 'salut' });
+  });
+
+  it('returns null when map is undefined', () => {
+    expect(pickLocaleMap(undefined, 'eng')).toBeNull();
+    expect(pickLocaleText(undefined, 'eng')).toBe('');
+  });
+
+  it('passes the fallback chain explicitly (no internal fallback inside fetchLocalizedString)', () => {
+    // fetchLocalizedString is called with null fallback for each locale
+    // we try. The chain is owned by THIS module, not the leaf primitive.
+    const map = { eng: 'hello', fra: 'salut' };
+    expect(pickLocaleText(map, 'deu', ['fra', 'eng'])).toBe('salut');
+  });
+});