explico 0.12.0 → 0.13.1

package/src/reference/remark-notation.mjs

@@ -35,9 +35,12 @@ export const NOTATION_KEY_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
 
 import {
   GlyphResolutionError,
+  baseSymbolLatex,
+  derivedNotationLatex,
   resolveMathGlyphs,
   stripNotationMarkers,
 } from './math-glyphs.mjs';
+import { composeDerivedEntry } from './derived-notation.mjs';
 import {
   EQ_CAPTION_PATTERN,
   EQ_LABEL_PATTERN,
@@ -234,6 +237,26 @@ function collectPageSharedKeys(tree) {
   return keys;
 }
 
+/**
+ * A derived card (rule N23) as the remark pass records it: the frontmatter of
+ * its base and index entries composed (`derived-notation.mjs`). Only an
+ * authored `label` is known here, so the title is composed when both entries
+ * author one, which is what a table header's label needs.
+ */
+function derivedResolution(key, base, index) {
+  const entry = composeDerivedEntry({
+    key,
+    notation: derivedNotationLatex(base.notation, index.notation),
+    baseLatex: baseSymbolLatex(base.notation),
+    base: { ...base, label: base.label ?? '' },
+    index: { ...index, label: index.label ?? '', summary: index.meaning },
+  });
+  const labelled =
+    typeof base.label === 'string' && typeof index.label === 'string';
+  const { label, ...rest } = entry;
+  return { ...rest, ...(labelled ? { label } : {}), scope: 'derived' };
+}
+
 function pageGlyphScope(localDefinitions, sharedDefinitions, pageSharedKeys) {
   return [
     ...localDefinitions.values(),
@@ -246,6 +269,8 @@ function pageGlyphScope(localDefinitions, sharedDefinitions, pageSharedKeys) {
   ].map((definition) => ({
     key: definition.key,
     notation: definition.notation,
+    // Rule N23: an entry whose index is a fixed label is no family.
+    ...(definition.fixedIndex === true ? { fixedIndex: true } : {}),
   }));
 }
 
@@ -405,8 +430,9 @@ function inlineEquationNode(mathNode) {
  * in a lesson is numbered; a keyed one anchors at `#eq-<key>`, an unkeyed one
  * at its positional `#eq-<section>-<index>`. The visible number is a focusable
  * `<a>` sibling — never authored, never inside KaTeX — so it survives print and
- * screen readers name it "Equation 2.4". A "Copy LaTeX" button sits beside it
- * (`.keyed-equation__controls`, styled in `global.css`; titled "Copy LaTeX —
+ * screen readers name it "Equation 2.4". A "Copy LaTeX" button sits on the
+ * equation's bottom border, under the number (`.keyed-equation__copy`, styled
+ * in `global.css` and placed by `float-toolbar.ts`; titled "Copy LaTeX —
  * ‹short›" when the equation has a `\caption{}`) — the equation's own
  * copy affordance, distinct from the notation popup card's (`NotationLayer.astro`),
  * which only exists for a symbol with a registry entry, not a bare display
@@ -451,19 +477,21 @@ function equationNode(mathNode, { key, number, short }) {
             },
           },
         },
-        el(
-          'button',
-          {
-            type: 'button',
-            className: ['keyed-equation__copy'],
-            'data-eq-copy': '',
-            'data-latex': latex,
-            'aria-label': `Copy LaTeX for Equation ${number}`,
-            title: short ? `Copy LaTeX — ${short}` : 'Copy LaTeX',
-          },
-          [copyIconNode()],
-        ),
       ]),
+      // On the block's border, not beside the number: the number's toolbar
+      // (`float-toolbar.ts`) takes the room around the number.
+      el(
+        'button',
+        {
+          type: 'button',
+          className: ['keyed-equation__copy'],
+          'data-eq-copy': '',
+          'data-latex': latex,
+          'aria-label': `Copy LaTeX for Equation ${number}`,
+          title: short ? `Copy LaTeX — ${short}` : 'Copy LaTeX',
+        },
+        [copyIconNode()],
+      ),
     ],
   };
 }
