explico 0.11.1 → 0.13.0

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;
+}

package/src/reference/text-widths.ts

@@ -0,0 +1,133 @@
+/**
+ * Advance widths of DejaVu Sans (Version 2.37), in font units.
+ * Generated by `scripts/gen-text-widths.mjs` — do not edit by hand.
+ * `-1` marks a code point the font has no glyph for.
+ */
+
+export const UNITS_PER_EM = 2048;
+
+/** `[first code point, widths of it and the code points after it]`. */
+export const WIDTH_BLOCKS: readonly (readonly [number, readonly number[]])[] = [
+  // Basic Latin
+  [
+    0x0020,
+    [
+      651, 821, 942, 1716, 1303, 1946, 1597, 563, 799, 799, 1024, 1716, 651, 739, 651, 690,
+      1303, 1303, 1303, 1303, 1303, 1303, 1303, 1303, 1303, 1303, 690, 690, 1716, 1716, 1716, 1087,
+      2048, 1401, 1405, 1430, 1577, 1294, 1178, 1587, 1540, 604, 604, 1343, 1141, 1767, 1532, 1612,
+      1235, 1612, 1423, 1300, 1251, 1499, 1401, 2025, 1403, 1251, 1403, 799, 690, 799, 1716, 1024,
+      1024, 1255, 1300, 1126, 1300, 1260, 721, 1300, 1298, 569, 569, 1186, 569, 1995, 1298, 1253,
+      1300, 1300, 842, 1067, 803, 1298, 1212, 1675, 1212, 1212, 1075, 1303, 690, 1303, 1716,
+    ],
+  ],
+  // Latin-1 Supplement, Latin Extended-A
+  [
+    0x00a0,
+    [
+      651, 821, 1303, 1303, 1303, 1303, 690, 1024, 1024, 2048, 965, 1253, 1716, 739, 2048, 1024,
+      1024, 1716, 821, 821, 1024, 1303, 1303, 651, 1024, 821, 965, 1253, 1985, 1985, 1985, 1087,
+      1401, 1401, 1401, 1401, 1401, 1401, 1995, 1430, 1294, 1294, 1294, 1294, 604, 604, 604, 604,
+      1587, 1532, 1612, 1612, 1612, 1612, 1612, 1716, 1612, 1499, 1499, 1499, 1499, 1251, 1239, 1290,
+      1255, 1255, 1255, 1255, 1255, 1255, 2011, 1126, 1260, 1260, 1260, 1260, 569, 569, 569, 569,
+      1253, 1298, 1253, 1253, 1253, 1253, 1253, 1716, 1253, 1298, 1298, 1298, 1298, 1212, 1300, 1212,
+      1401, 1255, 1401, 1255, 1401, 1255, 1430, 1126, 1430, 1126, 1430, 1126, 1430, 1126, 1577, 1300,
+      1587, 1300, 1294, 1260, 1294, 1260, 1294, 1260, 1294, 1260, 1294, 1260, 1587, 1300, 1587, 1300,
+      1587, 1300, 1587, 1300, 1540, 1298, 1876, 1423, 604, 569, 604, 569, 604, 569, 604, 569,
+      604, 569, 1208, 1138, 604, 569, 1343, 1186, 1186, 1141, 569, 1141, 569, 1141, 768, 1141,
+      700, 1151, 582, 1532, 1298, 1532, 1298, 1532, 1298, 1666, 1532, 1298, 1612, 1253, 1612, 1253,
+      1612, 1253, 2191, 2095, 1423, 842, 1423, 842, 1423, 842, 1300, 1067, 1300, 1067, 1300, 1067,
+      1300, 1067, 1251, 803, 1251, 803, 1251, 803, 1499, 1298, 1499, 1298, 1499, 1298, 1499, 1298,
+      1499, 1298, 1499, 1298, 2025, 1675, 1251, 1212, 1251, 1403, 1075, 1403, 1075, 1403, 1075, 721,
+    ],
+  ],
+  // Greek
+  [
+    0x0370,
+    [
+      1340, 1163, 1765, 1326, 570, 570, 1532, 1331, -1, -1, 1024, 1125, 1126, 1125, 690, 604,
+      -1, -1, -1, -1, 1024, 1024, 1418, 651, 1528, 1784, 836, -1, 1664, -1, 1689, 1691,
+      693, 1401, 1405, 1141, 1401, 1294, 1403, 1540, 1612, 604, 1343, 1401, 1767, 1532, 1294, 1612,
+      1540, 1235, -1, 1294, 1251, 1251, 1612, 1403, 1612, 1565, 604, 1251, 1350, 1107, 1298, 693,
+      1185, 1350, 1307, 1212, 1253, 1107, 1114, 1298, 1253, 693, 1207, 1212, 1303, 1144, 1142, 1253,
+      1233, 1300, 1202, 1298, 1233, 1185, 1351, 1183, 1351, 1715, 693, 1185, 1253, 1185, 1715, 1343,
+      1258, 1268, 1431, 1725, 1431, 1351, 1715, 1359, 1612, 1253, 1328, 1202, 1178, 939, 1351, 1351,
+      1772, 1285, 1912, 1715, 1553, 1350, 1621, 1259, 1406, 1243, 1572, 1280, 1432, 1253, 1251, 1098,
+      1359, 1300, 1126, 569, 1612, 1260, 1260, 1239, 1300, 1430, 1767, 1333, 1300, 1440, 1430, 1440,
+    ],
+  ],
+  // General Punctuation
+  [
+    0x2000,
+    [
+      1024, 2048, 1024, 2048, 675, 512, 342, 1303, 651, 409, 204, 0, 0, 0, 0, 0,
+      739, 739, 1303, 1024, 2048, 2048, 1024, 1024, 651, 651, 651, 651, 1061, 1061, 1061, 1061,
+      1024, 1024, 1208, 1208, 685, 1367, 2048, 651, 0, 0, 0, 0, 0, 0, 0, 409,
+      2748, 3554, 465, 765, 1065, 465, 765, 1065, 694, 819, 819, 1716, 994, 1087, 1024, 1646,
+      1646, 512, 2048, 1024, 342, 799, 799, 1888, 1501, 1501, 1018, 1303, 1024, 1024, 1024, 690,
+      1646, 1024, 921, 2048, 1646, 1716, 1200, 1358, 1716, 1716, 651, 1633, 1716, 651, 651, 455,
+      0, 0, 0, 0, 0, -1, -1, -1, -1, -1, 0, 0, 0, 0, 0, 0,
+    ],
+  ],
+  // superscripts and subscripts
+  [
+    0x2070,
+    [
+      821, 366, -1, -1, 821, 821, 821, 821, 821, 821, 1081, 1081, 1081, 503, 503, 816,
+      821, 821, 821, 821, 821, 821, 821, 821, 821, 821, 1081, 1081, 1081, 503, 503, -1,
+      802, 854, 847, 909, 854, 828, 872, 340, 1276, 816, 877, 764, 604, -1, -1, -1,
+    ],
+  ],
+  // currency
+  [
+    0x20a0,
+    [
+      1796, 1303, 1303, 1303, 1303, 1995, 1303, 2606, 2199, 2025, 1606, 1303, 1303, 1303, 1303, 2606,
+      1303, 1303, 1303, 1303, 1585, 1303, -1, -1, 1303, 1303, 1303, -1, -1, 1303, -1, -1,
+      -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+    ],
+  ],
+  // letterlike symbols, number forms
+  [
+    0x2100,
+    [
+      2086, 2086, 1430, 2300, 1315, 2086, 2185, 1258, 1430, 1949, -1, 2024, 1545, 1740, 1298, 1298,
+      962, 1428, 1475, 846, 1675, 1640, 2130, 2048, 1428, 1436, 1612, 1634, 1667, 1622, 1836, 1401,
+      2088, 2200, 2048, 1401, 1525, 1183, 1565, 1565, 1262, 693, 1343, 1401, 1610, 1440, 1750, 1212,
+      1240, 1610, 1178, 2190, 946, 1526, 1380, 954, 1320, 778, 1896, 2445, 1438, 1490, 1340, 1738,
+      1660, 1587, 1141, 1141, 1251, 1677, 1450, 1260, 719, 719, -1, 1597, -1, -1, 1078, -1,
+      1985, 1985, 2806, 1985, 1985, 1985, 1985, 1985, 1985, 1985, 1985, 1985, 1985, 1985, 1985, 1163,
+      604, 1008, 1412, 1890, 1401, 1889, 2293, 2697, 1879, 1403, 1911, 2317, 1141, 1430, 1577, 1767,
+      569, 937, 1305, 1662, 1212, 1661, 2029, 2397, 1677, 1212, 1684, 2052, 569, 1126, 1300, 1995,
+      2550, 1577, 2550, 1440, 1125, 1430, -1, -1, -1, 1985, -1, -1, -1, -1, -1, -1,
+    ],
+  ],
+  // arrows, mathematical operators
+  [
+    0x2190,
+    [
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1401, 1303, 1059, 1294, 1294, 1784, 1370, 1370, 1784, 1784, 1470, 1784, 1784, 1470, 1303, 1550,
+      1550, 1380, 1716, 1716, 1716, 690, 1304, 1716, 1282, 1282, 1305, 1305, 1305, 1463, 1706, 1716,
+      1836, 1836, 1716, 1024, 1024, 1024, 1024, 1499, 1499, 1499, 1499, 1067, 1616, 2165, 1067, 1616,
+      2165, 1067, 1067, 1067, 1303, 1303, 533, 1303, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      768, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1718, 1718, 2048, 2048, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 2144, 2144, 950, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1499, 1499, 1499, 1716,
+      1716, 1716, 1716, 1598, 1598, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1784, 1784, 1784, 1784, 1066, 1066, 1784, 1784, 1784, 1784, 1784, 1784, 1784, 1784,
+      1716, 1716, 1716, 1716, 1716, 1716, 2048, 2048, 1716, 1716, 1066, 1499, 1499, 1499, 1716, 1716,
+      1680, 1680, 1680, 1680, 1282, 651, 1282, 1716, 2048, 2048, 2048, 2048, 2048, 1716, 1500, 1500,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 2913, 2913, 1716, 1716, 1716, 1716, 1716, 1716,
+      1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 1716, 2048, 2048,
+      2048, 2048, 2048, 1784, 1470, 1784, 1784, 1470, 1784, 1784, 2048, 1784, 1470, 1784, 1470, 1784,
+    ],
+  ],
+];

