explico 0.11.1 → 0.13.0

package/src/reference/katex-measure.ts

@@ -0,0 +1,384 @@
+/**
+ * The size of a formula as KaTeX lays it out, measured at build time.
+ *
+ * There is no browser at build time, but KaTeX already knows most of the
+ * answer: `katex.__renderToHTMLTree` returns the tree its HTML is printed
+ * from, and every `SymbolNode` in it carries the advance `width` and the
+ * `italic` correction of its glyph, in em, from KaTeX's own font metrics. A
+ * span carries no width, so {@link measureFormula} walks the tree the way the
+ * browser lays the HTML out: it sums a row, takes the widest row of a `vlist`
+ * (scripts, fractions, `\underset`), scales by the `sizing reset-sizeN sizeM`
+ * classes, and adds every margin and padding the tree writes inline (glue
+ * between atoms, `\,`, `\!`, the margin a subscript is shifted by).
+ *
+ * The rest of the widths live in `katex.css`, not in the tree, and are
+ * listed here class by class: the `0.12em` of a `.nulldelimiter` either side
+ * of every fraction and of `\left.`, the padding of `\boxed`, the zero width
+ * of an accent's glyph row and of `\llap`. KaTeX also joins a run of letters
+ * into one node that carries only the first letter's width; the rest of the
+ * run comes from KaTeX's metric tables, in the font `katex.css` gives it.
+ *
+ * Chromium on Linux rounds each glyph of KaTeX's web fonts up to a whole
+ * pixel, which widens a short formula by several percent at a diagram's
+ * 13.6px, so every glyph is counted that way: the result is never narrower
+ * than the browser's, and at most a pixel or so per glyph wider than where a
+ * browser positions glyphs at subpixel precision.
+ * `tests/reference/katex-measure.test.ts` pins it to widths measured in
+ * Chromium (`playground/scripts/measure-katex-widths.ts`), so a KaTeX upgrade
+ * that moves a width from the tree to the stylesheet fails there.
+ *
+ * Importing `katex-options.mjs`, as this module does, installs rule N17's
+ * delimiter sizing, so `\left…\right` is measured at the size it renders.
+ */
+import katex, { type KatexOptions } from 'katex';
+import fontMetricsData from 'katex/src/fontMetricsData.js';
+
+import { createNotationKatexOptions } from './katex-options.mjs';
+
+/** A formula's box at one font size, in px. */
+export interface FormulaMetrics {
+  /** Advance width. */
+  readonly width: number;
+  /** Height above the baseline. */
+  readonly height: number;
+  /** Depth below the baseline. */
+  readonly depth: number;
+}
+
+/** The shape of a node in KaTeX's HTML tree, read structurally. */
+interface KatexNode {
+  readonly classes?: readonly string[];
+  readonly children?: readonly KatexNode[];
+  readonly style?: Readonly<Record<string, string | undefined>>;
+  /** A `SymbolNode`'s text; absent on every other node. */
+  readonly text?: string;
+  readonly width?: number | null;
+  readonly italic?: number;
+  readonly height?: number;
+  readonly depth?: number;
+}
+
+/** `katex.css`: `.sizing.reset-sizeN.sizeM { font-size: (M / N)em }`. */
+const SIZE_MULTIPLIERS = [0.5, 0.6, 0.7, 0.8, 0.9, 1, 1.2, 1.44, 1.728, 2.074, 2.488];
+
+/** `katex.css` paddings, in em, as `[left, right]`. */
+const CLASS_PADDING: Readonly<Record<string, readonly [number, number]>> = {
+  'x-arrow-pad': [0.5, 0.5],
+  'cd-arrow-pad': [0.27778, 0.55556],
+  boxpad: [0.3, 0.3],
+  'cancel-pad': [0.2, 0.2],
+  anglpad: [0.03889, 0.03889],
+};
+
+/** `katex.css` margins, in em, as `[left, right]`. */
+const CLASS_MARGIN: Readonly<Record<string, readonly [number, number]>> = {
+  'cancel-lap': [-0.2, -0.2],
+  angl: [0, 0.03889],
+};
+
+/** `katex.css` borders, in em, as `[left, right]`. */
+const CLASS_BORDER: Readonly<Record<string, readonly [number, number]>> = {
+  fbox: [0.04, 0.04],
+  fcolorbox: [0.04, 0.04],
+  angl: [0, 0.049],
+};
+
+/** `katex.css` boxes whose width is zero whatever they hold. */
+const ZERO_WIDTH = new Set(['llap', 'rlap', 'clap', 'pstrut', 'vlist-s']);
+
+function has(node: KatexNode, name: string): boolean {
+  return node.classes?.includes(name) ?? false;
+}
+
+/** An inline length in em; a percentage or `calc()` is `auto`, so `0`. */
+function em(value: string | undefined): number {
+  if (!value) return 0;
+  const match = /^(-?\d*\.?\d+)em$/.exec(value.trim());
+  return match ? Number(match[1]) : 0;
+}
+
+/** The font-size factor a node's `sizing` classes apply, relative to its parent. */
+function sizing(node: KatexNode): number {
+  if (!has(node, 'sizing') && !has(node, 'fontsize-ensurer')) return 1;
+  let from = 0;
+  let to = 0;
+  for (const name of node.classes ?? []) {
+    const reset = /^reset-size(\d+)$/.exec(name);
+    if (reset) from = Number(reset[1]);
+    const size = /^size(\d+)$/.exec(name);
+    if (size) to = Number(size[1]);
+  }
+  const fromMultiplier = SIZE_MULTIPLIERS[from - 1];
+  const toMultiplier = SIZE_MULTIPLIERS[to - 1];
+  return fromMultiplier && toMultiplier ? toMultiplier / fromMultiplier : 1;
+}
+
+function pairOf(
+  table: Readonly<Record<string, readonly [number, number]>>,
+  node: KatexNode,
+): number {
+  let total = 0;
+  for (const name of node.classes ?? []) {
+    const pair = table[name];
+    if (pair) total += pair[0] + pair[1];
+  }
+  return total;
+}
+
+/** The font a node's text is drawn in, as `katex.css` cascades it. */
+interface Font {
+  readonly family: string;
+  readonly bold: boolean;
+  readonly italic: boolean;
+}
+
+/** `.katex { font: normal 1.21em KaTeX_Main }`. */
+const ROOT_FONT: Font = { family: 'Main', bold: false, italic: false };
+
+/** `katex.css`'s font rules, one class at a time. */
+const FONT_CLASSES: Readonly<Record<string, Partial<Font>>> = {
+  textbf: { bold: true },
+  textit: { italic: true },
+  textrm: { family: 'Main' },
+  texttt: { family: 'Typewriter' },
+  mathnormal: { family: 'Math', italic: true },
+  mathit: { family: 'Main', italic: true },
+  mathrm: { italic: false },
+  mathbf: { family: 'Main', bold: true },
+  boldsymbol: { family: 'Math', bold: true, italic: true },
+  amsrm: { family: 'AMS' },
+  mathbb: { family: 'AMS' },
+  textbb: { family: 'AMS' },
+  mathcal: { family: 'Caligraphic' },
+  mathfrak: { family: 'Fraktur' },
+  textfrak: { family: 'Fraktur' },
+  mathboldfrak: { family: 'Fraktur', bold: true },
+  textboldfrak: { family: 'Fraktur', bold: true },
+  mathtt: { family: 'Typewriter' },
+  mathscr: { family: 'Script' },
+  textscr: { family: 'Script' },
+  mathsf: { family: 'SansSerif' },
+  textsf: { family: 'SansSerif' },
+  mathboldsf: { family: 'SansSerif', bold: true },
+  textboldsf: { family: 'SansSerif', bold: true },
+  mathsfit: { family: 'SansSerif', italic: true },
+  mathitsf: { family: 'SansSerif', italic: true },
+  textitsf: { family: 'SansSerif', italic: true },
+  mainrm: { family: 'Main', italic: false },
+};
+
+function fontOf(node: KatexNode, inherited: Font): Font {
+  let font = inherited;
+  for (const name of node.classes ?? []) {
+    const rule = FONT_CLASSES[name];
+    if (rule) font = { ...font, ...rule };
+  }
+  if (has(node, 'delimsizing')) {
+    for (const size of [1, 2, 3, 4]) {
+      if (has(node, `size${size}`)) font = { ...font, family: `Size${size}` };
+    }
+  }
+  if (has(node, 'op-symbol')) {
+    if (has(node, 'small-op')) font = { ...font, family: 'Size1' };
+    if (has(node, 'large-op')) font = { ...font, family: 'Size2' };
+  }
+  return font;
+}
+
+type MetricTable = Readonly<Record<string, readonly number[] | undefined>>;
+const METRICS = fontMetricsData as unknown as Readonly<Record<string, MetricTable | undefined>>;
+
+/** KaTeX's metric table for `font`, falling back to the nearest it has. */
+function metricsFor(font: Font): MetricTable {
+  const variants = [
+    font.bold && font.italic ? 'BoldItalic' : font.bold ? 'Bold' : font.italic ? 'Italic' : 'Regular',
+    font.bold ? 'Bold' : undefined,
+    font.italic ? 'Italic' : undefined,
+    'Regular',
+  ];
+  for (const variant of variants) {
+    const table = variant && METRICS[`${font.family}-${variant}`];
+    if (table) return table;
+  }
+  return METRICS['Main-Regular'] ?? {};
+}
+
+/**
+ * Glyphs whose KaTeX metrics are far too narrow: the multiple integrals. KaTeX
+ * gives `∬` the single integral's width, while a browser draws it (from a
+ * fallback font) as wide as two: in Chromium on Linux, `\iint` is 13.6px
+ * against `\int`'s 9.6px at 13.6px, and `\iiint` 18.6px. An upper bound, in em.
+ */
+const WIDE_GLYPHS: ReadonlyMap<number, number> = new Map([
+  [0x222c, 0.85], // ∬ \iint
+  [0x222d, 1.22], // ∭ \iiint
+  [0x222f, 0.85], // ∯ \oiint
+  [0x2230, 1.22], // ∰ \oiiint
+  [0x2a0c, 1.6], // ⨌ \iiiint
+]);
+
+/** A glyph KaTeX has no metrics for is drawn from a fallback font: count it as an `M`. */
+function glyphWidth(table: MetricTable, char: string): number {
+  if (char === '\u200b') return 0;
+  const metrics = table[String(char.codePointAt(0))] ?? table['77'];
+  return metrics?.[4] ?? 1;
+}
+
+/**
+ * The advance of each glyph in a `SymbolNode`, in em. KaTeX joins a run of
+ * characters with the same classes into one node ("Var" in
+ * `\operatorname{Var}`, "if " in `\text{if }`) and keeps the first
+ * character's width for the whole run, so the rest of the run is looked up
+ * here, in the font the run is drawn in.
+ */
+function glyphAdvances(node: KatexNode, font: Font): number[] {
+  const [first, ...rest] = [...(node.text ?? '')];
+  if (first === undefined) return [];
+  const table = metricsFor(font);
+  const wide = (char: string) => WIDE_GLYPHS.get(char.codePointAt(0) ?? 0);
+  const firstWidth =
+    wide(first) ?? (node.width && node.width > 0 ? node.width : glyphWidth(table, first));
+  return [firstWidth, ...rest.map((char) => wide(char) ?? glyphWidth(table, char))];
+}
+
+/**
+ * A glyph's advance in px, the wider of the two ways a browser draws it.
+ * Chromium on Linux hints KaTeX's web fonts at a whole-pixel size and rounds
+ * each glyph to whole pixels: a 16.456px formula is laid out at 16px, a 13.6px
+ * one at 14px. A browser that positions glyphs at subpixel precision (macOS,
+ * iOS) takes the exact advance at the real size.
+ */
+function glyphPx(advanceEm: number, fontPx: number): number {
+  return Math.max(Math.round(advanceEm * Math.round(fontPx)), advanceEm * fontPx);
+}
+
+interface Context {
+  /** The formula's root font size in px. */
+  readonly fontPx: number;
+}
+
+/** What a node inherits from its parent: font size (in root em) and font. */
+interface Frame {
+  readonly scale: number;
+  readonly font: Font;
+}
+
+/**
+ * The horizontal advance of `node`, margins included, in px.
+ */
+function advance(node: KatexNode, inherited: Frame, context: Context, parent?: KatexNode): number {
+  const frame: Frame = {
+    scale: inherited.scale * sizing(node),
+    font: fontOf(node, inherited.font),
+  };
+  // 1em of this node's own font size, in px.
+  const scale = frame.scale * context.fontPx;
+  const style = node.style ?? {};
+
+  if (typeof node.text === 'string') {
+    // `SymbolNode.toMarkup` writes the italic correction as `margin-right`,
+    // then the node's own style, so an explicit margin-right replaces it.
+    const marginRight =
+      style.marginRight !== undefined ? em(style.marginRight) : Math.max(0, node.italic ?? 0);
+    const glyphs = glyphAdvances(node, frame.font).reduce(
+      (sum, width) => sum + glyphPx(width, scale),
+      0,
+    );
+    return glyphs + (marginRight + em(style.marginLeft)) * scale;
+  }
+  // An `SvgNode` or its paths: `.katex svg` is absolutely positioned, so the
+  // span around it is as wide as its own style says.
+  if (!node.classes) return 0;
+
+  const margins =
+    (em(style.marginLeft) +
+      em(style.marginRight) +
+      pairOf(CLASS_MARGIN, node) +
+      rootMargin(node, parent)) *
+    scale;
+  if (node.classes.some((name) => ZERO_WIDTH.has(name))) return margins;
+  if (has(node, 'accent-body') && !has(node, 'accent-full')) return margins;
+
+  let content: number;
+  if (has(node, 'nulldelimiter')) {
+    content = 0.12 * scale;
+  } else if (em(style.width) > 0) {
+    content = em(style.width) * scale;
+  } else if (has(node, 'vlist-t')) {
+    content = tableWidth(node, frame, context);
+  } else if (has(node, 'vlist')) {
+    // A cell of block rows: as wide as its widest row, margins included.
+    content = Math.max(
+      0,
+      ...(node.children ?? []).map((row) => advance(row, frame, context, node)),
+    );
+  } else {
+    content = (node.children ?? []).reduce(
+      (sum, child) => sum + advance(child, frame, context, node),
+      0,
+    );
+  }
+  content = Math.max(content, em(style.minWidth) * scale);
+  if (has(node, 'vertical-separator')) content = Math.max(content, 1);
+
+  const padding = (em(style.paddingLeft) + pairOf(CLASS_PADDING, node)) * scale;
+  const border = (em(style.borderRightWidth) + pairOf(CLASS_BORDER, node)) * scale;
+  return content + padding + border + margins;
+}
+
+/** `.sqrt > .root`: the index of `\sqrt[n]{x}` is kerned in from both sides. */
+function rootMargin(node: KatexNode, parent?: KatexNode): number {
+  return has(node, 'root') && parent !== undefined && has(parent, 'sqrt')
+    ? 0.2777777778 - 0.5555555556
+    : 0;
+}
+
+/**
+ * A `vlist-t` is an inline table of `vlist-r` rows. Its columns are as wide as
+ * their widest cell; the 2px `vlist-s` column a `vlist-t2` adds is taken back
+ * by that table's `margin-right: -2px`, so only the `vlist` cells count.
+ */
+function tableWidth(node: KatexNode, frame: Frame, context: Context): number {
+  const columns: number[] = [];
+  for (const row of node.children ?? []) {
+    let column = 0;
+    for (const cell of row.children ?? []) {
+      if (has(cell, 'vlist-s')) continue;
+      columns[column] = Math.max(columns[column] ?? 0, advance(cell, frame, context, row));
+      column += 1;
+    }
+  }
+  return columns.reduce((sum, width) => sum + width, 0);
+}
+
+function collectBases(node: KatexNode, out: KatexNode[]): KatexNode[] {
+  if (has(node, 'base')) {
+    out.push(node);
+    return out;
+  }
+  for (const child of node.children ?? []) collectBases(child, out);
+  return out;
+}
+
+/**
+ * Measure `latex` as the notation KaTeX renders it — the same macros
+ * (`\explain`, `\slot`), trust boundary and delimiter sizing as lesson math —
+ * at a font size of `fontPx`. Throws on LaTeX KaTeX cannot render.
+ */
+export function measureFormula(latex: string, fontPx: number): FormulaMetrics {
+  // Looked up at call time: `katex-delimiters.mjs` replaces it on the shared
+  // object with the build that has N17's sizing.
+  const { __renderToHTMLTree } = katex as unknown as {
+    __renderToHTMLTree(expression: string, options: KatexOptions): unknown;
+  };
+  const tree = __renderToHTMLTree(latex, {
+    ...createNotationKatexOptions(),
+    displayMode: false,
+  }) as KatexNode;
+  const bases = collectBases(tree, []);
+  return {
+    width: advance(tree, { scale: 1, font: ROOT_FONT }, { fontPx }),
+    height: Math.max(0, ...bases.map((base) => base.height ?? 0)) * fontPx,
+    depth: Math.max(0, ...bases.map((base) => base.depth ?? 0)) * fontPx,
+  };
+}

