@glossarist/concept-browser 0.7.43 → 0.7.45

package/cli/index.mjs

@@ -20,7 +20,7 @@
  */
 
 import { loadSiteConfig } from '../scripts/load-site-config.mjs';
-import { execSync } from 'child_process';
+import { existsSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -166,22 +166,21 @@ Environment:
       }
     }
 
-    // Run vite build using the package's vite.config.ts
+    // Run vite build using the package's vite.config.ts via programmatic API
     console.log(`\n=== BUILD SPA ===\n`);
     const viteConfig = resolve(pkgRoot, 'vite.config.ts');
-    const viteBin = [resolve(pkgRoot, 'node_modules', '.bin', 'vite'), 'vite'].find(p => {
-      try { execSync(`${p} --version`, { stdio: 'pipe' }); return true; } catch { return false; }
-    });
-    execSync(`${viteBin} build --config ${viteConfig}`, {
-      stdio: 'inherit',
-      env: { ...process.env },
+    const { build: viteBuild } = await import('vite');
+    await viteBuild({
+      configFile: viteConfig,
+      root: pkgRoot,
+      mode: 'production',
     });
 
-    // Run postbuild (404 page)
-    try {
-      const postbuild = resolve(pkgRoot, 'scripts', 'generate-404.js');
-      execSync(`node ${postbuild}`, { stdio: 'inherit' });
-    } catch {}
+    // Run postbuild (404 page) via dynamic import
+    const postbuild = resolve(pkgRoot, 'scripts', 'generate-404.js');
+    if (existsSync(postbuild)) {
+      await import(`file://${postbuild}`);
+    }
 
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.43",
+  "version": "0.7.45",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {
@@ -25,8 +25,9 @@
     "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",
     "postcss": "^8.5.3",
     "sharp": "^0.34.5",

package/scripts/__tests__/fetch-datasets.test.mjs

@@ -0,0 +1,105 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { assertLocalPathSafe } from '../lib/local-path-safety.mjs';
+
+function makeTmpTree() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cb-fetch-'));
+  const datasetsDir = path.join(root, '.datasets');
+  const sourceDir = path.join(root, 'source-data');
+  fs.mkdirSync(datasetsDir);
+  fs.mkdirSync(path.join(sourceDir, 'concepts'), { recursive: true });
+  fs.writeFileSync(path.join(sourceDir, 'concepts', 'a.yaml'), 'termid: 1\n');
+  return { root, datasetsDir, sourceDir };
+}
+
+describe('assertLocalPathSafe', () => {
+  let tree;
+
+  beforeEach(() => { tree = makeTmpTree(); });
+  afterEach(() => {
+    fs.rmSync(tree.root, { recursive: true, force: true });
+  });
+
+  it('returns resolved path for a safe external location', () => {
+    const resolved = assertLocalPathSafe('foo', tree.sourceDir, {
+      root: tree.root,
+      datasetsDir: tree.datasetsDir,
+    });
+    // Returns the realpath (symlinks resolved); on macOS tmpdir resolves
+    // /var → /private/var, so compare against realpath, not path.resolve.
+    expect(resolved).toBe(fs.realpathSync(path.resolve(tree.root, tree.sourceDir)));
+  });
+
+  it('throws when localPath does not exist', () => {
+    expect(() =>
+      assertLocalPathSafe('foo', path.join(tree.root, 'nope'), {
+        root: tree.root,
+        datasetsDir: tree.datasetsDir,
+      })
+    ).toThrow(/does not exist/);
+  });
+
+  it('throws when localPath equals .datasets/<id>', () => {
+    const staged = path.join(tree.datasetsDir, 'foo');
+    fs.mkdirSync(staged, { recursive: true });
+    expect(() =>
+      assertLocalPathSafe('foo', staged, {
+        root: tree.root,
+        datasetsDir: tree.datasetsDir,
+      })
+    ).toThrow(/same physical location/);
+  });
+
+  it('throws when localPath is nested inside .datasets/<id>', () => {
+    const staged = path.join(tree.datasetsDir, 'foo');
+    fs.mkdirSync(path.join(staged, 'subdir'), { recursive: true });
+    expect(() =>
+      assertLocalPathSafe('foo', path.join(staged, 'subdir'), {
+        root: tree.root,
+        datasetsDir: tree.datasetsDir,
+      })
+    ).toThrow(/nested inside/);
+  });
+
+  it('throws when localPath contains .datasets/<id> (parent-of-staging hazard)', () => {
+    // localPath = root itself, datasetsDir = root/.datasets — staging ops
+    // (rm -rf .datasets/<id>) would touch files inside localPath.
+    expect(() =>
+      assertLocalPathSafe('foo', tree.root, {
+        root: tree.root,
+        datasetsDir: tree.datasetsDir,
+      })
+    ).toThrow(/contains .datasets/);
+  });
+
+  it('throws when localPath is a symlink to .datasets/<id> (the reported bug)', () => {
+    const staged = path.join(tree.datasetsDir, 'foo');
+    fs.mkdirSync(staged, { recursive: true });
+    const symlinkPath = path.join(tree.root, 'evil-link');
+    fs.symlinkSync(staged, symlinkPath);
+    expect(() =>
+      assertLocalPathSafe('foo', symlinkPath, {
+        root: tree.root,
+        datasetsDir: tree.datasetsDir,
+      })
+    ).toThrow(/same physical location/);
+  });
+
+  it('does NOT modify the source directory (regression for data-loss bug)', () => {
+    const sentinel = path.join(tree.sourceDir, 'concepts', 'SENTINEL.yaml');
+    fs.writeFileSync(sentinel, 'termid: sentinel\n');
+    const beforeMtime = fs.statSync(sentinel).mtimeMs;
+
+    assertLocalPathSafe('foo', tree.sourceDir, {
+      root: tree.root,
+      datasetsDir: tree.datasetsDir,
+    });
+
+    // Source directory must be completely untouched after the safety check.
+    expect(fs.existsSync(sentinel)).toBe(true);
+    expect(fs.statSync(sentinel).mtimeMs).toBe(beforeMtime);
+    expect(fs.readdirSync(path.join(tree.sourceDir, 'concepts'))).toContain('SENTINEL.yaml');
+  });
+});

package/scripts/fetch-datasets.mjs

@@ -1,23 +1,26 @@
 #!/usr/bin/env node
 /**
- * fetch-datasets.mjs — Load datasets from .gcr files or clone source repos.
+ * fetch-datasets.mjs — Load datasets from .gcr files, local paths, or git repos.
  *
  * Reads site config (via load-site-config.mjs), for each dataset:
  *   1. If .gcr/{id}.gcr exists, extract to .datasets/{id}/
  *   2. Else download from gcrPackage URL and extract
- *   3. Else clone/update source repo into .datasets/{id}/
+ *   3. Else if localPath is set, use it in-place (NO copy, NO staging)
+ *   4. Else clone/update source repo into .datasets/{id}/
  *
  * After fetching, validates that all GCR dependencies are satisfiable
  * (either provided locally or routed externally).
  *
- * Supports localPath field in dataset config for local paths.
- * Supports GITHUB_TOKEN for private repos.
+ * No shell commands. All file ops use Node fs; ZIP uses JSZip; git uses
+ * execFileSync with array args (no shell interpolation).
  */
 import fs from 'fs';
 import path from 'path';
+import JSZip from 'jszip';
 import { loadGcr } from 'glossarist';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { loadSiteConfig } from './load-site-config.mjs';
+import { assertLocalPathSafe } from './lib/local-path-safety.mjs';
 
 const ROOT = process.cwd();
 const DATASETS_DIR = path.join(ROOT, '.datasets');
@@ -39,23 +42,29 @@ async function downloadGcr(url, destPath) {
   console.log(`  Saved to ${destPath} (${(buf.length / 1024).toFixed(0)} KB)`);
 }
 
-// --- GCR extraction ---
-function extractGcr(gcrPath, targetDir) {
-  if (fs.existsSync(targetDir)) {
-    fs.rmSync(targetDir, { recursive: true, force: true });
+// --- GCR extraction (pure JSZip; no shell, cross-platform) ---
+async function extractGcr(gcrPath, targetDir) {
+  const targetAbs = path.resolve(targetDir);
+  if (fs.existsSync(targetAbs)) {
+    fs.rmSync(targetAbs, { recursive: true, force: true });
   }
-  fs.mkdirSync(targetDir, { recursive: true });
-
-  try {
-    execSync(`unzip -o -q "${gcrPath}" -d "${targetDir}"`, { stdio: 'pipe' });
-  } catch {
-    try {
-      execSync(`python3 -c "import zipfile; zipfile.ZipFile('${gcrPath}').extractall('${targetDir}')"`, { stdio: 'pipe' });
-    } catch (e2) {
-      throw new Error(`Failed to extract ${gcrPath}`);
+  fs.mkdirSync(targetAbs, { recursive: true });
+
+  const buf = fs.readFileSync(gcrPath);
+  const zip = await JSZip.loadAsync(buf);
+  const entries = Object.values(zip.files);
+  for (const entry of entries) {
+    if (entry.dir) continue;
+    // zip-slip guard: refuse entries that escape targetDir
+    const dest = path.resolve(targetAbs, entry.name);
+    if (dest !== targetAbs && !dest.startsWith(targetAbs + path.sep)) {
+      throw new Error(`Refusing to extract entry outside target dir: ${entry.name}`);
     }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const content = await entry.async('nodebuffer');
+    fs.writeFileSync(dest, content);
   }
-  console.log(`  Extracted to ${targetDir}`);
+  console.log(`  Extracted to ${targetAbs}`);
 }
 
 // --- Read GCR metadata from ZIP without extraction ---
@@ -96,7 +105,7 @@ function validateDependencies(config, gcrMetadata) {
   return errors;
 }
 
-// --- Git operations ---
+// --- Git operations (execFileSync with array args — no shell) ---
 function cloneOrUpdate(sourceRepo, targetDir) {
   const env = { ...process.env };
   let repoUrl = sourceRepo;
@@ -104,24 +113,28 @@ function cloneOrUpdate(sourceRepo, targetDir) {
     repoUrl = sourceRepo.replace('https://', `https://x-access-token:${env.GITHUB_TOKEN}@`);
   }
 
-  if (fs.existsSync(path.join(targetDir, '.git'))) {
+  const targetAbs = path.resolve(targetDir);
+
+  if (fs.existsSync(path.join(targetAbs, '.git'))) {
     console.log(`  Updating existing clone...`);
     try {
-      execSync('git fetch origin', { cwd: targetDir, stdio: 'pipe', env });
-      execSync('git reset --hard origin/HEAD', { cwd: targetDir, stdio: 'pipe', env });
-      execSync('git clean -fd', { cwd: targetDir, stdio: 'pipe', env });
+      execFileSync('git', ['fetch', 'origin'], { cwd: targetAbs, stdio: 'pipe', env });
+      execFileSync('git', ['reset', '--hard', 'origin/HEAD'], { cwd: targetAbs, stdio: 'pipe', env });
+      execFileSync('git', ['clean', '-fd'], { cwd: targetAbs, stdio: 'pipe', env });
     } catch {
       console.warn(`  git update failed, re-cloning`);
-      fs.rmSync(targetDir, { recursive: true, force: true });
-      execSync(`git clone --depth 1 "${repoUrl}" "${targetDir}"`, { stdio: 'pipe', env });
+      fs.rmSync(targetAbs, { recursive: true, force: true });
+      execFileSync('git', ['clone', '--depth', '1', repoUrl, targetAbs], { stdio: 'pipe', env });
     }
   } else {
-    fs.mkdirSync(targetDir, { recursive: true });
+    fs.mkdirSync(targetAbs, { recursive: true });
     console.log(`  Cloning ${sourceRepo}...`);
-    execSync(`git clone --depth 1 "${repoUrl}" "${targetDir}"`, { stdio: 'pipe', env });
+    execFileSync('git', ['clone', '--depth', '1', repoUrl, targetAbs], { stdio: 'pipe', env });
   }
 }
 
+// --- localPath safety check: see scripts/lib/local-path-safety.mjs ---
+
 // --- Main ---
 console.log('Fetching glossarist datasets...\n');
 
@@ -137,7 +150,7 @@ for (const ds of config.datasets) {
   try {
     if (fs.existsSync(gcrPath)) {
       console.log(`  Using local .gcr/${ds.id}.gcr`);
-      extractGcr(gcrPath, targetDir);
+      await extractGcr(gcrPath, targetDir);
     } else if (ds.gcrPackage) {
       console.log(`  Using GCR package: ${ds.gcrPackage}`);
       try {
@@ -148,29 +161,18 @@ for (const ds of config.datasets) {
         console.log();
         continue;
       }
-      extractGcr(gcrPath, targetDir);
+      await extractGcr(gcrPath, targetDir);
+    } else if (ds.localPath) {
+      // localPath means "data is here, use in-place." No copy, no staging.
+      // generate-data.mjs reads from localPath directly via datasetDir(ds).
+      const localResolved = assertLocalPathSafe(ds.id, ds.localPath);
+      console.log(`  Using localPath in-place: ${localResolved}`);
+    } else if (ds.sourceRepo) {
+      cloneOrUpdate(ds.sourceRepo, targetDir);
     } else {
-      const envOverride = ds.localPath;
-      if (envOverride) {
-        console.log(`  Using local path: ${envOverride}`);
-        if (!fs.existsSync(targetDir)) fs.mkdirSync(targetDir, { recursive: true });
-        const localConcepts = path.join(envOverride, 'concepts');
-        const targetConcepts = path.join(targetDir, 'concepts');
-        if (fs.existsSync(localConcepts)) {
-          if (fs.existsSync(targetConcepts)) fs.rmSync(targetConcepts, { recursive: true, force: true });
-          execSync(`cp -r "${localConcepts}" "${targetConcepts}"`, { stdio: 'pipe' });
-        }
-        const registerYaml = path.join(envOverride, 'register.yaml');
-        if (fs.existsSync(registerYaml)) {
-          fs.copyFileSync(registerYaml, path.join(targetDir, 'register.yaml'));
-        }
-      } else if (ds.sourceRepo) {
-        cloneOrUpdate(ds.sourceRepo, targetDir);
-      } else {
-        console.warn(`  No source configured, skipping`);
-        console.log();
-        continue;
-      }
+      console.warn(`  No source configured, skipping`);
+      console.log();
+      continue;
     }
 
     // Read metadata for dependency validation (from GCR ZIP, not extracted dir)

package/scripts/generate-data.mjs

@@ -4,11 +4,25 @@ 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');
 const DATA = path.join(PUBLIC, 'data');
 
+/**
+ * Resolve a dataset's source directory.
+ * - If `ds.localPath` is set, use it in-place (resolved against ROOT).
+ *   No staging, no copy. fetch-datasets.mjs verifies the path is safe.
+ * - Otherwise fall back to the standard .datasets/<id>/ staging dir.
+ */
+function datasetDir(ds) {
+  return ds.localPath
+    ? path.resolve(ROOT, ds.localPath)
+    : path.join(ROOT, '.datasets', ds.id);
+}
+
 const DS_PALETTE = [
   '#3366ff', '#0d9488', '#d97706', '#8b5cf6',
   '#ec4899', '#059669', '#dc2626', '#6366f1',
@@ -934,7 +948,8 @@ function processDataset(dir, register, opts) {
   }
 
   // Copy bulk format files from compiled/ directory (full GCR)
-  const compiledDir = path.join(ROOT, '.datasets', register, 'compiled');
+  const sourceRoot = path.dirname(dir);
+  const compiledDir = path.join(sourceRoot, 'compiled');
   const bulkFormats = [];
   if (fs.existsSync(compiledDir)) {
     for (const file of fs.readdirSync(compiledDir)) {
@@ -993,27 +1008,34 @@ function processDataset(dir, register, opts) {
   writeJson(path.join(DATA, register, 'manifest.json'), manifest);
 
   // Copy bibliography.yaml → bibliography.json
-  const bibPath = path.join(ROOT, '.datasets', register, 'bibliography.yaml');
+  const bibPath = path.join(sourceRoot, 'bibliography.yaml');
   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/
-  const imagesSrcDir = path.join(ROOT, '.datasets', register, '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`);
@@ -1030,8 +1052,8 @@ const registerCache = {};
 
 // Pre-load all register.yaml files (needed before buildRefMaps for URI pattern indexing)
 for (const ds of config.datasets) {
-  const registerDir = path.join(ROOT, '.datasets', ds.id);
-  const registerYamlPath = path.join(registerDir, 'register.yaml');
+  const dsDir = datasetDir(ds);
+  const registerYamlPath = path.join(dsDir, 'register.yaml');
   if (fs.existsSync(registerYamlPath)) {
     try {
       const raw = yaml.load(fs.readFileSync(registerYamlPath, 'utf8'));
@@ -1047,7 +1069,7 @@ const refMaps = buildRefMaps(config, registerCache);
 for (let i = 0; i < config.datasets.length; i++) {
   const ds = config.datasets[i];
 
-  const dir = path.join(ROOT, '.datasets', ds.id, 'concepts');
+  const dir = path.join(datasetDir(ds), 'concepts');
   if (!fs.existsSync(dir)) {
     console.warn(`Skipping ${ds.id}: source directory not found (${dir})`);
     console.warn(`  Run: npm run fetch-datasets`);
@@ -1089,8 +1111,8 @@ for (let i = 0; i < config.datasets.length; i++) {
     status: ds.editionStatus || reg?.status,
     ordering: reg?.ordering || null,
     sections: reg?.sections ? reg.sections.map(s => s.toJSON()) : [],
-    hasBibliography: fs.existsSync(path.join(ROOT, '.datasets', ds.id, 'bibliography.yaml')),
-    hasImages: fs.existsSync(path.join(ROOT, '.datasets', ds.id, 'images')),
+    hasBibliography: fs.existsSync(path.join(datasetDir(ds), 'bibliography.yaml')),
+    hasImages: fs.existsSync(path.join(datasetDir(ds), 'images')),
   });
   registry.push({
     id: ds.id,

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 };
+}