explico 0.8.0 → 0.11.0

package/src/reference/remark-notation.mjs

@@ -39,6 +39,7 @@ import {
   stripNotationMarkers,
 } from './math-glyphs.mjs';
 import {
+  EQ_CAPTION_PATTERN,
   EQ_LABEL_PATTERN,
   collectDisplayEquations,
   collectEquationLabels,
@@ -57,6 +58,7 @@ import {
   parseKnowledgeCheckRef,
 } from './knowledge-checks.mjs';
 import { injectMdxStringAttributes } from './mdx-attributes.mjs';
+import { collectSectionHeadings, parseSectionRef } from './sections.mjs';
 
 const PROSE_SKIP_TYPES = new Set([
   'code',
@@ -128,6 +130,23 @@ function localDefinitionsFromFile(file) {
   return definitionsMap(candidates.find(Array.isArray));
 }
 
+/**
+ * The decorations a lesson suspends (`notation.suspend`, rule N22), by name.
+ * Read here as well as in the gate because `astro dev` renders without
+ * running the gate. The loader (`collections.ts`) validates the names.
+ */
+function suspendedOperatorsFromFile(file) {
+  const candidates = [
+    file?.data?.astro?.frontmatter?.notation?.suspend,
+    file?.data?.frontmatter?.notation?.suspend,
+    file?.data?.notation?.suspend,
+  ];
+  const suspend = candidates.find(Array.isArray) ?? [];
+  return suspend
+    .map((item) => (typeof item?.operator === 'string' ? item.operator.trim() : ''))
+    .filter((operator) => operator !== '');
+}
+
 // Registry definition pages (`src/content/notation/*.md`) carry their own
 // worked equations. Their math is resolved against the whole shared registry:
 // an author writes ordinary LaTeX (or an explicit `\explain{key}{latex}`) and
@@ -367,7 +386,8 @@ function inlineEquationNode(mathNode) {
  * at its positional `#eq-<section>-<index>`. The visible number is a focusable
  * `<a>` sibling — never authored, never inside KaTeX — so it survives print and
  * screen readers name it "Equation 2.4". A "Copy LaTeX" button sits beside it
- * (`.keyed-equation__controls`, styled in `global.css`) — the equation's own
+ * (`.keyed-equation__controls`, styled in `global.css`; titled "Copy LaTeX —
+ * ‹short›" when the equation has a `\caption{}`) — the equation's own
  * copy affordance, distinct from the notation popup card's (`NotationLayer.astro`),
  * which only exists for a symbol with a registry entry, not a bare display
  * equation. `mathNode.value` is read here — after the resolver above has
@@ -376,7 +396,7 @@ function inlineEquationNode(mathNode) {
  * author-written one; either way the reader copies plain LaTeX, never this
  * system's own notation-key plumbing (`math-glyphs.mjs:stripNotationMarkers`).
  */
-function equationNode(mathNode, { key, number }) {
+function equationNode(mathNode, { key, number, short }) {
   const id = equationAnchorId({ key, number });
   const hProperties = {
     id,
@@ -385,6 +405,9 @@ function equationNode(mathNode, { key, number }) {
   };
   if (key) hProperties['data-eq-key'] = key;
   else hProperties['data-eq-auto'] = '';
+  // The `\caption{}` short caption names the equation wherever it is shown
+  // away from itself: the `[[eq-…]]` preview card and the copy tooltip.
+  if (short) hProperties['data-eq-short'] = short;
 
   const latex = stripNotationMarkers(String(mathNode.value ?? ''));
 
@@ -416,7 +439,7 @@ function equationNode(mathNode, { key, number }) {
             'data-eq-copy': '',
             'data-latex': latex,
             'aria-label': `Copy LaTeX for Equation ${number}`,
-            title: 'Copy LaTeX',
+            title: short ? `Copy LaTeX — ${short}` : 'Copy LaTeX',
           },
           [copyIconNode()],
         ),
@@ -502,6 +525,47 @@ function resolveKeyedFloatRef(floatRef, ctx, { prefix, tagName }, file, node) {
   return { number, href: `#${prefix}-${floatRef.key}` };
 }
 
+/**
+ * Resolve a `[[sec-slug]]` / `[[lesson/slug#sec-slug]]` reference to the
+ * heading's `{ href, text }`: `§ 1.1.2` for a numbered section when the
+ * course shows section numbers, else the heading's own title in quotes — a
+ * reference never prints a number the reader cannot find on the page.
+ */
+function resolveSectionRef(secRef, ctx, file, node) {
+  const heading = secRef.lesson
+    ? ctx.crossPage?.[secRef.lesson]?.[secRef.key]
+    : ctx.pageHeadings.get(secRef.key);
+  if (heading === undefined) {
+    fail(
+      file,
+      secRef.lesson
+        ? `Unknown section reference [[${secRef.lesson}#sec-${secRef.key}]]: lesson ${secRef.lesson} has no top-level heading anchored #${secRef.key}.`
+        : `Unknown section reference [[sec-${secRef.key}]]: no top-level heading on this page is anchored #${secRef.key}.`,
+      node,
+    );
+  }
+  return {
+    href: secRef.lesson
+      ? `${ctx.base.replace(/\/$/, '')}/${secRef.lesson}/#${secRef.key}`
+      : `#${secRef.key}`,
+    text:
+      ctx.show && heading.number
+        ? `§ ${heading.number}`
+        : `“${heading.text}”`,
+  };
+}
+
+/**
+ * How a reference names a knowledge check or a worked-example set: `‹Kind›
+ * 1.1.1` when the course shows section numbers — those blocks' numbers follow
+ * the sections' (docs/plans/titles-and-containers.md Q11) — else `‹Kind›
+ * “‹title›”`, so a reference never prints a number the page does not show.
+ * The number is the fallback when the manifest carries no title.
+ */
+function blockRefText(kind, number, title, show) {
+  return show || !title ? `${kind} ${number}` : `${kind} “${title}”`;
+}
+
 /** Resolve a numbered knowledge check declared by a lesson's `.checks.yml`. */
 function resolveKnowledgeCheckRef(checkRef, ctx, file, node) {
   if (checkRef.lesson) {
@@ -515,6 +579,7 @@ function resolveKnowledgeCheckRef(checkRef, ctx, file, node) {
     }
     return {
       number,
+      title: ctx.titles?.[checkRef.lesson]?.[checkRef.key],
       href: `${ctx.base.replace(/\/$/, '')}/${checkRef.lesson}/#${knowledgeCheckAnchorId(checkRef.key)}`,
     };
   }
@@ -526,7 +591,11 @@ function resolveKnowledgeCheckRef(checkRef, ctx, file, node) {
       node,
     );
   }
-  return { number, href: `#${knowledgeCheckAnchorId(checkRef.key)}` };
+  return {
+    number,
+    title: ctx.titles?.[ctx.slug]?.[checkRef.key],
+    href: `#${knowledgeCheckAnchorId(checkRef.key)}`,
+  };
 }
 
 function proseNodes(
@@ -540,6 +609,8 @@ function proseNodes(
   figureCtx,
   diagramCtx,
   checkCtx,
+  sectionCtx,
+  exampleCtx,
 ) {
   const base = eqCtx?.base ?? '';
   const strayExplain = firstUnescaped(value, EXPLAIN);
@@ -571,16 +642,35 @@ function proseNodes(
       !eqRef && !tableRef && !figureRef && diagramCtx
         ? parseKeyedFloatRef(key, { prefix: 'dia' })
         : undefined;
+    // `ex-` (a worked-example set) is reserved the same way as `sec-` below.
+    const exampleRef =
+      !eqRef && !tableRef && !figureRef && !diagramRef && exampleCtx
+        ? parseKeyedFloatRef(key, { prefix: 'ex' })
+        : undefined;
     const checkRef =
-      !eqRef && !tableRef && !figureRef && !diagramRef && checkCtx
+      !eqRef && !tableRef && !figureRef && !diagramRef && !exampleRef && checkCtx
         ? parseKnowledgeCheckRef(key)
         : undefined;
+    // `sec-` is a reserved prefix like the others: `[[sec-foo]]` would also
+    // pass as a notation key, so it has to be claimed before that check.
+    const secRef =
+      !eqRef &&
+      !tableRef &&
+      !figureRef &&
+      !diagramRef &&
+      !exampleRef &&
+      !checkRef &&
+      sectionCtx
+        ? parseSectionRef(key)
+        : undefined;
     if (
       !eqRef &&
       !tableRef &&
       !figureRef &&
       !diagramRef &&
+      !exampleRef &&
       !checkRef &&
+      !secRef &&
       !NOTATION_KEY_PATTERN.test(key)
     ) {
       fail(file, `Invalid notation key "${key}" in [[...]].`, node);
@@ -613,8 +703,31 @@ function proseNodes(
       continue;
     }
 
+    if (secRef) {
+      const { href, text } = resolveSectionRef(secRef, sectionCtx, file, node);
+      output.push({
+        type: 'link',
+        url: href,
+        children: [{ type: 'text', value: text }],
+        data: {
+          hProperties: {
+            className: ['section-ref'],
+            'data-sec-ref': secRef.key,
+            ...(secRef.lesson ? { 'data-sec-lesson': secRef.lesson } : {}),
+          },
+        },
+      });
+      references.push({
+        key: secRef.key,
+        kind: 'section',
+        ...(secRef.lesson ? { lesson: secRef.lesson } : {}),
+      });
+      cursor = match.index + match[0].length;
+      continue;
+    }
+
     if (checkRef) {
-      const { number, href } = resolveKnowledgeCheckRef(
+      const { number, title, href } = resolveKnowledgeCheckRef(
         checkRef,
         checkCtx,
         file,
@@ -623,7 +736,12 @@ function proseNodes(
       output.push({
         type: 'link',
         url: href,
-        children: [{ type: 'text', value: `Knowledge check ${number}` }],
+        children: [
+          {
+            type: 'text',
+            value: blockRefText('Knowledge check', number, title, checkCtx.show),
+          },
+        ],
         data: {
           hProperties: {
             className: ['knowledge-check-ref'],
@@ -643,6 +761,43 @@ function proseNodes(
       continue;
     }
 
+    if (exampleRef) {
+      const { number, href } = resolveKeyedFloatRef(
+        exampleRef,
+        exampleCtx,
+        { prefix: 'ex', tagName: 'CompactExamples' },
+        file,
+        node,
+      );
+      const title = exampleCtx.titles?.[exampleRef.lesson ?? exampleCtx.slug]?.[
+        exampleRef.key
+      ];
+      output.push({
+        type: 'link',
+        url: href,
+        children: [
+          {
+            type: 'text',
+            value: blockRefText('Example', number, title, exampleCtx.show),
+          },
+        ],
+        data: {
+          hProperties: {
+            className: ['example-ref'],
+            'data-ex-ref': exampleRef.key,
+            ...(exampleRef.lesson ? { 'data-ex-lesson': exampleRef.lesson } : {}),
+          },
+        },
+      });
+      references.push({
+        key: exampleRef.key,
+        kind: 'example',
+        ...(exampleRef.lesson ? { lesson: exampleRef.lesson } : {}),
+      });
+      cursor = match.index + match[0].length;
+      continue;
+    }
+
     const floatRef = tableRef ?? figureRef ?? diagramRef;
     if (floatRef) {
       const kind = tableRef ? 'table' : figureRef ? 'figure' : 'diagram';
@@ -810,34 +965,67 @@ function inspectExplainCalls(value, resolve, file, node, references) {
  * Every number on a page comes from two places that MUST agree: the page's own
  * counters (`numbering`) and the manifest tables a cross-page `[[slug#eq-key]]`
  * is resolved against (`equations` / `tables` / `figures` / `diagrams` /
- * `checks`).
+ * `checks` / `examples`).
  * Deriving every input from the same manifest in one step stops a course config from
  * supplying one without the other — the omission that produced page-local
  * `(2.2)` and cross-page `(4.5)` for the same equation.
  *
  * `numbering` maps a lesson slug to
- * `{ part, equations, tables, figures, diagrams, checks }`: the part's ordinal
- * (the number before the dot) and, per numbered kind, how many earlier lessons
- * of that part already used.
+ * `{ part, chapter, prefix, equations, tables, figures, diagrams, checks,
+ * examples }`:
+ * the part and chapter ordinals, the float-number prefix (`‹part›.‹chapter›`,
+ * or the part alone under `numbering.floats: "part"`), and, per numbered kind,
+ * how many precede the lesson in that scope. `sections` maps a lesson slug to
+ * its top-level headings (`manifest.lessons[].headings`), and
+ * `sectionNumbering` is the course's `{ show, depth }`. `checkTitles` and
+ * `exampleTitles` map a lesson slug to its checks' and example sets' titles,
+ * which a reference prints when the course hides section numbers.
  */
 export function numberingFromManifest(manifest) {
   if (!manifest || typeof manifest !== 'object') return {};
+  const titlesOf = (entriesOf) =>
+    Object.fromEntries(
+      (manifest.lessons ?? []).map((lesson) => [
+        lesson.slug,
+        Object.fromEntries(
+          (entriesOf(lesson) ?? [])
+            .filter((entry) => entry.title)
+            .map((entry) => [entry.key, entry.title]),
+        ),
+      ]),
+    );
   return {
     equations: manifest.equations?.numbersBySlug ?? {},
     tables: manifest.tables?.numbersBySlug ?? {},
     figures: manifest.figures?.numbersBySlug ?? {},
     diagrams: manifest.diagrams?.numbersBySlug ?? {},
     checks: manifest.checks?.numbersBySlug ?? {},
+    examples: manifest.examples?.numbersBySlug ?? {},
+    checkTitles: titlesOf((lesson) => lesson.knowledgeChecks),
+    exampleTitles: titlesOf((lesson) =>
+      lesson.examples?.map(({ key, short }) => ({ key, title: short })),
+    ),
+    // Only a lesson that carries `headings` (schema v20 on) — a hand-built
+    // manifest without them leaves the page's headings as Astro would.
+    sections: Object.fromEntries(
+      (manifest.lessons ?? [])
+        .filter((lesson) => Array.isArray(lesson.headings))
+        .map((lesson) => [lesson.slug, lesson.headings]),
+    ),
+    sectionNumbering: manifest.numbering?.sections ?? { show: true, depth: 4 },
     numbering: Object.fromEntries(
       (manifest.lessons ?? []).map((lesson) => [
         lesson.slug,
         {
           part: lesson.part,
+          chapter: lesson.chapter,
+          prefix: lesson.numbering?.prefix ?? String(lesson.part || ''),
           equations: lesson.numbering?.equations ?? 0,
           tables: lesson.numbering?.tables ?? 0,
           figures: lesson.numbering?.figures ?? 0,
           diagrams: lesson.numbering?.diagrams ?? 0,
           checks: lesson.numbering?.checks ?? 0,
+          examples: lesson.numbering?.examples ?? 0,
         },
       ]),
     ),
@@ -876,20 +1064,77 @@ export function createRemarkNotationOptions(manifest, overrides = {}) {
 
 /**
  * `{ prefix, offset }` for one kind of float on one page, from whichever
- * numbering option the caller supplied. `numbering` is the current form;
- * `chapters` is the superseded per-lesson form (prefix = the lesson's ordinal,
- * no offset) and is still read so an unmigrated config keeps working.
+ * numbering option the caller supplied. `numbering` is the current form (its
+ * `prefix` when given, else the part alone); `chapters` is the superseded
+ * per-lesson form (prefix = the lesson's ordinal, no offset) and is still read
+ * so an unmigrated config keeps working.
  */
 function pageNumbering(options, slug, kind) {
   if (!slug) return undefined;
   const placement = options.numbering?.[slug];
   if (placement?.part) {
-    return { prefix: placement.part, offset: placement[kind] ?? 0 };
+    return {
+      prefix: placement.prefix || placement.part,
+      offset: placement[kind] ?? 0,
+    };
   }
   const chapter = options.chapters?.[slug];
   return chapter ? { prefix: chapter, offset: 0 } : undefined;
 }
 
+/**
+ * Give a lesson's top-level headings the anchors and outline numbers the
+ * manifest decided (`sections.mjs`): an `id` on every one, and
+ * `data-sec-number` on a numbered one when the course shows section numbers
+ * (`global.css` prints it). The page must see the headings the manifest saw —
+ * same count, same levels, so the same numbers — or a `[[sec-…]]` from another
+ * page would print a number this page does not show; any difference fails the
+ * build, the section counterpart of `assertManifestNumberParity`.
+ */
+function stampSectionHeadings({ tree, file, slug, published, placement, settings }) {
+  const onPage = collectSectionHeadings(tree, {
+    ...(placement?.part && placement?.chapter
+      ? { prefix: `${placement.part}.${placement.chapter}` }
+      : {}),
+    depth: settings.depth,
+  });
+  const outline = (headings) =>
+    headings.length === 0
+      ? '(none)'
+      : headings
+          .map((heading) =>
+            `${'#'.repeat(heading.level)}${heading.number ? ` ${heading.number}` : ''}`,
+          )
+          .join(', ');
+  const agree =
+    onPage.length === published.length &&
+    onPage.every(
+      (heading, index) =>
+        heading.level === published[index].level &&
+        heading.number === published[index].number,
+    );
+  if (!agree) {
+    fail(
+      file,
+      `Stale Explico manifest for ${slug}: this page's top-level headings are ` +
+        `${outline(onPage)}, but the manifest lists ${outline(published)}. ` +
+        'Recompile the manifest from the current content. If it is current, a ' +
+        'heading is written in a form the manifest does not read — an ' +
+        'underlined (setext) heading, or one inside a list or a blockquote; ' +
+        'write it as `## Heading` on a line of its own.',
+    );
+  }
+  onPage.forEach(({ node }, index) => {
+    const { slug: id, number } = published[index];
+    node.data = node.data ?? {};
+    node.data.hProperties = {
+      ...node.data.hProperties,
+      id,
+      ...(settings.show && number ? { 'data-sec-number': number } : {}),
+    };
+  });
+}
+
 /**
  * Fail when the number this page just computed for a keyed float disagrees
  * with the number the manifest publishes for the same key (WERN — a reference
@@ -950,9 +1195,10 @@ function assertManifestNumberParity({
  * missing/wrong map for *keyed* items (it walks `pageLabels`, which unkeyed
  * equations/floats never enter — see `keyed-jsx-floats.mjs`), so a lesson
  * whose only floats are unkeyed can silently fall back to `##`-section
- * numbering with no diagnostic at all. `Diagram` is deliberately excluded by
- * every caller: `Diagram.astro` already tolerates an unplaced diagram
- * rendering without a number, by design.
+ * numbering with no diagnostic at all. `Diagram` and `CompactExamples` are
+ * deliberately excluded by every caller: `Diagram.astro` and
+ * `CompactExamples.astro` already tolerate an unplaced one rendering without
+ * a number, by design.
  */
 function assertStrictNumbering({ file, slug, noun, count, placement, crossPage }) {
   if (!slug || count === 0) return;
@@ -992,7 +1238,12 @@ function assertStrictNumbering({ file, slug, noun, count, placement, crossPage }
  *   figures?: Record<string, Record<string, string>>,
  *   diagrams?: Record<string, Record<string, string>>,
  *   checks?: Record<string, Record<string, string>>,
- *   numbering?: Record<string, { part: number, equations: number, tables: number, figures: number, diagrams: number, checks: number }>,
+ *   examples?: Record<string, Record<string, string>>,
+ *   checkTitles?: Record<string, Record<string, string>>,
+ *   exampleTitles?: Record<string, Record<string, string>>,
+ *   sections?: Record<string, readonly { slug: string, text: string, level: number, number?: string }[]>,
+ *   sectionNumbering?: { show: boolean, depth: number },
+ *   numbering?: Record<string, { part: number, chapter?: number, prefix?: string, equations: number, tables: number, figures: number, diagrams: number, checks: number, examples?: number }>,
  *   chapters?: Record<string, number>,
  * }} [options]
  *
@@ -1001,16 +1252,23 @@ function assertStrictNumbering({ file, slug, noun, count, placement, crossPage }
  * They stay available individually for hand-built trees, and an explicitly
  * supplied one still wins over the manifest.
  *
- * `numbering` maps a lesson slug to its **part** (the number before the dot)
- * and, per kind of float, how many the earlier lessons of that part already
- * used. Every display equation / `<Table>` / `<Figure>` / `<Diagram>` on the page is then
- * numbered `‹part›.‹offset + n›`, with `##` and `###` headings ignored; with no
- * entry the legacy `##`-section scheme applies. It must agree with
+ * `numbering` maps a lesson slug to its **part** and **chapter**, its float
+ * `prefix` (`‹part›.‹chapter›`, or the part alone under `numbering.floats:
+ * "part"`) and, per kind of float, how many precede the lesson in that scope.
+ * Every display equation / `<Table>` / `<Figure>` / `<Diagram>` /
+ * `<CompactExamples>` on the page is then numbered `‹prefix›.‹offset + n›`,
+ * with `##` and `###` headings ignored;
+ * with no entry the legacy `##`-section scheme applies. It must agree with
  * `manifest.lessons[]`, which is what feeds `equations`/`tables`/`figures`/`diagrams`
  * above — supplying the tables without `numbering` numbers the same equation
  * twice, and `assertManifestNumberParity` turns that into a build error rather
  * than a page whose references disagree with their targets.
  *
+ * `sections` maps a lesson slug to its top-level headings, and
+ * `sectionNumbering` is the course's `{ show, depth }`: a page's own headings
+ * take the anchors and outline numbers listed there (`stampSectionHeadings`),
+ * and `[[sec-…]]` prints `§ 1.1.2` from the same list.
+ *
  * `chapters` is the superseded per-lesson form (slug → the lesson's course
  * ordinal, no running offset). Still read when `numbering` has no entry, so a
  * config written against the old option keeps building.
@@ -1029,6 +1287,15 @@ export default function remarkNotation(options = {}) {
   // The manifest supplies every numbering input at once; an explicit option
   // still overrides it, so existing per-field wiring keeps working.
   const numbering = { ...numberingFromManifest(options.manifest), ...options };
+  // Every lesson's headings by anchor, built once: `[[lesson#sec-…]]` reads
+  // another page's, `[[sec-…]]` the page's own.
+  const sectionSettings = { show: true, depth: 4, ...numbering.sectionNumbering };
+  const headingsBySlug = Object.fromEntries(
+    Object.entries(numbering.sections ?? {}).map(([slug, headings]) => [
+      slug,
+      Object.fromEntries(headings.map((heading) => [heading.slug, heading])),
+    ]),
+  );
 
   return function transform(tree, file) {
     const suppliedDefinitions =
@@ -1040,6 +1307,7 @@ export default function remarkNotation(options = {}) {
       (definition) => ({ key: definition.key, notation: definition.notation }),
     );
     const localDefinitions = localDefinitionsFromFile(file);
+    const suspendedOperators = suspendedOperatorsFromFile(file);
     const lessonId = lessonIdFrom(file);
     const lessonSlug = lessonId ? lessonId.replace(/\./g, '/') : undefined;
     // `{ prefix, offset }` per kind of float — see the `numbering` option.
@@ -1136,8 +1404,9 @@ export default function remarkNotation(options = {}) {
         noun: tagName,
         syntax: (key) => `<${tagName} id="${key}">`,
       });
-      // Diagram is deliberately excluded — see `assertStrictNumbering`'s doc.
-      if (strict && tagName !== 'Diagram') {
+      // Diagram and CompactExamples are deliberately excluded — see
+      // `assertStrictNumbering`'s doc.
+      if (strict && tagName !== 'Diagram' && tagName !== 'CompactExamples') {
         assertStrictNumbering({
           file,
           slug: lessonSlug,
@@ -1171,12 +1440,52 @@ export default function remarkNotation(options = {}) {
       numbering.diagrams,
       'diagrams',
     );
+    // A worked-example set is numbered like a float (docs/plans/
+    // titles-and-containers.md Part 6), but its number shows — and a
+    // reference prints it — by the section rules (`show`).
+    const { ctx: exampleFloatCtx, byNode: exampleByNode } = makeFloatCtx(
+      'CompactExamples',
+      numbering.examples,
+      'examples',
+    );
+    const exampleCtx = {
+      ...exampleFloatCtx,
+      slug: lessonSlug,
+      show: sectionSettings.show,
+      titles: numbering.exampleTitles ?? {},
+    };
     const checkCtx = {
       base: options.base ?? '',
       pageLabels: new Map(
         Object.entries(numbering.checks?.[lessonSlug] ?? {}),
       ),
       crossPage: numbering.checks ?? {},
+      slug: lessonSlug,
+      show: sectionSettings.show,
+      titles: numbering.checkTitles ?? {},
+    };
+
+    // Outline numbering: the lesson's top-level headings take the manifest's
+    // anchors and numbers before anything else reads them, and `[[sec-…]]`
+    // resolves against that same table.
+    const publishedHeadings = lessonSlug
+      ? numbering.sections?.[lessonSlug]
+      : undefined;
+    if (lessonId && publishedHeadings) {
+      stampSectionHeadings({
+        tree,
+        file,
+        slug: lessonSlug,
+        published: publishedHeadings,
+        placement: numbering.numbering?.[lessonSlug],
+        settings: sectionSettings,
+      });
+    }
+    const sectionCtx = {
+      base: options.base ?? '',
+      show: sectionSettings.show,
+      pageHeadings: new Map(Object.entries(headingsBySlug[lessonSlug] ?? {})),
+      crossPage: headingsBySlug,
     };
 
     const resolve = (key, kind, node) => {
@@ -1220,14 +1529,39 @@ export default function remarkNotation(options = {}) {
 
         EQ_LABEL_PATTERN.lastIndex = 0;
         const labelMatch = EQ_LABEL_PATTERN.exec(value);
-        if (labelMatch) {
+        const captions = [...value.matchAll(EQ_CAPTION_PATTERN)];
+        if (labelMatch && node.type === 'inlineMath') {
+          fail(
+            file,
+            `\\label{eq:${labelMatch[1]}} is only valid in a $$…$$ display equation, not inline $…$.`,
+            node,
+          );
+        }
+        if (captions.length > 0) {
           if (node.type === 'inlineMath') {
             fail(
               file,
-              `\\label{eq:${labelMatch[1]}} is only valid in a $$…$$ display equation, not inline $…$.`,
+              `\\caption{…} is only valid in a $$…$$ display equation, not inline $…$.`,
+              node,
+            );
+          }
+          if (captions.length > 1) {
+            fail(
+              file,
+              'A display equation takes one \\caption{…}; this one has ' +
+                `${captions.length}.`,
               node,
             );
           }
+          if (!captions[0][1].trim()) {
+            fail(
+              file,
+              '\\caption{} is empty: give the equation a short caption, or drop it.',
+              node,
+            );
+          }
+        }
+        if (labelMatch || captions.length > 0) {
           value = stripEquationLabels(value);
           replaceMathSource(node, value);
         }
@@ -1245,7 +1579,10 @@ export default function remarkNotation(options = {}) {
 
           let result;
           try {
-            result = resolveMathGlyphs(value, bindingScope);
+            // Suspension (rule N22) is lesson-body scope only.
+            result = resolveMathGlyphs(value, bindingScope, {
+              suspended: lessonId ? suspendedOperators : [],
+            });
           } catch (error) {
             const message =
               error instanceof GlyphResolutionError
@@ -1259,8 +1596,14 @@ export default function remarkNotation(options = {}) {
           if (result.unresolved.length > 0) {
             const unresolved = result.unresolved
               .map(
-                ({ token, start }) =>
-                  `${tokenLocation(file, node, value, start)}: "${token}"`,
+                ({ token, start, suspended, font }) =>
+                  `${tokenLocation(file, node, value, start)}: "${token}"${
+                    suspended
+                      ? ` (${suspended} is suspended on this page, so this form needs its own entry)`
+                      : font
+                        ? ' (a different symbol from the plain letter; it needs its own entry)'
+                        : ''
+                  }`,
               )
               .join(', ');
             fail(
@@ -1301,6 +1644,8 @@ export default function remarkNotation(options = {}) {
             figureCtx,
             diagramCtx,
             checkCtx,
+            sectionCtx,
+            exampleCtx,
           );
           if (replacement) {
             node.children.splice(index, 1, ...replacement);
@@ -1321,6 +1666,8 @@ export default function remarkNotation(options = {}) {
           injectFloatNumberAttributes(child, figureByNode.get(child), 'fig');
         } else if (child?.type === 'mdxJsxFlowElement' && diagramByNode.has(child)) {
           injectFloatNumberAttributes(child, diagramByNode.get(child), 'dia');
+        } else if (child?.type === 'mdxJsxFlowElement' && exampleByNode.has(child)) {
+          injectFloatNumberAttributes(child, exampleByNode.get(child), 'ex');
         }
       }
     };
@@ -1329,10 +1676,13 @@ export default function remarkNotation(options = {}) {
     // validation — the manifest builder runs the same check via
     // `validateRawFloats`/`scanRawFloats` (raw-floats.mjs); this catches
     // content added since the manifest was last compiled.
+    // A course that turned rule S3 (tables) or S4 (diagrams) off in its
+    // settings has `manifest.rules.disabled` say so; honour it here too.
+    const disabledRules = new Set(options.manifest?.rules?.disabled ?? []);
     if (lessonId) {
       const rawFloats = collectRawFloats(tree);
       const plural = (count, noun) => (count === 1 ? noun : `${noun}s`);
-      if (rawFloats.markdownTableNodes.length > 0) {
+      if (rawFloats.markdownTableNodes.length > 0 && !disabledRules.has('S3')) {
         warn(
           file,
           `${lessonSlug} has ${rawFloats.markdownTableNodes.length} raw ` +
@@ -1343,7 +1693,7 @@ export default function remarkNotation(options = {}) {
           rawFloats.markdownTableNodes[0],
         );
       }
-      if (rawFloats.htmlTableNodes.length > 0) {
+      if (rawFloats.htmlTableNodes.length > 0 && !disabledRules.has('S3')) {
         warn(
           file,
           `${lessonSlug} has ${rawFloats.htmlTableNodes.length} raw HTML ` +
@@ -1354,7 +1704,7 @@ export default function remarkNotation(options = {}) {
           rawFloats.htmlTableNodes[0],
         );
       }
-      if (rawFloats.unkeyedDiagramNodes.length > 0) {
+      if (rawFloats.unkeyedDiagramNodes.length > 0 && !disabledRules.has('S4')) {
         warn(
           file,
           `${lessonSlug} has ${rawFloats.unkeyedDiagramNodes.length} ` +
@@ -1364,14 +1714,14 @@ export default function remarkNotation(options = {}) {
           rawFloats.unkeyedDiagramNodes[0],
         );
       }
-      if (rawFloats.nestedDiagramNodes.length > 0) {
+      if (rawFloats.nestedDiagramNodes.length > 0 && !disabledRules.has('S4')) {
         warn(
           file,
           `${lessonSlug} has ${rawFloats.nestedDiagramNodes.length} ` +
             `<Diagram> ${plural(rawFloats.nestedDiagramNodes.length, 'component')} ` +
             `nested inside another component; it is invisible to diagram ` +
             `numbering. Move it to the top level (or inside ` +
-            `<Memo>/<ShortNote>), or wrap it in <Figure> to give it identity.`,
+            `<Memo>/<ShortNote>/<Fold>), or wrap it in <Figure> to give it identity.`,
           rawFloats.nestedDiagramNodes[0],
         );
       }
@@ -1401,5 +1751,6 @@ export default function remarkNotation(options = {}) {
     file.data.tableLabels = floatLabelData(tableByNode);
     file.data.figureLabels = floatLabelData(figureByNode);
     file.data.diagramLabels = floatLabelData(diagramByNode);
+    file.data.exampleLabels = floatLabelData(exampleByNode);
   };
 }