package/src/reference/keyed-float-validate.ts

@@ -28,6 +28,7 @@ import {
   scanKeyedJsxFloats,
 } from './keyed-jsx-floats.mjs';
 
+
 export interface KeyedFloatKind {
   /** The MDX component tag, e.g. `Table` or `Figure`. */
   readonly tagName: string;
@@ -159,6 +160,27 @@ export function validateKeyedFloats(
           ...(raw.key ? { key: raw.key } : {}),
         });
       }
+      // A caption the manifest cannot read — `short={…}` renders on the page,
+      // but the "Figures and tables" page, a folded section's line and a
+      // copied link name the float without it.
+      for (const prop of ['short', 'caption'] as const) {
+        if (!raw.props.includes(prop) || raw[prop] != null) continue;
+        const places =
+          prefix === 'ex'
+            ? `its [[${prefix}-…]] card and a copied link`
+            : `its [[${prefix}-…]] card, a copied link, a folded section's line and the "Figures and tables" page`;
+        diagnostics.push({
+          code: `${prefix}-unread-prop`,
+          severity: 'warning',
+          message:
+            `${lesson.lessonId} has a <${tagName} ${prop}={…}>${raw.key ? ` (id="${raw.key}")` : ''}, ` +
+            `but the manifest reads only a quoted \`${prop}\`, so ${places} name this ${noun} ` +
+            `without it. Write ${prop}="…", with typographic quotes (‘’ “”) inside.`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          ...(raw.key ? { key: raw.key } : {}),
+        });
+      }
       if (raw.key == null) continue;
       if (!KEYED_FLOAT_KEY_PATTERN.test(raw.key)) {
         diagnostics.push({

package/src/reference/keyed-jsx-floats.mjs

@@ -25,6 +25,7 @@
 
 import {
   resolveNumbering,
+  stripContainerDirectives,
   stripFencedCode,
   stripJsxComponents,
   TRANSPARENT_COMPONENTS,
@@ -131,10 +132,9 @@ function mdxStringAttribute(node, name) {
  */
 export function scanKeyedJsxFloats(markdown, { tagName, numbering }) {
   const { prefix, offset } = resolveNumbering(numbering);
-  const text = stripJsxComponents(
-    stripFencedCode(markdown),
-    tagName,
-    TRANSPARENT_COMPONENTS,
+  // A `:::note` aside is a callout, like `<Aside>`: nothing in it numbers.
+  const text = stripContainerDirectives(
+    stripJsxComponents(stripFencedCode(markdown), tagName, TRANSPARENT_COMPONENTS),
   );
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
@@ -196,8 +196,8 @@ export function countKeyedJsxFloats(markdown, { tagName }) {
 }
 
 /**
- * The mdast equivalent of `scanKeyedJsxFloats`: walk the tree's top-level
- * children (and through the `TRANSPARENT_COMPONENTS`' bodies) in document order, advancing the
+ * The mdast equivalent of `scanKeyedJsxFloats`: walk the lesson's flow (and
+ * through the `TRANSPARENT_COMPONENTS`' bodies) in document order, advancing the
  * section counter on every top-level depth-2 heading and emitting a record for
  * every `mdxJsxFlowElement` named `tagName` — keyed or not, exactly like
  * `collectDisplayEquations`. `numbering` is threaded the same way as in
@@ -210,8 +210,12 @@ export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
   let indexInSection = 0;
   let indexInLesson = 0;
 
+  // The lesson's flow — top-level blocks, list items, blockquotes — and the
+  // `TRANSPARENT_COMPONENTS`' bodies; never another component's body or a
+  // `:::note` aside. `scanKeyedJsxFloats` reads the same set from the text.
   const collectFromDetail = (node) => {
     if (!node || typeof node !== 'object') return;
+    if (node.type === 'containerDirective') return;
     if (node.type === 'mdxJsxFlowElement' && node.name === tagName) {
       indexInSection += 1;
       indexInLesson += 1;
@@ -256,14 +260,7 @@ export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
       indexInSection = 0;
       continue;
     }
-    if (node.type === 'mdxJsxFlowElement' && node.name === tagName) {
-      collectFromDetail(node);
-    } else if (
-      node.type === 'mdxJsxFlowElement' &&
-      TRANSPARENT_COMPONENTS.includes(node.name)
-    ) {
-      collectFromDetail(node);
-    }
+    collectFromDetail(node);
   }
   return floats;
 }

package/src/reference/lab-katex-validate.ts

@@ -0,0 +1,156 @@
+/**
+ * Rule V3's seam, checked in the source: a component a lesson renders draws
+ * its math through `renderLabMath`, which binds every symbol to the page's
+ * notation, never by calling KaTeX itself — a legend helper around
+ * `katex.renderToString` binds none, so its symbols open no card.
+ *
+ * Starting at each lesson's own imports, this follows every relative import
+ * — the course's visuals, wherever they live — and reports each file that
+ * imports `katex` as `lab-katex-direct`, with the chain of imports that
+ * reaches it. A package import (`explico/…`, `react`) is not followed:
+ * explico's own KaTeX use is the seam. A type-only import and the KaTeX
+ * stylesheet draw nothing and are not reported.
+ *
+ * `figure-symbols.ts` checks the same promise on the rendered page, which
+ * also catches math a lab draws some other way.
+ */
+
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+
+import { stripFencedCode } from './equations.mjs';
+
+export interface LabKatexDiagnostic {
+  readonly code: 'lab-katex-direct';
+  readonly severity: 'error';
+  readonly message: string;
+  /** The file that imports `katex`, repository-relative. */
+  readonly file: string;
+  /** The first lesson (by id) whose imports reach it. */
+  readonly lessonId: string;
+}
+
+export interface LabKatexLessonInput {
+  readonly lessonId: string;
+  /** Repository-relative path of the lesson file. */
+  readonly file: string;
+  readonly body: string;
+}
+
+/** Extensions tried, in order, for an import written without one. */
+const EXTENSIONS = ['.astro', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.mts', '.cjs'];
+/** Files worth reading for imports: scripts, components and MDX. */
+const SOURCE_FILE = /\.(?:astro|tsx|ts|jsx|js|mjs|mts|cjs|mdx)$/u;
+
+const IMPORT_PATTERNS = [
+  // import x from 'y' · import { x } from 'y' · import 'y' · import type … from 'y'
+  /\bimport\s+(type\s+)?(?:[\w*{}\s,$]+?\s+from\s+)?(['"])([^'"\n]+)\2/gu,
+  // export { x } from 'y' · export * from 'y' · export type { x } from 'y'
+  /\bexport\s+(type\s+)?(?:\*(?:\s+as\s+[\w$]+)?|\{[^}]*\})\s+from\s+(['"])([^'"\n]+)\2/gu,
+  // import('y') · require('y')
+  /\b(?:import|require)\s*\(\s*()(['"])([^'"\n]+)\2\s*\)/gu,
+];
+
+/**
+ * Every module a source file imports at run time, in order: static, re-exported,
+ * dynamic and `require`d. A type-only import is left out.
+ */
+export function importSpecifiers(source: string): string[] {
+  const found: { index: number; specifier: string }[] = [];
+  for (const pattern of IMPORT_PATTERNS) {
+    for (const match of source.matchAll(pattern)) {
+      if (match[1]) continue;
+      found.push({ index: match.index ?? 0, specifier: match[3]! });
+    }
+  }
+  return found.sort((a, b) => a.index - b.index).map(({ specifier }) => specifier);
+}
+
+/** `katex`, or a script inside it — not its stylesheet or its fonts. */
+function isKatexModule(specifier: string): boolean {
+  if (specifier !== 'katex' && !specifier.startsWith('katex/')) return false;
+  return !/\.(?:css|woff2?|ttf)$/u.test(specifier);
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** The file a relative import names, trying the extensions a bundler would. */
+function resolveRelative(fromFile: string, specifier: string): string | undefined {
+  const base = join(dirname(fromFile), specifier);
+  const candidates = [
+    base,
+    // `./chart.js` written for `./chart.ts`, the TypeScript ESM convention.
+    ...(/\.[cm]?js$/u.test(base) ? ['.ts', '.tsx', '.mts', '.cts'].map((ext) => base.replace(/\.[cm]?js$/u, ext)) : []),
+    ...EXTENSIONS.map((ext) => `${base}${ext}`),
+    ...EXTENSIONS.map((ext) => join(base, `index${ext}`)),
+  ];
+  return candidates.find(isFile);
+}
+
+/**
+ * Each course file that a lesson's imports reach and that imports `katex`.
+ * `root` is the repository root the lesson paths are relative to.
+ */
+export function validateLabKatexImports(
+  lessons: readonly LabKatexLessonInput[],
+  root: string = process.cwd(),
+): LabKatexDiagnostic[] {
+  const read = (path: string): string | undefined => {
+    try {
+      return readFileSync(path, 'utf8');
+    } catch {
+      return undefined;
+    }
+  };
+  const repoPath = (path: string) => relative(root, path).split(sep).join('/');
+
+  const diagnostics = new Map<string, LabKatexDiagnostic>();
+  const seen = new Set<string>();
+  for (const lesson of [...lessons].sort((a, b) => a.lessonId.localeCompare(b.lessonId))) {
+    const lessonPath = join(root, lesson.file);
+    // Breadth first, so a reported chain is the shortest one.
+    const queue: { path: string; source: string; chain: readonly string[] }[] = [
+      { path: lessonPath, source: stripFencedCode(lesson.body), chain: [lesson.file] },
+    ];
+    while (queue.length > 0) {
+      const { path, source, chain } = queue.shift()!;
+      for (const specifier of importSpecifiers(source)) {
+        if (isKatexModule(specifier)) {
+          const file = repoPath(path);
+          if (!diagnostics.has(file)) {
+            diagnostics.set(file, {
+              code: 'lab-katex-direct',
+              severity: 'error',
+              file,
+              lessonId: lesson.lessonId,
+              message:
+                `${file} imports '${specifier}' and draws math whose symbols open no ` +
+                `notation card (reached by ${chain.join(' → ')}). Render a lab's math ` +
+                `with renderLabMath(template, scope) — { display: false } for a legend ` +
+                `entry, an axis title or a label — so every symbol is bound to the ` +
+                `page's notation (rule V3).`,
+            });
+          }
+          continue;
+        }
+        if (!specifier.startsWith('.')) continue;
+        const target = resolveRelative(path, specifier);
+        if (!target || !SOURCE_FILE.test(target) || target.includes(`${sep}node_modules${sep}`)) {
+          continue;
+        }
+        if (seen.has(target)) continue;
+        seen.add(target);
+        const text = read(target);
+        if (text === undefined) continue;
+        queue.push({ path: target, source: text, chain: [...chain, repoPath(target)] });
+      }
+    }
+  }
+  return [...diagnostics.values()].sort((a, b) => a.file.localeCompare(b.file));
+}

package/src/reference/lab-math-scope.ts

@@ -1,6 +1,7 @@
 import { loadManifest } from '../compiler/manifest';
 import type { LabMathScopeDefinition } from './render-lab-math';
 import {
+  bindScopeToPage,
   registerPageNotationDependencies,
   routeIdFromLocals,
 } from './page-notation';
@@ -9,6 +10,7 @@ interface LessonNotationFrontmatter {
   readonly local?: ReadonlyArray<{
     readonly key: string;
     readonly latex: string;
+    readonly fixedIndex?: boolean;
   }>;
 }
 
@@ -39,6 +41,7 @@ export async function labMathScope(
   const scope: LabMathScopeDefinition[] = local.map((definition) => ({
     key: definition.key,
     notation: definition.latex,
+    ...(definition.fixedIndex === true ? { fixedIndex: true as const } : {}),
   }));
 
   const referenced = new Set<string>();
@@ -66,7 +69,11 @@ export async function labMathScope(
     }
     const shared = sharedByKey.get(key);
     if (shared) {
-      scope.push({ key: shared.key, notation: shared.notation });
+      scope.push({
+        key: shared.key,
+        notation: shared.notation,
+        ...(shared.fixedIndex ? { fixedIndex: true as const } : {}),
+      });
       resolvedKeys.add(key);
       continue;
     }
@@ -90,6 +97,13 @@ export async function labMathScope(
       resolvedKeys,
       component.context,
     );
+    // Rule N23: the lab's indexed symbols take derived cards on this page,
+    // and are held to the rule unless the course turned it off.
+    bindScopeToPage(scope, {
+      locals: component.locals,
+      context: component.context,
+      checkIndices: !manifest.rules.disabled.includes('N23'),
+    });
   }
 
   return scope;