explico 0.13.0 → 0.14.0

package/dist/reference/decks-validate.js

@@ -0,0 +1,359 @@
+import { lessonLine } from "./gate-prose-notation.js";
+import { frameAt } from "./deck-source.js";
+const RECALL_TABLE = { eq: "equations", fig: "figures", tab: "tables", dia: "diagrams" };
+function chapterNumberOf(ref, floats) {
+  const match = RECALL_REF.exec(ref);
+  if (!match || floats === void 0) return void 0;
+  const [, kind, key] = match;
+  if (kind === "eq") return floats.equations.get(key ?? "")?.number;
+  return floats[RECALL_TABLE[kind]].get(key ?? "");
+}
+function coveredSections(source, chapters) {
+  const covered = [];
+  const frameChapters = [];
+  let current;
+  source.frames.forEach((frame, position) => {
+    if (frame.kind === "section") {
+      current = frame.chapter !== void 0 && chapters.has(frame.chapter) ? frame.chapter : void 0;
+      if (current !== void 0 && !covered.some((entry) => entry.name === current)) {
+        covered.push({ name: current, position });
+      }
+    }
+    frameChapters.push(current);
+  });
+  return { covered, frameChapters };
+}
+function resolvePartRecalls(source, part) {
+  const byName = new Map(part.chapters.map((chapter) => [chapter.name, chapter]));
+  const sections = coveredSections(source, new Set(byName.keys()));
+  const covered = sections.covered.map(({ name, position }) => ({ ...byName.get(name), position }));
+  const frameChapters = sections.frameChapters.map(
+    (name) => name === void 0 ? void 0 : covered.find((chapter) => chapter.name === name)
+  );
+  const chapterOf = /* @__PURE__ */ new Map();
+  const problems = /* @__PURE__ */ new Map();
+  source.frames.forEach((frame, position) => {
+    const own = frameChapters[position];
+    for (const recall of frame.recalls) {
+      if (recall.ref === void 0 || !RECALL_REF.test(recall.ref)) continue;
+      const ref = recall.ref;
+      const numbering = covered.filter((chapter) => chapterNumberOf(ref, chapter.floats) !== void 0);
+      const from = own !== void 0 && numbering.includes(own) ? own : numbering.length === 1 ? numbering[0] : void 0;
+      const earlier = chapterOf.get(ref);
+      if (from === void 0) {
+        problems.set(
+          recall.index,
+          numbering.length === 0 ? covered.length === 0 ? `recalls \`${ref}\`, but no section of this deck names a chapter to recall from (\`## Title [chapter: <name>]\`)` : `recalls \`${ref}\`, which no chapter this deck covers numbers (${covered.map((chapter) => chapter.slug).join(", ")})` : `recalls \`${ref}\`, which ${numbering.map((chapter) => chapter.slug).join(" and ")} each number: recall it in the section that names the chapter you mean`
+        );
+      } else if (earlier !== void 0 && earlier !== from) {
+        problems.set(
+          recall.index,
+          `recalls \`${ref}\` from ${from.slug}, where an earlier frame recalls it from ${earlier.slug}: a deck shows one float under one anchor`
+        );
+      } else {
+        chapterOf.set(ref, from);
+      }
+    }
+  });
+  return { covered, frameChapters, chapterOf, problems };
+}
+const DECK_RULE_DEFAULTS = {
+  maxWords: 70,
+  maxBullets: 7,
+  maxTitleLength: 50,
+  maxSteps: 4,
+  maxNewSymbols: 4
+};
+const LESSON_FIELDS = ["teaches", "assumptions", "studyMinutes", "notation"];
+const RECALL_REF = /^(eq|fig|tab|dia)-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+const NOTATION_KEY = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+function comparableLatex(latex) {
+  let text = String(latex).replace(/\\label\{[^{}]*\}/g, "").replace(/\\caption\{(?:[^{}]|\{[^{}]*\})*\}/g, "");
+  for (let guard = 0; guard < 20 && /\\explain\s*\{/.test(text); guard += 1) {
+    text = text.replace(/\\explain\s*\{[^{}]*\}\s*\{((?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*)\}/g, "$1");
+  }
+  return text.replace(/\\(?:left|right|big|Big|bigg|Bigg)(?![A-Za-z])/g, "").replace(/\\(?:,|;|:|!|quad|qquad)(?![A-Za-z])/g, "").replace(/\s+/g, "");
+}
+function frameName(frame) {
+  return `${frame.kind === "section" ? "##" : "###"} ${JSON.stringify(frame.title)}`;
+}
+function validateDecks(decks, settings = DECK_RULE_DEFAULTS) {
+  const diagnostics = [];
+  for (const deck of decks) {
+    let checkFrame2 = function(frame, position) {
+      if (frame.words > settings.maxWords || frame.bullets > settings.maxBullets) {
+        const over = [
+          frame.words > settings.maxWords ? `${frame.words} words (most ${settings.maxWords})` : "",
+          frame.bullets > settings.maxBullets ? `${frame.bullets} list items (most ${settings.maxBullets})` : ""
+        ].filter(Boolean);
+        push({
+          code: "frame-dense",
+          severity: "warning",
+          message: `${frameName(frame)} shows ${over.join(" and ")} (rule D2): it will not fit its canvas. Split it into two frames, or move the argument into its \`<Notes>\`.`,
+          index: frame.index,
+          token: frame.title
+        });
+      }
+      if ((frame.words > 0 || frame.bullets > 0) && frame.notes.length === 0) {
+        push({
+          code: "frame-notes-missing",
+          severity: "warning",
+          message: `${frameName(frame)} has text but no \`<Notes>\` (rule D4): write what the speaker says \u2014 the reasoning, the transition, the question to ask \u2014 in \`<Notes>\u2026</Notes>\` on the frame.`,
+          index: frame.index,
+          token: frame.title
+        });
+      }
+      const steps = frame.pauses.length + 1;
+      if (steps > settings.maxSteps) {
+        push({
+          code: "frame-steps",
+          severity: "warning",
+          message: `${frameName(frame)} shows in ${steps} steps, more than ${settings.maxSteps} (rule D6, \`rules.D6.maxSteps\`). Make the later steps a frame of their own.`,
+          index: frame.index,
+          token: frame.title
+        });
+      }
+      const pictures = frame.floats.filter((float) => float.name === "Figure" || float.name === "Table" || float.name === "Diagram").length + frame.recalls.filter((recall) => recall.ref !== void 0 && !recall.ref.startsWith("eq-")).length;
+      if (pictures > 1) {
+        push({
+          code: "frame-floats",
+          severity: "warning",
+          message: `${frameName(frame)} holds ${pictures} figures, tables or diagrams (rule D7): one per frame, at the canvas width. Give the second its own frame.`,
+          index: frame.index,
+          token: frame.title
+        });
+      }
+      const drivesSomething = frame.floats.some((float) => float.name === "Figure") || frame.recalls.some((recall) => recall.ref?.startsWith("fig-") === true);
+      for (const pause of frame.pauses) {
+        const problems = pauseProblems(pause, drivesSomething);
+        if (problems.length > 0) {
+          push({
+            code: "pause-invalid",
+            severity: "error",
+            message: `<Pause> on ${frameName(frame)}: ${problems.join("; ")}. See docs/authoring/deck.md, "Steps and animation".`,
+            index: pause.index
+          });
+        }
+      }
+      for (const recall of frame.recalls) {
+        const problem = partRecalls === void 0 ? recallProblem(recall.ref, deck) : recallFormProblem(recall.ref) ?? partRecalls.problems.get(recall.index);
+        if (problem !== void 0) {
+          push({
+            code: "recall-unresolved",
+            severity: "error",
+            message: `<Recall> on ${frameName(frame)} ${problem}. A recall names a labelled equation (\`eq-<key>\`) or a ` + (partRecalls === void 0 ? "keyed `<Figure>`, `<Table>` or `<Diagram>` of the deck's own chapter." : "keyed `<Figure>`, `<Table>` or `<Diagram>` of a chapter a section of the deck covers."),
+            index: recall.index,
+            ...recall.ref === void 0 ? {} : { token: recall.ref }
+          });
+        }
+      }
+      if (part !== void 0 && frame.chapter === void 0 && frame.floats.some((float) => float.name === "AssessmentSet")) {
+        push({
+          code: "deck-check-no-chapter",
+          severity: "error",
+          message: `${frameName(frame)} holds <AssessmentSet>, but its section names no chapter. On a part's deck a question frame asks the checks of the chapter its section covers: move it into a \`## Title [chapter: <name>]\` section.`,
+          index: frame.floats.find((float) => float.name === "AssessmentSet")?.index ?? frame.index,
+          token: frame.title
+        });
+      }
+      const chapterEquations = (partRecalls === void 0 ? [...deck.chapter?.equations ?? /* @__PURE__ */ new Map()] : partRecalls.covered.flatMap((chapter) => [...chapter.floats.equations])).filter(([, equation]) => equation.latex !== void 0);
+      if (chapterEquations.length > 0) {
+        for (const math of frame.displayMath) {
+          const mine = comparableLatex(math.latex);
+          if (mine === "") continue;
+          const same = chapterEquations.find(([, equation]) => comparableLatex(equation.latex ?? "") === mine);
+          if (same) {
+            push({
+              code: "frame-retyped",
+              severity: "warning",
+              message: `${frameName(frame)} retypes the chapter's equation (${same[1].number}) (rule D8). Write <Recall ref="eq-${same[0]}" /> instead: it shows the chapter's number and links to it.`,
+              index: math.index,
+              token: `eq-${same[0]}`
+            });
+          }
+        }
+      }
+      const fresh = deck.newSymbols?.[position] ?? [];
+      if (fresh.length > settings.maxNewSymbols) {
+        push({
+          code: "frame-new-symbols",
+          severity: "info",
+          message: `${frameName(frame)} introduces ${fresh.length} symbols the deck has not shown before (${fresh.join(", ")}), more than ${settings.maxNewSymbols} (rule D9). Introduce some on an earlier frame.`,
+          index: frame.index,
+          token: frame.title
+        });
+      }
+    };
+    var checkFrame = checkFrame2;
+    const lineAt = (index) => lessonLine({ body: deck.body, bodyLine: deck.bodyLine }, index);
+    const push = (finding) => {
+      const { index, ...rest } = finding;
+      diagnostics.push({
+        context: "structure",
+        file: deck.file,
+        ...index === void 0 ? {} : { line: lineAt(index) },
+        ...rest
+      });
+    };
+    const { source, part } = deck;
+    if (!deck.inPart) {
+      push({
+        code: "deck-outside-part",
+        severity: "error",
+        message: part !== void 0 ? `${deck.file} is the deck of content/docs/${part.dir}/, which no part in course.settings.json \`parts\` lists. A part's deck sits in a part's directory: add { "dir": "${part.dir}", "label": "\u2026" } to \`parts\`, or move it.` : `${deck.file} is a deck outside a part's directory. A deck is the slide edition of a lesson: put it beside the lesson, \`content/docs/<part>/<lesson>.deck.mdx\`, or make it a part's, \`content/docs/<part>/index.deck.mdx\`.`
+      });
+    }
+    if (deck.hasChapter || part !== void 0) {
+      const set = LESSON_FIELDS.filter((field) => deck.data[field] !== void 0);
+      if (set.length > 0) {
+        push({
+          code: "deck-frontmatter",
+          severity: "error",
+          message: part !== void 0 ? `${deck.file} sets ${set.map((field) => `\`${field}\``).join(", ")}. A part's deck is no lesson: it sets only \`title\` and \`description\`, and shows its chapters' symbols and outcomes.` : `${deck.file} sets ${set.map((field) => `\`${field}\``).join(", ")}, which the lesson's chapter holds. A deck beside its chapter sets only \`title\` and \`description\`; move the rest into the chapter.`
+        });
+      }
+    }
+    const partRecalls = part === void 0 ? void 0 : resolvePartRecalls(source, part);
+    const named = /* @__PURE__ */ new Set();
+    let previous;
+    for (const frame of source.frames) {
+      if (frame.kind !== "section") continue;
+      const before = previous;
+      previous = frame.chapter;
+      if (frame.chapter === void 0) continue;
+      const chapter = frame.chapter;
+      if (part === void 0) {
+        push({
+          code: "deck-chapter-outside-part",
+          severity: "error",
+          message: `${frameName(frame)} names the chapter \`${chapter}\`, but this is a lesson's deck, which covers its own lesson. Only a part's deck (\`content/docs/<part>/index.deck.mdx\`) names the chapter a section covers; drop the \`[chapter: \u2026]\` marker.`,
+          index: frame.index,
+          token: chapter
+        });
+      } else if (!part.chapters.some((entry) => entry.name === chapter)) {
+        push({
+          code: "deck-chapter-unknown",
+          severity: "error",
+          message: (part.slidesFirst ?? []).includes(chapter) ? `${frameName(frame)} names \`${chapter}\`, a lesson of ${part.dir} taught as slides only: it has no chapter to cover. Drop the marker, or name a chapter of the part.` : `${frameName(frame)} names \`${chapter}\`, which is no chapter of ${part.dir}. ` + (part.chapters.length > 0 ? `Its chapters are ${part.chapters.map((entry) => `\`${entry.name}\``).join(", ")}: name one by its file's name.` : "The part has no chapter: drop the marker."),
+          index: frame.index,
+          token: chapter
+        });
+      } else if (named.has(chapter) && before !== chapter) {
+        push({
+          code: "deck-chapter-repeated",
+          severity: "error",
+          message: `${frameName(frame)} names \`${chapter}\`, which an earlier section of the deck covers already, with a section of another chapter or of the deck's own between them. A chapter's sections follow one another, the first one's divider the chapter's address in the deck: move this section up to the others.`,
+          index: frame.index,
+          token: chapter
+        });
+      } else {
+        named.add(chapter);
+      }
+    }
+    if (part !== void 0 && [...part.chapters.map((entry) => entry.name), ...part.slidesFirst ?? []].includes("slides")) {
+      push({
+        code: "deck-route-taken",
+        severity: "error",
+        message: `${deck.file} is served at /${part.dir}/slides/, which is the address of the lesson content/docs/${part.dir}/slides. Rename the lesson's file, or the part keeps no deck of its own.`
+      });
+    }
+    for (const marker of source.misplacedMarkers) {
+      push({
+        code: "deck-marker-misplaced",
+        severity: "error",
+        message: marker.marker === "chapter" ? `### ${JSON.stringify(marker.title)} carries \`[chapter: \u2026]\`, which a section's \`##\` heading carries: it names the chapter the whole section covers. Move it to the section.` : `## ${JSON.stringify(marker.title)} carries \`[morph]\`, which a frame's \`###\` heading carries: a section divider shows its title alone and has nothing to morph from. Drop it, or move it to the frame.`,
+        index: marker.index,
+        token: marker.title
+      });
+    }
+    const frames = source.frames.filter((frame) => frame.kind === "frame");
+    if (frames.length === 0) {
+      push({
+        code: "deck-empty",
+        severity: "error",
+        message: `${deck.file} has no frame. A frame is a \`###\` heading and what follows it (rule D1).`
+      });
+    }
+    for (const heading of source.deepHeadings) {
+      push({
+        code: "frame-depth",
+        severity: "error",
+        message: `A ${"#".repeat(heading.level)} heading ${JSON.stringify(heading.text)} in a deck (rule D1): \`##\` opens a section and \`###\` is a frame; nothing else is a heading here. Make it a frame, or bold text in the frame.`,
+        index: heading.index,
+        token: heading.text
+      });
+    }
+    for (const loose of source.loose) {
+      const section = loose.where === "section" ? frameAt(source, loose.index) : void 0;
+      push({
+        code: "deck-loose-content",
+        severity: "error",
+        message: loose.where === "before" ? "Content before the deck's first heading belongs to no frame (rule D1). Put it in a `###` frame; the title frame is generated." : `Content under ${section ? frameName(section) : "a section heading"} before its first \`###\` frame (rule D1): a section is a divider that shows only its title. Put the content in a \`###\` frame.`,
+        index: loose.index
+      });
+    }
+    for (const [position, frame] of source.frames.entries()) {
+      if (frame.title.length > settings.maxTitleLength) {
+        push({
+          code: "frame-title-length",
+          severity: "error",
+          message: `${frameName(frame)} is ${frame.title.length} characters, over the ${settings.maxTitleLength}-character limit (rule D5, \`rules.D5.maxLength\`): a frame title stays on one line. Shorten it and move the rest into the frame.`,
+          index: frame.index,
+          token: frame.title
+        });
+      }
+      if (frame.kind !== "frame") continue;
+      checkFrame2(frame, position);
+    }
+  }
+  return diagnostics;
+}
+function pauseProblems(pause, drivesSomething) {
+  const problems = [];
+  if (pause.unknown.length > 0) {
+    problems.push(`takes no ${pause.unknown.map((name) => `\`${name}\``).join(", ")}`);
+  }
+  const drives = pause.control !== void 0 || pause.to !== void 0 || pause.from !== void 0 || pause.seconds !== void 0;
+  if (drives && pause.highlight !== void 0) {
+    problems.push("either drives a figure (`control`, `to`) or lights a symbol (`highlight`), not both");
+  }
+  if (drives && (pause.control === void 0 || pause.control.trim() === "" || pause.to === void 0)) {
+    problems.push("drives a figure with both `control` (the label of the lab\u2019s control) and `to`");
+  }
+  for (const name of ["from", "to", "seconds"]) {
+    const value = pause[name];
+    if (value !== void 0 && !Number.isFinite(Number(value))) {
+      problems.push(`\`${name}="${value}"\` is not a number`);
+    }
+  }
+  if (pause.seconds !== void 0 && Number(pause.seconds) <= 0) {
+    problems.push("`seconds` is more than zero");
+  }
+  if (pause.control !== void 0 && !drivesSomething) {
+    problems.push("drives a lab control, but the frame has no `<Figure>` or recalled figure to drive");
+  }
+  if (pause.highlight !== void 0 && !NOTATION_KEY.test(pause.highlight)) {
+    problems.push(`\`highlight="${pause.highlight}"\` is not a notation key`);
+  }
+  return problems;
+}
+function recallFormProblem(ref) {
+  if (ref === void 0) return "has no `ref`";
+  return RECALL_REF.test(ref) ? void 0 : `\`ref="${ref}"\` is not \`eq-\`, \`fig-\`, \`tab-\` or \`dia-\` and a key`;
+}
+function recallProblem(ref, deck) {
+  const form = recallFormProblem(ref);
+  if (form !== void 0 || ref === void 0) return form;
+  if (!deck.hasChapter || deck.chapter === void 0) {
+    return `recalls \`${ref}\`, but this lesson has no chapter to recall from`;
+  }
+  return chapterNumberOf(ref, deck.chapter) === void 0 ? `recalls \`${ref}\`, which the chapter does not number` : void 0;
+}
+export {
+  DECK_RULE_DEFAULTS,
+  chapterNumberOf,
+  comparableLatex,
+  coveredSections,
+  resolvePartRecalls,
+  validateDecks
+};

