explico 0.8.0 → 0.11.0

package/dist/reference/consistency.js

@@ -1,6 +1,16 @@
+import { effectiveAccentAllowlist } from "./base-accents.mjs";
 import { effectiveOperatorAllowlist } from "./base-operators.mjs";
 import { effectiveRomanLabelAllowlist } from "./base-roman-labels.mjs";
-import { collectOperators, collectRomanLabels } from "./math-glyphs.mjs";
+import { stripEquationLabels } from "./equations.mjs";
+import { pageScope } from "./gate-math.js";
+import {
+  collectDecorations,
+  collectOperators,
+  collectRomanLabels,
+  decorationOfEntry,
+  operatorEntryLatex,
+  resolveMathGlyphs
+} from "./math-glyphs.mjs";
 import { offVocabularyTokens } from "./units-vocab.js";
 const CONVENTION_RE = /\bsign convention\b|\bcash-flow perspective\b|\bholder(?:'s)?(?:\s+\w+){0,2}\s+perspective\b|\bfrom (?:a|one|the|its)(?:\s+\w+){0,3}\s+perspective\b|\breverses? every sign\b|\bpositive (?:means|amounts?)\b/i;
 function stripCode(text) {
@@ -10,7 +20,7 @@ function mathSpans(body) {
   const searchable = stripCode(body);
   const spans = [];
   for (const match of searchable.matchAll(/\$\$([\s\S]+?)\$\$/g)) {
-    spans.push({ latex: match[1] ?? "" });
+    spans.push({ latex: stripEquationLabels(match[1] ?? "") });
   }
   for (const match of searchable.replace(/\$\$([\s\S]+?)\$\$/g, (block) => block.replace(/[^\n]/g, " ")).matchAll(/(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/g)) {
     spans.push({ latex: match[1] ?? "" });
@@ -335,6 +345,94 @@ function checkRomanLabelExplained(input, out) {
     }
   }
 }
+function sharedScopeByKey(input) {
+  return new Map(
+    input.notationInput.sharedDefinitions.map((definition) => [
+      definition.key,
+      { key: definition.key, notation: definition.notation }
+    ])
+  );
+}
+function checkAccentExplained(input, out) {
+  const allowlist = effectiveAccentAllowlist(input.accents);
+  const sharedByKey = sharedScopeByKey(input);
+  for (const lesson of input.notationInput.lessons) {
+    const scope = pageScope(lesson, sharedByKey);
+    const suspended = (lesson.suspended ?? []).map((item) => item.operator);
+    const reported = /* @__PURE__ */ new Set();
+    for (const span of mathSpans(lesson.body)) {
+      let decorations;
+      try {
+        ({ decorations } = resolveMathGlyphs(span.latex, scope, { suspended }));
+      } catch {
+        continue;
+      }
+      for (const decoration of decorations) {
+        if (decoration.wholeForm !== null || decoration.operator !== null) continue;
+        if (suspended.includes(decoration.name)) continue;
+        if (allowlist.has(decoration.name)) continue;
+        if (reported.has(decoration.name)) continue;
+        reported.add(decoration.name);
+        if (input.lintIgnore.matches("accent-explained", decoration.name)) {
+          continue;
+        }
+        out.push({
+          code: "accent-explained",
+          severity: "warning",
+          lessonId: lesson.lessonId,
+          file: lesson.source.file,
+          glyph: decoration.name,
+          message: `${lesson.lessonId}: decoration ${JSON.stringify(decoration.name)} (in ${JSON.stringify(decoration.token)}) is an operator that is neither universal for this course nor explained; give it an operator entry (latex ${JSON.stringify(operatorEntryLatex(decoration.name))}) introduced with [[key]] or in notation.local, give the whole form its own entry (latex ${JSON.stringify(decoration.token)}), or add ${JSON.stringify(decoration.name)} to rules.N22.allow`
+        });
+      }
+    }
+  }
+}
+function checkOperatorSuspension(input, out) {
+  const allowlist = effectiveAccentAllowlist(input.accents);
+  const sharedByKey = sharedScopeByKey(input);
+  for (const lesson of input.notationInput.lessons) {
+    const suspensions = lesson.suspended ?? [];
+    for (const { operator, reason } of suspensions) {
+      const code = reason === void 0 ? "operator-suspension-reason" : "operator-suspended";
+      if (input.lintIgnore.matches(code, operator)) continue;
+      out.push({
+        code,
+        severity: reason === void 0 ? "warning" : "info",
+        lessonId: lesson.lessonId,
+        file: lesson.source.file,
+        glyph: operator,
+        message: reason === void 0 ? `${lesson.lessonId}: notation.suspend suspends ${JSON.stringify(operator)} with no reason; say why it is not an operator on this page (reason: \u2026)` : `${lesson.lessonId}: ${JSON.stringify(operator)} is not an operator on this page (notation.suspend): ${reason}`
+      });
+    }
+    const suspended = new Set(suspensions.map((item) => item.operator));
+    const scope = pageScope(lesson, sharedByKey);
+    const explained = new Set(
+      scope.map((entry) => decorationOfEntry(entry.notation)).filter((name) => name !== void 0)
+    );
+    for (const entry of scope) {
+      if (decorationOfEntry(entry.notation) !== void 0) continue;
+      const names = new Set(
+        collectDecorations(entry.notation).map((decoration) => decoration.name)
+      );
+      for (const name of names) {
+        if (suspended.has(name)) continue;
+        const how = explained.has(name) ? "explained by an operator entry" : allowlist.has(name) ? "universal for this course" : void 0;
+        if (how === void 0) continue;
+        if (input.lintIgnore.matches("operator-shadowed", entry.key)) continue;
+        out.push({
+          code: "operator-shadowed",
+          severity: "info",
+          lessonId: lesson.lessonId,
+          file: lesson.source.file,
+          key: entry.key,
+          glyph: name,
+          message: `${lesson.lessonId}: ${entry.key} (${entry.notation}) has its own entry, so its card wins over the ${JSON.stringify(name)} operator (${how}) for that form; if ${JSON.stringify(name)} never means the operator on this page, suspend it (notation.suspend)`
+        });
+      }
+    }
+  }
+}
 const CHECKS = [
   checkGlyphUniqueness,
   checkNotationUnits,
@@ -345,7 +443,9 @@ const CHECKS = [
   checkCardWantsDemoting,
   checkGlossNameShape,
   checkOperatorExplained,
-  checkRomanLabelExplained
+  checkRomanLabelExplained,
+  checkAccentExplained,
+  checkOperatorSuspension
 ];
 function runConsistencyChecks(input) {
   const diagnostics = [];
@@ -366,7 +466,11 @@ function consistencyCounts(diagnostics) {
     "card-wants-demoting": 0,
     "gloss-name-shape": 0,
     "operator-explained": 0,
-    "roman-label-explained": 0
+    "roman-label-explained": 0,
+    "accent-explained": 0,
+    "operator-suspended": 0,
+    "operator-suspension-reason": 0,
+    "operator-shadowed": 0
   };
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;

package/dist/reference/delimiter-size.d.ts

@@ -9,8 +9,9 @@
  *
  * This deliberately parses only sizing syntax. It does not decide whether a
  * parenthesis, bracket, or brace is semantic, and it never recommends changing
- * one delimiter shape into another. N16's alternating-shape preference remains
- * a review-only authoring concern.
+ * one delimiter shape into another — N17's other half, that a delimiter's shape
+ * is fixed by its meaning and never alternates to show depth, stays a
+ * review-only authoring concern (which is why N17 is `partial`).
  */
 declare const DELIMITER_SIZE_DIAGNOSTIC_CODE: "delimiter-manual-size";
 type DelimiterSizeName = 'automatic' | 'big' | 'Big' | 'bigg' | 'Bigg';

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

@@ -2,7 +2,7 @@ import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } fr
 
 /** `validateKeyedFloats` for `<Diagram>` — see `keyed-float-validate.ts`. */
 
-type DiagramDiagnosticCode = 'dia-invalid-key' | 'dia-duplicate-key' | 'dia-ref-resolves' | 'dia-key-unused';
+type DiagramDiagnosticCode = 'dia-invalid-key' | 'dia-duplicate-key' | 'dia-ref-resolves' | 'dia-key-unused' | 'dia-removed-prop';
 interface DiagramDiagnostic {
     readonly code: DiagramDiagnosticCode;
     readonly severity: 'error' | 'warning' | 'info';
@@ -16,6 +16,11 @@ type DiagramLessonInput = KeyedFloatLessonInput;
 interface DiagramValidation extends KeyedFloatValidation {
     readonly diagnostics: readonly DiagramDiagnostic[];
 }
+/**
+ * The fix for a compaction prop: a diagram is always its graph and then its
+ * caption line (docs/plans/figures-and-short-captions.md, decision 7).
+ */
+declare const DIAGRAM_NO_LONGER_FOLDS = "a diagram no longer folds by itself \u2014 delete the prop. To let a reader fold it away, wrap it in a `<Fold>` or put it in a collapsible section.";
 declare function validateDiagrams(lessons: readonly DiagramLessonInput[]): DiagramValidation;
 
-export { type DiagramDiagnostic, type DiagramDiagnosticCode, type DiagramLabelRecord, type DiagramLessonInput, type DiagramValidation, validateDiagrams };
+export { DIAGRAM_NO_LONGER_FOLDS, type DiagramDiagnostic, type DiagramDiagnosticCode, type DiagramLabelRecord, type DiagramLessonInput, type DiagramValidation, validateDiagrams };

package/dist/reference/diagrams-validate.js

@@ -1,13 +1,21 @@
 import {
   validateKeyedFloats
 } from "./keyed-float-validate.js";
+const DIAGRAM_NO_LONGER_FOLDS = "a diagram no longer folds by itself \u2014 delete the prop. To let a reader fold it away, wrap it in a `<Fold>` or put it in a collapsible section.";
 function validateDiagrams(lessons) {
   return validateKeyedFloats(lessons, {
     tagName: "Diagram",
     prefix: "dia",
-    noun: "diagram"
+    noun: "diagram",
+    removedProps: {
+      label: "rename it `caption` (shown below the diagram with its number), and add an optional `short` caption if the caption is long.",
+      title: "a diagram is named by its `caption` (shown below it with its number) and an optional `short` caption.",
+      defaultOpen: DIAGRAM_NO_LONGER_FOLDS,
+      rememberState: DIAGRAM_NO_LONGER_FOLDS
+    }
   });
 }
 export {
+  DIAGRAM_NO_LONGER_FOLDS,
   validateDiagrams
 };

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

@@ -12,6 +12,8 @@
 interface EquationLabelRecord {
     readonly key: string;
     readonly number: string;
+    /** The equation's `\caption{…}` short caption, when it has one. */
+    readonly short?: string;
     readonly lessonId: string;
     readonly slug: string;
     readonly section: number;
@@ -45,13 +47,14 @@ interface EquationLessonInput {
     readonly file: string;
     readonly body: string;
     /**
-     * `{ prefix, offset }` — the part's 1-based ordinal among the sidebar groups,
-     * and how many display equations earlier lessons of that part already used.
-     * When set, equations are numbered `‹part›.‹offset + n›`; when omitted, the
-     * legacy `##`-section scheme. See `docs/authoring/structure.md`.
+     * `{ prefix, offset }` — the lesson's float-number prefix (`‹part›.‹chapter›`,
+     * or `‹part›` under `numbering.floats: "part"`) and how many display
+     * equations precede the lesson in that scope. When set, equations are
+     * numbered `‹prefix›.‹offset + n›`; when omitted, the legacy `##`-section
+     * scheme. See `docs/authoring/structure.md`.
      */
     readonly numbering?: {
-        readonly prefix: number;
+        readonly prefix: number | string;
         readonly offset: number;
     };
 }

package/dist/reference/equations-validate.js

@@ -42,6 +42,7 @@ function validateEquations(lessons) {
       labels.push({
         key: raw.key,
         number: raw.number,
+        ...raw.short ? { short: raw.short } : {},
         lessonId: lesson.lessonId,
         slug: lesson.slug,
         section: raw.section,

package/dist/reference/equations.d.mts

@@ -1,3 +1,9 @@
+/**
+ * The short caption a display equation carries, trimmed, or `null` when it
+ * has none. Only the first `\caption{}` counts; `remark-notation.mjs` fails a
+ * page that gives one equation two, or an empty one.
+ */
+export function equationCaption(latex: any): string | null;
 /** `{ lesson?, key }` when `raw` is an equation reference, else `undefined`. */
 export function parseEquationRef(raw: any): {
     lesson: string;
@@ -6,27 +12,31 @@ export function parseEquationRef(raw: any): {
     key: string;
     lesson?: undefined;
 } | undefined;
-/** Remove every `\label{eq:…}` (and the whitespace it leaves) from a math source. */
+/**
+ * Remove every `\label{eq:…}` and `\caption{…}` (and the whitespace they
+ * leave) from a math source: both are identity markers, not math KaTeX parses.
+ */
 export function stripEquationLabels(latex: any): string;
 /**
  * Normalise the numbering input to `{ prefix, offset }`.
  *
- * `prefix` is the number before the dot — the **part**'s ordinal (its position
- * among the sidebar groups). `offset` is how many display equations already
- * appeared in earlier lessons of that same part, so `n` runs continuously
- * across a part instead of restarting on every page. A bare number is the
- * legacy per-lesson form (`prefix = n`, `offset = 0`) and is still accepted so
- * hand-built trees and unit tests keep working. `undefined`/`null`/`0` ⇒ the
- * `##`-section fallback for non-lesson pages.
+ * `prefix` is everything before the last dot — `‹part›.‹chapter›` under the
+ * default `numbering.floats: "chapter"`, the part's ordinal under `"part"`.
+ * `offset` is how many items of the kind precede the lesson in that scope: 0
+ * for a chapter, the earlier chapters' count for a part, so `n` runs on
+ * across it. A bare number is the legacy per-lesson form (`prefix = n`,
+ * `offset = 0`) and is still accepted so hand-built trees and unit tests keep
+ * working. `undefined`/`null`/`0`/`''` ⇒ the `##`-section fallback for
+ * non-lesson pages.
  */
 export function resolveNumbering(input: any): {
     prefix: any;
     offset: number;
 };
 /**
- * The visible number for one display equation. With a `prefix` (the part's
- * ordinal) the scheme is `‹part›.‹offset + indexInLesson›` and `##` headings
- * are ignored; without it, the legacy `##`-section scheme.
+ * The visible number for one display equation. With a `prefix` the scheme is
+ * `‹prefix›.‹offset + indexInLesson›` and `##` headings are ignored; without
+ * it, the legacy `##`-section scheme.
  */
 export function displayEquationNumber({ prefix, offset, section, indexInSection, indexInLesson, }: {
     prefix: any;
@@ -59,20 +69,20 @@ export function stripFencedCode(markdown: any): string;
  * component while still finding `<Table>`/`<Figure>` tags at the top level.
  *
  * `transparent`, when given, removes only those components' opening/closing
- * tags and exposes their body to the later blanking pass. `<Memo>` and
- * `<ShortNote>` are intentional uses: unlike a worked-example/presentation
- * wrapper, their bodies are details in the lesson's reading order, so numbered
- * equations/floats in them stay in the official sequence. Section headings in
+ * tags and exposes their body to the later blanking pass. The
+ * {@link TRANSPARENT_COMPONENTS} are the intentional uses. Section headings in
  * a transparent body do not change the surrounding page's section counter.
  */
 export function stripJsxComponents(markdown: any, keep: any, transparent?: any[]): string;
 /**
  * Every display equation in a Markdown body, keyed or not, in appearance order
- * with its assigned number. `$$…$$` blocks only. With `numbering`
- * (`{ prefix, offset }`, the part's ordinal and the count of display equations
- * in earlier lessons of that part) the number is `‹part›.‹offset + n›`, `n`
- * sequential over every display block in the lesson; without it, `##` headings
- * advance a section counter and the number is `‹section›.‹indexInSection›`.
+ * with its assigned number and its `\caption{}` short caption (`short`, or
+ * `null`). `$$…$$` blocks only. With `numbering`
+ * (`{ prefix, offset }`, the lesson's float-number prefix and the count of
+ * display equations before it in that scope) the number is
+ * `‹prefix›.‹offset + n›`, `n` sequential over every display block in the
+ * lesson; without it, `##` headings advance a section counter and the number
+ * is `‹section›.‹indexInSection›`.
  * Either way every display block advances the index, so a keyed equation's
  * number reflects its position among *all* display equations, not only the
  * keyed ones.
@@ -80,6 +90,7 @@ export function stripJsxComponents(markdown: any, keep: any, transparent?: any[]
 export function scanDisplayEquations(markdown: any, numbering: any): {
     key: string | null | undefined;
     number: string;
+    short: string | null | undefined;
     section: number;
     indexInSection: number;
 }[];
@@ -87,6 +98,7 @@ export function scanDisplayEquations(markdown: any, numbering: any): {
 export function scanEquationLabels(markdown: any, numbering: any): {
     key: string | null | undefined;
     number: string;
+    short: string | null | undefined;
     section: number;
     indexInSection: number;
 }[];
@@ -115,23 +127,24 @@ export function collectEquationLabels(tree: any, numbering: any): any[];
  * Every display equation (`$$…$$`) in a lesson is numbered and given an `id`
  * from appearance order. When the caller supplies `numbering`
  * (`{ prefix, offset }` — see `resolveNumbering`), the number is
- * `‹part›.‹offset + n›`: the prefix is the **part**'s ordinal among the sidebar
- * groups, `n` counts every display equation in the lesson, and `offset` carries
- * the count from earlier lessons of the same part so the sequence runs
- * continuously across a part rather than restarting on every page. `##` and
- * `###` headings never affect it — `(2.4)` is the fourth display equation of
- * part 2, wherever in that part it sits. See `docs/authoring/structure.md` for
- * the level names. With no `numbering` the number falls back to the
- * `##`-section scheme `‹section›.‹indexInSection›` (used by hand-built test
- * trees and non-lesson pages). An author additionally
+ * `‹prefix›.‹offset + n›`: `n` counts every display equation in the lesson,
+ * and the course's `numbering.floats` scope decides the rest — `chapter` (the
+ * default) makes the prefix `‹part›.‹chapter›` with no offset, so `(2.2.4)` is
+ * the fourth display equation of part 2's second chapter; `part` makes it the
+ * part's ordinal alone, with `offset` carrying the count from earlier lessons
+ * of the part so the sequence runs on across it. `##` and `###` headings never
+ * affect it. See `docs/authoring/structure.md` for the level names. With no
+ * `numbering` the number falls back to the `##`-section scheme
+ * `‹section›.‹indexInSection›` (used by hand-built test trees and non-lesson
+ * pages). An author additionally
  * marks an equation with a trailing `\label{eq:<key>}` inside its `$$…$$`
  * block (inside math, so the `:` is safe and the form matches amsmath) when
  * they want a *stable* anchor that survives edits and cross-page references:
  *
- *   [[eq-discount-factor-def]]           same page  → "(2.4)" linked to #eq-…
+ *   [[eq-discount-factor-def]]           same page  → "(2.2.4)" linked to #eq-…
  *   [[foundations/present-value#eq-pv]]  cross page → number from the manifest
  *
- * An unkeyed equation still gets a positional anchor (`#eq-2-4`) so it can be
+ * An unkeyed equation still gets a positional anchor (`#eq-2-2-4`) so it can be
  * deep-linked, but only a keyed equation is referenceable by name.
  *
  * `scanEquationLabels` (raw Markdown) and `collectEquationLabels` (mdast tree)
@@ -144,9 +157,25 @@ export function collectEquationLabels(tree: any, numbering: any): any[];
 export const EQ_KEY_PATTERN: RegExp;
 /** A `\label{eq:<key>}` anywhere in a math source. Global; `key` in group 1. */
 export const EQ_LABEL_PATTERN: RegExp;
+/**
+ * A `\caption{<short caption>}` anywhere in a math source — the equation's
+ * short caption, plain text with no nested braces. Global; the text in group
+ * 1. An equation takes only a short caption: it names the equation in the
+ * `[[eq-…]]` preview card and in the "Copy LaTeX — ‹caption›" tooltip, and is
+ * stripped before KaTeX exactly like `\label{}`.
+ */
+export const EQ_CAPTION_PATTERN: RegExp;
 /**
  * A `[[ … ]]` payload that targets an equation: `eq-<key>` on the current page,
  * or `<lesson-slug>#eq-<key>` across pages. `lesson` (group 1) is a `/`-slug.
  * The `eq-` prefix is reserved — a notation key may not start with it.
  */
 export const EQ_REF_PATTERN: RegExp;
+/**
+ * The components whose bodies stay in the lesson's reading order: `<Memo>`,
+ * `<ShortNote>` and `<Fold>`. Unlike a worked-example/presentation wrapper,
+ * their bodies are details or folded stretches of the lesson itself, so a
+ * numbered equation or float in one stays in the official sequence. Every
+ * scan and tree walk that numbers equations or floats reads this list.
+ */
+export const TRANSPARENT_COMPONENTS: readonly string[];

package/dist/reference/equations.mjs

@@ -4,23 +4,24 @@
  * Every display equation (`$$…$$`) in a lesson is numbered and given an `id`
  * from appearance order. When the caller supplies `numbering`
  * (`{ prefix, offset }` — see `resolveNumbering`), the number is
- * `‹part›.‹offset + n›`: the prefix is the **part**'s ordinal among the sidebar
- * groups, `n` counts every display equation in the lesson, and `offset` carries
- * the count from earlier lessons of the same part so the sequence runs
- * continuously across a part rather than restarting on every page. `##` and
- * `###` headings never affect it — `(2.4)` is the fourth display equation of
- * part 2, wherever in that part it sits. See `docs/authoring/structure.md` for
- * the level names. With no `numbering` the number falls back to the
- * `##`-section scheme `‹section›.‹indexInSection›` (used by hand-built test
- * trees and non-lesson pages). An author additionally
+ * `‹prefix›.‹offset + n›`: `n` counts every display equation in the lesson,
+ * and the course's `numbering.floats` scope decides the rest — `chapter` (the
+ * default) makes the prefix `‹part›.‹chapter›` with no offset, so `(2.2.4)` is
+ * the fourth display equation of part 2's second chapter; `part` makes it the
+ * part's ordinal alone, with `offset` carrying the count from earlier lessons
+ * of the part so the sequence runs on across it. `##` and `###` headings never
+ * affect it. See `docs/authoring/structure.md` for the level names. With no
+ * `numbering` the number falls back to the `##`-section scheme
+ * `‹section›.‹indexInSection›` (used by hand-built test trees and non-lesson
+ * pages). An author additionally
  * marks an equation with a trailing `\label{eq:<key>}` inside its `$$…$$`
  * block (inside math, so the `:` is safe and the form matches amsmath) when
  * they want a *stable* anchor that survives edits and cross-page references:
  *
- *   [[eq-discount-factor-def]]           same page  → "(2.4)" linked to #eq-…
+ *   [[eq-discount-factor-def]]           same page  → "(2.2.4)" linked to #eq-…
  *   [[foundations/present-value#eq-pv]]  cross page → number from the manifest
  *
- * An unkeyed equation still gets a positional anchor (`#eq-2-4`) so it can be
+ * An unkeyed equation still gets a positional anchor (`#eq-2-2-4`) so it can be
  * deep-linked, but only a keyed equation is referenceable by name.
  *
  * `scanEquationLabels` (raw Markdown) and `collectEquationLabels` (mdast tree)
@@ -37,6 +38,28 @@ export const EQ_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 export const EQ_LABEL_PATTERN =
   /\\label\{\s*eq:([a-z0-9]+(?:-[a-z0-9]+)*)\s*\}/g;
 
+/**
+ * A `\caption{<short caption>}` anywhere in a math source — the equation's
+ * short caption, plain text with no nested braces. Global; the text in group
+ * 1. An equation takes only a short caption: it names the equation in the
+ * `[[eq-…]]` preview card and in the "Copy LaTeX — ‹caption›" tooltip, and is
+ * stripped before KaTeX exactly like `\label{}`.
+ */
+export const EQ_CAPTION_PATTERN = /\\caption\{([^{}]*)\}/g;
+
+/**
+ * The short caption a display equation carries, trimmed, or `null` when it
+ * has none. Only the first `\caption{}` counts; `remark-notation.mjs` fails a
+ * page that gives one equation two, or an empty one.
+ */
+export function equationCaption(latex) {
+  EQ_CAPTION_PATTERN.lastIndex = 0;
+  const match = EQ_CAPTION_PATTERN.exec(String(latex ?? ''));
+  EQ_CAPTION_PATTERN.lastIndex = 0;
+  const text = match?.[1]?.replace(/\s+/g, ' ').trim();
+  return text ? text : null;
+}
+
 /**
  * A `[[ … ]]` payload that targets an equation: `eq-<key>` on the current page,
  * or `<lesson-slug>#eq-<key>` across pages. `lesson` (group 1) is a `/`-slug.
@@ -52,10 +75,14 @@ export function parseEquationRef(raw) {
   return match[1] ? { lesson: match[1], key: match[2] } : { key: match[2] };
 }
 
-/** Remove every `\label{eq:…}` (and the whitespace it leaves) from a math source. */
+/**
+ * Remove every `\label{eq:…}` and `\caption{…}` (and the whitespace they
+ * leave) from a math source: both are identity markers, not math KaTeX parses.
+ */
 export function stripEquationLabels(latex) {
   return String(latex)
     .replace(EQ_LABEL_PATTERN, '')
+    .replace(EQ_CAPTION_PATTERN, '')
     .replace(/[ \t]+\n/g, '\n')
     .replace(/\n{3,}/g, '\n\n')
     .replace(/[ \t]{2,}/g, ' ')
@@ -70,13 +97,14 @@ function equationNumber(section, index) {
 /**
  * Normalise the numbering input to `{ prefix, offset }`.
  *
- * `prefix` is the number before the dot — the **part**'s ordinal (its position
- * among the sidebar groups). `offset` is how many display equations already
- * appeared in earlier lessons of that same part, so `n` runs continuously
- * across a part instead of restarting on every page. A bare number is the
- * legacy per-lesson form (`prefix = n`, `offset = 0`) and is still accepted so
- * hand-built trees and unit tests keep working. `undefined`/`null`/`0` ⇒ the
- * `##`-section fallback for non-lesson pages.
+ * `prefix` is everything before the last dot — `‹part›.‹chapter›` under the
+ * default `numbering.floats: "chapter"`, the part's ordinal under `"part"`.
+ * `offset` is how many items of the kind precede the lesson in that scope: 0
+ * for a chapter, the earlier chapters' count for a part, so `n` runs on
+ * across it. A bare number is the legacy per-lesson form (`prefix = n`,
+ * `offset = 0`) and is still accepted so hand-built trees and unit tests keep
+ * working. `undefined`/`null`/`0`/`''` ⇒ the `##`-section fallback for
+ * non-lesson pages.
  */
 export function resolveNumbering(input) {
   if (input == null) return { prefix: undefined, offset: 0 };
@@ -90,9 +118,9 @@ export function resolveNumbering(input) {
 }
 
 /**
- * The visible number for one display equation. With a `prefix` (the part's
- * ordinal) the scheme is `‹part›.‹offset + indexInLesson›` and `##` headings
- * are ignored; without it, the legacy `##`-section scheme.
+ * The visible number for one display equation. With a `prefix` the scheme is
+ * `‹prefix›.‹offset + indexInLesson›` and `##` headings are ignored; without
+ * it, the legacy `##`-section scheme.
  */
 export function displayEquationNumber({
   prefix,
@@ -136,10 +164,8 @@ export function stripFencedCode(markdown) {
  * component while still finding `<Table>`/`<Figure>` tags at the top level.
  *
  * `transparent`, when given, removes only those components' opening/closing
- * tags and exposes their body to the later blanking pass. `<Memo>` and
- * `<ShortNote>` are intentional uses: unlike a worked-example/presentation
- * wrapper, their bodies are details in the lesson's reading order, so numbered
- * equations/floats in them stay in the official sequence. Section headings in
+ * tags and exposes their body to the later blanking pass. The
+ * {@link TRANSPARENT_COMPONENTS} are the intentional uses. Section headings in
  * a transparent body do not change the surrounding page's section counter.
  */
 export function stripJsxComponents(markdown, keep, transparent = []) {
@@ -169,23 +195,35 @@ export function stripJsxComponents(markdown, keep, transparent = []) {
   );
 }
 
+/**
+ * The components whose bodies stay in the lesson's reading order: `<Memo>`,
+ * `<ShortNote>` and `<Fold>`. Unlike a worked-example/presentation wrapper,
+ * their bodies are details or folded stretches of the lesson itself, so a
+ * numbered equation or float in one stays in the official sequence. Every
+ * scan and tree walk that numbers equations or floats reads this list.
+ */
+export const TRANSPARENT_COMPONENTS = Object.freeze(['Memo', 'ShortNote', 'Fold']);
+
 /**
  * Every display equation in a Markdown body, keyed or not, in appearance order
- * with its assigned number. `$$…$$` blocks only. With `numbering`
- * (`{ prefix, offset }`, the part's ordinal and the count of display equations
- * in earlier lessons of that part) the number is `‹part›.‹offset + n›`, `n`
- * sequential over every display block in the lesson; without it, `##` headings
- * advance a section counter and the number is `‹section›.‹indexInSection›`.
+ * with its assigned number and its `\caption{}` short caption (`short`, or
+ * `null`). `$$…$$` blocks only. With `numbering`
+ * (`{ prefix, offset }`, the lesson's float-number prefix and the count of
+ * display equations before it in that scope) the number is
+ * `‹prefix›.‹offset + n›`, `n` sequential over every display block in the
+ * lesson; without it, `##` headings advance a section counter and the number
+ * is `‹section›.‹indexInSection›`.
  * Either way every display block advances the index, so a keyed equation's
  * number reflects its position among *all* display equations, not only the
  * keyed ones.
  */
 export function scanDisplayEquations(markdown, numbering) {
   const { prefix, offset } = resolveNumbering(numbering);
-  const text = stripJsxComponents(stripFencedCode(markdown), undefined, [
-    'Memo',
-    'ShortNote',
-  ]);
+  const text = stripJsxComponents(
+    stripFencedCode(markdown),
+    undefined,
+    TRANSPARENT_COMPONENTS,
+  );
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
   const display = /\$\$([\s\S]+?)\$\$/g;
@@ -199,6 +237,7 @@ export function scanDisplayEquations(markdown, numbering) {
       kind: 'equation',
       index: match.index,
       key: label ? label[1] : null,
+      short: equationCaption(match[1]),
     });
   }
   tokens.sort((a, b) => a.index - b.index);
@@ -224,6 +263,7 @@ export function scanDisplayEquations(markdown, numbering) {
         indexInSection,
         indexInLesson,
       }),
+      short: token.short,
       section,
       indexInSection,
     });
@@ -261,11 +301,11 @@ export function collectDisplayEquations(tree, numbering) {
   let indexInSection = 0;
   let indexInLesson = 0;
 
-  // Top-level blocks plus the bodies of `<Memo>` and `<ShortNote>`: other MDX
-  // components (a `<CompactExample>` worked example, an `<Aside>`) remain
-  // illustrative and outside the lesson's official equation sequence. These
-  // two detail components are deliberately transparent because they occupy an
-  // exact point in the reading order, even while visually collapsed.
+  // Top-level blocks plus the bodies of the `TRANSPARENT_COMPONENTS`: other
+  // MDX components (a `<CompactExample>` worked example, an `<Aside>`) remain
+  // illustrative and outside the lesson's official equation sequence. The
+  // transparent ones occupy an exact point in the reading order, even while
+  // visually collapsed.
   const collectFromDetail = (node) => {
     if (!node || typeof node !== 'object') return;
     if (node.type === 'math') {
@@ -275,6 +315,7 @@ export function collectDisplayEquations(tree, numbering) {
       const label = EQ_LABEL_PATTERN.exec(String(node.value ?? ''));
       equations.push({
         key: label ? label[1] : null,
+        short: equationCaption(node.value),
         number: displayEquationNumber({
           prefix,
           offset,
@@ -290,8 +331,7 @@ export function collectDisplayEquations(tree, numbering) {
     }
     if (
       node.type === 'mdxJsxFlowElement' &&
-      node.name !== 'Memo' &&
-      node.name !== 'ShortNote'
+      !TRANSPARENT_COMPONENTS.includes(node.name)
     ) {
       return;
     }
@@ -310,7 +350,7 @@ export function collectDisplayEquations(tree, numbering) {
     if (node.type === 'math') collectFromDetail(node);
     else if (
       node.type === 'mdxJsxFlowElement' &&
-      (node.name === 'Memo' || node.name === 'ShortNote')
+      TRANSPARENT_COMPONENTS.includes(node.name)
     ) {
       collectFromDetail(node);
     }