explico 0.7.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

@@ -1,15 +1,21 @@
 /**
- * Rule N17: nested scalable delimiters must make their hierarchy visible.
+ * Rule N17: a nested scalable delimiter is sized by the engine, never by hand.
+ *
+ * The engine installs a KaTeX whose `\delimitershortfall` is `-1pt`
+ * (`katex-delimiters.mjs`), so a `\left`/`\right` pair is always
+ * strictly taller than what it wraps. Nesting depth therefore shows up on its
+ * own, and a hand-picked `\bigl`…`\Biggr` inside a nest only replaces a size
+ * that tracks the content with a fixed glyph that does not.
  *
  * 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-size-hierarchy";
+declare const DELIMITER_SIZE_DIAGNOSTIC_CODE: "delimiter-manual-size";
 type DelimiterSizeName = 'automatic' | 'big' | 'Big' | 'bigg' | 'Bigg';
 interface DelimiterSizeSuggestion {
-    readonly size: Exclude<DelimiterSizeName, 'automatic' | 'big'>;
     readonly open: string;
     readonly close: string;
     readonly latex: string;
@@ -20,15 +26,19 @@ interface DelimiterSizeDiagnostic {
     readonly offset: number;
     readonly line: number;
     readonly column: number;
-    readonly outerSize: DelimiterSizeName;
-    readonly nestedSize: DelimiterSizeName;
-    readonly suggestion?: DelimiterSizeSuggestion;
+    /** The hand-picked size that should become `\left`/`\right`. */
+    readonly size: Exclude<DelimiterSizeName, 'automatic'>;
+    readonly suggestion: DelimiterSizeSuggestion;
     readonly message: string;
 }
 /**
- * Warn when a scalable outer pair is not at least one manual size level above
- * everything nested inside it. `\left` and `\big` form the baseline level;
- * progressively larger levels are `\Big`, `\bigg`, and `\Bigg`.
+ * Warn when a pair that takes part in a nest of scalable delimiters is sized
+ * by hand instead of by `\left`/`\right`.
+ *
+ * A pair takes part in a nest when it contains, or sits inside, another pair
+ * this linter tracks. A lone hand-sized pair around otherwise bare content —
+ * `\bigl(x(t),\ y(t)\bigr)` for a tuple — is a deliberate typographic
+ * choice at a single level, has no hierarchy to get wrong, and is left alone.
  *
  * Only `()`, `[]`, and `\{\}` are parsed. Bare delimiters are intentionally
  * ignored: N15 owns that separate error, while ordinary semantic notation

package/dist/reference/delimiter-size.js

@@ -1,4 +1,4 @@
-const DELIMITER_SIZE_DIAGNOSTIC_CODE = "delimiter-size-hierarchy";
+const DELIMITER_SIZE_DIAGNOSTIC_CODE = "delimiter-manual-size";
 const SIZE_SPECS = [
   {
     name: "automatic",
@@ -40,9 +40,6 @@ const COMMAND_SPECS = SIZE_SPECS.flatMap((spec) => [
   { ...spec, command: spec.openCommand, tokenKind: "open" },
   { ...spec, command: spec.closeCommand, tokenKind: "close" }
 ]).sort((left, right) => right.command.length - left.command.length);
-const SUGGESTION_BY_RANK = new Map(
-  SIZE_SPECS.filter((spec) => spec.rank >= 2).map((spec) => [spec.rank, spec])
-);
 function delimiterAt(latex, offset, kind) {
   const candidates = kind === "open" ? ["\\{", "(", "["] : ["\\}", ")", "]"];
   for (const delimiter of candidates) {
@@ -120,55 +117,34 @@ function lineAndColumn(source, offset) {
     column: offset - lastNewline
   };
 }
-function sizeName(rank) {
-  return SUGGESTION_BY_RANK.get(rank)?.name ?? "Bigg";
-}
-function suggestionFor(pair, requiredRank) {
-  const close = pair.close;
-  const spec = SUGGESTION_BY_RANK.get(requiredRank);
-  if (!close || !spec || spec.name === "automatic" || spec.name === "big") {
-    return void 0;
-  }
-  return {
-    size: spec.name,
-    open: `${spec.openCommand}${pair.open.delimiter}`,
-    close: `${spec.closeCommand}${close.delimiter}`,
-    latex: `${spec.openCommand}${pair.open.delimiter} ... ${spec.closeCommand}${close.delimiter}`
-  };
+const SPEC_BY_SIZE = new Map(SIZE_SPECS.map((spec) => [spec.name, spec]));
+function suggestionFor(pair) {
+  const open = `\\left${pair.open.delimiter}`;
+  const close = `\\right${pair.close?.delimiter ?? pair.open.delimiter}`;
+  return { open, close, latex: `${open} ... ${close}` };
 }
 function lintDelimiterSizes(latex) {
   const roots = parseDelimiterPairs(latex);
   if (!roots) return [];
   const diagnostics = [];
-  const assess = (pair) => {
-    let largestNestedRequirement = 0;
-    let representativeNestedSize = "automatic";
-    for (const child of pair.children) {
-      const childRequired = assess(child);
-      if (childRequired > largestNestedRequirement) {
-        largestNestedRequirement = childRequired;
-        representativeNestedSize = sizeName(childRequired);
-      }
-    }
-    const requiredRank = largestNestedRequirement === 0 ? pair.open.rank : largestNestedRequirement + 1;
-    pair.requiredRank = Math.max(pair.open.rank, requiredRank);
-    if (largestNestedRequirement > 0 && pair.open.rank < requiredRank) {
+  const visit = (pair, nested) => {
+    const inNest = nested || pair.children.length > 0;
+    if (inNest && pair.open.pairKind === "manual") {
       const location = lineAndColumn(latex, pair.open.offset);
-      const suggestion = suggestionFor(pair, requiredRank);
+      const suggestion = suggestionFor(pair);
       diagnostics.push({
         code: DELIMITER_SIZE_DIAGNOSTIC_CODE,
         severity: "warning",
         offset: pair.open.offset,
         ...location,
-        outerSize: pair.open.size,
-        nestedSize: representativeNestedSize,
-        ...suggestion ? { suggestion } : {},
-        message: suggestion ? `Outer delimiters are not larger than their nested pair. Use ${suggestion.latex}; preserve the original opening and closing delimiter shapes (rule N17).` : `Outer delimiters are not larger than their nested pair, and no larger standard manual delimiter size remains. Preserve the original opening and closing shapes and restructure the expression if necessary (rule N17).`
+        size: pair.open.size,
+        suggestion,
+        message: `A nested delimiter pair is sized by hand with ${SPEC_BY_SIZE.get(pair.open.size)?.openCommand ?? pair.open.size}${pair.open.delimiter}. Use ${suggestion.latex} and let the engine size the nest; preserve the original opening and closing delimiter shapes (rule N17).`
       });
     }
-    return pair.requiredRank;
+    for (const child of pair.children) visit(child, true);
   };
-  for (const root of roots) assess(root);
+  for (const root of roots) visit(root, false);
   return diagnostics.sort((left, right) => left.offset - right.offset);
 }
 export {

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;
@@ -35,10 +45,16 @@ export function displayEquationNumber({ prefix, offset, section, indexInSection,
     indexInSection: any;
     indexInLesson: any;
 }): string;
-/** The positional anchor id for an unkeyed equation, e.g. `2.4` → `eq-2-4`. */
+/**
+ * A display equation's anchor id: `eq-<key>` when it carries a
+ * `\label{eq:…}`, else the positional form, e.g. `2.4` → `eq-2-4`.
+ *
+ * @param {{ key?: string, number?: string | number }} equation - `number` is
+ *   read only when there is no `key`, so a keyed caller may omit it.
+ */
 export function equationAnchorId({ key, number }: {
-    key: any;
-    number: any;
+    key?: string;
+    number?: string | number;
 }): string;
 export function stripFencedCode(markdown: any): string;
 /**
@@ -53,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.
@@ -74,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;
 }[];
@@ -81,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;
 }[];
@@ -109,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)
@@ -138,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[];