package/src/reference/types.ts

@@ -1,5 +1,3 @@
-export type EditorialStatus = 'draft' | 'in-review' | 'reviewed';
-
 export interface SourceSpan {
   readonly file: string;
   readonly line?: number;
@@ -19,7 +17,13 @@ export type NotationAlignment =
       readonly rationale: string;
     };
 
-export type NotationReferenceKind = 'prose' | 'math' | 'definition';
+/**
+ * Where a reference was written: in prose, in math, in a definition's meaning
+ * or body, or in its `formula`. A formula's references bring their cards onto
+ * the page but are no dependency: two formulas may name each other
+ * (γ = 1 − α, α = 1 − γ).
+ */
+export type NotationReferenceKind = 'prose' | 'math' | 'definition' | 'formula';
 
 /**
  * A gloss resolved by the loader (D15). Declared on a card, keyed
@@ -50,10 +54,17 @@ export interface SharedNotationDefinitionInput {
   readonly domain: string;
   readonly formula?: string;
   readonly units?: string;
+  /** Rule N23: an index entry's title for what it indexes, `{base} …`. */
+  readonly reads?: string;
+  /** Rule N23: the set a running index letter runs over. */
+  readonly range?: string;
+  /** Rule N23: as an index, a fixed label rather than a running position. */
+  readonly fixedIndex?: true;
+  /** Rule N23: an index entry's `formula` as written, `{base}` unbound. */
+  readonly formulaTemplate?: string;
   readonly sources: readonly string[];
   readonly seeAlso: readonly string[];
   readonly alignment: NotationAlignment;