@@ -581,7 +609,9 @@ function blockingComponent(tree, target) {
       node.name &&
       !TRANSPARENT_COMPONENTS.includes(node.name)
         ? node.name
-        : blocking;
+        : node.type === 'containerDirective'
+          ? `:::${node.name ?? ''}`
+          : blocking;
     for (const child of node.children) {
       const found = search(child, here);
       if (found !== undefined) return found;
@@ -593,11 +623,16 @@ function blockingComponent(tree, target) {
 
 /**
  * Why a `<Table>`/`<Figure>` on a lesson page got no number: it sits in a
- * component other than the `TRANSPARENT_COMPONENTS`, where a float is
- * illustrative, as an equation there is (`keyed-jsx-floats.mjs`).
+ * component other than the `TRANSPARENT_COMPONENTS`, or in a `:::note`
+ * aside, where a float is illustrative, as an equation there is
+ * (`keyed-jsx-floats.mjs`).
  */
 function unnumberedFloatMessage(tagName, component) {
-  const where = component ? `<${component}>` : 'another component';
+  const where = !component
+    ? 'another component'
+    : component.startsWith(':::')
+      ? `a ${component} aside`
+      : `<${component}>`;
   const noun = tagName === 'Table' ? 'table' : 'figure';
   const instead =
     tagName === 'Table'
@@ -1305,6 +1340,16 @@ function assertManifestNumberParity({
 
   for (const [key, number] of pageLabels) {
     const expected = published[key];
+    if (expected === undefined && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(key)) {
+      // The manifest left it out on purpose: `validate:content` reports the
+      // id (`<prefix>-invalid-key`), and recompiling changes nothing.
+      fail(
+        file,
+        `${slug}: the id in ${syntax(key)} is not a valid key — lowercase ` +
+          `letters, digits and hyphens only — so the manifest leaves it unnumbered. ` +
+          `Fix the id.`,
+      );
+    }
     if (expected === undefined) {
       fail(
         file,
@@ -1744,6 +1789,9 @@ export default function remarkNotation(options = {}) {
             // Suspension (rule N22) is lesson-body scope only.
             result = resolveMathGlyphs(value, bindingScope, {
               suspended: lessonId ? suspendedOperators : [],
+              // Derived cards (rule N23) are a page's own, built by the
+              // manifest for its body math — not the registry page's.
+              derive: Boolean(lessonId || nonChapterPage),
             });
           } catch (error) {
             const message =
@@ -1758,13 +1806,15 @@ export default function remarkNotation(options = {}) {
           if (result.unresolved.length > 0) {
             const unresolved = result.unresolved
               .map(
-                ({ token, start, suspended, font }) =>
+                ({ token, start, suspended, font, lenders }) =>
                   `${tokenLocation(file, node, value, start)}: "${token}"${
                     suspended
                       ? ` (${suspended} is suspended on this page, so this form needs its own entry)`
                       : font
                         ? ' (a different symbol from the plain letter; it needs its own entry)'
-                        : ''
+                        : lenders
+                          ? ` (${lenders.join(', ')} explains only its own instances with a subscript, never a bare "${token}", rule N4: give it its own entry, or \\explain{${lenders[0]}}{${token}} if it is that entry's shorthand)`
+                          : ''
                   }`,
               )
               .join(', ');
@@ -1779,9 +1829,23 @@ export default function remarkNotation(options = {}) {
 
           for (const binding of result.bindings) {
             if (binding.level === 'explicit') continue;
+            if (binding.match === 'derived') continue;
             resolve(binding.key, 'math', node);
             references.push({ key: binding.key, kind: 'math' });
           }
+          // A derived card (rule N23) uses its base and its index entry; it
+          // is recorded composed, so a table header reads its own label.
+          for (const derived of result.derived) {
+            const base = resolve(derived.base, 'math', node);
+            const index = resolve(derived.index, 'math', node);
+            references.push(
+              { key: derived.base, kind: 'math' },
+              { key: derived.index, kind: 'math' },
+            );
+            if (base && index) {
+              resolved.set(derived.key, derivedResolution(derived.key, base, index));
+            }
+          }
           replaceMathSource(node, result.latex);
         }
         return;

package/src/reference/render-lab-math.ts

@@ -2,6 +2,9 @@ import katex from './katex-delimiters.mjs';
 import { resolveMathGlyphs, stripNotationMarkers } from './math-glyphs.mjs';
 import { createNotationKatexOptions } from './katex-options.mjs';
 import { slotPlaceholder, type RenderedLabMath } from './lab-math-slot';
+import { pageOfScope, registerPageDerivedNotation } from './page-notation';
+import { indexFindings } from './gate-indices';
+import type { DerivedUse, IndexedSymbol } from './types';
 
 // Re-exported so server code keeps one import. An island imports these from
 // `lab-math-slot` instead: this module is server-only.
@@ -10,6 +13,8 @@ export { slotPlaceholder, type RenderedLabMath };
 export interface LabMathScopeDefinition {
   readonly key: string;
   readonly notation: string;
+  /** Rule N23: the entry's index is a fixed label, so it is no family. */
+  readonly fixedIndex?: true;
 }
 
 export interface RenderLabMathOptions {
@@ -26,6 +31,8 @@ interface BindResult {
   latex: string;
   bindings: ReadonlyArray<{ key: string }>;
   unresolved: ReadonlyArray<{ token: string; start: number; font?: string }>;
+  derived: readonly DerivedUse[];
+  indices: readonly IndexedSymbol[];
 }
 
 // `\slot{name}{fallback}` — `name` is a lab-slot id, `fallback` may contain one
@@ -58,9 +65,14 @@ export function renderLabMath(
     },
   );
 
+  // A table `labMathScope` built knows its page: its indexed symbols take
+  // derived cards there (rule N23), registered so the page ships them.
+  const page = pageOfScope(scope);
   let result: BindResult;
   try {
-    result = resolveMathGlyphs(forBinding, [...scope]) as BindResult;
+    result = resolveMathGlyphs(forBinding, [...scope], {
+      derive: page !== undefined,
+    }) as BindResult;
   } catch (error) {
     throw new Error(
       `Lab math failed to compile: ${
@@ -87,6 +99,17 @@ export function renderLabMath(
     );
   }
 
+  if (page?.checkIndices) {
+    const findings = indexFindings(result.indices);
+    if (findings.length > 0) {
+      throw new Error(
+        `Lab math has an index no card explains (rule N23, ${page.context}): ` +
+          `${findings.join('; ')}.\n  template: ${template.trim()}`,
+      );
+    }
+  }
+  if (page) registerPageDerivedNotation(page.locals, result.derived, page.context);
+
   let bound = result.latex;
   let copyBound = result.latex;
   slots.forEach(({ name, fallback }, index) => {
@@ -104,10 +127,11 @@ export function renderLabMath(
     copyBound = copyBound.replace(sentinel, slotPlaceholder(name));
   });
 
-  const html = katex.renderToString(
-    bound,
-    createNotationKatexOptions({ displayMode: display }),
-  );
+  // The site search indexes a formula's glyphs, not its MathML copy and the
+  // LaTeX annotation in it (`rehype-fail-katex-errors.mjs`).
+  const html = katex
+    .renderToString(bound, createNotationKatexOptions({ displayMode: display }))
+    .replaceAll('<span class="katex-mathml">', '<span class="katex-mathml" data-pagefind-ignore="">');
 
   return {
     html,

package/src/reference/sections-validate.ts

@@ -10,7 +10,7 @@
  */
 import type { MathGateDiagnostic } from './gate-math';
 import { lessonLine } from './gate-prose-notation';
-import { parseSectionRef } from './sections.mjs';
+import { parseSectionRef, scanOutlineBlocks } from './sections.mjs';
 
 export interface SectionRefLessonInput {
   /** Lesson slug, e.g. `motion/position-and-coordinates`. */
@@ -36,10 +36,19 @@ function withoutCode(text: string): string {
 function unresolved(
   ref: { readonly lesson?: string; readonly key: string },
   lessonExists: boolean,
+  pages: ReadonlySet<string>,
 ): string {
   const written = ref.lesson
     ? `[[${ref.lesson}#sec-${ref.key}]]`
     : `[[sec-${ref.key}]]`;
+  const page = ref.lesson?.replace(/\/index$/, '');
+  if (page !== undefined && !lessonExists && pages.has(page)) {
+    return (
+      `${written} names ${page}, a page that is not a chapter: a section reference ` +
+      `reaches a chapter's top-level headings only (rule S10). Link the heading ` +
+      `with a Markdown link instead, [its words](/${page}/#${ref.key}).`
+    );
+  }
   if (ref.lesson && !lessonExists) {
     return `${written} names lesson ${ref.lesson}, which does not exist.`;
   }
@@ -52,10 +61,17 @@ function unresolved(
   );
 }
 
-/** One `sec-ref-resolves` error per `[[sec-…]]` that names no heading. */
+/**
+ * One `sec-ref-resolves` error per `[[sec-…]]` that names no heading.
+ * `pageSlugs` are the pages that are not chapters (`motion/index`), which a
+ * section reference cannot reach; the message says so instead of calling the
+ * page missing.
+ */
 export function validateSectionRefs(
   lessons: readonly SectionRefLessonInput[],
+  pageSlugs: readonly string[] = [],
 ): MathGateDiagnostic[] {
+  const pages = new Set(pageSlugs.map((slug) => slug.replace(/\/index$/, '')));
   const headingsByLesson = new Map(
     lessons.map((lesson) => [lesson.slug, new Set(lesson.headingSlugs)]),
   );
@@ -73,9 +89,57 @@ export function validateSectionRefs(
         file: lesson.file,
         line: lessonLine(lesson, match.index ?? 0),
         token: match[0],
-        message: unresolved(ref, headings !== undefined),
+        message: unresolved(ref, headings !== undefined, pages),
       });
     }
   }
   return diagnostics;
 }
+
+export interface HeadingAnchorLessonInput {
+  readonly file: string;
+  readonly body: string;
+  readonly bodyLine?: number;
+  /** The lesson's outline headings in order (`manifest.lessons[].headings`). */
+  readonly headings: readonly { readonly slug: string; readonly text: string }[];
+  /** Every anchor the engine writes on the page, with what it belongs to. */
+  readonly anchors: ReadonlyMap<string, string>;
+}
+
+/**
+ * One `heading-anchor-collision` error per heading whose anchor the engine
+ * already gives something else on the page — `## References` on a page that
+ * cites (the generated References section is `#references`), or `## Tab x`
+ * beside `<Table id="x">` (`#tab-x`). Two elements with one id send every link
+ * to the first, and the LaTeX export defines the label twice.
+ */
+export function validateHeadingAnchors(
+  lessons: readonly HeadingAnchorLessonInput[],
+): MathGateDiagnostic[] {
+  const diagnostics: MathGateDiagnostic[] = [];
+  for (const lesson of lessons) {
+    const offsets = scanOutlineBlocks(lesson.body)
+      .filter((block) => block.kind === 'heading')
+      .map((block) => block.index);
+    lesson.headings.forEach((heading, index) => {
+      const owner = lesson.anchors.get(heading.slug);
+      if (owner === undefined) return;
+      const advice =
+        heading.slug === 'references'
+          ? 'Rename the heading, or drop it: the References section is generated from the page’s citations.'
+          : `Rename the heading, or give ${owner} another id.`;
+      diagnostics.push({
+        context: 'structure',
+        code: 'heading-anchor-collision',
+        severity: 'error',
+        file: lesson.file,
+        line: lessonLine(lesson, offsets[index] ?? 0),
+        token: heading.text,
+        message:
+          `The heading "${heading.text}" gets the anchor #${heading.slug}, which ${owner} ` +
+          `already has on this page, so a link to either lands on the first. ${advice}`,
+      });
+    });
+  }
+  return diagnostics;
+}

package/src/reference/sections.mjs

@@ -27,6 +27,8 @@
  */
 
 import { rehypeHeadingIds } from '@astrojs/markdown-remark';
+import katex from 'katex';
+import { createNotationKatexOptions } from './katex-options.mjs';
 import { headingCardTier, stripHeadingMarker } from './rehype-heading-anchors.mjs';
 
 /** The deepest heading level numbered when a course sets nothing (`####`). */
@@ -113,19 +115,18 @@ const ATX_HEADING = /^[ \t]{0,3}(#{1,6})(?:[ \t]+([^\n]*?))?(?:[ \t]+#+)?[ \t]*$
 const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
 
 /**
- * The text a heading's source renders as, near enough to slug it the way
- * Astro would: markup goes, the words stay. Inline code and math keep their
- * source (math renders as KaTeX, whose text is no use as a slug); a notation
- * term keeps its key; a link keeps its text; an image, a citation and an MDX
+ * A heading source's text, with `math` and `term` deciding what a `$…$` span
+ * and a `[[key]]` contribute. Markup goes, the words stay; inline code keeps
+ * its source; a link keeps its text; an image, a citation and an MDX
  * expression contribute nothing; the authoring marker is dropped.
  */
-export function headingPlainText(source) {
+function headingText(source, { math, term }) {
   const literals = [];
   const keep = (value) => `\u0000${literals.push(value) - 1}\u0000`;
   let text = stripHeadingMarker(source ?? '')
     .replace(/(`+)([\s\S]*?[^`])\1(?!`)/g, (_, _ticks, code) => keep(code.trim()))
-    .replace(/\$([^$\n]+)\$/g, (_, latex) => keep(latex.trim()))
-    .replace(/\[\[\s*([^\][]+?)\s*\]\]/g, (_, key) => keep(key))
+    .replace(/\$([^$\n]+)\$/g, (_, latex) => keep(math(latex.trim())))
+    .replace(/\[\[\s*([^\][]+?)\s*\]\]/g, (_, key) => keep(term(key)))
     .replace(/\[@[^\]]*\]/g, '')
     .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
     .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
@@ -138,17 +139,84 @@ export function headingPlainText(source) {
     .replace(/(^|[^\w])_(?=\S)([\s\S]*?\S)_(?!\w)/g, '$1$2')
     .replace(/~~(?=\S)([\s\S]*?\S)~~/g, '$1')
     .replace(/\\([!-/:-@[-`{-~])/g, '$1')
-    .replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (entity, name) => {
-      if (name[0] !== '#') return ENTITIES[name.toLowerCase()] ?? entity;
-      const code = name[1] === 'x' || name[1] === 'X'
-        ? Number.parseInt(name.slice(2), 16)
-        : Number.parseInt(name.slice(1), 10);
-      return Number.isFinite(code) ? String.fromCodePoint(code) : entity;
-    });
+    .replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (entity, name) => decodeEntity(entity, name));
   text = text.replace(/\u0000(\d+)\u0000/g, (_, index) => literals[Number(index)]);
   return text.replace(/\s+/g, ' ').trim();
 }
 
+function decodeEntity(entity, name) {
+  if (name[0] !== '#') return ENTITIES[name.toLowerCase()] ?? entity;
+  const code = name[1] === 'x' || name[1] === 'X'
+    ? Number.parseInt(name.slice(2), 16)
+    : Number.parseInt(name.slice(1), 10);
+  return Number.isFinite(code) ? String.fromCodePoint(code) : entity;
+}
+
+/**
+ * The text a heading's source slugs as, near enough to the way Astro would:
+ * math as it reads, a notation term its key. A heading's anchor is made from
+ * it, so a plain heading keeps the id it always had; math reads as it renders
+ * (`mathSlugText`), so `## The range $\explain{motion.range}{R}$` is
+ * `#the-range-r` and not `#the-range-explainmotionranger`.
+ */
+export function headingPlainText(source) {
+  return headingText(source, { math: mathSlugText, term: (key) => key });
+}
+
+/** A Greek letter as LaTeX names it, for a slug that stays in ASCII. */
+const GREEK_NAMES = {
+  α: 'alpha', β: 'beta', γ: 'gamma', δ: 'delta', ε: 'epsilon', ϵ: 'epsilon', ζ: 'zeta', η: 'eta',
+  θ: 'theta', ϑ: 'theta', ι: 'iota', κ: 'kappa', λ: 'lambda', μ: 'mu', ν: 'nu', ξ: 'xi', ο: 'omicron',
+  π: 'pi', ϖ: 'pi', ρ: 'rho', ϱ: 'rho', σ: 'sigma', ς: 'sigma', τ: 'tau', υ: 'upsilon', φ: 'phi',
+  ϕ: 'phi', χ: 'chi', ψ: 'psi', ω: 'omega', Γ: 'Gamma', Δ: 'Delta', Θ: 'Theta', Λ: 'Lambda',
+  Ξ: 'Xi', Π: 'Pi', Σ: 'Sigma', Υ: 'Upsilon', Φ: 'Phi', Ψ: 'Psi', Ω: 'Omega',
+};
+
+/**
+ * The text a heading's math slugs as: what it reads, each Greek letter spelled
+ * as LaTeX names it. `$e^{\lambda\cos(u)}$` reads `eλcos(u)` and slugs as
+ * `elambdacosu`, the anchor its source always gave it; what changes is the
+ * markup that never shows (`\explain{motion.range}{R}` is `R`).
+ */
+function mathSlugText(latex) {
+  return mathPlainText(latex).replace(/[\u0370-\u03FF]/g, (char) => GREEK_NAMES[char] ?? char);
+}
+
+/**
+ * The text a reader sees for a math span: KaTeX's MathML without the LaTeX
+ * annotation, so `$\explain{motion.range}{R}$` reads `R` and `$v_0$` reads
+ * `v0`. Falls back to the source when KaTeX cannot render it.
+ */
+export function mathPlainText(latex) {
+  let markup;
+  try {
+    markup = katex.renderToString(latex, createNotationKatexOptions());
+  } catch {
+    return latex;
+  }
+  const mathml = /<math[\s\S]*?<\/math>/.exec(markup)?.[0] ?? '';
+  return mathml
+    .replace(/<annotation[\s\S]*?<\/annotation>/g, '')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (entity, name) => decodeEntity(entity, name))
+    .replace(/[\u200b\u2061-\u2064]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * The text a reader sees for a heading: math as it reads (`mathPlainText`)
+ * and a `[[key]]` term as its label, from `labelFor` (the page's notation),
+ * else as its key. "On this page", an unnumbered section's quoted title and a
+ * copied link name use it; the anchor is `headingPlainText`'s.
+ */
+export function headingDisplayText(source, { labelFor } = {}) {
+  return headingText(source, {
+    math: mathPlainText,
+    term: (key) => labelFor?.(key) ?? key,
+  });
+}
+
 /**
  * Anchors for a page's headings, in order, from Astro's own `rehypeHeadingIds`
  * run over their plain text: the same slugger with the same duplicate
@@ -171,18 +239,24 @@ export function slugHeadings(texts) {
 /**
  * Every top-level heading of a lesson body in document order, as the
  * manifest records it: `{ level, text, slug, number? }`. `prefix` is the
- * chapter's `‹part›.‹chapter›`; without one nothing is numbered.
+ * chapter's `‹part›.‹chapter›`; without one nothing is numbered. `text` is
+ * what a reader sees (`headingDisplayText`, with `labelFor` naming a
+ * `[[key]]` term); the `slug` is made from `headingPlainText`.
+ * `math: true` marks a heading with inline math, whose text Astro's own
+ * heading list garbles (`LayoutPageSidebar.astro` relabels it).
  */
 export function scanSectionHeadings(markdown, options = {}) {
   const found = [];
   for (const match of outlineSource(markdown).matchAll(ATX_HEADING)) {
     found.push({
       level: match[1].length,
-      text: headingPlainText(match[2] ?? ''),
+      slugText: headingPlainText(match[2] ?? ''),
+      text: headingDisplayText(match[2] ?? '', options),
+      math: /\$[^$\n]+\$/.test(stripHeadingMarker(match[2] ?? '')),
       meta: headingCardTier(match[2] ?? '') === 'meta',
     });
   }
-  const slugs = slugHeadings(found.map((heading) => heading.text));
+  const slugs = slugHeadings(found.map((heading) => heading.slugText));
   const numbers = sectionNumbers(
     found.map((heading) => heading.level),
     { ...options, unnumbered: found.map((heading) => heading.meta) },
@@ -192,6 +266,7 @@ export function scanSectionHeadings(markdown, options = {}) {
     text: heading.text,
     slug: slugs[index],
     ...(numbers[index] === undefined ? {} : { number: numbers[index] }),
+    ...(heading.math ? { math: true } : {}),
   }));
 }
 

package/src/reference/tables-validate.ts

@@ -12,7 +12,9 @@ export type TableDiagnosticCode =
   | 'tab-duplicate-key'
   | 'tab-ref-resolves'
   | 'tab-key-unused'
-  | 'tab-removed-prop';
+  | 'tab-removed-prop'
+  | 'tab-unread-prop'
+  | 'tab-several-tables';
 
 export interface TableDiagnostic {
   readonly code: TableDiagnosticCode;
@@ -33,9 +35,45 @@ export interface TableValidation extends KeyedFloatValidation {
 export function validateTables(
   lessons: readonly TableLessonInput[],
 ): TableValidation {
-  return validateKeyedFloats(lessons, {
+  const validation = validateKeyedFloats(lessons, {
     tagName: 'Table',
     prefix: 'tab',
     noun: 'table',
   }) as TableValidation;
+  const several = lessons.flatMap(severalTables);
+  return several.length === 0
+    ? validation
+    : { ...validation, diagnostics: [...validation.diagnostics, ...several] };
+}
+
+/** A pipe table's delimiter row, `| --- | :-: |`: one per pipe table. */
+const DELIMITER_ROW = /^[ \t]*\|?(?:[ \t]*:?-+:?[ \t]*\|)+(?:[ \t]*:?-+:?[ \t]*)?$/gm;
+
+/**
+ * A `<Table>` holds one table: it has one number and one caption, and a
+ * reference to it names one table. The page showed a second under the same
+ * number, and every export kept only the first (`static-tree.ts`), silently.
+ */
+function severalTables(lesson: TableLessonInput): TableDiagnostic[] {
+  const blank = (match: string) => match.replace(/[^\n]/g, ' ');
+  const body = lesson.body.replace(/```[\s\S]*?```/g, blank).replace(/\{\/\*[\s\S]*?\*\/\}/g, blank);
+  const found: TableDiagnostic[] = [];
+  for (const table of body.matchAll(/<Table\b((?:[^>"']|"[^"]*"|'[^']*')*?)(?<!\/)>([\s\S]*?)<\/Table>/g)) {
+    const inner = table[2] ?? '';
+    const count = (inner.match(DELIMITER_ROW)?.length ?? 0) + (inner.match(/<table\b/g)?.length ?? 0);
+    if (count < 2) continue;
+    const key = /\bid\s*=\s*["']([^"']*)["']/.exec(table[1] ?? '')?.[1];
+    found.push({
+      code: 'tab-several-tables',
+      severity: 'error',
+      message:
+        `${lesson.lessonId} has a <Table${key ? ` id="${key}"` : ''}> holding ${count} tables: a <Table> ` +
+        'holds one, with one number and one caption, and every export keeps only the first. Give ' +
+        'each table its own <Table id>, or join them into one.',
+      file: lesson.file,
+      lessonId: lesson.lessonId,
+      ...(key ? { key } : {}),
+    });
+  }
+  return found;
 }

package/src/reference/text-measure.ts

@@ -0,0 +1,63 @@
+/**
+ * The width of a diagram label, measured at build time.
+ *
+ * The site draws text in the reader's system font, so no width computed at
+ * build time is exact. DejaVu Sans is the widest of the common system
+ * sans-serifs (Segoe UI, San Francisco, Roboto, Helvetica, Arial, Noto Sans,
+ * Ubuntu, Cantarell), so a label measured with its advance widths
+ * (`text-widths.ts`, generated from the font) fits in every one of them.
+ * Kerning only ever narrows that, and is ignored: measured in Chromium, the
+ * table gives DejaVu Sans's own width or up to 3% more, and no label of the
+ * playground or of data-science-I is wider in Liberation Sans (Arial's
+ * metrics), Noto Sans or Lato than in DejaVu Sans.
+ */
+import { UNITS_PER_EM, WIDTH_BLOCKS } from './text-widths';
+
+const WIDTHS = new Map<number, number>();
+for (const [first, widths] of WIDTH_BLOCKS) {
+  widths.forEach((width, offset) => {
+    if (width >= 0) WIDTHS.set(first + offset, width / UNITS_PER_EM);
+  });
+}
+
+/** A character outside the table (a CJK ideograph, an emoji) is about 1em. */
+const FALLBACK_EM = 1;
+const COMBINING_MARK = /\p{M}/u;
+
+/** One character's advance, in em. */
+function advanceEm(char: string): number {
+  if (COMBINING_MARK.test(char)) return 0;
+  return WIDTHS.get(char.codePointAt(0) ?? 0) ?? FALLBACK_EM;
+}
+
+/** The advance of `text` at `fontPx`, in px, rounded up to a whole pixel. */
+export function textWidth(text: string, fontPx: number): number {
+  let em = 0;
+  for (const char of text) em += advanceEm(char);
+  return Math.ceil(em * fontPx - 1e-6);
+}
+
+/**
+ * Break `text` into lines no wider than `maxWidth` px, greedily at spaces,
+ * the way a browser wraps it. A word wider than `maxWidth` keeps a line of its
+ * own (the caller widens the box to it); a space never ends or starts a line.
+ */
+export function wrapText(text: string, maxWidth: number, fontPx: number): string[] {
+  const words = text.trim().split(/[ \t\r\n]+/u).filter(Boolean);
+  const space = textWidth(' ', fontPx);
+  const lines: string[] = [];
+  let line = '';
+  let lineWidth = 0;
+  for (const word of words) {
+    const wordWidth = textWidth(word, fontPx);
+    if (line && lineWidth + space + wordWidth > maxWidth) {
+      lines.push(line);
+      line = '';
+      lineWidth = 0;
+    }
+    line = line ? `${line} ${word}` : word;
+    lineWidth = lineWidth ? lineWidth + space + wordWidth : wordWidth;
+  }
+  if (line) lines.push(line);
+  return lines;
+}