explico 0.11.1 → 0.13.0

package/src/reference/diagram-fit.ts

@@ -0,0 +1,104 @@
+/**
+ * Rule V8: a diagram is no wider than the lesson column.
+ *
+ * `Diagram.astro` lays a diagram out at build time and so knows its width, but
+ * not the page it is on or what the course allows, and a diagram drawn by a
+ * wrapper component (`<CourseDiagram kind="…">`) never shows its nodes to the
+ * manifest walk. So the check runs on what was rendered: the component marks
+ * a diagram wider than {@link diagramWidthLimit} with `data-diagram-too-wide`,
+ * `compiler/astro.ts` finds each mark with {@link oversizedDiagrams} on every
+ * built page and reports a `dia-too-wide` warning with the lesson file and the
+ * diagram id, and `content warnings` lists what the last build reported
+ * (`compiler/render-diagnostics.ts`). Under `astro dev` the component prints
+ * the same message as it renders.
+ */
+
+import { parse, type DefaultTreeAdapterMap } from 'parse5';
+
+import type { ManifestRules } from '../rules/settings';
+
+type HtmlNode = DefaultTreeAdapterMap['node'];
+type HtmlElement = DefaultTreeAdapterMap['element'];
+
+/**
+ * The lesson column at a 1366px-wide window, the most common laptop screen
+ * (632px at 1280, 832px at 1920), unless the course sets
+ * `rules.V8.columnWidth`.
+ */
+export const DEFAULT_COLUMN_WIDTH = 707;
+
+/**
+ * The widest a diagram may lay out, or `undefined` when nothing checks it: rule
+ * V8 is off, or the diagram says `warnAboveWidth={false}`. A number in
+ * `warnAboveWidth` replaces the course's column width for that diagram.
+ */
+export function diagramWidthLimit(
+  warnAboveWidth: number | false | undefined,
+  rules: Pick<ManifestRules, 'disabled' | 'settings'> | undefined,
+): number | undefined {
+  if (warnAboveWidth === false || rules?.disabled.includes('V8')) return undefined;
+  if (warnAboveWidth !== undefined) return warnAboveWidth;
+  const columnWidth = rules?.settings.V8?.columnWidth;
+  return typeof columnWidth === 'number' ? columnWidth : DEFAULT_COLUMN_WIDTH;
+}
+
+/** What to tell the author about one diagram wider than its limit. */
+export function diagramTooWideMessage(id: string, width: number, limit: number): string {
+  return (
+    `Diagram "${id}" lays out ${Math.round(width)}px wide, wider than the ${limit}px it may ` +
+    `take (rule V8), so a reader has to scroll it or widen it to see it whole. Try ` +
+    `direction="TB", a shorter label, or a narrower node \`width\` (its label wraps inside ` +
+    `it); set warnAboveWidth={false} only when the diagram is meant to scroll.`
+  );
+}
+
+/** A diagram on a built page that is wider than its limit. */
+export interface OversizedDiagram {
+  readonly code: 'dia-too-wide';
+  /** The diagram's `id`. */
+  readonly key: string;
+  readonly width: number;
+  readonly limit: number;
+}
+
+function isElement(node: HtmlNode): node is HtmlElement {
+  return 'tagName' in node;
+}
+
+function attribute(node: HtmlElement, name: string): string | undefined {
+  return node.attrs.find((attr) => attr.name === name)?.value;
+}
+
+function viewportKey(node: HtmlNode): string | undefined {
+  for (const child of 'childNodes' in node ? node.childNodes : []) {
+    if (!isElement(child)) continue;
+    const match = /^diagram-(.+)-viewport$/.exec(attribute(child, 'id') ?? '');
+    if (match) return match[1];
+    const inner = viewportKey(child);
+    if (inner) return inner;
+  }
+  return undefined;
+}
+
+/** The diagrams `Diagram.astro` marked too wide in `html`. */
+export function oversizedDiagrams(html: string): OversizedDiagram[] {
+  if (!html.includes('data-diagram-too-wide')) return [];
+  const found: OversizedDiagram[] = [];
+  const visit = (node: HtmlNode) => {
+    for (const child of 'childNodes' in node ? node.childNodes : []) {
+      if (!isElement(child)) continue;
+      const limit = attribute(child, 'data-diagram-too-wide');
+      if (limit !== undefined) {
+        found.push({
+          code: 'dia-too-wide',
+          key: viewportKey(child) ?? attribute(child, 'id') ?? '',
+          width: Number(attribute(child, 'data-diagram-width')),
+          limit: Number(limit),
+        });
+      }
+      visit(child);
+    }
+  };
+  visit(parse(html));
+  return found;
+}

