ranger-compiler 3.5.1 → 3.5.2

package/dist/lib/evg/showcase/build.mjs

@@ -0,0 +1,651 @@
+/**
+ * Build the EVG showcase: every page in every theme, rendered to PDF, PNG and
+ * HTML, plus an index that puts them side by side.
+ *
+ *   node lib/evg/showcase/build.mjs                       # -> showcase/dist
+ *   node lib/evg/showcase/build.mjs --out "$SITE/evg"     # for Pages
+ *
+ * The point of the gallery is that the pages carry no visual attributes at
+ * all — they say what is on the page, and themes/showcase.css says how it
+ * looks. Rendering the same tree under two themes and three targets is the
+ * demonstration.
+ *
+ * Requires the Ranger compiler to be built (npm run compile).
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, "../../..");
+
+const argv = process.argv.slice(2);
+const outFlag = argv.indexOf("--out");
+const OUT = outFlag >= 0 ? path.resolve(argv[outFlag + 1]) : path.join(HERE, "dist");
+const TOOLS = path.join(OUT, ".tools");
+
+/** Pages, in the order they appear in the gallery. */
+const PAGES = [
+  {
+    id: "album",
+    title: "Album spread",
+    blurb:
+      "grid-template-areas draws the spread as a picture of names, so a theme can rearrange it without touching the tree.",
+    shows: ["grid-template-areas", "spans", "object-fit: cover", "gap"],
+  },
+  {
+    id: "cards",
+    title: "Cards on shared rows",
+    blurb:
+      "Three cards, three caption lengths, one baseline. Each card spans the deck's rows and declares grid-template-rows: subgrid, so the photo band and the caption band are shared.",
+    shows: ["subgrid (rows)", "grid spans", "text wrapping"],
+  },
+  {
+    id: "typography",
+    title: "Type specimens",
+    blurb:
+      "Measured from the same TTF the page is painted with, kerned from the font's own GPOS pairs, and encoded so ä, — and “ ” survive the trip to PDF.",
+    shows: ["real TTF metrics", "GPOS kerning", "align-items: baseline", "UTF-8 + WinAnsi"],
+  },
+  {
+    id: "units",
+    title: "Length units",
+    blurb:
+      "Five bars declared in five units, all the same length, because CSS pins them to the reference pixel. em follows the local font-size; rem stays with the root.",
+    shows: ["px % em rem", "pt pc in mm cm"],
+  },
+  {
+    id: "vector",
+    title: "Vector paths",
+    blurb:
+      "One path parser, one viewBox transform, three targets: real vector operators in the PDF, an inline <svg> in the HTML, and the same anti-aliased scanline fill that paints this page's glyphs in the PNG.",
+    shows: ["viewBox scaling", "fill-rule holes", "cubic + quadratic", "smooth S/T", "elliptical arcs"],
+  },
+  {
+    id: "svg",
+    title: "Imported SVG",
+    blurb:
+      "Two SVG files read into the same vector layer the rest of the gallery draws with: groups resolved, transforms baked into the geometry, <use> expanded where it is referenced. The browser is handed the resolved shapes rather than the original markup, so the preview cannot draw anything the printer will not.",
+    shows: ["<use> and <defs>", "baked transforms", "inherited paint", "themed from CSS"],
+  },
+  {
+    id: "charts",
+    title: "Charts",
+    blurb:
+      "Unmodified Vega specifications, compiled from Vega-Lite examples and run by the Vela runtime in this repository: every gridline, bar, wedge, key and label is geometry Ranger computed and the EVG vector layer drew. The page is generated, and its colours are not in it — the series are numbered and the stylesheet paints them, so the same charts come out in three palettes, legends included.",
+    shows: ["generated path data", "series colours from CSS", "one path per paint", "arcs, symbols and legends"],
+    themes: ["editorial", "studio", "autumn"],
+  },
+  {
+    id: "chart_api",
+    title: "Charts, called",
+    blurb:
+      "The only page here whose charts came from a program rather than from a specification: each one was built by calling Vela's chart API (gallery/vela/src/VlChart.rgr), and the lines printed above it are the calls that built it — read out of the generating tool's own source, so the code on the page and the code that drew it cannot drift apart. A view's encoding is inherited by its marks, and no channel says what it is: a column of ISO dates is an instant, a column of numbers is a quantity, read off the data.",
+    shows: ["marks and channels, called", "inherited view encoding", "types read off the data", "the calls that drew it"],
+    themes: ["editorial", "studio", "autumn"],
+  },
+  {
+    id: "plots",
+    title: "Chart types",
+    blurb:
+      "The rest of the runtime's chart types, and the features only some charts have: a size legend whose rows are all different heights, a stroke legend, a log axis that labels only some of the ticks it draws, two marks sharing one plot, and text as a mark. Generated from the same specifications the parity harness compares against official Vega.",
+    shows: ["size and colour legends", "log scale", "layered marks", "text marks", "grouped bands"],
+    themes: ["editorial", "studio", "autumn"],
+  },
+  {
+    id: "more",
+    title: "More chart types",
+    blurb:
+      "The chart types the runtime learned most recently, which are also the ones that exercise the most of it: a continuous colour ramp with the gradient key it earns, a series that is a faceted group of its own, a stack centred on a common line, a calendar on an axis, and a box plot whose quartiles are computed rather than approximated.",
+    shows: ["colour ramps", "gradient legends", "faceted series", "time scales", "computed quartiles"],
+    themes: ["editorial", "studio", "autumn"],
+  },
+  {
+    id: "variants",
+    title: "Variants",
+    blurb:
+      "The same marks a chart already on this showcase uses, drawn a different way — bars that go down as well as up, bars that lie on their side, a bar between two values rather than from a baseline, a line that steps instead of sloping, a line that shows its own vertices, a single row of ticks, a shape legend, a mean drawn across the plot, and a pie whose wedges differ in length as well as angle. It is the variants that break a runtime rather than the types.",
+    shows: ["negative bars", "horizontal bars", "step interpolation", "shape scales", "rules across a plot", "radial scales"],
+    themes: ["editorial", "studio", "autumn"],
+  },
+  {
+    id: "tables",
+    title: "Tables",
+    blurb:
+      "The plots where the cell is the datum: both axes are categories, or both are bins, and the value is carried by the cell's colour, its area, or the number printed in it. The two-dimensional histogram is the one that exercises the most — it bins on both axes, counts what lands in each cell, and ticks its axes on the bin edges rather than wherever a tick algorithm would have put them.",
+    shows: ["binning on both axes", "counts as colour", "point scales", "layered labels"],
+    themes: ["editorial", "studio", "autumn"],
+  },
+  {
+    id: "drawing",
+    title: "What a renderer has to get right",
+    blurb:
+      "Four specifications that exist to be drawn rather than to say anything: every symbol shape the grammar offers, every interpolation that joins a line's points, the paint channels that change the ink without moving it — a dash pattern, a rounded corner, a square cap, a fill more translucent than its own outline — and a label against each alignment, baseline, nudge and angle. A scenegraph says \"diamond\" and stops; these are the specs that make a renderer say what a diamond looks like, and each of them is compared against the picture official Vega's own renderer produces.",
+    shows: ["twelve symbol shapes", "nine interpolations", "dashes and corner radii", "separate fill and stroke opacity", "text anchoring"],
+    themes: ["editorial", "studio", "autumn"],
+  },
+  {
+    id: "views",
+    title: "More than one chart",
+    blurb:
+      "The four ways a chart can be more than one chart, all of them laid out by their own bounds rather than by a size anyone declared: a trellis by column, by row, and wrapped onto a grid whose shape is computed from the data, plus two plots concatenated with only the dimension across the join in common. The grid axes stay inside each panel; the labelled axes are drawn once, in the footer and the row header.",
+    shows: ["column and row facets", "wrapped grids", "concatenation", "bounds-based layout", "shared axes"],
+    themes: ["editorial", "studio", "autumn"],
+  },
+  {
+    id: "flex",
+    title: "Flex",
+    blurb:
+      "Grow, shrink and basis; wrapping; and what a row does with what is left over. Every arrangement is a class.",
+    shows: ["flex shorthand", "flex-shrink: 0", "justify-content", "flex-wrap"],
+  },
+  {
+    id: "emoji",
+    title: "Emoji",
+    blurb:
+      "Each specimen is several codepoints and one glyph, and only becomes that glyph if the whole cluster reaches the shaper together. The tinted rows use emoji-color, which exists because there are no inline spans to hang a second colour on.",
+    shows: ["grapheme clusters", "GSUB ligatures", "Type0 / Identity-H", "emoji-color"],
+  },
+  {
+    id: "boxmodel",
+    title: "Box model",
+    blurb:
+      "Padding, per-side padding, borders, nesting and margins — the same geometry the browser-parity gate checks against Chromium.",
+    shows: ["padding", "border", "margins", "nesting"],
+  },
+];
+
+const THEMES = [
+  { id: "editorial", label: "Editorial", note: "warm paper, serif display" },
+  { id: "studio", label: "Studio", note: "dark, geometric sans" },
+];
+
+/** Themes beyond the two every page gets. A page names them in `themes`. */
+const EXTRA_THEMES = {
+  autumn: { id: "autumn", label: "Autumn", note: "muted ochre, rust and olive" },
+};
+
+/** The themes one page is rendered under. */
+function themesFor(page) {
+  if (!page.themes) return THEMES;
+  return page.themes.map((id) => THEMES.find((t) => t.id === id) || EXTRA_THEMES[id]);
+}
+
+const CSS = path.join(HERE, "themes/showcase.css");
+/** Stylesheets a page needs beyond the gallery's own, in cascade order. */
+const PAGE_CSS = {
+  // The colours the chart specifications asked for. Unscoped, so a theme's
+  // scoped chart rules override them and a build with no chart theme still
+  // draws the chart the spec described.
+  charts: [path.join(HERE, "themes/charts-default.css")],
+  chart_api: [path.join(HERE, "themes/chart_api-default.css")],
+  plots: [path.join(HERE, "themes/plots-default.css")],
+  more: [path.join(HERE, "themes/more-default.css")],
+  views: [path.join(HERE, "themes/views-default.css")],
+  variants: [path.join(HERE, "themes/variants-default.css")],
+  tables: [path.join(HERE, "themes/tables-default.css")],
+  drawing: [path.join(HERE, "themes/drawing-default.css")],
+};
+
+function sh(cmd, args, opts = {}) {
+  return execFileSync(cmd, args, {
+    cwd: ROOT,
+    encoding: "utf8",
+    maxBuffer: 1 << 28,
+    ...opts,
+  });
+}
+
+/** Compile a Ranger tool. The compiler prints failures but still exits 0. */
+function compile(src, outFile) {
+  const log = sh("node", [
+    "dist/rgrc.js",
+    "-es6",
+    src,
+    `-d=${path.relative(ROOT, TOOLS)}`,
+    `-o=${outFile}`,
+    "-nodecli",
+  ], { env: { ...process.env, RANGER_LIB: "./compiler/Lang.rgr" } });
+  if (log.includes("Compilation FAILED")) {
+    process.stderr.write(log.split("\n").slice(-30).join("\n") + "\n");
+    throw new Error(`compile failed: ${src}`);
+  }
+}
+
+function render(tool, page, theme, outFile, extra = []) {
+  const sheets = [...(PAGE_CSS[page] || []), CSS];
+  const args = [
+    path.join(TOOLS, tool),
+    path.join(HERE, "pages", `${page}.tsx`),
+    outFile,
+    ...sheets.flatMap((sheet) => ["-css", sheet]),
+    "-theme",
+    theme,
+    ...extra,
+  ];
+  const log = sh("node", args);
+  const warnings = log
+    .split("\n")
+    .filter((l) => /warning:/i.test(l))
+    .map((l) => l.trim());
+  return warnings;
+}
+
+/** The WebGL viewer page. One canvas, one display list, the real faces. */
+function viewerHtml(faceCss) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>EVG on WebGL</title>
+<style>
+  ${faceCss}
+  :root { color-scheme: light dark; }
+  body { margin:0; background:#8b8f94; display:flex; flex-direction:column;
+         align-items:center; gap:14px; padding:24px;
+         font:14px/1.5 ui-sans-serif, system-ui, sans-serif; color:#fff }
+  canvas { background:#fff; box-shadow:0 3px 22px rgba(0,0,0,.4); max-width:100%; height:auto }
+  .bar { display:flex; gap:14px; align-items:baseline; flex-wrap:wrap; justify-content:center }
+  a { color:#cfe4ff }
+  code { background:rgba(0,0,0,.25); padding:1px 5px; border-radius:4px }
+  #err { color:#ffd0d0; font:12px/1.4 monospace; white-space:pre-wrap; max-width:70ch }
+</style>
+</head>
+<body>
+  <div class="bar">
+    <strong>EVG on WebGL</strong>
+    <span id="stats" class="muted">loading…</span>
+    <a href="../index.html">back to the gallery</a>
+  </div>
+  <canvas id="c"></canvas>
+  <p class="bar">Same layout as the PDF — flex, grid, TTF metrics and kerning — drawn as GPU quads.
+     Rounded corners come from a distance field in the fragment shader.</p>
+  <p id="err"></p>
+<script type="module">
+import { renderDisplayList, loadImages } from "./evg-webgl.js";
+const list = new URLSearchParams(location.search).get("list") || "album-editorial.json";
+const err = document.getElementById("err");
+try {
+  const doc = await (await fetch(list)).json();
+  const dpr = Math.min(2, window.devicePixelRatio || 1);
+  const c = document.getElementById("c");
+  c.style.width = doc.width + "px";
+  c.width = Math.round(doc.width * dpr);
+  c.height = Math.round(doc.height * dpr);
+  const gl = c.getContext("webgl2", { antialias: true, premultipliedAlpha: false, stencil: true });
+  if (!gl) throw new Error("This browser has no WebGL 2.");
+  await document.fonts.ready;
+  // A face nothing has used yet is not fetched until asked for by size.
+  await Promise.all(doc.list.cmds.filter(x => x.text)
+    .map(x => document.fonts.load(\`\${x.size}px "\${x.font}"\`).catch(() => {})));
+  // Photos have to be in the GPU before the first draw, or the page paints
+  // once with holes where they go.
+  const images = await loadImages(doc);
+  const s = renderDisplayList(gl, doc, { dpr, images });
+  document.getElementById("stats").textContent =
+    \`\${s.drawn} quads · \${s.paths || 0} paths · \${s.textRuns} text runs · \${s.images} images\`
+    + (s.missingImages ? \` · \${s.missingImages} could not be loaded\` : "")
+    + (s.skippedFills ? \` · \${s.skippedFills} fills need a stencil buffer\` : "");
+  window.__evgStats = s;
+} catch (e) {
+  err.textContent = String((e && e.stack) || e);
+  window.__evgStats = { error: String(e) };
+}
+</script>
+</body>
+</html>
+`;
+}
+
+const esc = (s) =>
+  String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+function indexHtml(entries, warnings) {
+  const cards = PAGES.map((p) => {
+    const shots = themesFor(p).map((t) => {
+      const e = entries.find((x) => x.page === p.id && x.theme === t.id);
+      return `
+        <figure class="shot">
+          <a href="${e.png}"><img src="${e.png}" alt="${esc(p.title)} — ${esc(t.label)}" loading="lazy"></a>
+          <figcaption>
+            <strong>${esc(t.label)}</strong> <span class="muted">${esc(t.note)}</span>
+            <a class="dl" href="${e.pdf}">PDF</a>
+            <a class="dl" href="${e.html}">HTML</a>
+            <a class="dl" href="${e.gl}">WebGL</a>
+          </figcaption>
+        </figure>`;
+    }).join("");
+    // The first theme's rendered page, which is what "open this page" means.
+    const lead = entries.find((x) => x.page === p.id && x.theme === themesFor(p)[0].id);
+    return `
+      <section class="page" id="${p.id}">
+        <header>
+          <h2><a href="${lead.html}">${esc(p.title)}</a> <a class="open" href="${lead.html}">open the page &rsaquo;</a></h2>
+          <p>${esc(p.blurb)}</p>
+          <ul class="tags">${p.shows.map((s) => `<li>${esc(s)}</li>`).join("")}</ul>
+          <p class="src"><a href="pages/${p.id}.tsx.txt">${p.id}.tsx</a> — no visual attributes; every rule is in <a href="showcase.css.txt">showcase.css</a></p>
+        </header>
+        <div class="shots">${shots}</div>
+      </section>`;
+  }).join("");
+
+  // A gallery of eleven pages needs a way in that is not scrolling. Each entry
+  // opens the page itself; the small link beside it jumps to that page's
+  // section, where its other themes and targets are.
+  const contents = PAGES.map((p) => {
+    const lead = entries.find((x) => x.page === p.id && x.theme === themesFor(p)[0].id);
+    return `<li><a class="go" href="${lead.html}">${esc(p.title)}</a> <a class="jump" href="#${p.id}" title="details, themes and targets">details</a></li>`;
+  }).join("");
+
+  const warnBlock = warnings.length
+    ? `<section class="warnings"><h2>Engine warnings from this build</h2><pre>${esc(warnings.join("\n"))}</pre></section>`
+    : `<section class="warnings"><h2>Engine warnings from this build</h2><p class="muted">None. Every declaration on every page was honoured.</p></section>`;
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>EVG showcase</title>
+<style>
+  :root {
+    --bg: #ffffff; --fg: #1a1d21; --muted: #5c6672; --line: #e3e7ec;
+    --accent: #2f6fd0; --card: #f7f9fb;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root { --bg: #12141a; --fg: #e8ecf1; --muted: #939eab; --line: #262b33;
+            --accent: #6aa8ff; --card: #171b22; }
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--fg);
+         font: 16px/1.55 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; }
+  .wrap { max-width: 1100px; margin: 0 auto; padding: 48px 24px 96px; }
+  h1 { font-size: 2rem; margin: 0 0 .3em; letter-spacing: -.02em; }
+  .lede { color: var(--muted); max-width: 62ch; margin: 0 0 8px; }
+  .meta { color: var(--muted); font-size: .85rem; margin: 24px 0 0; }
+  .page { border-top: 1px solid var(--line); padding-top: 32px; margin-top: 48px; }
+  .page h2 { font-size: 1.25rem; margin: 0 0 .35em; }
+  .page header p { color: var(--muted); max-width: 68ch; margin: 0 0 10px; }
+  .tags { list-style: none; display: flex; flex-wrap: wrap; gap: 6px; padding: 0; margin: 0 0 10px; }
+  .tags li { font-size: .72rem; letter-spacing: .02em; text-transform: uppercase;
+             color: var(--muted); border: 1px solid var(--line); border-radius: 999px; padding: 2px 9px; }
+  .src { font-size: .85rem; }
+  a { color: var(--accent); }
+  .shots { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 20px; margin-top: 18px; }
+  .shot { margin: 0; background: var(--card); border: 1px solid var(--line); border-radius: 10px; overflow: hidden; }
+  .shot img { display: block; width: 100%; height: auto; }
+  figcaption { padding: 10px 12px; font-size: .85rem; border-top: 1px solid var(--line);
+               display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+  .muted { color: var(--muted); }
+  .dl { margin-left: auto; font-size: .78rem; border: 1px solid var(--line);
+        border-radius: 6px; padding: 2px 8px; text-decoration: none; }
+  .dl + .dl { margin-left: 0; }
+  .toc { border-top: 1px solid var(--line); margin-top: 32px; padding-top: 24px; }
+  .toc h2 { font-size: .8rem; letter-spacing: .08em; text-transform: uppercase;
+            color: var(--muted); margin: 0 0 12px; font-weight: 600; }
+  .toc ul { list-style: none; padding: 0; margin: 0;
+            display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 8px 20px; }
+  .toc li { display: flex; align-items: baseline; gap: 8px; }
+  .toc .go { font-weight: 600; text-decoration: none; }
+  .toc .go:hover { text-decoration: underline; }
+  .toc .jump { font-size: .72rem; color: var(--muted); text-decoration: none;
+               border: 1px solid var(--line); border-radius: 999px; padding: 1px 8px; }
+  .page h2 a { color: inherit; text-decoration: none; }
+  .page h2 a:hover { text-decoration: underline; }
+  .open { font-size: .72rem; font-weight: 400; letter-spacing: .02em; color: var(--accent);
+          border: 1px solid var(--line); border-radius: 999px; padding: 2px 9px;
+          vertical-align: middle; margin-left: 6px; }
+  .warnings { border-top: 1px solid var(--line); padding-top: 32px; margin-top: 48px; }
+  .warnings pre { background: var(--card); border: 1px solid var(--line); border-radius: 8px;
+                  padding: 12px; overflow-x: auto; font-size: .8rem; }
+  .note { background: var(--card); border: 1px solid var(--line); border-left: 3px solid var(--accent);
+          border-radius: 8px; padding: 12px 14px; margin: 24px 0 0; font-size: .9rem; color: var(--muted); }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>EVG showcase</h1>
+  <p class="lede">
+    EVG is the layout engine behind Ranger's PDF and image writers: a print-safe
+    CSS subset — flex, grid, a stylesheet layer and real TrueType metrics —
+    with no browser anywhere in the pipeline.
+  </p>
+  <p class="lede">
+    Every page below is the same tree rendered under two themes and three
+    targets. The <code>.tsx</code> files carry no colours, sizes or spacing:
+    they say what is on the page, and one stylesheet says how it looks.
+  </p>
+  <p class="meta">Built from <code>lib/evg/showcase</code>. PDF is the print target; PNG is the raster preview; HTML is the debug view.</p>
+
+  <div class="note">
+    <strong>The chart API, running.</strong> Every page below is a rendered
+    file. <a href="chart-api/">Charts, called &mdash; live</a> is not: it loads
+    the compiled <code>VlChart</code> API into the browser and dispatches the
+    lines you type to it, method by method, drawing the answer as you edit.
+  </div>
+  <div class="note">
+    <strong>Responsive layout, live.</strong>
+    <a href="responsive/">One page, laid out on every frame</a> at the width of
+    your window. The <code>@media</code> blocks, <code>vw</code> lengths and the
+    card grid are resolved by the compiled engine in the browser, and the
+    browser is handed finished pixels &mdash; drag the window edge and watch the
+    whole pipeline run again. <a href="responsive/?painter=dom">The same page as
+    retained DOM</a>: one node per element, kept across frames and patched from
+    the engine's own diff (<code>EVGHostTree</code>) &mdash; open the dev tools
+    and the picture is a tree you can read.
+  </div>
+  <div class="note">
+    <strong>Bitmap tracer, live.</strong>
+    <a href="tracer/">Upload a JPEG/PNG</a>, tweak Potrace-style parameters
+    (<code>turdsize</code>, <code>alphamax</code>, color posterize) and
+    vectorize in the browser with the compiled <code>EvgBitmapTracer</code>.
+    Nothing is uploaded — the image stays on the page.
+  </div>
+
+  <nav class="toc" aria-label="Pages">
+    <h2>Pages</h2>
+    <ul>${contents}</ul>
+  </nav>
+
+  ${cards}
+
+  ${warnBlock}
+
+  <div class="note">
+    <strong>Known limits, visible here.</strong> The raster target decodes JPEGs
+    with the repository's own decoder, which shows block artefacts — the PDF
+    path embeds the original file untouched, so print output is unaffected.
+  </div>
+</div>
+</body>
+</html>
+`;
+}
+
+// ---------------------------------------------------------------------------
+
+fs.rmSync(OUT, { recursive: true, force: true });
+fs.mkdirSync(path.join(OUT, "pages"), { recursive: true });
+fs.mkdirSync(path.join(OUT, "gl", "fonts"), { recursive: true });
+fs.mkdirSync(TOOLS, { recursive: true });
+
+process.stdout.write("Compiling EVG tools...\n");
+compile("./gallery/pdf_writer/src/tools/evg_pdf_tool.rgr", "evg_pdf_tool.js");
+compile("./gallery/pdf_writer/src/tools/evg_png_tool.rgr", "evg_png_tool.js");
+compile("./gallery/pdf_writer/src/tools/evg_html_tool.rgr", "evg_html_tool.js");
+compile("./gallery/pdf_writer/src/tools/evg_displaylist_tool.rgr", "evg_displaylist_tool.js");
+
+
+/**
+ * Copy the photos a display list refers to next to the viewer, and rewrite the
+ * list to point at the copies.
+ *
+ * The `src` in a display list is the path the AUTHOR wrote, relative to the
+ * page source — `../../../pdf_writer/assets/images/…`. That resolves in the
+ * repository and nowhere else, so the published viewer fetched four 404s and
+ * drew a page with holes in it. The PDF and PNG targets never hit this: they
+ * read the file at render time and embed the pixels.
+ */
+function publishImages(jsonPath) {
+  const doc = JSON.parse(fs.readFileSync(jsonPath, "utf8"));
+  const dir = path.join(OUT, "gl", "images");
+  let changed = false;
+  for (const cmd of doc.list.cmds) {
+    if (cmd.k !== 2 || !cmd.src) continue;
+    const abs = path.resolve(HERE, "pages", cmd.src);
+    if (!fs.existsSync(abs)) {
+      // Left pointing at the original, so the viewer reports it as missing
+      // rather than silently drawing nothing.
+      continue;
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    // Keyed by full path, so two different photos with the same basename do
+    // not overwrite each other.
+    let name = imageNames.get(abs);
+    if (!name) {
+      const base = path.basename(abs);
+      name = imageNames.has(base) ? `${imageNames.size}-${base}` : base;
+      imageNames.set(abs, name);
+      imageNames.set(base, true);
+      fs.copyFileSync(abs, path.join(dir, name));
+    }
+    cmd.src = `images/${name}`;
+    changed = true;
+  }
+  if (changed) fs.writeFileSync(jsonPath, JSON.stringify(doc), "utf8");
+}
+const imageNames = new Map();
+
+const entries = [];
+const allWarnings = [];
+
+for (const page of PAGES) {
+  for (const theme of themesFor(page)) {
+    const stem = `${page.id}-${theme.id}`;
+    process.stdout.write(`  ${stem}\n`);
+    const png = `${stem}.png`;
+    const json = `${stem}.json`;
+    const pdf = `${stem}.pdf`;
+    const html = `${stem}.html`;
+    allWarnings.push(...render("evg_png_tool.js", page.id, theme.id, path.join(OUT, png)));
+    allWarnings.push(...render("evg_pdf_tool.js", page.id, theme.id, path.join(OUT, pdf)));
+    // The same page as draw commands, for the WebGL viewer.
+    allWarnings.push(...render("evg_displaylist_tool.js", page.id, theme.id, path.join(OUT, "gl", json)));
+    publishImages(path.join(OUT, "gl", json));
+    // -embed inlines the TTFs as data URIs. Without it the page references
+    // font files by path, which resolves on the build machine and nowhere
+    // else — the browser then falls back to a system face, wraps text where
+    // EVG did not, and the absolutely-positioned boxes land on the headings.
+    allWarnings.push(...render("evg_html_tool.js", page.id, theme.id, path.join(OUT, html), ["-embed"]));
+    entries.push({ page: page.id, theme: theme.id, png, pdf, html, gl: `gl/view.html?list=${json}` });
+  }
+  // Source, served as text so the gallery can link to what produced the page.
+  fs.copyFileSync(
+    path.join(HERE, "pages", `${page.id}.tsx`),
+    path.join(OUT, "pages", `${page.id}.tsx.txt`)
+  );
+}
+fs.copyFileSync(CSS, path.join(OUT, "showcase.css.txt"));
+
+// ---- WebGL viewer ---------------------------------------------------------
+// The renderer itself, the faces it needs, and a page to put them together.
+// Fonts are copied rather than linked: the published site has no access to the
+// repository tree, and the whole point is that these are the same TTFs the
+// layout was measured with.
+fs.copyFileSync(path.join(ROOT, "lib/evg/gl/evg-webgl.js"), path.join(OUT, "gl", "evg-webgl.js"));
+const FONTS = path.join(ROOT, "gallery/pdf_writer/assets/fonts");
+const FACES = [
+  ["Cinzel", "Cinzel/Cinzel-Regular.ttf"],
+  ["Cinzel-Bold", "Cinzel/Cinzel-Bold.ttf"],
+  ["Noto Sans", "Noto_Sans/NotoSans-Regular.ttf"],
+  ["Noto Sans-Bold", "Noto_Sans/NotoSans-Bold.ttf"],
+  ["Josefin Sans", "Josefin_Sans/JosefinSans-Regular.ttf"],
+  ["Josefin Sans-Bold", "Josefin_Sans/JosefinSans-Bold.ttf"],
+];
+const faceCss = [];
+for (const [family, rel] of FACES) {
+  const src = path.join(FONTS, rel);
+  if (!fs.existsSync(src)) continue;
+  const base = "fonts/" + path.basename(rel);
+  fs.copyFileSync(src, path.join(OUT, "gl", base));
+  faceCss.push(`@font-face{font-family:"${family}";src:url("${base}")}`);
+}
+fs.writeFileSync(path.join(OUT, "gl", "view.html"), viewerHtml(faceCss.join("\n  ")), "utf8");
+
+// ---- the live page --------------------------------------------------------
+// The rest of this gallery is rendered ahead of time; this one runs. The chart
+// API is compiled to a browser bundle and the page dispatches what a reader
+// types to the real methods — which is the one thing a picture of a chart
+// cannot demonstrate.
+{
+  const LIVE = path.join(OUT, "chart-api");
+  fs.mkdirSync(LIVE, { recursive: true });
+  compile(path.join(ROOT, "gallery/vela/tools/vela_chart_web.rgr"), "vela_chart_api.js");
+  const bundlePath = path.join(TOOLS, "vela_chart_api.js");
+  // The shebang is for a shell, and a `<script>` is not one: left in, the
+  // browser stops at the `#` and the page loads nothing.
+  const bundle = fs.readFileSync(bundlePath, "utf8").replace(/^#![^\n]*\n/, "");
+  // A browser has no `require`, and a file-system call compiles fine and fails
+  // only when somebody opens the page. Loading it here with `require`
+  // undefined is a stricter check than grepping for one.
+  {
+    const previous = globalThis.require;
+    globalThis.require = undefined;
+    const found = (0, eval)(bundle + "; typeof VelaChartApi");
+    globalThis.require = previous;
+    if (found !== "function") {
+      throw new Error("vela_chart_api.js does not define VelaChartApi without require()");
+    }
+  }
+  // The API classes go out with it, not just the entry point: the page's
+  // JavaScript mode calls `chart.bar().x("region")` on the compiled
+  // `VlChart` itself, so what a reader types reaches the same methods the
+  // Ranger interpreter beside it dispatches to.
+  fs.writeFileSync(path.join(LIVE, "vela_chart_api.js"),
+    "// GENERATED from gallery/vela/tools/vela_chart_web.rgr — do not edit.\n"
+    + "(function () {\n" + bundle + "\n;globalThis.VelaChartApi = VelaChartApi;"
+    + "\n;globalThis.Vela = { VelaChartApi: VelaChartApi, VlChart: VlChart,"
+    + " VlChartMark: VlChartMark, VlDataset: VlDataset, VlDataRow: VlDataRow, VlJson: VlJson };\n})();\n");
+  fs.copyFileSync(path.join(ROOT, "gallery/vela/web/chart_api.html"), path.join(LIVE, "index.html"));
+  process.stdout.write("  chart-api/ (live)\n");
+}
+
+// ---- live bitmap tracer ---------------------------------------------------
+// Same idea as chart-api/: a page that runs the compiled library in the
+// browser. Build logic lives in lib/evg/web/tracer/build.mjs so it can
+// also be invoked alone during development.
+{
+  execFileSync(process.execPath, [
+    path.join(ROOT, "lib/evg/web/tracer/build.mjs"),
+    "--out",
+    path.join(OUT, "tracer"),
+  ], { cwd: ROOT, stdio: "inherit" });
+  process.stdout.write("  tracer/ (live)\n");
+}
+
+// ---- live responsive page --------------------------------------------------
+// The third page that runs rather than being rendered, and the only one whose
+// LAYOUT is the thing running: the compiled engine lays the page out again at
+// whatever width the reader's window is.
+{
+  execFileSync(process.execPath, [
+    path.join(ROOT, "lib/evg/web/responsive/build.mjs"),
+    "--out",
+    path.join(OUT, "responsive"),
+  ], { cwd: ROOT, stdio: "inherit" });
+  process.stdout.write("  responsive/ (live)\n");
+}
+
+const unique = [...new Set(allWarnings)];
+fs.writeFileSync(path.join(OUT, "index.html"), indexHtml(entries, unique), "utf8");
+fs.rmSync(TOOLS, { recursive: true, force: true });
+
+process.stdout.write(
+  `\nWrote ${entries.length * 3} files + index to ${path.relative(ROOT, OUT) || OUT}\n`
+);
+if (unique.length) {
+  process.stdout.write(`Engine warnings (${unique.length}):\n`);
+  for (const w of unique) process.stdout.write(`  ${w}\n`);
+}