explico 0.12.0 → 0.13.0

package/dist/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/dist/reference/render-lab-math.d.ts

@@ -4,6 +4,8 @@ export { slotPlaceholder } from './lab-math-slot.js';
 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;
 }
 interface RenderLabMathOptions {
     /**

package/dist/reference/render-lab-math.js

@@ -2,6 +2,8 @@ import katex from "./katex-delimiters.mjs";
 import { resolveMathGlyphs, stripNotationMarkers } from "./math-glyphs.mjs";
 import { createNotationKatexOptions } from "./katex-options.mjs";
 import { slotPlaceholder } from "./lab-math-slot.js";
+import { pageOfScope, registerPageDerivedNotation } from "./page-notation.js";
+import { indexFindings } from "./gate-indices.js";
 const SLOT_PATTERN = /\\slot\{([a-z][a-z0-9]*)\}\{((?:[^{}]|\{[^{}]*\})*)\}/g;
 const sentinelFor = (index) => `909909${index}.909909`;
 function renderLabMath(template, scope, { display = true } = {}) {
@@ -14,9 +16,12 @@ function renderLabMath(template, scope, { display = true } = {}) {
       return ` ${sentinel} `;
     }
   );
+  const page = pageOfScope(scope);
   let result;
   try {
-    result = resolveMathGlyphs(forBinding, [...scope]);
+    result = resolveMathGlyphs(forBinding, [...scope], {
+      derive: page !== void 0
+    });
   } catch (error) {
     throw new Error(
       `Lab math failed to compile: ${error instanceof Error ? error.message : String(error)}
@@ -32,6 +37,16 @@ function renderLabMath(template, scope, { display = true } = {}) {
   template: ${template.trim()}`
     );
   }
+  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("; ")}.
+  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) => {
@@ -48,10 +63,7 @@ function renderLabMath(template, scope, { display = true } = {}) {
     );
     copyBound = copyBound.replace(sentinel, slotPlaceholder(name));
   });
-  const html = katex.renderToString(
-    bound,
-    createNotationKatexOptions({ displayMode: display })
-  );
+  const html = katex.renderToString(bound, createNotationKatexOptions({ displayMode: display })).replaceAll('<span class="katex-mathml">', '<span class="katex-mathml" data-pagefind-ignore="">');
   return {
     html,
     slots: slots.map(({ name }) => name),

package/dist/reference/sections-validate.d.ts

@@ -21,7 +21,32 @@ interface SectionRefLessonInput {
     /** The anchors of the lesson's top-level headings (`manifest.lessons[].headings`). */
     readonly headingSlugs: readonly string[];
 }
-/** One `sec-ref-resolves` error per `[[sec-…]]` that names no heading. */
-declare function validateSectionRefs(lessons: readonly SectionRefLessonInput[]): MathGateDiagnostic[];
+/**
+ * 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.
+ */
+declare function validateSectionRefs(lessons: readonly SectionRefLessonInput[], pageSlugs?: readonly string[]): MathGateDiagnostic[];
+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.
+ */
+declare function validateHeadingAnchors(lessons: readonly HeadingAnchorLessonInput[]): MathGateDiagnostic[];
 
-export { type SectionRefLessonInput, validateSectionRefs };
+export { type HeadingAnchorLessonInput, type SectionRefLessonInput, validateHeadingAnchors, validateSectionRefs };

package/dist/reference/sections-validate.js

@@ -1,18 +1,23 @@
 import { lessonLine } from "./gate-prose-notation.js";
-import { parseSectionRef } from "./sections.mjs";
+import { parseSectionRef, scanOutlineBlocks } from "./sections.mjs";
 const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
 function withoutCode(text) {
   const blank = (block) => block.replace(/[^\n]/g, " ");
   return text.replace(/```[\s\S]*?```/g, blank).replace(/~~~[\s\S]*?~~~/g, blank).replace(/`[^`\n]*`/g, blank);
 }
-function unresolved(ref, lessonExists) {
+function unresolved(ref, lessonExists, pages) {
   const written = ref.lesson ? `[[${ref.lesson}#sec-${ref.key}]]` : `[[sec-${ref.key}]]`;
+  const page = ref.lesson?.replace(/\/index$/, "");
+  if (page !== void 0 && !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.`;
   }
   return `${written} names no heading: ${ref.lesson ? `lesson ${ref.lesson}` : "this lesson"} has no top-level heading anchored #${ref.key}. A heading's anchor is its text in lowercase with spaces as hyphens and punctuation dropped: \`## Two ways to name the same point\` is \`[[sec-two-ways-to-name-the-same-point]]\`.`;
 }
-function validateSectionRefs(lessons) {
+function validateSectionRefs(lessons, pageSlugs = []) {
+  const pages = new Set(pageSlugs.map((slug) => slug.replace(/\/index$/, "")));
   const headingsByLesson = new Map(
     lessons.map((lesson) => [lesson.slug, new Set(lesson.headingSlugs)])
   );
@@ -30,12 +35,34 @@ function validateSectionRefs(lessons) {
         file: lesson.file,
         line: lessonLine(lesson, match.index ?? 0),
         token: match[0],
-        message: unresolved(ref, headings !== void 0)
+        message: unresolved(ref, headings !== void 0, pages)
       });
     }
   }
   return diagnostics;
 }
+function validateHeadingAnchors(lessons) {
+  const diagnostics = [];
+  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 === void 0) return;
+      const advice = heading.slug === "references" ? "Rename the heading, or drop it: the References section is generated from the page\u2019s 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;
+}
 export {
+  validateHeadingAnchors,
   validateSectionRefs
 };