package/src/reference/diagram-layout.ts

@@ -8,11 +8,11 @@
  * SVG; this module only computes geometry and is deliberately framework-free
  * so it is unit-testable without KaTeX, Astro, or a browser.
  *
- * Box sizes are not measured from a real render (there is no DOM at build
- * time) — `estimateBoxSize` is a deliberately generous character-count
- * heuristic. It is meant to avoid overlap and clipping in the common case,
- * not to be pixel-accurate; a diagram author can always pass an explicit
- * `width`/`height` on a node for a wide equation.
+ * A node's box is sized from what it holds (`nodeBoxSize`): its label's
+ * width in DejaVu Sans, the widest common system font (`text-measure.ts`),
+ * wrapped to a line count that sets the height, and its formula's width as
+ * KaTeX lays it out (`katex-measure.ts`, measured by the caller). An explicit
+ * `width` or `height` on the node overrides either side.
  */
 import dagre from '@dagrejs/dagre';
 import type {
@@ -21,6 +21,8 @@ import type {
   NodeLabel as DagreNodeLabel,
 } from '@dagrejs/dagre';
 
+import { textWidth, wrapText } from './text-measure';
+
 export interface DiagramNodeInput {
   readonly id: string;
   readonly width: number;
@@ -98,6 +100,14 @@ export function layoutDiagram(
     if (!ids.has(edge.to)) {
       throw new Error(`Diagram edge references unknown node "${edge.to}".`);
     }
+    // The layout draws a self-loop as a stray line out of the node.
+    if (edge.from === edge.to) {
+      throw new Error(
+        `Diagram edge from "${edge.from}" to itself: a diagram draws no loop on one ` +
+          'node. Name the repetition in the label ("Repeat until it converges"), or ' +
+          'draw the step it returns to as its own node.',
+      );
+    }
   }
 
   const graph = new dagre.graphlib.Graph<
@@ -185,62 +195,183 @@ export function layoutDiagram(
   };
 }
 
-// --- box-size estimation (no DOM at build time) --------------------------
+// --- node boxes -----------------------------------------------------------
+//
+// The constants mirror `Diagram.astro`'s `.diagram-node-content`, set in px
+// so a reader's font size cannot outgrow a box: `font-size: 13.6px`,
+// `line-height: 1.25`, `padding: 3.2px 8px`, `gap: 2.4px`.
 
-export interface BoxSizeEstimate {
+/** A node's text font size, in px. */
+export const NODE_FONT_PX = 13.6;
+/**
+ * A node's formula font size, in px: KaTeX's own `.katex { font-size: 1.21em }`
+ * of the node's text. `katex.css` is unlayered, so no rule in the component's
+ * `@layer` can shrink it, and at that size KaTeX_Main's x-height matches the
+ * label's.
+ */
+export const FORMULA_FONT_PX = NODE_FONT_PX * 1.21;
+/** One line of node text, in px. */
+const LINE_PX = 17;
+/** The horizontal CSS padding inside a node's box, per side. */
+const CSS_PADDING_X = 8;
+/** Space between the content and the box, per side: the CSS padding and some air. */
+const INSET_X = 16;
+const INSET_Y = 14;
+/** The gap between a node's text and its formula. */
+const GAP_PX = 2.4;
+/**
+ * A formula's line reaches at least this far above and below its baseline:
+ * the strut of the line it sits in, measured in Chromium, with room for a
+ * system font that sits higher than DejaVu Sans.
+ */
+const FORMULA_ASCENT_PX = 14;
+const FORMULA_DESCENT_PX = 5.5;
+const MIN_WIDTH = 90;
+const DEFAULT_MAX_WIDTH = 220;
+
+/** What a node holds, measured: its label, and its formula's box in px. */
+export interface NodeBoxContent {
+  readonly text?: string;
+  /** `measureFormula(latex, FORMULA_FONT_PX)`. */
+  readonly formula?: {
+    readonly width: number;
+    readonly height: number;
+    readonly depth: number;
+  };
+}
+
+export interface NodeBoxOptions {
+  /** The author's width: the label wraps inside it and the height follows. */
+  readonly width?: number;
+  /** The author's height. */
+  readonly height?: number;
+  /** The widest box a label is wrapped to fit before it takes a second line. */
+  readonly maxWidth?: number;
+}
+
+export interface NodeBox {
   readonly width: number;
   readonly height: number;
+  /** The label as it is wrapped in DejaVu Sans. */
+  readonly lines: readonly string[];
 }
 
-const DEFAULT_MAX_WIDTH = 220;
-const MIN_WIDTH = 90;
-const PADDING_X = 20;
-const PADDING_Y = 16;
-const LINE_HEIGHT = 22;
-/** Generous per-visible-character width estimates, in px, at diagram scale. */
-const CHAR_WIDTH: Record<'text' | 'formula', number> = {
-  text: 7.2,
-  formula: 11,
-};
+/**
+ * The narrowest wrap of `text` that needs no more lines than it needs at
+ * `maxWidth`: a two-line label splits near its middle rather than leaving one
+ * word on the second line, and its box is no wider than that takes.
+ */
+function balancedLines(text: string, maxWidth: number): string[] {
+  const greedy = wrapText(text, maxWidth, NODE_FONT_PX);
+  if (greedy.length <= 1) return greedy;
+  let low = 1;
+  let high = Math.ceil(maxWidth);
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2);
+    if (wrapText(text, middle, NODE_FONT_PX).length <= greedy.length) high = middle;
+    else low = middle + 1;
+  }
+  return wrapText(text, high, NODE_FONT_PX);
+}
 
 /**
- * A LaTeX command name (`\theta`, `\cdot`, …) renders as roughly one glyph,
- * not one character per letter of its name; braces are structural, not
- * visible. Collapsing both keeps the estimate from reading a formula as far
- * wider than it will actually render.
+ * Size a node's box from its measured content: as wide as its widest line of
+ * text or its formula, whichever is wider, plus the inset, and as tall as its
+ * lines of text, the gap and its formula's line. A label wider than `maxWidth`
+ * wraps; a formula never does, so a wide formula widens the box instead and the
+ * label wraps to it. An author's `width` or `height` makes the box larger,
+ * never too small for its formula or its lines.
  */