package/dist/reference/derived-entries.d.ts

@@ -3,7 +3,7 @@ import { GlyphScopeEntry } from './gloss.js';
 import { DerivedUse, NotationDefinitionRecord } from './types.js';
 import '../curriculum/validation.js';
 import './consistency.js';
-import '../course-config-rRtME5UV.js';
+import '../course-config-BLtIdkei.js';
 import '../rules/catalog.js';
 import '../rules/course-rules.js';
 import '../compiler/collections.js';
@@ -23,6 +23,10 @@ import './gate-math.js';
 import './mixed-content.js';
 import '../rules/waivers.js';
 import '../compiler/knowledge-version.js';
+import '../compiler/page-versions.js';
+import '../compiler/decks.js';
+import './decks-validate.js';
+import './deck-source.js';
 import '../compiler/lesson-derivation.js';
 
 /**

package/dist/reference/diagram-fit.d.ts

@@ -1,4 +1,4 @@
-import { M as ManifestRules } from '../course-config-rRtME5UV.js';
+import { M as ManifestRules } from '../course-config-BLtIdkei.js';
 import '../rules/catalog.js';
 import '../rules/course-rules.js';
 

package/dist/reference/figure-symbols.d.ts

@@ -11,9 +11,16 @@
  * `figure.keyed-figure` (a lab's tools included), every letter KaTeX draws
  * must sit in a `[data-notation-key]`. Upright text is not a symbol:
  * `\text{…}`, `\mathrm{…}` (the resolver skips its body, rule N10) and a
- * named operator (`\sin`, `\max`). `compiler/astro.ts` runs it on every
- * built page, and a course's browser test can run it on a hydrated figure's
- * `outerHTML`, which also holds what an island draws only in the browser.
+ * named operator (`\sin`, `\max`). Nor is a plain base-library atom (`d`,
+ * `e`, `i`, `\pi`; `base-library.mjs`), which the resolver leaves without a
+ * card in lab math as in a lesson's, because every reader knows it — in a
+ * power too (`e^{i\pi}`). A styled one (`\mathbf{e}`), a decorated one
+ * (`\hat{e}`, rule N22) and an index (`x_i`, `e_i`, rule N23) are other
+ * symbols and still need a card; a subscript is told from a power by
+ * KaTeX's `vlist-t2`, the vertical list that has a lowered row.
+ * `compiler/astro.ts` runs it on every built page, and a course's browser
+ * test can run it on a hydrated figure's `outerHTML`, which also holds what
+ * an island draws only in the browser.
  */
 interface UnboundFigureSymbols {
     /** The figure's anchor id, e.g. `fig-latent-factor-model`. */
@@ -23,10 +30,20 @@ interface UnboundFigureSymbols {
 }
 /** The figures in `html` that draw a symbol with no card, and those symbols. */
 declare function unboundFigureSymbols(html: string): UnboundFigureSymbols[];
+/** One rendered page and the figures on it that draw a symbol with no card. */
+interface PageUnboundFigureSymbols {
+    /** The page's path in the build output, e.g. `lecture-5/chernoff/index.html`. */
+    readonly page: string;
+    readonly figures: readonly UnboundFigureSymbols[];
+}
 /**
- * Fail a build whose rendered page shows a symbol in a figure that opens no
- * card, naming the figure, the symbols, and the way to bind them.
+ * Fail a build over the pages that show a symbol in a figure that opens no
+ * card, naming every page, its figures and symbols, and the way to bind them.
+ * A build collects the whole list first (`compiler/astro.ts`), so it reports
+ * every page at once instead of one per run.
  */
+declare function assertNoUnboundFigureSymbols(pages: readonly PageUnboundFigureSymbols[]): void;
+/** Fail a build whose rendered page shows a symbol in a figure that opens no card. */
 declare function assertFigureSymbolsBound(page: string, html: string): void;
 
-export { type UnboundFigureSymbols, assertFigureSymbolsBound, unboundFigureSymbols };
+export { type PageUnboundFigureSymbols, type UnboundFigureSymbols, assertFigureSymbolsBound, assertNoUnboundFigureSymbols, unboundFigureSymbols };

package/dist/reference/figure-symbols.js

@@ -1,5 +1,8 @@
 import { parse } from "parse5";
+import { isBaseLibraryGlyph } from "./base-library.mjs";
 const UPRIGHT = /* @__PURE__ */ new Set(["text", "mathrm", "textrm", "mop"]);
+const PLAIN = /* @__PURE__ */ new Set(["mathnormal", "mathit"]);
+const DECORATED = /* @__PURE__ */ new Set(["accent"]);
 const LETTER = new RegExp("\\p{L}", "u");
 function isElement(node) {
   return "tagName" in node;
@@ -19,37 +22,70 @@ function childrenOf(node) {
 function unboundFigureSymbols(html) {
   if (!html.includes("keyed-figure") || !html.includes("katex-html")) return [];
   const found = /* @__PURE__ */ new Map();
-  const visit = (node, figure, inKatex, covered) => {
+  const visit = (node, context, row) => {
+    let next = context;
     if (isElement(node)) {
       const names = classes(node);
+      next = {
+        ...context,
+        // A letter's own element says how it is drawn; its ancestors do not.
+        plain: names.some((name) => PLAIN.has(name)),
+        // Only the rows of a script's own vertical list are its sub and sup.
+        lowered: names.includes("msupsub") ? childrenOf(node).some((child) => isElement(child) && classes(child).includes("vlist-t2")) : row === void 0 ? context.lowered : false
+      };
       if (node.tagName === "figure" && names.includes("keyed-figure")) {
-        figure = attribute(node, "id") ?? "(a figure with no id)";
+        next = { ...next, figure: attribute(node, "id") ?? "(a figure with no id)" };
       }
-      if (names.includes("katex-html")) inKatex = true;
-      if (attribute(node, "data-notation-key") !== void 0 || inKatex && names.some((name) => UPRIGHT.has(name))) {
-        covered = true;
+      if (names.includes("katex-html")) next = { ...next, inKatex: true };
+      if (names.some((name) => DECORATED.has(name)) || row === 0 && context.lowered) {
+        next = { ...next, decorated: true };
       }
-    } else if (node.nodeName === "#text" && figure !== void 0 && inKatex && !covered) {
+      if (attribute(node, "data-notation-key") !== void 0 || next.inKatex && names.some((name) => UPRIGHT.has(name))) {
+        next = { ...next, covered: true };
+      }
+    } else if (node.nodeName === "#text" && context.figure !== void 0 && context.inKatex && !context.covered) {
       const text = node.value.trim();
-      if (LETTER.test(text)) {
-        const symbols = found.get(figure) ?? [];
+      const library = context.plain && !context.decorated && [...text].every((glyph) => !LETTER.test(glyph) || isBaseLibraryGlyph(glyph));
+      if (LETTER.test(text) && !library) {
+        const symbols = found.get(context.figure) ?? [];
         if (!symbols.includes(text)) symbols.push(text);
-        found.set(figure, symbols);
+        found.set(context.figure, symbols);
       }
     }
-    for (const child of childrenOf(node)) visit(child, figure, inKatex, covered);
+    const isVlist = isElement(node) && classes(node).includes("vlist");
+    let rows = 0;
+    for (const child of childrenOf(node)) {
+      const isRow = isVlist && isElement(child);
+      visit(child, next, isRow ? rows : void 0);
+      if (isRow) rows += 1;
+    }
   };
-  visit(parse(html), void 0, false, false);
+  visit(parse(html), {
+    figure: void 0,
+    inKatex: false,
+    covered: false,
+    decorated: false,
+    plain: false,
+    lowered: false
+  });
   return [...found].map(([figure, symbols]) => ({ figure, symbols }));
 }
-function assertFigureSymbolsBound(page, html) {
-  const unbound = unboundFigureSymbols(html);
-  if (unbound.length === 0) return;
+const describeFigures = (figures) => figures.map(({ figure, symbols }) => `#${figure} shows ${symbols.map((s) => `"${s}"`).join(", ")}`).join("; ");
+function assertNoUnboundFigureSymbols(pages) {
+  const found = pages.filter(({ figures }) => figures.length > 0);
+  const [only] = found;
+  if (!only) return;
+  const head = found.length === 1 ? `Explico figure symbols without a notation card on rendered page "${only.page}": ` + describeFigures(only.figures) : `Explico figure symbols without a notation card on ${found.length} rendered pages:
+` + found.map(({ page, figures }) => `  "${page}": ${describeFigures(figures)}`).join("\n");
   throw new Error(
-    `Explico figure symbols without a notation card on rendered page "${page}": ` + unbound.map(({ figure, symbols }) => `#${figure} shows ${symbols.map((s) => `"${s}"`).join(", ")}`).join("; ") + ". Every symbol a figure shows opens its card (rule N4): render its math with renderLabMath (`{ display: false }` for a legend, an axis title or a label; a `{ math }` run for the caption clause), never with katex directly. Write a unit as `\\text{\u2026}`."
+    `${head}. Every symbol a figure shows opens its card (rule N4): render its math with renderLabMath (\`{ display: false }\` for a legend, an axis title or a label; a \`{ math }\` run for the caption clause), never with katex directly. Write a unit as \`\\text{\u2026}\`.`
   );
 }
+function assertFigureSymbolsBound(page, html) {
+  assertNoUnboundFigureSymbols([{ page, figures: unboundFigureSymbols(html) }]);
+}
 export {
   assertFigureSymbolsBound,
+  assertNoUnboundFigureSymbols,
   unboundFigureSymbols
 };

package/dist/reference/float-name.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A numbered float's reader-facing name: its kind word and number, then its
+ * short caption when it has one — "Diagram 2.1.1 Steps of the range
+ * derivation" (docs/plans/figures-and-short-captions.md, decisions 9 and 11).
+ * A `<Fold>`'s bar names the floats inside it this way.
+ *
+ * A float carries both halves on its root element, as `data-<kind>-number`
+ * and `data-<kind>-short` (`Figure.astro`, `Table.astro`, `Diagram.astro`);
+ * nothing else in the page carries those attributes.
+ */
+type FloatKind = 'fig' | 'tab' | 'dia';
+declare const FLOAT_KIND_WORDS: Readonly<Record<FloatKind, string>>;
+interface NamedFloat {
+    readonly kind: FloatKind;
+    readonly number: string;
+    readonly short?: string;
+    /** Its anchor (`fig-…`, `tab-…`, `dia-…`), when the scan found one. */
+    readonly anchorId?: string;
+}
+/** `Figure 2.1.1 Projectile trajectory explorer`, or `Figure 2.1.1` with no short caption. */
+declare function floatName(float: NamedFloat): string;
+/**
+ * The bold title that opens a caption line when the float has a short
+ * caption (docs/plans/figures-and-short-captions.md, decision 9.1): the
+ * short caption with a closing period, unless it already ends in one — the
+ * journal-legend style, "Fig. 1 | Title. Description".
+ */
+declare function captionTitle(short: string): string;
+/**
+ * A numbered float's name, read off its root element in the page — the same
+ * `data-<kind>-number` / `data-<kind>-short` pair `floatsInHtml` reads from
+ * markup. `null` for an element that is no numbered float.
+ */
+declare function floatOf(element: Element): NamedFloat | null;
+/**
+ * Every numbered float in rendered HTML, in document order — for a build-time
+ * component that renders its slot first (`<Fold>`). Reads the start tags
+ * only: attribute values are double-quoted, with `"` escaped, so a tag ends
+ * at the first `>` outside one.
+ */
+declare function floatsInHtml(html: string): NamedFloat[];
+
+export { FLOAT_KIND_WORDS, type FloatKind, type NamedFloat, captionTitle, floatName, floatOf, floatsInHtml };

package/dist/reference/float-name.js

@@ -0,0 +1,58 @@
+const FLOAT_KIND_WORDS = {
+  fig: "Figure",
+  tab: "Table",
+  dia: "Diagram"
+};
+function floatName(float) {
+  const label = `${FLOAT_KIND_WORDS[float.kind]} ${float.number}`;
+  return float.short ? `${label} ${float.short}` : label;
+}
+function captionTitle(short) {
+  const title = short.trim();
+  return /[.!?…:;]$/u.test(title) ? title : `${title}.`;
+}
+function floatOf(element) {
+  for (const kind of ["fig", "tab", "dia"]) {
+    const number = element.getAttribute(`data-${kind}-number`);
+    if (!number) continue;
+    const short = element.getAttribute(`data-${kind}-short`) ?? void 0;
+    return {
+      kind,
+      number,
+      ...short ? { short } : {},
+      ...element.id ? { anchorId: element.id } : {}
+    };
+  }
+  return null;
+}
+function decodeAttribute(value) {
+  return value.replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code))).replace(
+    /&#x([\da-f]+);/gi,
+    (_, code) => String.fromCodePoint(Number.parseInt(code, 16))
+  ).replace(/&quot;/g, '"').replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+}
+function floatsInHtml(html) {
+  const floats = [];
+  for (const tag of html.matchAll(/<[A-Za-z][\w-]*((?:\s+[^\s"'>/=]+(?:="[^"]*")?)*)\s*\/?>/g)) {
+    const attributes = tag[1] ?? "";
+    const number = /\sdata-(fig|tab|dia)-number="([^"]*)"/.exec(attributes);
+    if (!number?.[2]) continue;
+    const kind = number[1];
+    const short = new RegExp(`\\sdata-${kind}-short="([^"]*)"`).exec(attributes)?.[1];
+    const anchorId = /\sid="([^"]*)"/.exec(attributes)?.[1];
+    floats.push({
+      kind,
+      number: decodeAttribute(number[2]),
+      ...short ? { short: decodeAttribute(short) } : {},
+      ...anchorId ? { anchorId: decodeAttribute(anchorId) } : {}
+    });
+  }
+  return floats;
+}
+export {
+  FLOAT_KIND_WORDS,
+  captionTitle,
+  floatName,
+  floatOf,
+  floatsInHtml
+};

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

@@ -4,7 +4,7 @@ import { KeyedFloatLessonInput } from './keyed-float-validate.js';
  * `<Fold>` validation, run inside `compileManifest()`
  * (docs/plans/figures-and-short-captions.md, decision 11). A fold's bar is
  * its `label` or, without one, the numbers and short captions of the floats
- * it holds (`../components/float-name.ts`), so a fold needs one or the other:
+ * it holds (`./float-name.ts`), so a fold needs one or the other:
  *
  * - `fold-unnamed` (error): a `<Fold>` with no `label` and no `<Figure>`,
  *   `<Table>` or `<Diagram>` that takes a number inside it — its bar would

package/dist/reference/gate-abbreviations.d.ts

@@ -1,6 +1,6 @@
 import { MathGateDiagnostic } from './gate-math.js';
 import { NotationRegistryInput, AbbreviationDefinitionInput } from './types.js';
-import { h as CourseAbbreviations } from '../course-config-rRtME5UV.js';
+import { l as CourseAbbreviations } from '../course-config-BLtIdkei.js';
 import '../rules/catalog.js';
 import '../rules/course-rules.js';