@dataimago/css 0.1.0-alpha.20 → 0.1.0-alpha.22

package/dist/bin/dataimago-figures.mjs

@@ -0,0 +1,703 @@
+#!/usr/bin/env node
+/**
+ * dataimago-figures — the one figure build for PSTricks sources (spec: "The figure toolkit and build").
+ *
+ *   dataimago-figures build [<dir|file>...] [--toolkit <dir>] [--force]
+ *   dataimago-figures build --check [...]      exit 1 if any figure is out of date (needs no TeX)
+ *   dataimago-figures --help
+ *   node tools/formats/dataimago-figures.mjs --self-test      (repo only; needs TeX, else skipped)
+ *
+ * Each standalone source compiles ONCE under XeLaTeX into <name>.pdf (the PDF), <name>.svg (the HTML,
+ * fonts as paths) and <name>.png (300 dpi, slides and previews):
+ *
+ *   xelatex -no-pdf  ->  .xdv     xdvipdfmx  ->  .pdf
+ *   dvisvgm --no-fonts --exact-bbox (on the .xdv)  ->  .svg      pdftocairo -png -transp -r 300 (on the .pdf)  ->  .png (RGBA)
+ *
+ * Composites (a source that \includegraphics other figures) are the one exception for the SVG: dvisvgm
+ * silently drops the PDF images an .xdv includes ("6 PDF specials ignored") and cannot read PDFs here
+ * (Ghostscript >= 10.01 is unsupported, mutool absent), so a composite's SVG is `pdftocairo -svg` of its
+ * PDF instead, which also draws glyphs as paths.
+ *
+ * The toolkit directory (default: where the work's .dataimago/design.json puts `figures/`) holds
+ * dataimago-figure.sty, dataimago-tokens.sty and the static Noto fonts; it is put on TEXINPUTS,
+ * OPENTYPEFONTS and TTFONTS for the run. A figure that embeds any font outside the house faces
+ * (see ALLOWED_FONT) fails the build, naming the source and the font.
+ *
+ * A `figures.json` beside the sources is optional:
+ *   { "<source>.tex": { "out": "<dir>", "name": "<stable>", "inputs": ["<dir>"],
+ *       "variants": { "<id>": { "define": "\\panelletterstrue", "out": "<dir>", "name": "<n>", "inputs": [...] } } } }
+ * Every field is optional and every path is relative to the source's directory. Without it, outputs land
+ * beside the sources under the source's own name. `define` is TeX run at \begin{document}; `inputs` are
+ * extra directories searched first for \includegraphics (a composite's lettered variant points at the
+ * lettered panels).
+ *
+ * Panels build before the composites that \includegraphics them (by output name). A content hash of the
+ * source, its local \input files, the toolkit and its dependencies is kept in `.dataimago-figures.json`
+ * in each output directory; unchanged figures are skipped.
+ *
+ * Exit codes: 0 ok, 1 build or check failure, 2 usage or configuration error (including missing tools).
+ * Node built-ins only: this file ships in @dataimago/css dist/bin/ like dataimago-sync.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { fileURLToPath } from 'node:url';
+
+const MANIFEST = '.dataimago-figures.json';
+const TOOLS = ['xelatex', 'xdvipdfmx', 'dvisvgm', 'pdffonts', 'pdftocairo'];
+/** Bump when the pipeline's output changes, so existing figures rebuild without --force. 2: RGBA PNGs. */
+const PIPELINE_VERSION = 2;
+const INSTALL_HINT = 'Install TeX Live or MacTeX (xelatex, xdvipdfmx, dvisvgm) and poppler (pdffonts, pdftocairo), e.g. `brew install texlive poppler`.';
+const TOOLKIT_FILES = ['dataimago-figure.sty', 'dataimago-tokens.sty', 'NotoSans-Regular.otf', 'NotoSans-Italic.otf', 'NotoSans-Bold.otf', 'NotoSans-BoldItalic.otf', 'NotoSansMath-Regular.ttf'];
+
+/**
+ * The font allowlist, matched against pdffonts names with the subset tag ("ABCDEF+") and the
+ * "-Identity-H" CID suffix removed. House faces only: Noto Sans and Noto Sans Math.
+ * PSTricksDotFont is the one exception, explicitly: PSTricks' \psdots (dotstyle *, o, square, ...) draws
+ * every dot as a glyph of that generated Type 1 font. It has no text, no letterforms and no licence
+ * question, and it cannot be avoided without giving up \psdots, so it is allowed by name.
+ */
+/** The exceptions named above, in one place: the allowlist is built from them, and a checker that must allow one by name (tools/pdf-fixture-check.mjs) imports them. */
+export const FIGURE_FONT_EXCEPTIONS = ['PSTricksDotFont'];
+const ALLOWED_FONT = new RegExp(`^(NotoSans-(Regular|Italic|Bold|BoldItalic)|NotoSansMath-Regular|${FIGURE_FONT_EXCEPTIONS.join('|')})$`);
+
+class ConfigError extends Error {}
+
+const USAGE = `dataimago-figures — build PSTricks figure sources into .pdf, .svg and .png
+
+  dataimago-figures build [<dir|file>...]    compile each standalone .tex source (default: the current directory)
+  dataimago-figures build --check [...]      exit 1 if any figure is out of date (no TeX needed)
+  dataimago-figures build --force [...]      rebuild even when the content hash matches
+  dataimago-figures build --toolkit <dir>    use <dir> as the toolkit (default: the \`figures/\` destination
+                                             in .dataimago/design.json, searched upward from here)
+  dataimago-figures --help                   this text
+
+A source is a .tex file containing \\documentclass. Outputs land beside it, or where an optional
+figures.json beside the sources says. Needs xelatex, xdvipdfmx, dvisvgm, pdffonts and pdftocairo.
+${INSTALL_HINT}`;
+
+// ---------------------------------------------------------------- helpers
+
+const sha = (...parts) => {
+  const h = createHash('sha256');
+  for (const p of parts) { h.update(p); h.update('\0'); }
+  return h.digest('hex');
+};
+
+function readJson(file, what) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (e) { throw new ConfigError(`cannot read ${what} at ${file}: ${e.message}`); }
+}
+
+/** Find an executable on PATH (our own scan, so tests can narrow PATH). */
+function which(cmd, env = process.env) {
+  for (const dir of (env.PATH ?? '').split(path.delimiter)) {
+    if (!dir) continue;
+    const p = path.join(dir, cmd);
+    try { fs.accessSync(p, fs.constants.X_OK); if (fs.statSync(p).isFile()) return p; } catch { /* next */ }
+  }
+  return null;
+}
+
+function parseArgs(argv) {
+  const o = { cmd: null, paths: [], check: false, force: false, toolkit: null, help: false, selfTest: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') o.help = true;
+    else if (a === '--self-test') o.selfTest = true;
+    else if (a === '--check') o.check = true;
+    else if (a === '--force') o.force = true;
+    else if (a === '--toolkit') {
+      if (!argv[i + 1] || argv[i + 1].startsWith('--')) throw new ConfigError('--toolkit needs a directory');
+      o.toolkit = path.resolve(argv[++i]);
+    } else if (a.startsWith('--')) throw new ConfigError(`unknown argument ${a} (see --help)`);
+    else if (o.cmd === null) o.cmd = a;
+    else o.paths.push(a);
+  }
+  return o;
+}
+
+/** The toolkit: --toolkit, else the `figures/` output of the nearest .dataimago/design.json. */
+function resolveToolkit(explicit, cwd) {
+  let dir = explicit;
+  if (!dir) {
+    for (let d = cwd; ; d = path.dirname(d)) {
+      const cfg = path.join(d, '.dataimago', 'design.json');
+      if (fs.existsSync(cfg)) {
+        const outputs = readJson(cfg, '.dataimago/design.json').outputs ?? {};
+        const key = Object.keys(outputs).find((k) => k.replace(/\/+$/, '') === 'figures');
+        if (!key) throw new ConfigError(`${cfg} lists no \`figures/\` output; run dataimago-sync, or pass --toolkit <dir>`);
+        dir = path.resolve(d, outputs[key]);
+        break;
+      }
+      if (path.dirname(d) === d) throw new ConfigError('no .dataimago/design.json found; pass --toolkit <dir>');
+    }
+  }
+  const missing = TOOLKIT_FILES.filter((f) => !fs.existsSync(path.join(dir, f)));
+  if (missing.length) throw new ConfigError(`toolkit ${dir} is missing ${missing.join(', ')} (run dataimago-sync, or pass --toolkit <dir>)`);
+  return dir;
+}
+
+function toolkitHash(dir) {
+  // TEXINPUTS searches toolkit//, so every .sty/.otf/.ttf at any depth counts.
+  const files = [];
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (/\.(sty|otf|ttf|cls|def|cfg|tex)$/i.test(e.name)) files.push(p);
+    }
+  };
+  walk(dir);
+  files.sort();
+  return sha(...files.flatMap((f) => [path.relative(dir, f), fs.readFileSync(f)]));
+}
+
+// ---------------------------------------------------------------- discovery
+
+function findSources(inputs, cwd) {
+  const out = new Set();
+  const walk = (dir) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.name.endsWith('.tex') && /\\documentclass/.test(fs.readFileSync(p, 'utf8'))) out.add(p);
+    }
+  };
+  for (const raw of inputs.length ? inputs : ['.']) {
+    const p = path.resolve(cwd, raw);
+    if (!fs.existsSync(p)) throw new ConfigError(`no such file or directory: ${raw}`);
+    if (fs.statSync(p).isDirectory()) walk(p);
+    else if (p.endsWith('.tex')) out.add(p);
+    else throw new ConfigError(`not a .tex source: ${raw}`);
+  }
+  return [...out].sort();
+}
+
+const strList = (v, what) => {
+  if (v === undefined) return [];
+  if (!Array.isArray(v) || v.some((x) => typeof x !== 'string')) throw new ConfigError(`${what} must be an array of paths`);
+  return v;
+};
+
+/** One job per (source, variant): { src, srcDir, label, name, outDir, define, inputs }. */
+function planJobs(sources, cwd) {
+  const configs = new Map();
+  const cfgFor = (dir) => {
+    if (!configs.has(dir)) {
+      const f = path.join(dir, 'figures.json');
+      const c = fs.existsSync(f) ? readJson(f, 'figures.json') : {};
+      if (c === null || typeof c !== 'object' || Array.isArray(c)) throw new ConfigError(`${f} must be an object keyed by source file`);
+      configs.set(dir, c);
+    }
+    return configs.get(dir);
+  };
+  const jobs = [];
+  for (const src of sources) {
+    const srcDir = path.dirname(src);
+    const base = path.basename(src);
+    const stem = base.replace(/\.tex$/, '');
+    const entry = cfgFor(srcDir)[base] ?? {};
+    const where = `${path.join(srcDir, 'figures.json')} entry ${base}`;
+    for (const k of ['out', 'name', 'define']) if (entry[k] !== undefined && typeof entry[k] !== 'string') throw new ConfigError(`${where}: ${k} must be a string`);
+    const entryName = entry.name ?? stem;
+    const entryInputs = strList(entry.inputs, `${where}: inputs`);
+    const mk = (label, v) => ({
+      src, srcDir, label,
+      name: v.name ?? entryName,
+      outDir: path.resolve(srcDir, v.out ?? entry.out ?? '.'),
+      define: v.define ?? '',
+      inputs: [...strList(v.inputs, `${where}: ${label} inputs`), ...entryInputs].map((d) => path.resolve(srcDir, d)),
+    });
+    jobs.push(mk('', { define: entry.define }));
+    const variants = entry.variants ?? {};
+    if (variants === null || typeof variants !== 'object' || Array.isArray(variants)) throw new ConfigError(`${where}: variants must be an object`);
+    for (const [id, v] of Object.entries(variants)) {
+      for (const k of ['out', 'name', 'define']) if (v[k] !== undefined && typeof v[k] !== 'string') throw new ConfigError(`${where}: variant ${id}: ${k} must be a string`);
+      jobs.push(mk(id, v));
+    }
+  }
+  const seen = new Map();
+  for (const j of jobs) {
+    const key = path.join(j.outDir, j.name);
+    if (seen.has(key)) throw new ConfigError(`two figures write ${key}.* (${path.basename(seen.get(key).src)} ${seen.get(key).label || 'base'} and ${path.basename(j.src)} ${j.label || 'base'})`);
+    seen.set(key, j);
+    j.id = `${path.relative(cwd, j.src).startsWith('..') ? j.src : path.relative(cwd, j.src)}${j.label ? ` [${j.label}]` : ''}`;
+  }
+  return jobs;
+}
+
+/** Local files the source pulls in with \input / \InputIfFileExists (recursive), as absolute paths. */
+function localInputs(src) {
+  const found = new Set();
+  const visit = (file) => {
+    const text = fs.readFileSync(file, 'utf8');
+    for (const m of text.matchAll(/\\(?:input|InputIfFileExists)\s*\{([^}]+)\}/g)) {
+      for (const cand of [m[1], `${m[1]}.tex`]) {
+        const p = path.resolve(path.dirname(src), cand);
+        if (fs.existsSync(p) && fs.statSync(p).isFile() && !found.has(p)) { found.add(p); visit(p); break; }
+      }
+    }
+  };
+  visit(src);
+  return [...found].sort();
+}
+
+/** Order jobs so every figure comes after the figures it \includegraphics. Returns { order, deps }. */
+function orderJobs(jobs) {
+  const byName = new Map();
+  for (const j of jobs) byName.set(j.name, [...(byName.get(j.name) ?? []), j]);
+  const deps = new Map();
+  for (const j of jobs) {
+    const text = fs.readFileSync(j.src, 'utf8').replace(/(^|[^\\])%.*$/gm, '$1');
+    const wanted = new Map();
+    for (const m of text.matchAll(/\\includegraphics\s*(?:\[[^\]]*\])?\s*\{([^}]+)\}/g)) {
+      wanted.set(path.basename(m[1]).replace(/\.(pdf|png|svg)$/i, ''), m[1].trim());
+    }
+    j.composite = wanted.size > 0;
+    j.externals = [];
+    const mine = [];
+    for (const [n, written] of wanted) {
+      let cands = (byName.get(n) ?? []).filter((d) => d !== j);
+      if (cands.length > 1) {
+        // Resolve as TEXINPUTS does: the figure's `inputs` directories, in order, first.
+        for (const dir of j.inputs) {
+          const hit = cands.filter((d) => d.outDir === dir);
+          if (hit.length) { cands = hit; break; }
+        }
+      }
+      if (cands.length > 1) {
+        throw new ConfigError(`${j.id}: \\includegraphics{${written}} matches ${cands.length} built figures (${cands.map((d) => path.join(d.outDir, d.name)).join(', ')}); ` +
+          'set `inputs` for it in figures.json to say which directory to use.');
+      }
+      if (cands.length === 1) mine.push(cands[0]);
+      else {
+        // Not built by any job: a user's own image. Its bytes belong in the hash.
+        const dirs = [...j.inputs, j.srcDir];
+        const hit = dirs.flatMap((d) => ['', '.pdf', '.png', '.jpg', '.jpeg', '.svg'].map((x) => path.resolve(d, written + x)))
+          .find((f) => fs.existsSync(f) && fs.statSync(f).isFile());
+        if (hit) j.externals.push(hit);
+      }
+    }
+    j.resolved = mine;
+    deps.set(j, mine);
+  }
+  const order = [];
+  const state = new Map();
+  const visit = (j, trail) => {
+    if (state.get(j) === 2) return;
+    if (state.get(j) === 1) throw new ConfigError(`figures include each other: ${[...trail, j].map((x) => x.id).join(' -> ')}`);
+    state.set(j, 1);
+    for (const d of deps.get(j)) visit(d, [...trail, j]);
+    state.set(j, 2);
+    order.push(j);
+  };
+  for (const j of jobs) visit(j, []);
+  return { order, deps };
+}
+
+// ---------------------------------------------------------------- manifest
+
+const readManifest = (dir) => {
+  try { return JSON.parse(fs.readFileSync(path.join(dir, MANIFEST), 'utf8')).figures ?? {}; } catch { return {}; }
+};
+function writeManifest(dir, name, entry) {
+  const figures = readManifest(dir);
+  figures[name] = entry;
+  const sorted = Object.fromEntries(Object.keys(figures).sort().map((k) => [k, figures[k]]));
+  fs.writeFileSync(path.join(dir, MANIFEST), `${JSON.stringify({ version: 1, figures: sorted }, null, 2)}\n`);
+}
+const outputsOf = (j) => ['pdf', 'svg', 'png'].map((e) => path.join(j.outDir, `${j.name}.${e}`));
+const isFresh = (j) => outputsOf(j).every((f) => fs.existsSync(f)) && readManifest(j.outDir)[j.name]?.hash === j.hash;
+
+// ---------------------------------------------------------------- building
+
+function texEnv(job, toolkit, allJobs) {
+  const dirs = [`${toolkit}//`, ...job.inputs, job.srcDir, ...new Set(allJobs.map((j) => j.outDir))];
+  const fonts = `${toolkit}//${path.delimiter}`;
+  return {
+    ...process.env,
+    TEXINPUTS: dirs.join(path.delimiter) + path.delimiter,
+    OPENTYPEFONTS: fonts,
+    TTFONTS: fonts,
+    SOURCE_DATE_EPOCH: '1767225600',
+    FORCE_SOURCE_DATE: '1',
+  };
+}
+
+/** A path for messages: relative when it stays inside cwd, else absolute. */
+const show = (p, cwd) => { const r = path.relative(cwd, p); return r.startsWith('..') ? p : r || '.'; };
+
+const tail = (text, n) => text.trim().split('\n').slice(-n).join('\n');
+
+/** The first TeX error (file:line: message, or "! message") from a log, with its context lines. */
+function texError(log) {
+  const lines = log.split('\n');
+  const i = lines.findIndex((l) => /^\S+:\d+: /.test(l) || l.startsWith('! '));
+  return i === -1 ? tail(log, 8) : lines.slice(i, i + 4).join('\n');
+}
+
+/** Fonts embedded in a PDF, normalised, with pdffonts' raw name for messages. */
+function embeddedFonts(pdf, pdffonts) {
+  const r = spawnSync(pdffonts, [pdf], { encoding: 'utf8' });
+  if (r.status !== 0) throw new Error(`pdffonts failed on ${pdf}: ${tail(r.stderr || r.stdout, 3)}`);
+  return r.stdout.split('\n').slice(2).filter((l) => l.trim()).map((l) => {
+    const cols = l.trim().split(/\s+/);
+    const raw = cols[0];
+    const name = raw.replace(/^[A-Z]{6}\+/, '').replace(/-Identity-[HV]$/, '');
+    return { raw, name, embedded: cols.includes('yes') && cols.indexOf('yes') === cols.findIndex((c) => c === 'yes' || c === 'no') };
+  });
+}
+
+function buildJob(job, toolkit, allJobs, tools) {
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), 'di-fig-build-'));
+  try {
+    const env = texEnv(job, toolkit, allJobs);
+    const define = job.define ? `\\AtBeginDocument{${job.define}}` : '';
+    const tex = spawnSync(tools.xelatex, [
+      '-no-pdf', '-interaction=nonstopmode', '-halt-on-error', '-file-line-error',
+      `-jobname=${job.name}`, `-output-directory=${work}`, `${define}\\input{${path.basename(job.src)}}`,
+    ], { cwd: job.srcDir, env, encoding: 'utf8' });
+    const xdv = path.join(work, `${job.name}.xdv`);
+    if (tex.status !== 0 || !fs.existsSync(xdv)) {
+      let log = tex.stdout;
+      try { log = fs.readFileSync(path.join(work, `${job.name}.log`), 'utf8'); } catch { /* use stdout */ }
+      return `${job.id}: TeX error (xelatex, log ${job.name}.log)\n${texError(log)}`;
+    }
+    const pdf = path.join(work, `${job.name}.pdf`);
+    const svgOut = path.join(work, `${job.name}.svg`);
+    const run = (label, bin, args) => {
+      const r = spawnSync(bin, args, { cwd: job.srcDir, env, encoding: 'utf8' });
+      return r.status === 0 ? null : `${job.id}: ${label} failed\n${tail(r.stderr || r.stdout, 6)}`;
+    };
+    const bad0 = run('xdvipdfmx', tools.xdvipdfmx, ['-q', '-o', pdf, xdv])
+      ?? (job.composite
+        ? run('pdftocairo', tools.pdftocairo, ['-svg', pdf, svgOut])
+        : run('dvisvgm', tools.dvisvgm, ['--no-fonts', '--exact-bbox', '-o', svgOut, xdv]));
+    if (bad0) return bad0;
+    // The font allowlist: the point of the build. Checked before anything is published.
+    const bad = embeddedFonts(pdf, tools.pdffonts).filter((f) => !ALLOWED_FONT.test(f.name) || !f.embedded);
+    if (bad.length) {
+      return `${job.id}: embeds a font outside the house faces: ${[...new Set(bad.map((f) => f.raw))].join(', ')} ` +
+        '(allowed: NotoSans-{Regular,Italic,Bold,BoldItalic}, NotoSansMath-Regular, PSTricksDotFont). ' +
+        'Remove the \\usepackage or \\fontfamily that selects it.';
+    }
+    const svg = fs.readFileSync(path.join(work, `${job.name}.svg`), 'utf8');
+    if (/<text[\s>]/.test(svg)) return `${job.id}: the SVG contains <text> elements; fonts must be paths`;
+    const png = spawnSync(tools.pdftocairo, ['-png', '-transp', '-r', '300', '-singlefile', pdf, path.join(work, job.name)], { encoding: 'utf8' });
+    if (png.status !== 0) return `${job.id}: pdftocairo (png) failed\n${tail(png.stderr, 4)}`;
+    fs.mkdirSync(job.outDir, { recursive: true });
+    for (const ext of ['pdf', 'svg', 'png']) fs.copyFileSync(path.join(work, `${job.name}.${ext}`), path.join(job.outDir, `${job.name}.${ext}`));
+    writeManifest(job.outDir, job.name, { source: path.relative(job.outDir, job.src), hash: job.hash });
+    return null;
+  } finally {
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** Fingerprint each job in dependency order: source, local inputs, define, toolkit, dependency hashes. */
+function fingerprint(order, deps, tkHash) {
+  for (const j of order) {
+    const files = [j.src, ...localInputs(j.src)];
+    const config = JSON.stringify({
+      define: j.define, inputs: j.inputs.map((d) => path.relative(j.srcDir, d)), name: j.name,
+      out: path.relative(j.srcDir, j.outDir), variant: j.label, composite: j.composite,
+    });
+    const externals = j.externals.flatMap((f) => [path.relative(j.srcDir, f), fs.readFileSync(f)]);
+    j.hash = sha(`pipeline:${PIPELINE_VERSION}`, config, ...externals, tkHash, j.define, ...files.flatMap((f) => [path.basename(f), fs.readFileSync(f)]), ...deps.get(j).map((d) => d.hash));
+  }
+}
+
+function main(argv, cwd = process.cwd(), env = process.env) {
+  let opts;
+  try { opts = parseArgs(argv); } catch (e) { console.error(`dataimago-figures: ${e.message}`); return 2; }
+  if (opts.help || !opts.cmd) { console.log(USAGE); return opts.help ? 0 : 2; }
+  try {
+    if (opts.cmd !== 'build') throw new ConfigError(`unknown command ${opts.cmd} (see --help)`);
+    const toolkit = resolveToolkit(opts.toolkit, cwd);
+    const jobs = planJobs(findSources(opts.paths, cwd), cwd);
+    const { order, deps } = orderJobs(jobs);
+
+    let tools = null;
+    if (!opts.check) {
+      tools = {};
+      const missing = [];
+      for (const t of TOOLS) { tools[t] = which(t, env); if (!tools[t]) missing.push(t); }
+      if (missing.length) throw new ConfigError(`missing required tool${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}. ${INSTALL_HINT}`);
+    }
+    fingerprint(order, deps, toolkitHash(toolkit));
+
+    if (opts.check) {
+      const stale = order.filter((j) => !isFresh(j));
+      for (const j of stale) console.error(`dataimago-figures: out of date: ${j.id} -> ${show(path.join(j.outDir, j.name), cwd)}.*`);
+      console.log(`figures: ${order.length - stale.length} up to date, ${stale.length} out of date`);
+      return stale.length ? 1 : 0;
+    }
+
+    let built = 0; let upToDate = 0; const failed = []; const failedJobs = new Set();
+    for (const j of order) {
+      const blocker = deps.get(j).find((d) => failedJobs.has(d));
+      if (blocker) { failed.push(`${j.id}: skipped, ${blocker.id} failed`); failedJobs.add(j); continue; }
+      if (!opts.force && isFresh(j)) { upToDate += 1; continue; }
+      const err = buildJob(j, toolkit, order, tools);
+      if (err) { failed.push(err); failedJobs.add(j); continue; }
+      built += 1;
+      console.log(`built ${show(path.join(j.outDir, j.name), cwd)}.{pdf,svg,png}`);
+    }
+    for (const f of failed) console.error(`dataimago-figures: ${f}`);
+    console.log(`figures: ${built} built, ${upToDate} up to date, ${failed.length} failed`);
+    return failed.length ? 1 : 0;
+  } catch (e) {
+    if (!(e instanceof ConfigError)) throw e;
+    console.error(`dataimago-figures: ${e.message}`);
+    return 2;
+  }
+}
+
+// ---------------------------------------------------------------- self-test
+
+async function selfTest() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const repo = path.resolve(here, '..', '..');
+  const fixtures = path.join(repo, 'tools', '__fixtures__', 'figures');
+  if (!fs.existsSync(fixtures)) {
+    console.error('dataimago-figures --self-test runs from the dataimago-design repo (tools/formats/).');
+    process.exit(2);
+  }
+  const missing = TOOLS.filter((t) => !which(t));
+  if (!which('xelatex') || (missing.length && process.env.DATAIMAGO_REQUIRE_TEX === '1')) {
+    const msg = `dataimago-figures self-test: missing ${missing.join(', ')}`;
+    if (process.env.DATAIMAGO_REQUIRE_TEX === '1') {
+      console.error(`${msg} and DATAIMAGO_REQUIRE_TEX=1`);
+      process.exit(1);
+    }
+    console.log('dataimago-figures self-test: SKIPPED (xelatex not found). It runs in the PDF job.');
+    return;
+  }
+  if (missing.length) {
+    console.error(`dataimago-figures self-test: cannot run, missing ${missing.join(', ')}. ${INSTALL_HINT}`);
+    process.exit(2);
+  }
+  const assert = (await import('node:assert/strict')).default;
+  const pdffonts = which('pdffonts');
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'di-fig-'));
+  const run = (args, { cwd = tmp, env = process.env } = {}) =>
+    spawnSync(process.execPath, [fileURLToPath(import.meta.url), ...args], { cwd, encoding: 'utf8', env });
+  const out = (r) => `${r.stdout}\n${r.stderr}`;
+
+  // The toolkit as Task 6 ships it: figures/ = the two .sty, the static OTFs and Math, the OFL texts.
+  const toolkit = path.join(tmp, 'toolkit');
+  fs.mkdirSync(toolkit);
+  const fontDir = path.join(repo, 'packages', 'css', 'fonts');
+  for (const f of ['dataimago-figure.sty', 'dataimago-tokens.sty']) fs.copyFileSync(path.join(repo, 'src', 'latex', f), path.join(toolkit, f));
+  for (const f of TOOLKIT_FILES.filter((x) => /\.(otf|ttf)$/.test(x))) fs.copyFileSync(path.join(fontDir, 'latex', f), path.join(toolkit, f));
+  for (const f of ['OFL-NotoSans.txt', 'OFL-NotoSansMath.txt']) fs.copyFileSync(path.join(fontDir, f), path.join(toolkit, f));
+
+  const work = path.join(tmp, 'work');
+  fs.cpSync(fixtures, work, { recursive: true });
+  const badDir = path.join(tmp, 'bad');
+  fs.mkdirSync(badDir);
+  fs.renameSync(path.join(work, 'bad-font.tex'), path.join(badDir, 'bad-font.tex'));
+  const tk = ['--toolkit', toolkit];
+  const summary = (r) => { const m = /figures: (\d+) built, (\d+) up to date, (\d+) failed/.exec(r.stdout); return m ? m.slice(1).map(Number) : null; };
+  const fontsOf = (rel) => embeddedFonts(path.join(work, rel), pdffonts);
+
+  // 1. The panels and the composite build into .pdf, .svg, .png, and figures.json places them.
+  let r = run(['build', work, ...tk]);
+  assert.equal(r.status, 0, out(r));
+  assert.deepEqual(summary(r), [5, 0, 0], out(r));
+  const expected = ['build/kernel_slices', 'build/lettered/kernel_slices', 'panel-b', 'build/composite', 'build/lettered/composite'];
+  for (const e of expected) for (const ext of ['pdf', 'svg', 'png']) assert.ok(fs.existsSync(path.join(work, `${e}.${ext}`)), `${e}.${ext} exists`);
+  assert.ok(!fs.existsSync(path.join(work, 'panel-a.pdf')), 'a stable name replaces the source name');
+  assert.equal(fs.readFileSync(path.join(work, 'build/kernel_slices.png')).subarray(1, 4).toString(), 'PNG', 'a real PNG');
+  assert.equal(fs.readFileSync(path.join(work, 'build/kernel_slices.pdf')).subarray(0, 4).toString(), '%PDF', 'a real PDF');
+
+  // 2. Fonts as paths in the SVG; house faces only in the PDF (pst-plot, pst-node, pst-3dplot, \psdots all covered).
+  for (const e of expected) {
+    const svg = fs.readFileSync(path.join(work, `${e}.svg`), 'utf8');
+    assert.ok(svg.includes('<svg') && !/<text[\s>]/.test(svg), `${e}.svg has no <text>`);
+    assert.ok(/<path/.test(svg), `${e}.svg draws paths`);
+    for (const f of fontsOf(`${e}.pdf`)) assert.match(f.name, ALLOWED_FONT, `${e}.pdf embeds only house faces (saw ${f.raw})`);
+  }
+  assert.ok(fontsOf('panel-b.pdf').some((f) => f.name === 'PSTricksDotFont'), '\\psdots does emit PSTricksDotFont (the explicit allowance is load-bearing)');
+  assert.ok(fontsOf('build/kernel_slices.pdf').some((f) => /^NotoSans-/.test(f.name)), 'Noto Sans is embedded');
+  assert.ok(fontsOf('build/kernel_slices.pdf').some((f) => f.name === 'NotoSansMath-Regular'), 'Noto Sans Math is embedded');
+
+  assert.ok((fs.readFileSync(path.join(work, 'build/composite.svg'), 'utf8').match(/<path/g) ?? []).length > 40, 'the composite SVG carries its panels (dvisvgm would drop included PDFs)');
+
+  // 3. The lettered variant differs from the unlettered one (\panelletterstrue ran), and the composite's
+  //    lettered variant took the lettered panels (figures.json `inputs`).
+  assert.notEqual(fs.readFileSync(path.join(work, 'build/kernel_slices.svg'), 'utf8'), fs.readFileSync(path.join(work, 'build/lettered/kernel_slices.svg'), 'utf8'), 'the lettered panel carries its letter');
+  assert.notEqual(fs.readFileSync(path.join(work, 'build/composite.svg'), 'utf8'), fs.readFileSync(path.join(work, 'build/lettered/composite.svg'), 'utf8'), "the composite's lettered variant includes the lettered panels");
+
+  // 3b. PNGs are RGBA with a transparent page: colour type 6, and the top-left pixel's alpha is 0.
+  const png = fs.readFileSync(path.join(work, 'build/kernel_slices.png'));
+  assert.equal(png[25], 6, 'PNG colour type 6 (RGBA)');
+  assert.equal(png[24], 8, '8-bit PNG');
+  const idat = Buffer.concat((() => {
+    const parts = []; let o = 8;
+    while (o < png.length) { const len = png.readUInt32BE(o); if (png.subarray(o + 4, o + 8).toString() === 'IDAT') parts.push(png.subarray(o + 8, o + 8 + len)); o += 12 + len; }
+    return parts;
+  })());
+  assert.equal(zlib.inflateSync(idat)[4], 0, 'the corner pixel is fully transparent');
+
+  // 4. Dependency order: from a clean slate with the composite listed first, it still builds last.
+  const w2 = path.join(tmp, 'order');
+  fs.mkdirSync(w2);
+  for (const f of ['panel-b.tex', 'composite.tex']) fs.copyFileSync(path.join(fixtures, f), path.join(w2, f));
+  fs.copyFileSync(path.join(fixtures, 'panel-a.tex'), path.join(w2, 'kernel_slices.tex'));
+  r = run(['build', path.join(w2, 'composite.tex'), path.join(w2, 'panel-b.tex'), path.join(w2, 'kernel_slices.tex'), ...tk]);
+  assert.equal(r.status, 0, out(r));
+  assert.ok(r.stdout.split('\n').filter((l) => l.startsWith('built ')).at(-1).includes('composite'), `the composite builds last:\n${r.stdout}`);
+
+  // 5. A second run rebuilds nothing; --force rebuilds.
+  r = run(['build', work, ...tk]);
+  assert.equal(r.status, 0, out(r));
+  assert.deepEqual(summary(r), [0, 5, 0], `second run is a no-op:\n${out(r)}`);
+  assert.deepEqual(summary(run(['build', work, '--force', ...tk])), [5, 0, 0], '--force rebuilds');
+
+  // 6. --check passes when fresh and fails after a source edit; the edit reaches the composites that include it.
+  r = run(['build', '--check', work, ...tk]);
+  assert.equal(r.status, 0, out(r));
+  fs.appendFileSync(path.join(work, 'panel-b.tex'), '\n% edited\n');
+  r = run(['build', '--check', work, ...tk]);
+  assert.equal(r.status, 1, out(r));
+  assert.match(r.stderr, /panel-b\.tex/);
+  assert.match(r.stderr, /composite\.tex/, 'the composite is stale too: it includes the edited panel');
+  r = run(['build', work, ...tk]);
+  assert.equal(r.status, 0, out(r));
+  assert.equal(summary(r)[0], 3, `the edited panel and its two composites rebuilt:\n${out(r)}`);
+  fs.appendFileSync(path.join(toolkit, 'dataimago-figure.sty'), '\n% toolkit edited\n');
+  assert.equal(run(['build', '--check', work, ...tk]).status, 1, 'a toolkit change makes every figure stale');
+  fs.copyFileSync(path.join(repo, 'src', 'latex', 'dataimago-figure.sty'), path.join(toolkit, 'dataimago-figure.sty'));
+  assert.equal(run(['build', '--check', work, ...tk]).status, 0, 'restoring the toolkit makes the figures fresh again');
+  fs.mkdirSync(path.join(toolkit, 'sub'));
+  fs.writeFileSync(path.join(toolkit, 'sub', 'extra.sty'), '% a toolkit subdirectory file\n');
+  assert.equal(run(['build', '--check', work, ...tk]).status, 1, 'a file in a toolkit subdirectory (on TEXINPUTS toolkit//) counts');
+  fs.rmSync(path.join(toolkit, 'sub'), { recursive: true });
+
+  // 6b. Changing a composite variant's `inputs` makes it stale. NOTE: the dependency hash (it now includes a different panel) is what
+  //     catches this case; the config hash is proven on its own in 6b2.
+  const cfgFile = path.join(work, 'figures.json');
+  const cfgText = fs.readFileSync(cfgFile, 'utf8');
+  assert.equal(run(['build', '--check', work, ...tk]).status, 0);
+  fs.writeFileSync(cfgFile, cfgText.replace('"inputs": ["build/lettered"]', '"inputs": []'));
+  r = run(['build', '--check', work, ...tk]);
+  assert.equal(r.status, 1, out(r));
+  assert.match(r.stderr, /composite\.tex \[lettered\]/);
+  fs.writeFileSync(cfgFile, cfgText);
+  assert.equal(run(['build', '--check', work, ...tk]).status, 0);
+
+  // 6b2. The config hash alone: a panel with no composites gets an `inputs` entry in figures.json (an empty dir). Source, toolkit,
+  //      dependencies and outputs are untouched, so only the hashed config can flag it.
+  const w8 = path.join(tmp, 'cfgonly');
+  fs.mkdirSync(path.join(w8, 'extra'), { recursive: true });
+  fs.copyFileSync(path.join(fixtures, 'panel-b.tex'), path.join(w8, 'solo.tex'));
+  assert.equal(run(['build', w8, ...tk]).status, 0);
+  assert.equal(run(['build', '--check', w8, ...tk]).status, 0);
+  fs.writeFileSync(path.join(w8, 'figures.json'), JSON.stringify({ 'solo.tex': { inputs: ['extra'] } }));
+  r = run(['build', '--check', w8, ...tk]);
+  assert.equal(r.status, 1, `a config-only change (inputs) makes the figure stale:\n${out(r)}`);
+  fs.rmSync(path.join(w8, 'figures.json'));
+  assert.equal(run(['build', '--check', w8, ...tk]).status, 0, 'restoring the config makes it fresh again');
+
+  // 6c. An external image a source includes (not built by any figure) is hashed: editing it makes --check fail.
+  const w6 = path.join(tmp, 'external');
+  fs.mkdirSync(w6);
+  fs.copyFileSync(path.join(work, 'build/kernel_slices.png'), path.join(w6, 'pic.png'));
+  fs.writeFileSync(path.join(w6, 'uses-pic.tex'), '\\documentclass[border=2pt]{standalone}\n\\usepackage{dataimago-figure}\n\\usepackage{graphicx}\n\\begin{document}\n\\includegraphics[width=1in]{pic}\n\\end{document}\n');
+  r = run(['build', w6, ...tk]);
+  assert.equal(r.status, 0, out(r));
+  assert.equal(run(['build', '--check', w6, ...tk]).status, 0);
+  fs.appendFileSync(path.join(w6, 'pic.png'), Buffer.from([0]));
+  assert.equal(run(['build', '--check', w6, ...tk]).status, 1, 'editing an external included image makes the figure stale');
+
+  // 6d. Ambiguity is an error, not traversal luck: a composite with no `inputs` that names a panel built in two places.
+  const w7 = path.join(tmp, 'ambiguous');
+  fs.mkdirSync(w7);
+  for (const f of ['panel-a.tex', 'composite.tex', 'figures.json']) fs.copyFileSync(path.join(fixtures, f), path.join(w7, f));
+  fs.writeFileSync(path.join(w7, 'figures.json'), JSON.stringify({ 'panel-a.tex': { name: 'kernel_slices', out: 'build', variants: { lettered: { define: '\\panelletterstrue', out: 'build/lettered' } } } }));
+  r = run(['build', w7, ...tk]);
+  assert.equal(r.status, 2, out(r));
+  assert.match(r.stderr, /kernel_slices/);
+  assert.match(r.stderr, /build[\\/]lettered[\\/]kernel_slices/, 'names both candidates');
+  assert.match(r.stderr, /inputs/, 'tells the user to set inputs');
+
+  // 7. Review Focus 3: a figure that reaches for Computer Modern fails, naming the file and the font; nothing is published.
+  r = run(['build', badDir, ...tk]);
+  assert.equal(r.status, 1, out(r));
+  assert.match(r.stderr, /bad-font\.tex/, 'names the figure');
+  assert.match(r.stderr, /CMSS/, 'names the font');
+  assert.ok(!fs.existsSync(path.join(badDir, 'bad-font.pdf')), 'a rejected figure writes no outputs');
+
+  // 8. A TeX error names the source and the error, and does not stop independent figures.
+  const w3 = path.join(tmp, 'texerr');
+  fs.mkdirSync(w3);
+  fs.writeFileSync(path.join(w3, 'broken.tex'), '\\documentclass[border=2pt]{standalone}\n\\usepackage{dataimago-figure}\n\\begin{document}\n\\undefinedmacro\n\\end{document}\n');
+  fs.copyFileSync(path.join(fixtures, 'panel-b.tex'), path.join(w3, 'fine.tex'));
+  r = run(['build', w3, ...tk]);
+  assert.equal(r.status, 1, out(r));
+  assert.match(r.stderr, /broken\.tex/);
+  assert.match(r.stderr, /Undefined control sequence/);
+  assert.ok(fs.existsSync(path.join(w3, 'fine.pdf')), 'an independent figure still builds');
+
+  // 9. Configuration errors exit 2: no toolkit, a bad toolkit, an unknown flag, a bad figures.json.
+  assert.equal(run(['build', work]).status, 2, 'no toolkit and no design.json');
+  assert.equal(run(['build', work, '--toolkit', tmp]).status, 2, 'a directory without the toolkit files');
+  assert.equal(run(['build', work, '--nope']).status, 2);
+  const w4 = path.join(tmp, 'badcfg');
+  fs.mkdirSync(w4);
+  fs.copyFileSync(path.join(fixtures, 'panel-b.tex'), path.join(w4, 'p.tex'));
+  fs.writeFileSync(path.join(w4, 'figures.json'), '{ nope');
+  assert.equal(run(['build', w4, ...tk]).status, 2, 'unparseable figures.json');
+
+  // 10. The default toolkit is the `figures/` destination of .dataimago/design.json.
+  const w5 = path.join(tmp, 'viaconfig');
+  fs.mkdirSync(path.join(w5, '.dataimago'), { recursive: true });
+  fs.copyFileSync(path.join(fixtures, 'panel-b.tex'), path.join(w5, 'p.tex'));
+  fs.writeFileSync(path.join(w5, '.dataimago', 'design.json'), JSON.stringify({ package: '@dataimago/css', version: '0.0.0', outputs: { 'figures/': `${path.relative(w5, toolkit)}/` } }));
+  r = run(['build', '.'], { cwd: w5 });
+  assert.equal(r.status, 0, out(r));
+  assert.ok(fs.existsSync(path.join(w5, 'p.svg')));
+
+  // 11. A missing dvisvgm exits 2 naming it (PATH narrowed to links of every other tool; nothing is run).
+  const bin = path.join(tmp, 'bin');
+  fs.mkdirSync(bin);
+  for (const t of TOOLS.filter((x) => x !== 'dvisvgm')) fs.symlinkSync(which(t), path.join(bin, t));
+  fs.writeFileSync(path.join(w5, 'p.tex'), `${fs.readFileSync(path.join(w5, 'p.tex'), 'utf8')}\n% stale\n`);
+  r = run(['build', w5, ...tk], { env: { ...process.env, PATH: bin } });
+  assert.equal(r.status, 2, out(r));
+  assert.match(r.stderr, /dvisvgm/);
+  assert.match(r.stderr, /missing required tool: dvisvgm\./, 'only the missing tool is named');
+
+  // 12. The wrong-engine error halts the run (as dataimago-base.sty does): one error, nothing after it.
+  if (which('lualatex')) {
+    const w9 = path.join(tmp, 'engine');
+    fs.mkdirSync(w9);
+    fs.writeFileSync(path.join(w9, 'x.tex'), '\\documentclass{article}\n\\usepackage{dataimago-figure}\n\\begin{document}x\\end{document}\n');
+    const lr = spawnSync('lualatex', ['-interaction=nonstopmode', 'x.tex'], { cwd: w9, encoding: 'utf8', env: { ...process.env, TEXINPUTS: `${toolkit}//:` } });
+    const lout = `${lr.stdout}\n${lr.stderr}`;
+    assert.match(lout, /This toolkit needs XeLaTeX/, lout.slice(-800));
+    assert.equal((lout.match(/^! /gm) ?? []).length, 1, `exactly one error, then a halt:\n${lout.slice(-1200)}`);
+  }
+
+  assert.match(run(['--help']).stdout, /dataimago-figures build/);
+  // The font allowlist is built from FIGURE_FONT_EXCEPTIONS: every exception passes it, a house face passes, Computer Modern does not.
+  for (const name of [...FIGURE_FONT_EXCEPTIONS, 'NotoSans-Bold', 'NotoSansMath-Regular']) assert.match(name, ALLOWED_FONT, `${name} is allowed`);
+  for (const name of ['CMR10', 'LMRoman10-Regular', 'NotoSans-ExtraBold', 'NotoSansMono-Regular']) assert.doesNotMatch(name, ALLOWED_FONT, `${name} is refused`);
+  assert.equal(run([]).status, 2, 'no command is a usage error');
+  fs.rmSync(tmp, { recursive: true, force: true });
+  console.log('dataimago-figures self-test: all checks passed');
+}
+
+// Run only as a program: tools/pdf-fixture-check.mjs imports FIGURE_FONT_EXCEPTIONS. realpath, because npx runs the bin through a symlink.
+const asProgram = process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+if (asProgram) {
+  if (process.argv.includes('--self-test')) await selfTest();
+  else process.exitCode = main(process.argv.slice(2));
+}