-function formulaVisibleLength(latex: string): number {
-  const collapsed = latex
-    .replace(/\\[a-zA-Z]+/g, 'x')
-    .replace(/[{}$]/g, '')
-    .trim();
-  return Math.max(1, collapsed.length);
+export function nodeBoxSize(content: NodeBoxContent, options: NodeBoxOptions = {}): NodeBox {
+  const text = content.text?.trim() ?? '';
+  const formula = content.formula;
+  const formulaWidth = formula?.width ?? 0;
+
+  let width: number;
+  let lines: string[];
+  if (options.width !== undefined) {
+    // A formula never wraps, so an author's width narrower than it would cut
+    // it off: the box takes the formula's width, and the label wraps to that.
+    width = Math.max(options.width, Math.ceil(formulaWidth + 2 * CSS_PADDING_X));
+    lines = text ? wrapText(text, width - 2 * CSS_PADDING_X, NODE_FONT_PX) : [];
+  } else {
+    const maxContent = Math.max(
+      (options.maxWidth ?? DEFAULT_MAX_WIDTH) - 2 * INSET_X,
+      formulaWidth,
+    );
+    lines = text ? balancedLines(text, maxContent) : [];
+    const contentWidth = Math.max(
+      formulaWidth,
+      ...lines.map((line) => textWidth(line, NODE_FONT_PX)),
+    );
+    width = Math.max(MIN_WIDTH, Math.ceil(contentWidth + 2 * INSET_X));
+  }
+
+  const formulaHeight = formula
+    ? Math.max(FORMULA_ASCENT_PX, formula.height) + Math.max(FORMULA_DESCENT_PX, formula.depth)
+    : 0;
+  const gap = lines.length > 0 && formula ? GAP_PX : 0;
+  // An author's height adds room; it never cuts what the box holds.
+  const contentHeight = Math.ceil(lines.length * LINE_PX + gap + formulaHeight + 2 * INSET_Y);
+  const height = Math.max(options.height ?? 0, contentHeight);
+
+  return { width, height, lines };
+}
+
+/** One node to fit: what it holds, and the author's size if any. */
+export interface FitNodeInput {
+  readonly id: string;
+  readonly content: NodeBoxContent;
+  readonly width?: number;
+  readonly height?: number;
 }
 
+export interface FitOptions extends DiagramLayoutOptions {
+  /** The widest the diagram should lay out (rule V8's column); omit to skip fitting. */
+  readonly fitWidth?: number;
+}
+
+/**
+ * The widest box a label wraps to fit, tried in turn while the diagram is
+ * still wider than its column: a left-to-right chain of four steps fits a
+ * 707px column once its labels wrap at 140px.
+ */
+const FIT_MAX_WIDTHS = [DEFAULT_MAX_WIDTH, 200, 180, 160, 140, 120];
+
 /**
- * Estimate a diagram node's box from its label text (or raw, pre-resolution
- * LaTeX for a formula node). Deliberately generous: it is meant to avoid
- * clipping, not to match a real render pixel-for-pixel. Pass an explicit
- * `width`/`height` on the node to override for a label this estimate gets
- * badly wrong.
+ * Size every node from its content and lay the diagram out. When `fitWidth`
+ * is set and the diagram comes out wider, wrap the labels of the nodes without
+ * an author's `width` narrower, step by step, until it fits; a diagram that
+ * still does not fit keeps its narrowest layout, and the caller warns.
  */
-export function estimateBoxSize(
-  content: string,
-  kind: 'text' | 'formula',
-  options: { readonly maxWidth?: number } = {},
-): BoxSizeEstimate {
-  const maxWidth = options.maxWidth ?? DEFAULT_MAX_WIDTH;
-  const visibleLength =
-    kind === 'formula' ? formulaVisibleLength(content) : content.trim().length || 1;
-  const charWidth = CHAR_WIDTH[kind];
-
-  const naturalWidth = visibleLength * charWidth + PADDING_X * 2;
-  const width = Math.min(maxWidth, Math.max(MIN_WIDTH, naturalWidth));
-
-  const usableWidth = width - PADDING_X * 2;
-  const charsPerLine = Math.max(1, Math.floor(usableWidth / charWidth));
-  const lines = Math.max(1, Math.ceil(visibleLength / charsPerLine));
-  const height = lines * LINE_HEIGHT + PADDING_Y * 2;
-
-  return { width: Math.round(width), height: Math.round(height) };
+export function fitDiagramLayout(
+  nodes: readonly FitNodeInput[],
+  edges: readonly DiagramEdgeInput[],
+  options: FitOptions = {},
+): { readonly layout: DiagramLayout; readonly boxes: ReadonlyMap<string, NodeBox> } {
+  let result: { layout: DiagramLayout; boxes: Map<string, NodeBox> } | undefined;
+  for (const maxWidth of FIT_MAX_WIDTHS) {
+    const boxes = new Map(
+      nodes.map((node) => [
+        node.id,
+        nodeBoxSize(node.content, {
+          maxWidth,
+          ...(node.width !== undefined ? { width: node.width } : {}),
+          ...(node.height !== undefined ? { height: node.height } : {}),
+        }),
+      ]),
+    );
+    const layout = layoutDiagram(
+      nodes.map((node) => ({ id: node.id, ...sizeOf(boxes.get(node.id)!) })),
+      edges,
+      options,
+    );
+    result = { layout, boxes };
+    if (options.fitWidth === undefined || layout.width <= options.fitWidth) break;
+  }
+  return result!;
+}
+
+function sizeOf(box: NodeBox): { width: number; height: number } {
+  return { width: box.width, height: box.height };
 }

package/src/reference/diagrams-validate.ts

@@ -12,7 +12,8 @@ export type DiagramDiagnosticCode =
   | 'dia-duplicate-key'
   | 'dia-ref-resolves'
   | 'dia-key-unused'
-  | 'dia-removed-prop';
+  | 'dia-removed-prop'
+  | 'dia-unread-prop';
 
 export interface DiagramDiagnostic {
   readonly code: DiagramDiagnosticCode;

package/src/reference/equations-validate.ts

@@ -10,7 +10,8 @@
  * fast `pnpm validate:content` the same coverage and feeds the manifest.
  */
 
-import { parseEquationRef, scanEquationLabels } from './equations.mjs';
+import { parseEquationRef, repeatedEquationLabels, scanEquationLabels } from './equations.mjs';
+import { proseOnly } from './gate-prose-notation';
 
 export interface EquationLabelRecord {
   readonly key: string;
@@ -31,7 +32,11 @@ export interface EquationRefRecord {
 }
 
 export type EquationDiagnosticCode =
-  'eq-duplicate-key' | 'eq-ref-resolves' | 'eq-key-unused';
+  | 'eq-duplicate-key'
+  | 'eq-ref-resolves'
+  | 'eq-key-unused'
+  | 'eq-label-repeated'
+  | 'eq-latex-ref';
 
 export interface EquationDiagnostic {
   readonly code: EquationDiagnosticCode;
@@ -88,6 +93,9 @@ function bodyEquationRefs(lesson: EquationLessonInput): EquationRefRecord[] {
   return refs;
 }
 
+/** `\\eqref{eq:key}`, `\\ref{fig:key}` and their kin, as LaTeX writes a reference. */
+const LATEX_REFERENCE = /\\(eqref|ref|autoref|cref|Cref)\s*\{([^{}\n]*)\}/g;
+
 export function validateEquations(
   lessons: readonly EquationLessonInput[],
 ): EquationValidation {
@@ -131,6 +139,37 @@ export function validateEquations(
       });
     }
     numbersBySlug[lesson.slug] = table;
+    // LaTeX's own reference in prose: MDX reads its `{…}` as JavaScript, so
+    // the page fails to build with a parse error that names neither.
+    for (const match of proseOnly(lesson.body).matchAll(LATEX_REFERENCE)) {
+      const [, command, target = ''] = match;
+      const [prefix, key] = target.includes(':') ? target.split(':', 2) : ['eq', target];
+      diagnostics.push({
+        code: 'eq-latex-ref',
+        severity: 'error',
+        message:
+          `${lesson.lessonId} writes \\${command}{${target}}, LaTeX's reference: MDX reads its ` +
+          `{…} as JavaScript, and the page fails to build. Write [[${prefix}-${key}]].`,
+        file: lesson.file,
+        lessonId: lesson.lessonId,
+        key: key ?? target,
+      });
+    }
+    for (const keys of repeatedEquationLabels(lesson.body) as string[][]) {
+      const [first, ...rest] = keys;
+      diagnostics.push({
+        code: 'eq-label-repeated',
+        severity: 'error',
+        message:
+          `${lesson.lessonId} puts ${keys.map((key) => `\\label{eq:${key}}`).join(' and ')} in one ` +
+          `display block, which is one numbered equation: eq:${first} names it, and ` +
+          `${rest.map((key) => `[[eq-${key}]]`).join(', ')} would point at nothing. Split the block ` +
+          'into one $$…$$ block per equation you refer to.',
+        file: lesson.file,
+        lessonId: lesson.lessonId,
+        key: rest[0]!,
+      });
+    }
   }
 
   const referenced = new Set<string>();

package/src/reference/equations.mjs

@@ -204,6 +204,87 @@ export function stripJsxComponents(markdown, keep, transparent = []) {
  */
 export const TRANSPARENT_COMPONENTS = Object.freeze(['Memo', 'ShortNote', 'Fold']);
 
+/**
+ * Blank the body of every `:::name … :::` container directive — a Starlight
+ * aside (`:::note`, `:::tip`, …) — keeping newlines, the text-scan twin of a
+ * tree walk that never enters a `containerDirective`. An aside is a callout,
+ * like `<Aside>`: what it holds is illustrative and numbers nothing. A fence
+ * of more colons closes only on as many; one left open runs to the end.
+ */
+export function stripContainerDirectives(markdown) {
+  const lines = String(markdown).split('\n');
+  let fence = 0;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index] ?? '';
+    if (fence === 0) {
+      const open = /^[ \t]{0,3}(:{3,})[A-Za-z]/.exec(line);
+      if (!open) continue;
+      fence = open[1].length;
+      lines[index] = line.replace(/[^\n]/g, ' ');
+      continue;
+    }
+    const close = /^[ \t]{0,3}(:{3,})[ \t]*$/.exec(line);
+    if (close && close[1].length >= fence) fence = 0;
+    lines[index] = line.replace(/[^\n]/g, ' ');
+  }
+  return lines.join('\n');
+}
+
+/** A line with its blockquote markers, list marker and indentation removed. */
+function containerContent(line) {
+  let rest = String(line);
+  for (;;) {
+    const next = rest
+      .replace(/^[ \t]*>[ \t]?/, '')
+      .replace(/^[ \t]*(?:[-*+]|\d{1,9}[.)])[ \t]+/, '');
+    if (next === rest) return rest.replace(/^[ \t]+/, '');
+    rest = next;
+  }
+}
+
+/**
+ * Every `$$` display block in a Markdown text the way remark-math reads one:
+ * an opening fence of two or more `$` that starts a line — inside a list item
+ * or a blockquote too — with nothing but a `$`-free meta after it, up to a
+ * closing fence of at least as many `$` on a line of its own (or the end of
+ * the text). `$$x$$` inside a paragraph, or on one line, is inline math and
+ * is not a display block. Each block is `{ index, body }`: the offset of its
+ * opening line and the text between the fences.
+ */
+export function displayMathBlocks(markdown) {
+  const text = String(markdown);
+  const lines = text.split('\n');
+  const starts = [];
+  let offset = 0;
+  for (const line of lines) {
+    starts.push(offset);
+    offset += line.length + 1;
+  }
+  const blocks = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const open = /^(\${2,})[ \t]*[^$]*$/.exec(containerContent(lines[index]));
+    if (!open) continue;
+    const size = open[1].length;
+    let end = lines.length;
+    for (let next = index + 1; next < lines.length; next += 1) {
+      const close = /^(\${2,})[ \t]*$/.exec(containerContent(lines[next]));
+      if (close && close[1].length >= size) {
+        end = next;
+        break;
+      }
+    }
+    blocks.push({
+      index: starts[index],
+      body: lines
+        .slice(index + 1, end)
+        .map((line) => containerContent(line))
+        .join('\n'),
+    });
+    index = end;
+  }
+  return blocks;
+}
+
 /**
  * Every display equation in a Markdown body, keyed or not, in appearance order
  * with its assigned number and its `\caption{}` short caption (`short`, or
@@ -219,25 +300,20 @@ export const TRANSPARENT_COMPONENTS = Object.freeze(['Memo', 'ShortNote', 'Fold'
  */
 export function scanDisplayEquations(markdown, numbering) {
   const { prefix, offset } = resolveNumbering(numbering);
-  const text = stripJsxComponents(
-    stripFencedCode(markdown),
-    undefined,
-    TRANSPARENT_COMPONENTS,
-  );
+  const text = equationText(markdown);
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
-  const display = /\$\$([\s\S]+?)\$\$/g;
   for (const match of text.matchAll(heading)) {
     tokens.push({ kind: 'section', index: match.index });
   }
-  for (const match of text.matchAll(display)) {
+  for (const block of displayMathBlocks(text)) {
     EQ_LABEL_PATTERN.lastIndex = 0;
-    const label = EQ_LABEL_PATTERN.exec(match[1]);
+    const label = EQ_LABEL_PATTERN.exec(block.body);
     tokens.push({
       kind: 'equation',
-      index: match.index,
+      index: block.index,
       key: label ? label[1] : null,
-      short: equationCaption(match[1]),
+      short: equationCaption(block.body),
     });
   }
   tokens.sort((a, b) => a.index - b.index);
@@ -271,6 +347,31 @@ export function scanDisplayEquations(markdown, numbering) {
   return labels;
 }
 
+/**
+ * A lesson body as the equation scans read it: no fenced code, no component
+ * but the transparent ones, no `:::` directive body.
+ */
+function equationText(markdown) {
+  return stripContainerDirectives(
+    stripJsxComponents(stripFencedCode(markdown), undefined, TRANSPARENT_COMPONENTS),
+  );
+}
+
+/**
+ * The keys of each display block that carries more than one `\label{eq:…}`,
+ * in order. A block is one numbered equation: its first label names it, and
+ * a later one would name nothing.
+ */
+export function repeatedEquationLabels(markdown) {
+  return displayMathBlocks(equationText(markdown))
+    // A copy: `matchAll` starts at the shared pattern's `lastIndex`, which
+    // `scanDisplayEquations`' `exec` leaves past the label it found.
+    .map((block) =>
+      [...block.body.matchAll(new RegExp(EQ_LABEL_PATTERN.source, 'g'))].map((match) => match[1]),
+    )
+    .filter((keys) => keys.length > 1);
+}
+
 /** The keyed subset of `scanDisplayEquations` — the manifest builder's view. */
 export function scanEquationLabels(markdown, numbering) {
   return scanDisplayEquations(markdown, numbering).filter(
@@ -301,13 +402,16 @@ export function collectDisplayEquations(tree, numbering) {
   let indexInSection = 0;
   let indexInLesson = 0;
 
-  // 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.
+  // The lesson's flow — top-level blocks, list items, blockquotes — plus the
+  // bodies of the `TRANSPARENT_COMPONENTS`: other MDX components (a
+  // `<CompactExample>` worked example, an `<Aside>`) and `:::note`-style
+  // asides 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. `scanDisplayEquations` reads the
+  // same set from the text.
   const collectFromDetail = (node) => {
     if (!node || typeof node !== 'object') return;
+    if (node.type === 'containerDirective') return;
     if (node.type === 'math') {
       indexInSection += 1;
       indexInLesson += 1;
@@ -347,13 +451,7 @@ export function collectDisplayEquations(tree, numbering) {
       indexInSection = 0;
       continue;
     }
-    if (node.type === 'math') collectFromDetail(node);
-    else if (
-      node.type === 'mdxJsxFlowElement' &&
-      TRANSPARENT_COMPONENTS.includes(node.name)
-    ) {
-      collectFromDetail(node);
-    }
+    collectFromDetail(node);
   }
   return equations;
 }

package/src/reference/examples-validate.ts

@@ -24,6 +24,7 @@ export type ExampleDiagnosticCode =
   | 'ex-ref-resolves'
   | 'ex-key-unused'
   | 'ex-removed-prop'
+  | 'ex-unread-prop'
   | 'ex-missing-prop';
 
 export interface ExampleDiagnostic {