explico 0.12.0 → 0.13.0

package/src/compiler/exports/static-tree.ts

@@ -0,0 +1,944 @@
+import { parse, parseFragment } from 'parse5';
+
+import {
+  attribute,
+  childrenOf,
+  elements,
+  hasClass,
+  inferBasePrefix,
+  isElement,
+  type HtmlElement,
+  type HtmlNode,
+} from './html-tree';
+
+/**
+ * explico's static reading tree: a built page reduced to what a reader reads,
+ * with explico's meaning kept — a float with its number and captions, a
+ * cross-reference by its target, a check by its anchor. Print exporters (the
+ * LaTeX source now, Markdown later) serialize this tree; none of them
+ * re-walks `content/` or recomputes a number.
+ *
+ * It is read off Astro's static output, where every disclosure's body, every
+ * table row and every formula's TeX already sit in the markup, whatever the
+ * reader would see collapsed. What the static page does not hold — a lab's
+ * drawing, a check's answers — comes from the capture pass and the manifest.
+ *
+ * Math keeps the author's `\explain{key}{…}` and `\slot{key}{…}` markers (the
+ * KaTeX annotation, not the stripped `data-latex`): a printer that understands
+ * them (explico's LaTeX class) needs no stripping, and one that doesn't strips
+ * them itself.
+ */
+
+export type RefKind =
+  | 'equation'
+  | 'figure'
+  | 'table'
+  | 'diagram'
+  | 'section'
+  | 'example'
+  | 'check'
+  | 'memo'
+  | 'anchor'
+  | 'page';
+
+/** A link target inside the course: a page route (base-relative, no slashes at the ends) and an anchor. */
+export interface CourseTarget {
+  readonly route: string;
+  readonly anchor: string;
+}
+
+export type Inline =
+  | { readonly kind: 'text'; readonly value: string }
+  | { readonly kind: 'emphasis'; readonly children: readonly Inline[] }
+  | { readonly kind: 'strong'; readonly children: readonly Inline[] }
+  | { readonly kind: 'superscript'; readonly children: readonly Inline[] }
+  | { readonly kind: 'subscript'; readonly children: readonly Inline[] }
+  | { readonly kind: 'code'; readonly value: string }
+  | { readonly kind: 'math'; readonly tex: string }
+  | { readonly kind: 'break' }
+  | { readonly kind: 'link'; readonly href: string; readonly children: readonly Inline[] }
+  | {
+      readonly kind: 'ref';
+      readonly refKind: RefKind;
+      readonly target: CourseTarget;
+      readonly children: readonly Inline[];
+    }
+  | { readonly kind: 'term'; readonly key: string; readonly children: readonly Inline[] }
+  | {
+      readonly kind: 'cite';
+      readonly number: string;
+      readonly anchor: string;
+      readonly sourceId?: string;
+      readonly locator?: string;
+    }
+  | { readonly kind: 'memoMark'; readonly anchor: string; readonly label: string }
+  | { readonly kind: 'noteMark'; readonly anchor: string; readonly children: readonly Inline[] };
+
+export interface TableCell {
+  readonly header: boolean;
+  readonly colspan: number;
+  readonly rowspan: number;
+  readonly align?: 'left' | 'center' | 'right';
+  readonly children: readonly Inline[];
+}
+
+export interface DiagramNodeShape {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly radius: number;
+  readonly text?: string;
+  readonly tex?: string;
+}
+
+export interface DiagramGeometry {
+  readonly width: number;
+  readonly height: number;
+  readonly nodes: readonly DiagramNodeShape[];
+  /** Each edge as its polyline, start to end; the arrowhead sits at the end. */
+  readonly edges: readonly (readonly (readonly [number, number])[])[];
+}
+
+/** What a figure shows: an image file, or something only a browser can draw. */
+export type FigurePicture =
+  | { readonly kind: 'image'; readonly src: string; readonly alt: string }
+  | { readonly kind: 'diagram'; readonly geometry: DiagramGeometry }
+  | { readonly kind: 'capture' };
+
+interface FloatBase {
+  /** The float's anchor id on its page (`fig-…`, `tab-…`, `dia-…`). */
+  readonly anchor: string;
+  readonly number: string;
+  readonly key?: string;
+  readonly short?: string;
+  /** The long caption. */
+  readonly caption: readonly Inline[];
+}
+
+export type Block =
+  | {
+      readonly kind: 'heading';
+      readonly level: number;
+      readonly anchor?: string;
+      readonly number?: string;
+      readonly children: readonly Inline[];
+    }
+  | { readonly kind: 'paragraph'; readonly children: readonly Inline[] }
+  | {
+      readonly kind: 'list';
+      readonly ordered: boolean;
+      readonly start?: number;
+      readonly items: readonly (readonly Block[])[];
+    }
+  | {
+      readonly kind: 'equation';
+      readonly anchor: string;
+      readonly number: string;
+      readonly key?: string;
+      readonly tex: string;
+    }
+  | { readonly kind: 'displayMath'; readonly tex: string }
+  | (FloatBase & {
+      readonly kind: 'figure';
+      /** The live clause a lab writes after its caption; empty in the static page. */
+      readonly live: readonly Inline[];
+      readonly picture: FigurePicture;
+      /** The lab's own accessible label, when it gives one. */
+      readonly alt?: string;
+    })
+  | (FloatBase & {
+      readonly kind: 'table';
+      readonly head: readonly (readonly TableCell[])[];
+      readonly body: readonly (readonly TableCell[])[];
+    })
+  | (FloatBase & { readonly kind: 'diagram'; readonly geometry: DiagramGeometry })
+  | {
+      readonly kind: 'memo';
+      readonly anchor: string;
+      readonly label: string;
+      readonly short?: string;
+      readonly title: readonly Inline[];
+      readonly children: readonly Block[];
+    }
+  | {
+      readonly kind: 'note';
+      readonly anchor: string;
+      readonly title: string;
+      readonly children: readonly Block[];
+    }
+  | {
+      readonly kind: 'aside';
+      readonly variant: string;
+      readonly title: readonly Inline[];
+      readonly children: readonly Block[];
+    }
+  | {
+      readonly kind: 'fold';
+      readonly title?: readonly Inline[];
+      readonly children: readonly Block[];
+    }
+  | {
+      readonly kind: 'examples';
+      readonly anchor: string;
+      readonly number: string;
+      readonly title: readonly Inline[];
+      readonly items: readonly {
+        readonly title: readonly Inline[];
+        readonly children: readonly Block[];
+      }[];
+    }
+  | {
+      readonly kind: 'check';
+      readonly anchor: string;
+      readonly number: string;
+      readonly assessmentId: string;
+      readonly title: readonly Inline[];
+    }
+  | { readonly kind: 'quote'; readonly children: readonly Block[] }
+  | { readonly kind: 'image'; readonly src: string; readonly alt: string }
+  | { readonly kind: 'code'; readonly value: string }
+  | { readonly kind: 'rule' }
+  | {
+      readonly kind: 'references';
+      readonly items: readonly {
+        readonly number: string;
+        readonly anchor: string;
+        readonly children: readonly Inline[];
+      }[];
+    };
+
+export interface NotationEntry {
+  readonly key: string;
+  readonly anchor: string;
+  readonly symbolTex?: string;
+  readonly label: readonly Inline[];
+  readonly summary: readonly Inline[];
+  readonly units?: readonly Inline[];
+  readonly formulaTex?: string;
+}
+
+export interface StaticPage {
+  /** The page's docs slug, e.g. `projectiles/optimal-launch-angle`. */
+  readonly slug: string;
+  /** Base-relative route of the page, e.g. `projectiles/optimal-launch-angle`. */
+  readonly route: string;
+  readonly title: string;
+  readonly blocks: readonly Block[];
+  /** "Notation used on this page", in the page's order. */
+  readonly notation: readonly NotationEntry[];
+  /** The notation list's page-specific remarks ("On this page, ′ is not an operator …"). */
+  readonly notationRemarks: readonly (readonly Inline[])[];
+}
+
+interface ReadContext {
+  readonly route: string;
+  readonly base: string;
+}
+
+const SKIPPED_TAGS = new Set([
+  'button',
+  'input',
+  'nav',
+  'noscript',
+  'script',
+  'select',
+  'style',
+  'svg',
+  'template',
+  'textarea',
+  'astro-island',
+]);
+
+/** Page chrome and interaction affordances that never reach paper. */
+const SKIPPED_CLASSES = [
+  'sr-only',
+  'sl-anchor-link',
+  'keyed-equation__controls',
+  'float-tools',
+  'float-caption__anchor',
+  'keyed-figure__tools-stub',
+  'short-note__collapse',
+  'notation-enhancement-help',
+  'pagination-links',
+  'explico-site-footer',
+  'lesson-breadcrumb',
+  // A part page's stats line and chapter list are navigation the site builds;
+  // a print export's own contents replace them. Its objectives stay.
+  'part-meta',
+  'part-chapters',
+];
+
+const REF_CLASSES: readonly (readonly [string, RefKind])[] = [
+  ['equation-ref', 'equation'],
+  ['figure-ref', 'figure'],
+  ['table-ref', 'table'],
+  ['diagram-ref', 'diagram'],
+  ['section-ref', 'section'],
+  ['example-ref', 'example'],
+  ['knowledge-check-ref', 'check'],
+  ['memo-ref', 'memo'],
+];
+
+function skipped(node: HtmlElement): boolean {
+  if (SKIPPED_TAGS.has(node.tagName)) return true;
+  if (attribute(node, 'aria-hidden') === 'true') return true;
+  if (attribute(node, 'data-print-omit') !== undefined) return true;
+  return SKIPPED_CLASSES.some((name) => hasClass(node, name));
+}
+
+/** All text below `node`, as a reader sees it: no screen-reader-only or hidden helpers. */
+export function readableText(node: HtmlNode): string {
+  if (!isElement(node)) {
+    return node.nodeName === '#text' ? (node as { value: string }).value : '';
+  }
+  if (skipped(node)) return '';
+  return childrenOf(node).map(readableText).join('');
+}
+
+function collapse(text: string): string {
+  return text.replace(/[ \t\r\n\f]+/gu, ' ');
+}
+
+/** The TeX source KaTeX was given, from the MathML annotation it keeps. */
+function texOf(katex: HtmlElement): string | undefined {
+  const annotation = elements(
+    katex,
+    (node) =>
+      node.tagName === 'annotation' &&
+      attribute(node, 'encoding') === 'application/x-tex',
+  )[0];
+  if (!annotation) return undefined;
+  return childrenOf(annotation)
+    .map((child) => ('value' in child ? String(child.value) : ''))
+    .join('')
+    .trim();
+}
+
+function firstByClass(root: HtmlNode, name: string): HtmlElement | undefined {
+  return elements(root, (node) => hasClass(node, name))[0];
+}
+
+function cleanRoute(pathname: string, base: string): string {
+  let path = pathname;
+  if (path.startsWith(base)) path = path.slice(base.length);
+  return path
+    .replace(/\/index\.html$/u, '')
+    .replace(/\.html$/u, '')
+    .replace(/^\/+|\/+$/gu, '');
+}
+
+/** Resolve a link to a course target, or `undefined` when it leaves the course. */
+export function courseTarget(href: string, context: ReadContext): CourseTarget | undefined {
+  const trimmed = href.trim();
+  if (trimmed.startsWith('#')) {
+    return { route: context.route, anchor: decodeURIComponent(trimmed.slice(1)) };
+  }
+  if (/^[a-z][a-z0-9+.-]*:/iu.test(trimmed) || trimmed.startsWith('//')) return undefined;
+  const page = new URL(
+    `${context.base}${context.route ? `${context.route}/` : ''}`,
+    'https://explico.invalid',
+  );
+  const url = new URL(trimmed, page);
+  return {
+    route: cleanRoute(url.pathname, context.base),
+    anchor: decodeURIComponent(url.hash.slice(1)),
+  };
+}
+
+function trimInlines(inlines: Inline[]): Inline[] {
+  const result = [...inlines];
+  while (result[0]?.kind === 'text' && !result[0].value.trim()) result.shift();
+  while (result.at(-1)?.kind === 'text' && !(result.at(-1) as { value: string }).value.trim()) {
+    result.pop();
+  }
+  const first = result[0];
+  if (first?.kind === 'text') result[0] = { kind: 'text', value: first.value.replace(/^ +/u, '') };
+  const last = result.at(-1);
+  if (last?.kind === 'text') {
+    result[result.length - 1] = { kind: 'text', value: last.value.replace(/ +$/u, '') };
+  }
+  return result;
+}
+
+function readLink(node: HtmlElement, context: ReadContext): Inline[] {
+  const href = attribute(node, 'href') ?? '';
+  const children = readInlines(node, context);
+  if (hasClass(node, 'citation-ref')) {
+    const number = attribute(node, 'data-citation-number') ?? readableText(node).replace(/\D/gu, '');
+    return [
+      {
+        kind: 'cite',
+        number,
+        anchor: href.replace(/^#/u, ''),
+        sourceId: attribute(node, 'data-citation-id'),
+        locator: attribute(node, 'data-citation-locator') || undefined,
+      },
+    ];
+  }
+  if (hasClass(node, 'memo-marker')) {
+    return [
+      {
+        kind: 'memoMark',
+        anchor: href.replace(/^#/u, ''),
+        label: attribute(node, 'data-memo-number') ?? readableText(node).trim(),
+      },
+    ];
+  }
+  if (hasClass(node, 'short-note-marker')) {
+    return [{ kind: 'noteMark', anchor: href.replace(/^#/u, ''), children }];
+  }
+  if (hasClass(node, 'notation-term')) {
+    return [{ kind: 'term', key: attribute(node, 'data-notation-key') ?? '', children }];
+  }
+  if (!href) return children;
+  const target = courseTarget(href, context);
+  if (!target) return [{ kind: 'link', href, children }];
+  const refKind =
+    REF_CLASSES.find(([name]) => hasClass(node, name))?.[1] ??
+    (target.route === context.route ? 'anchor' : 'page');
+  return [{ kind: 'ref', refKind, target, children }];
+}
+
+function readInline(node: HtmlNode, context: ReadContext): Inline[] {
+  if (!isElement(node)) {
+    if (node.nodeName !== '#text') return [];
+    const value = collapse((node as { value: string }).value);
+    return value ? [{ kind: 'text', value }] : [];
+  }
+  if (hasClass(node, 'katex')) {
+    const tex = texOf(node);
+    return tex ? [{ kind: 'math', tex }] : [];
+  }
+  if (skipped(node)) return [];
+  switch (node.tagName) {
+    case 'em':
+    case 'i':
+      return [{ kind: 'emphasis', children: readInlines(node, context) }];
+    case 'strong':
+    case 'b':
+      return [{ kind: 'strong', children: readInlines(node, context) }];
+    case 'sup':
+      if (hasClass(node, 'memo-marker-wrap')) return readInlines(node, context);
+      return [{ kind: 'superscript', children: readInlines(node, context) }];
+    case 'sub':
+      return [{ kind: 'subscript', children: readInlines(node, context) }];
+    case 'code':
+    case 'kbd':
+      return [{ kind: 'code', value: readableText(node) }];
+    case 'br':
+      return [{ kind: 'break' }];
+    case 'a':
+      return readLink(node, context);
+    default:
+      return readInlines(node, context);
+  }
+}
+
+function readInlines(node: HtmlNode, context: ReadContext): Inline[] {
+  const result: Inline[] = [];
+  for (const child of childrenOf(node)) {
+    for (const inline of readInline(child, context)) {
+      const previous = result.at(-1);
+      if (inline.kind === 'text' && previous?.kind === 'text') {
+        result[result.length - 1] = {
+          kind: 'text',
+          value: collapse(previous.value + inline.value),
+        };
+      } else {
+        result.push(inline);
+      }
+    }
+  }
+  return result;
+}
+
+/** Inline content of `node`, trimmed at both ends as a block's content is. */
+function inlineContent(node: HtmlNode | undefined, context: ReadContext): Inline[] {
+  return node ? trimInlines(readInlines(node, context)) : [];
+}
+
+function numberAttribute(node: HtmlElement, name: string): number {
+  return Number.parseFloat(attribute(node, name) ?? '0') || 0;
+}
+
+/** Node boxes and edge polylines of a built `<Diagram>`'s SVG. */
+export function readDiagramGeometry(figure: HtmlElement): DiagramGeometry | undefined {
+  const svg = elements(figure, (node) => node.tagName === 'svg' && !!attribute(node, 'viewBox'))
+    .find((node) => elements(node, (child) => hasClass(child, 'diagram-node')).length > 0);
+  if (!svg) return undefined;
+  const [, , width, height] = (attribute(svg, 'viewBox') ?? '0 0 0 0')
+    .trim()
+    .split(/[\s,]+/u)
+    .map(Number);
+  const nodes = elements(svg, (node) => hasClass(node, 'diagram-node')).flatMap((group) => {
+    const rect = elements(group, (node) => node.tagName === 'rect')[0];
+    if (!rect) return [];
+    const text = firstByClass(group, 'diagram-node-text');
+    const formula = firstByClass(group, 'diagram-node-formula');
+    const katex = formula ? elements(formula, (node) => hasClass(node, 'katex'))[0] : undefined;
+    const label = text ? collapse(readableText(text)).trim() : '';
+    const tex = katex ? texOf(katex) : undefined;
+    return [
+      {
+        x: numberAttribute(rect, 'x'),
+        y: numberAttribute(rect, 'y'),
+        width: numberAttribute(rect, 'width'),
+        height: numberAttribute(rect, 'height'),
+        radius: numberAttribute(rect, 'rx'),
+        ...(label ? { text: label } : {}),
+        ...(tex ? { tex } : {}),
+      },
+    ];
+  });
+  const edges = elements(svg, (node) => node.tagName === 'path' && hasClass(node, 'diagram-edge'))
+    .map((path) =>
+      [...(attribute(path, 'd') ?? '').matchAll(/[ML]\s*(-?[\d.]+)[\s,]+(-?[\d.]+)/gu)].map(
+        (match) => [Number(match[1]), Number(match[2])] as const,
+      ),
+    )
+    .filter((points) => points.length >= 2);
+  return { width: width ?? 0, height: height ?? 0, nodes, edges };
+}
+
+function readCaption(figcaption: HtmlElement | undefined, context: ReadContext): Inline[] {
+  if (!figcaption) return [];
+  const text = firstByClass(figcaption, 'float-caption__text');
+  return inlineContent(text, context);
+}
+
+function floatBase(node: HtmlElement, prefix: string, context: ReadContext): FloatBase {
+  const figcaption = elements(node, (child) => child.tagName === 'figcaption')[0];
+  const key = attribute(node, `data-${prefix}-key`);
+  const short = attribute(node, `data-${prefix}-short`);
+  return {
+    anchor: attribute(node, 'id') ?? '',
+    number: attribute(node, `data-${prefix}-number`) ?? '',
+    ...(key ? { key } : {}),
+    ...(short ? { short } : {}),
+    caption: readCaption(figcaption, context),
+  };
+}
+
+function readFigurePicture(body: HtmlElement | undefined): FigurePicture {
+  if (!body) return { kind: 'capture' };
+  const diagram = elements(body, (node) => node.tagName === 'figure' && hasClass(node, 'diagram'))[0];
+  if (diagram) {
+    const geometry = readDiagramGeometry(diagram);
+    if (geometry) return { kind: 'diagram', geometry };
+  }
+  const meaningful = childrenOf(body).filter(
+    (child) =>
+      (isElement(child) && !['script', 'style'].includes(child.tagName)) ||
+      (child.nodeName === '#text' && (child as { value: string }).value.trim()),
+  );
+  const only = meaningful.length === 1 && isElement(meaningful[0]!) ? meaningful[0] : undefined;
+  const image =
+    only?.tagName === 'img'
+      ? only
+      : only?.tagName === 'picture'
+        ? elements(only, (node) => node.tagName === 'img')[0]
+        : undefined;
+  if (image && attribute(image, 'src')) {
+    return { kind: 'image', src: attribute(image, 'src')!, alt: attribute(image, 'alt') ?? '' };
+  }
+  return { kind: 'capture' };
+}
+
+function readTableCells(row: HtmlElement, context: ReadContext): TableCell[] {
+  return childrenOf(row)
+    .filter((cell): cell is HtmlElement => isElement(cell) && ['td', 'th'].includes(cell.tagName))
+    .map((cell) => {
+      const style = attribute(cell, 'style') ?? '';
+      const align =
+        attribute(cell, 'align') ?? /text-align:\s*(left|center|right)/u.exec(style)?.[1];
+      return {
+        header: cell.tagName === 'th',
+        colspan: Number.parseInt(attribute(cell, 'colspan') ?? '1', 10) || 1,
+        rowspan: Number.parseInt(attribute(cell, 'rowspan') ?? '1', 10) || 1,
+        ...(align === 'left' || align === 'center' || align === 'right' ? { align } : {}),
+        children: inlineContent(cell, context),
+      };
+    });
+}
+
+function readTable(table: HtmlElement, context: ReadContext) {
+  const rows = (section: string) =>
+    elements(table, (node) => node.tagName === section)
+      .flatMap((group) =>
+        childrenOf(group).filter(
+          (row): row is HtmlElement =>
+            isElement(row) && row.tagName === 'tr' && !hasClass(row, 'keyed-table__more-row'),
+        ),
+      )
+      .map((row) => readTableCells(row, context));
+  const head = rows('thead');
+  const body = rows('tbody');
+  if (head.length === 0 && body.length === 0) {
+    return {
+      head: [],
+      body: childrenOf(table)
+        .filter((row): row is HtmlElement => isElement(row) && row.tagName === 'tr')
+        .map((row) => readTableCells(row, context)),
+    };
+  }
+  return { head, body };
+}
+
+function headingOf(wrapper: HtmlElement): HtmlElement | undefined {
+  return childrenOf(wrapper).find(
+    (child): child is HtmlElement => isElement(child) && /^h[1-6]$/u.test(child.tagName),
+  );
+}
+
+function blockTitle(heading: HtmlElement | undefined, context: ReadContext): Inline[] {
+  if (!heading) return [];
+  return inlineContent(firstByClass(heading, 'block-heading__title') ?? heading, context);
+}
+
+function readExamples(node: HtmlElement, context: ReadContext): Block {
+  const heading = elements(node, (child) => hasClass(child, 'block-heading'))[0];
+  const items = elements(node, (child) => hasClass(child, 'compact-example')).map((section) => {
+    const title = elements(section, (child) => hasClass(child, 'compact-example__heading'))[0];
+    return {
+      title: title
+        ? inlineContent(title, context)
+        : [{ kind: 'text', value: attribute(section, 'data-example-label') ?? '' } as const],
+      children: readBlocks(section, context, (child) => child !== title),
+    };
+  });
+  return {
+    kind: 'examples',
+    anchor: attribute(heading ?? node, 'id') ?? '',
+    number: (heading && attribute(heading, 'data-ex-number')) ?? '',
+    title: blockTitle(heading, context),
+    items,
+  };
+}
+
+function readNotationEntry(entry: HtmlElement, context: ReadContext): NotationEntry {
+  const key = attribute(entry, 'data-notation-entry') ?? '';
+  const symbol = elements(entry, (node) => hasClass(node, 'notation-symbol'))[0];
+  const symbolKatex = symbol ? elements(symbol, (node) => hasClass(node, 'katex'))[0] : undefined;
+  const label = elements(entry, (node) => node.tagName === 'a' && !!attribute(node, 'data-notation-link'))[0];
+  const summary = elements(entry, (node) => attribute(node, 'data-notation-summary') !== undefined)[0];
+  const units = elements(entry, (node) => attribute(node, 'data-notation-units') !== undefined)[0];
+  const formula = elements(entry, (node) => attribute(node, 'data-notation-formula') !== undefined)[0];
+  const formulaKatex = formula ? elements(formula, (node) => hasClass(node, 'katex'))[0] : undefined;
+  const unitsInlines = units
+    ? trimInlines(
+        readInlines(units, context).filter(
+          (inline) => !(inline.kind === 'strong'),
+        ),
+      )
+    : undefined;
+  const symbolTex = symbolKatex ? texOf(symbolKatex) : undefined;
+  const formulaTex = formulaKatex ? texOf(formulaKatex) : undefined;
+  return {
+    key,
+    anchor: attribute(entry, 'id') ?? `notation-${key}`,
+    ...(symbolTex ? { symbolTex } : {}),
+    label: inlineContent(label, context),
+    summary: inlineContent(summary, context),
+    ...(unitsInlines && unitsInlines.length > 0 ? { units: unitsInlines } : {}),
+    ...(formulaTex ? { formulaTex } : {}),
+  };
+}
+
+/**
+ * Convert the block-level children of `node`. Loose inline content between
+ * blocks (text directly inside a `<div>`) becomes a paragraph of its own.
+ */
+function readBlocks(
+  node: HtmlNode,
+  context: ReadContext,
+  keep: (child: HtmlNode) => boolean = () => true,
+): Block[] {
+  const blocks: Block[] = [];
+  let pending: Inline[] = [];
+  const flush = () => {
+    const content = trimInlines(pending);
+    if (content.length > 0) blocks.push({ kind: 'paragraph', children: content });
+    pending = [];
+  };
+  for (const child of childrenOf(node)) {
+    if (!keep(child)) continue;
+    const block = isElement(child) ? readBlock(child, context) : undefined;
+    if (block === undefined) {
+      pending.push(...readInline(child, context));
+      continue;
+    }
+    flush();
+    blocks.push(...block);
+  }
+  flush();
+  return blocks;
+}
+
+/** A block-level element as blocks, or `undefined` when it is inline content. */
+function readBlock(node: HtmlElement, context: ReadContext): Block[] | undefined {
+  if (hasClass(node, 'katex-display')) {
+    const katex = elements(node, (child) => hasClass(child, 'katex'))[0];
+    const tex = katex ? texOf(katex) : undefined;
+    return tex ? [{ kind: 'displayMath', tex }] : [];
+  }
+  if (skipped(node)) return [];
+  if (hasClass(node, 'notation-layer')) return [];
+  if (hasClass(node, 'keyed-equation')) {
+    const katex = elements(node, (child) => hasClass(child, 'katex'))[0];
+    const key = attribute(node, 'data-eq-key');
+    return [
+      {
+        kind: 'equation',
+        anchor: attribute(node, 'id') ?? '',
+        number: attribute(node, 'data-eq-number') ?? '',
+        ...(key ? { key } : {}),
+        tex: (katex && texOf(katex)) ?? '',
+      },
+    ];
+  }
+  if (node.tagName === 'figure' && hasClass(node, 'keyed-figure')) {
+    const body = firstByClass(node, 'keyed-figure__body');
+    const island = body ? elements(body, (child) => child.tagName === 'astro-island')[0] : undefined;
+    const figcaption = elements(node, (child) => child.tagName === 'figcaption')[0];
+    const live = figcaption ? firstByClass(figcaption, 'float-caption__state') : undefined;
+    const alt = island ? undefined : body && attribute(body, 'aria-label');
+    return [
+      {
+        kind: 'figure',
+        ...floatBase(node, 'fig', context),
+        live: inlineContent(live, context),
+        picture: readFigurePicture(body),
+        ...(alt ? { alt } : {}),
+      },
+    ];
+  }
+  if (node.tagName === 'figure' && hasClass(node, 'keyed-table')) {
+    const table = elements(node, (child) => child.tagName === 'table')[0];
+    return [
+      {
+        kind: 'table',
+        ...floatBase(node, 'tab', context),
+        ...(table ? readTable(table, context) : { head: [], body: [] }),
+      },
+    ];
+  }
+  if (node.tagName === 'figure' && hasClass(node, 'diagram')) {
+    const geometry = readDiagramGeometry(node);
+    return [
+      {
+        kind: 'diagram',
+        ...floatBase(node, 'dia', context),
+        geometry: geometry ?? { width: 0, height: 0, nodes: [], edges: [] },
+      },
+    ];
+  }
+  if (hasClass(node, 'memo-block')) {
+    const heading = elements(node, (child) => hasClass(child, 'memo-block__heading'))[0];
+    const body = firstByClass(node, 'memo-block__body');
+    const short = attribute(node, 'data-memo-short');
+    return [
+      {
+        kind: 'memo',
+        anchor: (heading && attribute(heading, 'id')) ?? `memo-${attribute(node, 'data-memo-key') ?? ''}`,
+        label: attribute(node, 'data-memo-number') ?? '',
+        ...(short ? { short } : {}),
+        title: inlineContent(heading, context),
+        children: body ? readBlocks(body, context) : [],
+      },
+    ];
+  }
+  if (node.tagName === 'aside' && hasClass(node, 'short-note')) {
+    const body = firstByClass(node, 'short-note__body');
+    return [
+      {
+        kind: 'note',
+        anchor: attribute(node, 'id') ?? '',
+        title: attribute(node, 'aria-label') ?? '',
+        children: body ? readBlocks(body, context) : [],
+      },
+    ];
+  }
+  if (node.tagName === 'aside' && hasClass(node, 'starlight-aside')) {
+    const variant =
+      /starlight-aside--([a-z]+)/u.exec(attribute(node, 'class') ?? '')?.[1] ?? 'note';
+    const title = firstByClass(node, 'starlight-aside__title');
+    const content = firstByClass(node, 'starlight-aside__content');
+    return [
+      {
+        kind: 'aside',
+        variant,
+        title: inlineContent(title, context),
+        children: content ? readBlocks(content, context) : [],
+      },
+    ];
+  }
+  if (hasClass(node, 'fold')) {
+    const label = firstByClass(node, 'fold__label');
+    const body = firstByClass(node, 'fold__body');
+    const namesFloats = attribute(node, 'data-names-floats') !== undefined;
+    return [
+      {
+        kind: 'fold',
+        ...(label && !namesFloats ? { title: inlineContent(label, context) } : {}),
+        children: body ? readBlocks(body, context) : [],
+      },
+    ];
+  }
+  if (node.tagName === 'compact-examples' || hasClass(node, 'compact-examples')) {
+    return [readExamples(node, context)];
+  }
+  if (hasClass(node, 'sl-heading-wrapper')) {
+    const heading = headingOf(node);
+    if (!heading) return readBlocks(node, context);
+    if (attribute(heading, 'data-block-kind') === 'check') {
+      const anchor = attribute(heading, 'id') ?? '';
+      return [
+        {
+          kind: 'check',
+          anchor,
+          number: attribute(heading, 'data-check-number') ?? '',
+          assessmentId: anchor.replace(/^check-/u, ''),
+          title: blockTitle(heading, context),
+        },
+      ];
+    }
+    return readBlock(heading, context) ?? [];
+  }
+  if (/^h[1-6]$/u.test(node.tagName)) {
+    if (hasClass(node, 'citations-heading')) return [];
+    const anchor = attribute(node, 'id');
+    const number = attribute(node, 'data-sec-number');
+    return [
+      {
+        kind: 'heading',
+        level: Number(node.tagName.slice(1)),
+        ...(anchor ? { anchor } : {}),
+        ...(number ? { number } : {}),
+        children: inlineContent(node, context),
+      },
+    ];
+  }
+  if (node.tagName === 'ol' && hasClass(node, 'citations-list')) {
+    return [
+      {
+        kind: 'references',
+        items: childrenOf(node)
+          .filter((item): item is HtmlElement => isElement(item) && item.tagName === 'li')
+          .map((item) => {
+            const anchor = attribute(item, 'id') ?? '';
+            return {
+              number: anchor.replace(/^cite-/u, ''),
+              anchor,
+              children: trimInlines(
+                readInlines(item, context).filter(
+                  (inline) => !(inline.kind === 'ref' && inline.target.anchor.startsWith('cite-ref-')),
+                ),
+              ),
+            };
+          }),
+      },
+    ];
+  }
+  switch (node.tagName) {
+    case 'p': {
+      const children = inlineContent(node, context);
+      return children.length > 0 ? [{ kind: 'paragraph', children }] : [];
+    }
+    case 'ul':
+    case 'ol': {
+      const start = Number.parseInt(attribute(node, 'start') ?? '', 10);
+      return [
+        {
+          kind: 'list',
+          ordered: node.tagName === 'ol',
+          ...(Number.isFinite(start) ? { start } : {}),
+          items: childrenOf(node)
+            .filter((item): item is HtmlElement => isElement(item) && item.tagName === 'li')
+            .map((item) => readBlocks(item, context)),
+        },
+      ];
+    }
+    case 'blockquote':
+      return [{ kind: 'quote', children: readBlocks(node, context) }];
+    case 'pre':
+      return [{ kind: 'code', value: readableText(node).replace(/\n$/u, '') }];
+    case 'hr':
+      return [{ kind: 'rule' }];
+    case 'img': {
+      const src = attribute(node, 'src');
+      return src ? [{ kind: 'image', src, alt: attribute(node, 'alt') ?? '' }] : [];
+    }
+    case 'table':
+      return [
+        {
+          kind: 'table',
+          anchor: attribute(node, 'id') ?? '',
+          number: '',
+          caption: [],
+          ...readTable(node, context),
+        },
+      ];
+    case 'details':
+      return readBlocks(node, context, (child) => !(isElement(child) && child.tagName === 'summary'));
+    case 'div':
+    case 'section':
+    case 'article':
+    case 'header':
+    case 'footer':
+    case 'main':
+    case 'figure':
+    case 'aside':
+    case 'dl':
+    case 'dd':
+    case 'dt':
+    case 'li':
+    case 'compact-example':
+      return readBlocks(node, context);
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Inline content from an HTML fragment of a page — a lab's live caption
+ * clause, which only exists once the lab has run.
+ */
+export function readInlineFragment(html: string, route: string, base = '/'): Inline[] {
+  return inlineContent(parseFragment(html), { route, base });
+}
+
+/** Read the static reading tree of one built page. */
+export function readStaticPage(html: string, slug: string, route: string): StaticPage {
+  const document = parse(html);
+  const base = inferBasePrefix(document);
+  const context: ReadContext = { route, base };
+  const main = elements(document, (node) => node.tagName === 'main')[0];
+  if (!main) throw new Error(`Built page ${slug} has no <main> element.`);
+  const title = elements(main, (node) => node.tagName === 'h1')[0];
+  const content = elements(main, (node) => hasClass(node, 'sl-markdown-content'))[0];
+  if (!content) throw new Error(`Built page ${slug} has no .sl-markdown-content element.`);
+  const layer = elements(
+    main,
+    (node) => hasClass(node, 'notation-layer') && attribute(node, 'data-notation-layer-id') === 'page-notation',
+  )[0];
+  const entries = layer
+    ? elements(layer, (node) => hasClass(node, 'notation-entry') && attribute(node, 'data-notation-entry') !== undefined)
+    : [];
+  const remarks = layer
+    ? elements(layer, (node) => node.tagName === 'ul' && hasClass(node, 'notation-suspended')).flatMap(
+        (list) =>
+          childrenOf(list)
+            .filter((item): item is HtmlElement => isElement(item) && item.tagName === 'li')
+            .map((item) => inlineContent(item, context)),
+      )
+    : [];
+  return {
+    slug,
+    route,
+    title: title ? collapse(readableText(title)).trim() : slug,
+    blocks: readBlocks(content, context),
+    notation: entries.map((entry) => readNotationEntry(entry, context)),
+    notationRemarks: remarks,
+  };
+}