package/dist/reference/sections.d.mts

@@ -20,13 +20,26 @@ export function sectionNumbers(levels: any, { prefix, depth, unnumbered }?: {
     unnumbered?: never[] | undefined;
 }): any;
 /**
- * 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
- * expression contribute nothing; the authoring marker is dropped.
+ * 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: any): string;
+/**
+ * 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: any): any;
+/**
+ * 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: any, { labelFor }?: {}): string;
 /**
  * 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
@@ -36,9 +49,14 @@ export function slugHeadings(texts: any): any;
 /**
  * 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: any, options?: {}): {
+    math?: boolean | undefined;
     number?: any;
     level: number;
     text: string;

package/dist/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/dist/reference/tables-validate.d.ts

@@ -2,7 +2,7 @@ import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } fr
 
 /** `validateKeyedFloats` for `<Table>` — see `keyed-float-validate.ts`. */
 
-type TableDiagnosticCode = 'tab-invalid-key' | 'tab-duplicate-key' | 'tab-ref-resolves' | 'tab-key-unused' | 'tab-removed-prop';
+type TableDiagnosticCode = 'tab-invalid-key' | 'tab-duplicate-key' | 'tab-ref-resolves' | 'tab-key-unused' | 'tab-removed-prop' | 'tab-unread-prop' | 'tab-several-tables';
 interface TableDiagnostic {
     readonly code: TableDiagnosticCode;
     readonly severity: 'error' | 'warning' | 'info';

package/dist/reference/tables-validate.js

@@ -2,11 +2,34 @@ import {
   validateKeyedFloats
 } from "./keyed-float-validate.js";
 function validateTables(lessons) {
-  return validateKeyedFloats(lessons, {
+  const validation = validateKeyedFloats(lessons, {
     tagName: "Table",
     prefix: "tab",
     noun: "table"
   });
+  const several = lessons.flatMap(severalTables);
+  return several.length === 0 ? validation : { ...validation, diagnostics: [...validation.diagnostics, ...several] };
+}
+const DELIMITER_ROW = /^[ \t]*\|?(?:[ \t]*:?-+:?[ \t]*\|)+(?:[ \t]*:?-+:?[ \t]*)?$/gm;
+function severalTables(lesson) {
+  const blank = (match) => match.replace(/[^\n]/g, " ");
+  const body = lesson.body.replace(/```[\s\S]*?```/g, blank).replace(/\{\/\*[\s\S]*?\*\/\}/g, blank);
+  const found = [];
+  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;
 }
 export {
   validateTables

package/dist/reference/text-measure.d.ts

@@ -0,0 +1,10 @@
+/** The advance of `text` at `fontPx`, in px, rounded up to a whole pixel. */
+declare function textWidth(text: string, fontPx: number): number;
+/**
+ * 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.
+ */
+declare function wrapText(text: string, maxWidth: number, fontPx: number): string[];
+
+export { textWidth, wrapText };

package/dist/reference/text-measure.js

@@ -0,0 +1,41 @@
+import { UNITS_PER_EM, WIDTH_BLOCKS } from "./text-widths.js";
+const WIDTHS = /* @__PURE__ */ new Map();
+for (const [first, widths] of WIDTH_BLOCKS) {
+  widths.forEach((width, offset) => {
+    if (width >= 0) WIDTHS.set(first + offset, width / UNITS_PER_EM);
+  });
+}
+const FALLBACK_EM = 1;
+const COMBINING_MARK = new RegExp("\\p{M}", "u");
+function advanceEm(char) {
+  if (COMBINING_MARK.test(char)) return 0;
+  return WIDTHS.get(char.codePointAt(0) ?? 0) ?? FALLBACK_EM;
+}
+function textWidth(text, fontPx) {
+  let em = 0;
+  for (const char of text) em += advanceEm(char);
+  return Math.ceil(em * fontPx - 1e-6);
+}
+function wrapText(text, maxWidth, fontPx) {
+  const words = text.trim().split(/[ \t\r\n]+/u).filter(Boolean);
+  const space = textWidth(" ", fontPx);
+  const lines = [];
+  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;
+}
+export {
+  textWidth,
+  wrapText
+};