-  readonly status: EditorialStatus;
   readonly aiAssisted: boolean;
   readonly body: string;
   /** References harvested from the Markdown body. */
@@ -70,6 +81,14 @@ export interface LocalNotationDefinitionInput {
   readonly summary: string;
   readonly formula?: string;
   readonly units?: string;
+  /** Rule N23: an index entry's title for what it indexes, `{base} …`. */
+  readonly reads?: string;
+  /** Rule N23: the set a running index letter runs over. */
+  readonly range?: string;
+  /** Rule N23: as an index, a fixed label rather than a running position. */
+  readonly fixedIndex?: true;
+  /** Rule N23: an index entry's `formula` as written, `{base}` unbound. */
+  readonly formulaTemplate?: string;
   readonly sources: readonly string[];
   readonly seeAlso: readonly string[];
   readonly alignment: NotationAlignment;
@@ -94,7 +113,6 @@ export interface NotationSuspension {
 
 export interface NotationLessonInput {
   readonly lessonId: string;
-  readonly status: EditorialStatus;
   readonly localDefinitions: readonly LocalNotationDefinitionInput[];
   /**
    * Decorations this page suspends (`notation.suspend`, rule N22). Optional
@@ -144,11 +162,12 @@ export type NotationDiagnosticCode =
   | 'undefined-reference'
   | 'reference-cycle'
   | 'unused-definition'
+  | 'local-shadows-shared'
+  | 'malformed-reference'
   | 'alignment-unknown-competency'
   | 'alignment-unknown-lesson'
   | 'alignment-introduction'
   | 'alignment-unavailable'
-  | 'alignment-review-state'
   | 'gloss-collides-with-card';
 
 export type DiagnosticSeverity = 'error' | 'warning' | 'info';
@@ -188,9 +207,16 @@ interface NotationDefinitionRecordBase {
   readonly scope: NotationDefinitionScope;
   readonly notation: string;
   readonly label: string;
+  /** Rule N23: an index entry's title for what it indexes, `{base} …`. */
+  readonly reads?: string;
+  /** Rule N23: the set a running index letter runs over. */
+  readonly range?: string;
+  /** Rule N23: as an index, a fixed label rather than a running position. */
+  readonly fixedIndex?: true;
+  /** Rule N23: an index entry's `formula` as written, `{base}` unbound. */
+  readonly formulaTemplate?: string;
   readonly seeAlso: readonly string[];
   readonly alignment: NotationAlignment;
-  readonly status: EditorialStatus;
   readonly source: SourceSpan;
   readonly resolvedReferences: readonly ResolvedNotationReference[];
 }
@@ -226,7 +252,6 @@ export interface NotationBinding {
 
 export interface NotationPageBundle {
   readonly lessonId: string;
-  readonly status: EditorialStatus;
   readonly source: SourceSpan;
   readonly bindings: readonly NotationBinding[];
   readonly definitionIds: readonly string[];
@@ -245,3 +270,45 @@ export interface NotationRegistry {
   readonly backlinks: readonly NotationBacklink[];
   readonly diagnostics: readonly NotationDiagnostic[];
 }
+
+/** A derived card a math source uses (rule N23): `key` is `<base>.sub.<index>`. */
+export interface DerivedUse {
+  readonly key: string;
+  readonly base: string;
+  readonly index: string;
+}
+
+/**
+ * How one symbol with a subscript is explained (rule N23), as
+ * `resolveMathGlyphs` reports it in `indices`.
+ */
+export interface IndexedSymbol {
+  readonly token: string;
+  readonly start: number;
+  readonly end: number;
+  readonly base: string;
+  readonly index: string;
+  readonly how:
+    | 'whole-form'
+    | 'family'
+    | 'derived'
+    | 'inside-form'
+    | 'explicit'
+    | 'swallowed'
+    | 'inside-wrap'
+    | 'composed'
+    | 'unresolved';
+  readonly key: string | null;
+  readonly explained: boolean;
+  readonly baseExplained: boolean;
+  /** The parts no card explains: the base first, when it has none, then each slot. */
+  readonly unexplained: readonly string[];
+  /** Running index letters (`i`, `k`, `t`) in its slots, for the index-set check. */
+  readonly running: readonly {
+    readonly letter: string;
+    readonly start: number;
+    readonly end: number;
+    readonly key: string | null;
+    readonly cover: string | null;
+  }[];
+}