explico 0.11.1 → 0.13.0

package/src/compiler/exports/latex/capture.ts

@@ -0,0 +1,651 @@
+import { Buffer } from 'node:buffer';
+import { createServer, type Server } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { extname, join, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * The capture pass: draw each figure a browser has to draw (a hydrated lab, a
+ * course component's SVG) and print it as a vector PDF for the LaTeX source.
+ *
+ * Recipe, from the spike that tested it:
+ * 1. Serve the finished `dist/` on loopback, at the site's base path.
+ * 2. Open the page in a fresh light-mode context and fire
+ *    `explico:prepare-static-export` in `markdown` mode, which opens every
+ *    disclosure so a figure in a collapsed section gets a layout box.
+ * 3. Scroll each figure into view so its `client:visible` lab hydrates, and
+ *    wait until it has drawn and stopped changing.
+ * 4. Clone the hydrated figure into a clean page *on the same origin* that
+ *    links the site's stylesheets — hiding the rest of the live page around it
+ *    loses Plot's tick labels and blanks a diagram, and a page on another
+ *    origin cannot load the site's fonts (fonts are CORS-restricted).
+ * 5. Print that page at the figure's size: every path and label stays vector,
+ *    with its fonts embedded.
+ *
+ * Playwright is resolved from the course itself, so the browser it drives is
+ * the one the course installed for its own tests.
+ */
+
+export interface CaptureRequest {
+  /** Base-relative route of the page, e.g. `projectiles/optimal-launch-angle`. */
+  readonly route: string;
+  /** Anchor ids of the figures and diagrams to capture (`fig-…`, `dia-…`). */
+  readonly anchors: readonly string[];
+}
+
+export interface CapturedFigure {
+  /** The figure's picture as a one-page vector PDF. */
+  readonly pdf: Uint8Array;
+  /** The same picture as PNG at two device pixels per CSS pixel, when asked for. */
+  readonly png?: Uint8Array;
+  /** The caption's live clause after the lab wrote it, as HTML. */
+  readonly liveHtml: string;
+  /** Fonts some of the figure's text came from that the machine supplied, not the site. */
+  readonly machineFonts: readonly string[];
+  /** The size, in points, the figure's most common SVG label prints at in the book. */
+  readonly labelPt?: number;
+}
+
+/** By route, then by figure anchor. */
+export type CaptureResults = Map<string, Map<string, CapturedFigure>>;
+
+interface ChromiumLike {
+  launch(options?: Record<string, unknown>): Promise<BrowserLike>;
+}
+interface BrowserLike {
+  newContext(options?: Record<string, unknown>): Promise<ContextLike>;
+  close(): Promise<void>;
+}
+interface ContextLike {
+  newPage(): Promise<PageLike>;
+  /** Chromium only: the DevTools protocol, which names the fonts text was drawn with. */
+  newCDPSession?(page: PageLike): Promise<SessionLike>;
+  close(): Promise<void>;
+}
+interface SessionLike {
+  send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+  detach(): Promise<void>;
+}
+interface PageLike {
+  goto(url: string, options?: Record<string, unknown>): Promise<unknown>;
+  setContent(html: string, options?: Record<string, unknown>): Promise<void>;
+  evaluate<R, A>(fn: (arg: A) => R | Promise<R>, arg?: A): Promise<R>;
+  emulateMedia(options: Record<string, unknown>): Promise<void>;
+  pdf(options: Record<string, unknown>): Promise<Uint8Array>;
+  screenshot(options: Record<string, unknown>): Promise<Uint8Array>;
+  close(): Promise<void>;
+}
+
+/** Playwright's Chromium from the course's own dependencies, or `undefined`. */
+export async function courseChromium(projectRoot: string): Promise<ChromiumLike | undefined> {
+  const require = createRequire(join(projectRoot, 'package.json'));
+  type PlaywrightModule = { chromium?: ChromiumLike; default?: { chromium?: ChromiumLike } };
+  for (const name of ['playwright-core', 'playwright', '@playwright/test']) {
+    let path: string;
+    try {
+      path = require.resolve(name);
+    } catch {
+      continue; // Not installed under this name.
+    }
+    // Playwright is CommonJS; `require` also works where the exporter runs
+    // inside Vite's module runner (a workspace course loading explico's source).
+    try {
+      const module = require(path) as PlaywrightModule;
+      const chromium = module.chromium ?? module.default?.chromium;
+      if (chromium) return chromium;
+    } catch {
+      const module = (await import(/* @vite-ignore */ pathToFileURL(path).href)) as PlaywrightModule;
+      const chromium = module.chromium ?? module.default?.chromium;
+      if (chromium) return chromium;
+    }
+  }
+  return undefined;
+}
+
+const MIME_TYPES: Readonly<Record<string, string>> = {
+  '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.txt': 'text/plain; charset=utf-8',
+  '.xml': 'application/xml',
+  '.wasm': 'application/wasm',
+};
+
+const CAPTURE_PATH = '__explico_capture__';
+
+async function existingFile(path: string): Promise<string | undefined> {
+  try {
+    const info = await stat(path);
+    if (info.isFile()) return path;
+    if (info.isDirectory()) return existingFile(join(path, 'index.html'));
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+/** Serve `root` on loopback at `base`; resolves with the origin once listening. */
+async function serve(root: string, base: string): Promise<{ origin: string; server: Server }> {
+  const rootPath = resolve(root);
+  const server = createServer((request, response) => {
+    void (async () => {
+      let pathname = '/';
+      try {
+        pathname = decodeURIComponent(new URL(request.url ?? '/', 'http://localhost').pathname);
+      } catch {
+        response.writeHead(400).end();
+        return;
+      }
+      if (pathname.startsWith(base)) pathname = `/${pathname.slice(base.length)}`;
+      if (pathname === `/${CAPTURE_PATH}`) {
+        response.writeHead(200, { 'Content-Type': MIME_TYPES['.html']! });
+        response.end('<!doctype html><html><head></head><body></body></html>');
+        return;
+      }
+      const candidate = resolve(rootPath, `.${pathname}`);
+      if (candidate !== rootPath && !candidate.startsWith(`${rootPath}${sep}`)) {
+        response.writeHead(403).end();
+        return;
+      }
+      const file = (await existingFile(candidate)) ?? (await existingFile(`${candidate}.html`));
+      if (!file) {
+        response.writeHead(404).end();
+        return;
+      }
+      response.writeHead(200, {
+        'Content-Type': MIME_TYPES[extname(file).toLowerCase()] ?? 'application/octet-stream',
+      });
+      response.end(await readFile(file));
+    })().catch(() => {
+      if (!response.headersSent) response.writeHead(500);
+      response.end();
+    });
+  });
+  await new Promise<void>((resolveListen, rejectListen) => {
+    server.once('error', rejectListen);
+    server.listen(0, '127.0.0.1', () => resolveListen());
+  });
+  const address = server.address();
+  if (!address || typeof address === 'string') throw new Error('Capture server has no port.');
+  return { origin: `http://127.0.0.1:${address.port}`, server };
+}
+
+interface FigureSnapshot {
+  readonly html: string;
+  readonly width: number;
+  readonly height: number;
+  readonly links: readonly string[];
+  readonly styles: string;
+  readonly live: string;
+}
+
+/** Wait until a figure's lab has hydrated and its drawing has stopped changing. */
+async function settleFigure(page: PageLike, anchor: string, timeoutMs: number): Promise<void> {
+  const settled = await page.evaluate(
+    async ({ anchor: id, timeout }: { anchor: string; timeout: number }) => {
+      const figure = document.getElementById(id);
+      if (!figure) return `no element #${id}`;
+      const body = figure.querySelector('.keyed-figure__body, .diagram__body') ?? figure;
+      body.scrollIntoView({ block: 'center' });
+      const frame = () => new Promise<void>((done) => requestAnimationFrame(() => done()));
+      const started = performance.now();
+      let previous = '';
+      let stableSince = performance.now();
+      while (performance.now() - started < timeout) {
+        await frame();
+        const pending = body.querySelector('astro-island[ssr]');
+        const current = body.innerHTML;
+        if (current !== previous) {
+          previous = current;
+          stableSince = performance.now();
+        }
+        if (!pending && performance.now() - stableSince > 400) {
+          await document.fonts.ready;
+          return '';
+        }
+        await new Promise((done) => setTimeout(done, 50));
+      }
+      return body.querySelector('astro-island[ssr]')
+        ? `#${id} never hydrated`
+        : `#${id} kept changing`;
+    },
+    { anchor, timeout: timeoutMs },
+  );
+  if (settled) throw new Error(`Figure capture: ${settled} within ${timeoutMs} ms.`);
+}
+
+async function snapshotFigure(page: PageLike, anchor: string): Promise<FigureSnapshot> {
+  return page.evaluate((id: string) => {
+    const figure = document.getElementById(id)!;
+    const body = (figure.querySelector('.keyed-figure__body, .diagram__body') as HTMLElement | null) ?? figure;
+    const box = body.getBoundingClientRect();
+    // A diagram scrolls its canvas inside its body: the picture is the canvas.
+    const scrolled = [...body.querySelectorAll<HTMLElement>('*')].map((element) => element.scrollWidth);
+    const clone = figure.cloneNode(true) as HTMLElement;
+    clone.querySelectorAll('script').forEach((node) => node.remove());
+    const live = figure.querySelector('.float-caption__state');
+    return {
+      html: clone.outerHTML,
+      width: Math.ceil(Math.max(box.width, body.scrollWidth, ...scrolled)),
+      height: Math.ceil(Math.max(box.height, body.scrollHeight)),
+      links: [...document.styleSheets].flatMap((sheet) => (sheet.href ? [sheet.href] : [])),
+      styles: [...document.querySelectorAll('style')].map((node) => node.textContent ?? '').join('\n'),
+      live: live?.innerHTML ?? '',
+    };
+  }, anchor);
+}
+
+/**
+ * A figure's labels on paper are set in the book's typeface: KaTeX's
+ * Computer Modern, whose fonts explico's stylesheet loads on every page, so
+ * CI and a laptop draw the same figure. Upright Latin comes from KaTeX_Main;
+ * KaTeX_Math adds the italic Greek a label may name. A character in neither
+ * falls back to the machine's serif, which `machineFonts` reports.
+ */
+const LABEL_FONT = 'KaTeX_Main, KaTeX_Math, serif';
+
+/** The size a figure's most common label prints at, as `\footnotesize` in the book's 11 pt. */
+export const LABEL_PT = 9;
+
+/** PostScript points per CSS pixel: Chromium prints 96 px to the inch. */
+const PT_PER_PX = 0.75;
+
+const CAPTURE_STYLE = `
+@page { margin: 0 }
+html, body { margin: 0 !important; padding: 0 !important; background: #fff !important; }
+main, .sl-markdown-content { margin: 0 !important; padding: 0 !important; max-width: none !important; }
+figure { margin: 0 !important; padding: 0 !important; border: 0 !important; box-shadow: none !important; }
+figure > :not(.keyed-figure__body, .diagram__body) { display: none !important; }
+:is(.keyed-figure__body, .diagram__body) { font-family: ${LABEL_FONT}; }
+:is(.keyed-figure__body, .diagram__body) :is(svg text, svg tspan) { font-family: ${LABEL_FONT} !important; }
+:is(.keyed-figure__body, .diagram__body), :is(.keyed-figure__body, .diagram__body) :is(svg, .diagram-scroll) { overflow: visible !important; }
+`;
+
+/** The page a figure's PDF is printed on: its laid-out box, in CSS pixels. */
+interface PrintBox {
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * How many points one CSS pixel of the figure prints at in the book, once
+ * `\includegraphics[max width=\linewidth,max height=0.6\textheight]` has
+ * scaled it into the measure.
+ */
+function printedPtPerPx(box: PrintBox, measure: FigureMeasure): number {
+  const fit = Math.min(1, measure.width / (box.width * PT_PER_PX), measure.maxHeight / (box.height * PT_PER_PX));
+  return PT_PER_PX * fit;
+}
+
+/** The box to print, and the size the figure's most common label prints at. */
+interface SizedLabels extends PrintBox {
+  readonly labelPt?: number;
+}
+
+/**
+ * Size the figure's SVG labels so the most common one prints at `labelPt`
+ * after LaTeX scales the figure, every other label keeping its proportion
+ * to it. An SVG's labels are drawn in its own units, so a plot drawn wide
+ * and shown narrow prints them small; text outside an SVG keeps its size.
+ *
+ * A layout made for smaller labels has no room for larger ones. An axis
+ * title of Observable Plot moves clear of its grown tick labels, as Plot
+ * would have placed it; beyond that, labels grow only as far as they can
+ * without two of them touching that did not before. Resolves with the box
+ * to print, grown to any label that now overflows it.
+ */
+async function sizeLabels(page: PageLike, box: PrintBox, measure: FigureMeasure): Promise<SizedLabels> {
+  return page.evaluate(
+    async ({ labelPt, ptPerPx, width, height }: { labelPt: number; ptPerPx: number; width: number; height: number }) => {
+      const body = document.querySelector<HTMLElement>('.keyed-figure__body, .diagram__body');
+      if (!body) return { width, height };
+      const scaleOf = (element: SVGGraphicsElement) => {
+        const matrix = element.getScreenCTM();
+        return matrix ? Math.hypot(matrix.a, matrix.b) : 1;
+      };
+      const elements = [...body.querySelectorAll<SVGTextContentElement>('svg text, svg tspan')];
+      const own = new Map(elements.map((element) => [element, Number.parseFloat(getComputedStyle(element).fontSize)]));
+      const weights = new Map<number, number>();
+      for (const element of elements) {
+        const characters = [...element.childNodes]
+          .filter((node) => node.nodeType === Node.TEXT_NODE)
+          .reduce((count, node) => count + (node.textContent ?? '').trim().length, 0);
+        const printed = Math.round((own.get(element) ?? 0) * scaleOf(element) * ptPerPx * 10) / 10;
+        if (characters > 0 && printed > 0) weights.set(printed, (weights.get(printed) ?? 0) + characters);
+      }
+      const common = [...weights].sort((a, b) => b[1] - a[1] || b[0] - a[0])[0]?.[0];
+      if (!common) return { width, height };
+
+      // Where a label's glyphs are, on screen: its advance box across, and
+      // from cap height above the baseline to descender depth below it.
+      const texts = [...body.querySelectorAll<SVGTextElement>('svg text')];
+      const ink = (text: SVGTextElement) => {
+        const rect = text.getBoundingClientRect();
+        const size = Number.parseFloat(getComputedStyle(text).fontSize) * scaleOf(text);
+        const matrix = text.getScreenCTM();
+        if (!matrix || text.getNumberOfChars() === 0 || rect.height > 1.6 * size) {
+          return { left: rect.left, right: rect.right, top: rect.top, bottom: rect.bottom };
+        }
+        const start = text.getStartPositionOfChar(0);
+        const baseline = matrix.b * start.x + matrix.d * start.y + matrix.f;
+        return { left: rect.left, right: rect.right, top: baseline - 0.72 * size, bottom: baseline + 0.22 * size };
+      };
+      type Box = ReturnType<typeof ink>;
+      const touching = (a: Box, b: Box) =>
+        a.left < b.right - 0.5 && b.left < a.right - 0.5 && a.top < b.bottom - 0.5 && b.top < a.bottom - 0.5;
+      const contacts = () => {
+        const boxes = texts.map(ink);
+        const found = new Set<string>();
+        boxes.forEach((a, i) => boxes.slice(i + 1).forEach((b, j) => touching(a, b) && found.add(`${i}:${i + 1 + j}`)));
+        return found;
+      };
+      const before = contacts();
+
+      // Plot's axis titles and the tick labels they sit beside, with the gap between them.
+      const transforms = new Map(texts.map((text) => [text, text.getAttribute('transform')]));
+      const titles = ['x', 'y', 'fx', 'fy'].flatMap((axis) => {
+        const ticks = [...body.querySelectorAll<SVGTextElement>(`g[aria-label="${axis}-axis tick label"] text`)];
+        return [...body.querySelectorAll<SVGTextElement>(`g[aria-label="${axis}-axis label"] text`)].flatMap((title) => {
+          const box = ink(title);
+          const near = ticks.filter((tick) => {
+            const other = ink(tick);
+            return other.left < box.right && box.left < other.right;
+          });
+          if (near.length === 0) return [];
+          const boxes = near.map(ink);
+          const below = (box.top + box.bottom) / 2 > Math.max(...boxes.map((other) => (other.top + other.bottom) / 2));
+          const gap = below
+            ? box.top - Math.max(...boxes.map((other) => other.bottom))
+            : Math.min(...boxes.map((other) => other.top)) - box.bottom;
+          return [{ title, near, below, gap: Math.max(1, gap) }];
+        });
+      });
+
+      const apply = (ratio: number) => {
+        for (const element of elements) {
+          element.style.setProperty('font-size', `${(own.get(element) ?? 0) * ratio}px`, 'important');
+        }
+        for (const [text, transform] of transforms) {
+          if (transform === null) text.removeAttribute('transform');
+          else text.setAttribute('transform', transform);
+        }
+        for (const { title, near, below, gap } of titles) {
+          const box = ink(title);
+          const boxes = near.map(ink);
+          const shift = below
+            ? Math.max(0, Math.max(...boxes.map((other) => other.bottom)) + gap - box.top)
+            : Math.min(0, Math.min(...boxes.map((other) => other.top)) - gap - box.bottom);
+          if (shift === 0) continue;
+          const transform = transforms.get(title);
+          title.setAttribute('transform', `${transform ?? ''} translate(0 ${shift / scaleOf(title)})`.trim());
+        }
+      };
+      const collides = () => [...contacts()].some((pair) => !before.has(pair));
+
+      const goal = Math.min(2.5, Math.max(0.4, labelPt / common));
+      let ratio = goal;
+      apply(ratio);
+      if (goal > 1 && collides()) {
+        let [fits, fails] = [1, goal];
+        for (let step = 0; step < 8; step++) {
+          const middle = (fits + fails) / 2;
+          apply(middle);
+          if (collides()) fails = middle;
+          else fits = middle;
+        }
+        ratio = fits;
+        apply(ratio);
+      }
+      await document.fonts.ready;
+
+      // A label grown past its SVG's edge would be cut off by the page: grow
+      // the page to it, moving the figure right or down when it is left or
+      // above, and let every box between the SVG and the figure show it.
+      for (const svg of body.querySelectorAll('svg')) {
+        for (let node = svg.parentElement; node && node !== body; node = node.parentElement) {
+          node.style.setProperty('overflow', 'visible', 'important');
+        }
+      }
+      const frame = body.getBoundingClientRect();
+      let [left, top, right, bottom] = [frame.left, frame.top, frame.left + width, frame.top + height];
+      for (const element of elements) {
+        const rect = element.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) continue;
+        [left, top] = [Math.min(left, rect.left), Math.min(top, rect.top)];
+        [right, bottom] = [Math.max(right, rect.right), Math.max(bottom, rect.bottom)];
+      }
+      const [shiftX, shiftY] = [Math.ceil(frame.left - left), Math.ceil(frame.top - top)];
+      if (shiftX > 0 || shiftY > 0) {
+        document.body.style.setProperty('padding', `${shiftY}px 0 0 ${shiftX}px`, 'important');
+      }
+      return {
+        width: Math.ceil(right - left),
+        height: Math.ceil(bottom - top),
+        labelPt: Math.round(common * ratio * 10) / 10,
+      };
+    },
+    { labelPt: LABEL_PT, ptPerPx: printedPtPerPx(box, measure), width: box.width, height: box.height },
+  );
+}
+
+/**
+ * The machine's own fonts any text in the figure was drawn with: a glyph
+ * the site's fonts lack, or a lab that sets its own family. Such a figure
+ * may print differently on another machine.
+ */
+async function machineFonts(context: ContextLike, page: PageLike): Promise<string[]> {
+  if (!context.newCDPSession) return [];
+  await page.evaluate(() => {
+    for (const element of document.querySelectorAll(
+      ':is(.keyed-figure__body, .diagram__body), :is(.keyed-figure__body, .diagram__body) *',
+    )) {
+      // KaTeX's MathML copy is for screen readers, clipped out of sight.
+      if (element.closest('.katex-mathml')) continue;
+      const text = [...element.childNodes].some(
+        (node) => node.nodeType === Node.TEXT_NODE && (node.textContent ?? '').trim() !== '',
+      );
+      if (text) element.setAttribute('data-explico-capture-text', '');
+    }
+  });
+  const session = await context.newCDPSession(page);
+  try {
+    await session.send('DOM.enable');
+    await session.send('CSS.enable');
+    const { root } = (await session.send('DOM.getDocument', { depth: 0 })) as { root: { nodeId: number } };
+    const { nodeIds } = (await session.send('DOM.querySelectorAll', {
+      nodeId: root.nodeId,
+      selector: '[data-explico-capture-text]',
+    })) as { nodeIds: number[] };
+    // Each machine font, with the text of the first element it drew.
+    const found = new Map<string, string>();
+    for (const nodeId of nodeIds) {
+      const { fonts } = (await session.send('CSS.getPlatformFontsForNode', { nodeId })) as {
+        fonts: { familyName: string; isCustomFont: boolean }[];
+      };
+      for (const font of fonts) {
+        if (font.isCustomFont || found.has(font.familyName)) continue;
+        const { outerHTML } = (await session.send('DOM.getOuterHTML', { nodeId })) as { outerHTML: string };
+        const sample = outerHTML.replace(/<[^>]*>/gu, ' ').replace(/\s+/gu, ' ').trim().slice(0, 40);
+        found.set(font.familyName, sample);
+      }
+    }
+    return [...found].sort(([a], [b]) => a.localeCompare(b)).map(([family, sample]) => `${family} ("${sample}")`);
+  } finally {
+    await session.detach();
+  }
+}
+
+async function printFigure(
+  context: ContextLike,
+  origin: string,
+  snapshot: FigureSnapshot,
+  measure: FigureMeasure,
+  withPng: boolean,
+): Promise<Omit<CapturedFigure, 'liveHtml'>> {
+  const page = await context.newPage();
+  try {
+    await page.goto(`${origin}/${CAPTURE_PATH}`);
+    const links = snapshot.links
+      .map((href) => `<link rel="stylesheet" href="${href.replace(/"/gu, '&quot;')}">`)
+      .join('');
+    await page.setContent(
+      `<!doctype html><html data-theme="light"><head><meta charset="utf-8">${links}` +
+        `<style>${snapshot.styles.replace(/<\/style/giu, '<\\/style')}</style>` +
+        `<style>${CAPTURE_STYLE}</style></head><body>` +
+        `<main><div class="sl-markdown-content" style="width:${snapshot.width}px">${snapshot.html}</div></main>` +
+        `</body></html>`,
+      { waitUntil: 'load' },
+    );
+    await page.evaluate(async () => {
+      await document.fonts.ready;
+    });
+    await page.emulateMedia({ media: 'screen' });
+    const box = await sizeLabels(page, { width: snapshot.width, height: snapshot.height }, measure);
+    const fonts = await machineFonts(context, page);
+    const png = withPng
+      ? await page.screenshot({
+          type: 'png',
+          clip: { x: 0, y: 0, width: box.width, height: box.height },
+          animations: 'disabled',
+          caret: 'hide',
+        })
+      : undefined;
+    const pdf = await page.pdf({
+      width: `${box.width}px`,
+      height: `${box.height}px`,
+      printBackground: true,
+      pageRanges: '1',
+    });
+    return {
+      pdf,
+      ...(png ? { png } : {}),
+      machineFonts: fonts,
+      ...(box.labelPt ? { labelPt: box.labelPt } : {}),
+    };
+  } finally {
+    await page.close();
+  }
+}
+
+/** The book's measure, in PostScript points: the most a figure is set at. */
+export interface FigureMeasure {
+  /** `\linewidth` of the page. */
+  readonly width: number;
+  /** `0.6\textheight`, the tallest a figure is included. */
+  readonly maxHeight: number;
+}
+
+/** The measure of explico.cls on letter or A4 paper with one-inch margins. */
+export function figureMeasure(paper: 'letter' | 'a4'): FigureMeasure {
+  const inch = 72;
+  const millimetre = 72 / 25.4;
+  return paper === 'a4'
+    ? { width: (210 - 50.8) * millimetre, maxHeight: 0.6 * (297 - 50.8) * millimetre }
+    : { width: 6.5 * inch, maxHeight: 0.6 * 9 * inch };
+}
+
+/**
+ * Chromium stamps a PDF with the moment it prints it (`/CreationDate`,
+ * `/ModDate`), and LaTeX copies an included PDF's dates into its own, so
+ * no two builds would agree. Each date becomes `epoch`'s, written in the
+ * same number of bytes so the cross-reference table stays right.
+ */
+export function stampPdfDates(pdf: Uint8Array, epoch: number): Uint8Array {
+  const date = new Date(epoch * 1000).toISOString().replace(/\D/gu, '').slice(0, 14);
+  const text = Buffer.from(pdf).toString('latin1');
+  return Buffer.from(
+    text.replace(/(\/(?:CreationDate|ModDate)\s*\(D:)\d{14}/gu, (_match, key: string) => `${key}${date}`),
+    'latin1',
+  );
+}
+
+export interface CaptureOptions {
+  /** The finished build output. */
+  readonly outputRoot: string;
+  /** The site's base path, `/` or `/course/`. */
+  readonly base: string;
+  readonly chromium: ChromiumLike;
+  /** The book's measure, which sizes figure labels (letter paper's by default). */
+  readonly measure?: FigureMeasure;
+  /** Seconds since 1970 to date every figure PDF with, so a build is reproducible. */
+  readonly epoch?: number;
+  /** Also take each figure as PNG, from the same page as its PDF (Markdown). */
+  readonly png?: boolean;
+  /** Per-figure limit for hydrating and settling. */
+  readonly timeoutMs?: number;
+}
+
+/** Capture every requested figure, one browser for the whole build. */
+export async function captureFigures(
+  requests: readonly CaptureRequest[],
+  options: CaptureOptions,
+): Promise<CaptureResults> {
+  const results: CaptureResults = new Map();
+  if (requests.length === 0) return results;
+  const { origin, server } = await serve(options.outputRoot, options.base);
+  const browser = await options.chromium.launch();
+  try {
+    for (const request of requests) {
+      const context = await browser.newContext({
+        viewport: { width: 1200, height: 900 },
+        // Two device pixels per CSS pixel: the PNG a Markdown export shows.
+        deviceScaleFactor: 2,
+        colorScheme: 'light',
+        reducedMotion: 'reduce',
+        locale: 'en-US',
+      });
+      try {
+        const page = await context.newPage();
+        const path = `${options.base}${request.route ? `${request.route}/` : ''}`;
+        await page.goto(`${origin}${path}`, { waitUntil: 'load' });
+        await page.evaluate(() => {
+          window.dispatchEvent(
+            new CustomEvent('explico:prepare-static-export', { detail: { mode: 'markdown' } }),
+          );
+        });
+        const figures = new Map<string, CapturedFigure>();
+        for (const anchor of request.anchors) {
+          await settleFigure(page, anchor, options.timeoutMs ?? 30_000);
+          const snapshot = await snapshotFigure(page, anchor);
+          const printed = await printFigure(
+            context,
+            origin,
+            snapshot,
+            options.measure ?? figureMeasure('letter'),
+            options.png ?? false,
+          );
+          const pdf = options.epoch === undefined ? printed.pdf : stampPdfDates(printed.pdf, options.epoch);
+          figures.set(anchor, { ...printed, pdf, liveHtml: snapshot.live });
+        }
+        results.set(request.route, figures);
+      } catch (error) {
+        throw new Error(
+          `Could not capture the figures of ${request.route || 'the landing page'}: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      } finally {
+        await context.close();
+      }
+    }
+  } finally {
+    await browser.close();
+    await new Promise<void>((done) => server.close(() => done()));
+  }
+  return results;
+}