explico 0.2.0 → 0.3.0

package/src/reference/consistency.ts

@@ -19,15 +19,23 @@
  *   (f) weak-local                   a `notation.local` symbol used only in its
  *                                     own defining equation and prose
  *   (g) notation-source-locator      every notation `sources` entry has a locator
+ *   (h) operator-explained           a named operator a lesson uses is on the
+ *                                     shipped/course operator allowlist or
+ *                                     carries a notation entry (rule N8)
  *
  * Check (d) — the committed per-lesson resolution report — lives in
  * `src/content/resolution-report.ts`.
  */
 
-import type { CourseConventions } from '../compiler/course-config';
+import type {
+  CourseConventions,
+  CourseOperators,
+} from '../compiler/course-config';
 import type { CurriculumCatalog } from '../curriculum/validation';
 import type { NotationSpec } from '../compiler/collections';
 import type { LintIgnore } from './lint-ignore';
+import { effectiveOperatorAllowlist } from './base-operators.mjs';
+import { collectOperators } from './math-glyphs.mjs';
 import { offVocabularyTokens } from './units-vocab';
 import type {
   NotationDefinitionRecord,
@@ -45,7 +53,8 @@ export type ConsistencyCode =
   | 'notation-source-locator'
   | 'gloss-wants-promoting'
   | 'card-wants-demoting'
-  | 'gloss-name-shape';
+  | 'gloss-name-shape'
+  | 'operator-explained';
 
 export interface ConsistencyDiagnostic {
   readonly code: ConsistencyCode;
@@ -68,6 +77,8 @@ export interface ConsistencyInput {
   readonly lintIgnore: LintIgnore;
   /** Convention keys this course anchors on (from `content/course.config.ts`). */
   readonly conventions: CourseConventions;
+  /** This course's edits to the named-operator baseline (rule N8). */
+  readonly operators?: CourseOperators;
 }
 
 const CONVENTION_RE =
@@ -472,6 +483,74 @@ function checkGlossNameShape(
   }
 }
 
+/**
+ * A named operator a lesson uses is either universal — on the shipped
+ * `BASE_OPERATORS` baseline plus this course's `operators.allow`, minus its
+ * `operators.deny` — or it is explained: a notation card or `notation.local`
+ * entry the lesson binds with `[[key]]` whose `latex` is that operator, so the
+ * reader can hover it. Anything else (`\operatorname{Var}` with no entry, or a
+ * baseline operator the course chose to `deny`) is a finding. Rule N8.
+ *
+ * The glyph resolver skips operator bodies whole, so this is the only check
+ * that looks at them; it reads `collectOperators`, which parses with the same
+ * pinned KaTeX as the completeness gate.
+ */
+function checkOperatorExplained(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const allowlist = effectiveOperatorAllowlist(input.operators);
+  const byId = new Map<string, NotationDefinitionRecord>(
+    input.registry.definitions.map((definition) => [definition.id, definition]),
+  );
+  const bindingsByLesson = new Map(
+    input.registry.bundles.map((bundle) => [bundle.lessonId, bundle.bindings]),
+  );
+
+  for (const lesson of input.notationInput.lessons) {
+    // Operators the reader is shown on this page: the lesson's own
+    // `notation.local` entries, plus every shared card it binds with `[[key]]`.
+    const explained = new Set<string>();
+    const noteEntryOperators = (latex: string): void => {
+      for (const operator of collectOperators(latex)) {
+        explained.add(operator.name);
+      }
+    };
+    for (const definition of lesson.localDefinitions) {
+      noteEntryOperators(definition.notation);
+    }
+    for (const binding of bindingsByLesson.get(lesson.lessonId) ?? []) {
+      const definition = byId.get(binding.definitionId);
+      if (definition) noteEntryOperators(definition.notation);
+    }
+
+    const reported = new Set<string>();
+    for (const span of mathSpans(lesson.body)) {
+      for (const operator of collectOperators(span.latex)) {
+        if (allowlist.has(operator.name)) continue;
+        if (explained.has(operator.name)) continue;
+        if (reported.has(operator.name)) continue;
+        reported.add(operator.name);
+        if (input.lintIgnore.matches('operator-explained', operator.name)) {
+          continue;
+        }
+        const display =
+          operator.source === 'operatorname'
+            ? `\\operatorname{${operator.name}}`
+            : `\\${operator.name}`;
+        out.push({
+          code: 'operator-explained',
+          severity: 'warning',
+          lessonId: lesson.lessonId,
+          file: lesson.source.file,
+          glyph: operator.name,
+          message: `${lesson.lessonId}: operator ${JSON.stringify(display)} is neither on the course operator allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(display)}) introduced with [[key]], or add ${JSON.stringify(operator.name)} to operators.allow in course.config.ts`,
+        });
+      }
+    }
+  }
+}
+
 const CHECKS: ((
   input: ConsistencyInput,
   out: ConsistencyDiagnostic[],
@@ -485,6 +564,7 @@ const CHECKS: ((
   checkGlossWantsPromoting,
   checkCardWantsDemoting,
   checkGlossNameShape,
+  checkOperatorExplained,
 ];
 
 /**
@@ -522,6 +602,7 @@ export function consistencyCounts(
     'gloss-wants-promoting': 0,
     'card-wants-demoting': 0,
     'gloss-name-shape': 0,
+    'operator-explained': 0,
   } satisfies Record<ConsistencyCode, number>;
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;

package/src/reference/diagram-layout.ts

@@ -0,0 +1,246 @@
+/**
+ * Build-time graph layout for the `Diagram` component.
+ *
+ * Wraps `@dagrejs/dagre` — a pure layout algorithm, no DOM — so node
+ * positions and edge routes are computed once at build time, the same way
+ * `renderLabMath` and the notation formulas are: static output, no runtime
+ * layout library shipped to the reader. `Diagram.astro` turns the result into
+ * 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.
+ */
+import dagre from '@dagrejs/dagre';
+import type {
+  EdgeLabel as DagreEdgeLabel,
+  GraphLabel as DagreGraphLabel,
+  NodeLabel as DagreNodeLabel,
+} from '@dagrejs/dagre';
+
+export interface DiagramNodeInput {
+  readonly id: string;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface DiagramEdgeInput {
+  readonly from: string;
+  readonly to: string;
+}
+
+export interface DiagramLayoutOptions {
+  /** Top-to-bottom (default) or left-to-right. */
+  readonly direction?: 'TB' | 'LR';
+  readonly nodeSeparation?: number;
+  readonly rankSeparation?: number;
+  /** Uniform padding added around the computed bounding box. */
+  readonly padding?: number;
+}
+
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+export interface LaidOutNode {
+  readonly id: string;
+  /** Top-left corner, not the center dagre itself works in. */
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface LaidOutEdge {
+  readonly from: string;
+  readonly to: string;
+  readonly points: readonly Point[];
+}
+
+export interface DiagramLayout {
+  readonly nodes: readonly LaidOutNode[];
+  readonly edges: readonly LaidOutEdge[];
+  /** The SVG canvas size a caller should use as the `viewBox`. */
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * Lay out a small directed graph. Node ids must be unique; an edge naming an
+ * undeclared node fails loudly rather than silently dropping it (dagre itself
+ * would otherwise create a phantom zero-size node).
+ */
+export function layoutDiagram(
+  nodes: readonly DiagramNodeInput[],
+  edges: readonly DiagramEdgeInput[],
+  options: DiagramLayoutOptions = {},
+): DiagramLayout {
+  const ids = new Set<string>();
+  for (const node of nodes) {
+    if (ids.has(node.id)) {
+      throw new Error(`Diagram declares node "${node.id}" more than once.`);
+    }
+    if (!(node.width > 0) || !(node.height > 0)) {
+      throw new Error(
+        `Diagram node "${node.id}" must have a positive width and height.`,
+      );
+    }
+    ids.add(node.id);
+  }
+  for (const edge of edges) {
+    if (!ids.has(edge.from)) {
+      throw new Error(`Diagram edge references unknown node "${edge.from}".`);
+    }
+    if (!ids.has(edge.to)) {
+      throw new Error(`Diagram edge references unknown node "${edge.to}".`);
+    }
+  }
+
+  const graph = new dagre.graphlib.Graph<
+    DagreGraphLabel,
+    DagreNodeLabel,
+    DagreEdgeLabel
+  >();
+  graph.setGraph({
+    rankdir: options.direction ?? 'TB',
+    nodesep: options.nodeSeparation ?? 24,
+    ranksep: options.rankSeparation ?? 48,
+    marginx: 0,
+    marginy: 0,
+  });
+  graph.setDefaultEdgeLabel(() => ({}));
+
+  for (const node of nodes) {
+    graph.setNode(node.id, { width: node.width, height: node.height });
+  }
+  for (const edge of edges) {
+    graph.setEdge(edge.from, edge.to);
+  }
+
+  dagre.layout(graph);
+
+  const centeredNodes = nodes.map((node) => {
+    const label = graph.node(node.id);
+    const cx = label.x ?? 0;
+    const cy = label.y ?? 0;
+    return {
+      id: node.id,
+      x: cx - node.width / 2,
+      y: cy - node.height / 2,
+      width: node.width,
+      height: node.height,
+    };
+  });
+
+  const rawEdges = edges.map((edge) => {
+    const label = graph.edge(edge.from, edge.to) ?? {};
+    return {
+      from: edge.from,
+      to: edge.to,
+      points: (label.points ?? []).map((point) => ({
+        x: point.x,
+        y: point.y,
+      })),
+    };
+  });
+
+  // dagre does not guarantee the layout starts at (0, 0); compute the real
+  // bounding box from node boxes and edge routing points, then shift
+  // everything so the canvas starts at `padding`.
+  const padding = options.padding ?? 12;
+  const xs = [
+    ...centeredNodes.flatMap((node) => [node.x, node.x + node.width]),
+    ...rawEdges.flatMap((edge) => edge.points.map((point) => point.x)),
+  ];
+  const ys = [
+    ...centeredNodes.flatMap((node) => [node.y, node.y + node.height]),
+    ...rawEdges.flatMap((edge) => edge.points.map((point) => point.y)),
+  ];
+  const minX = xs.length > 0 ? Math.min(...xs) : 0;
+  const minY = ys.length > 0 ? Math.min(...ys) : 0;
+  const maxX = xs.length > 0 ? Math.max(...xs) : 0;
+  const maxY = ys.length > 0 ? Math.max(...ys) : 0;
+  const shiftX = padding - minX;
+  const shiftY = padding - minY;
+
+  return {
+    nodes: centeredNodes.map((node) => ({
+      ...node,
+      x: node.x + shiftX,
+      y: node.y + shiftY,
+    })),
+    edges: rawEdges.map((edge) => ({
+      ...edge,
+      points: edge.points.map((point) => ({
+        x: point.x + shiftX,
+        y: point.y + shiftY,
+      })),
+    })),
+    width: maxX - minX + padding * 2,
+    height: maxY - minY + padding * 2,
+  };
+}
+
+// --- box-size estimation (no DOM at build time) --------------------------
+
+export interface BoxSizeEstimate {
+  readonly width: number;
+  readonly height: number;
+}
+
+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,
+};
+
+/**
+ * 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.
+ */
+function formulaVisibleLength(latex: string): number {
+  const collapsed = latex
+    .replace(/\\[a-zA-Z]+/g, 'x')
+    .replace(/[{}$]/g, '')
+    .trim();
+  return Math.max(1, collapsed.length);
+}
+
+/**
+ * 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.
+ */
+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) };
+}

package/src/reference/equations-validate.ts

@@ -53,6 +53,11 @@ export interface EquationLessonInput {
   readonly slug: string;
   readonly file: string;
   readonly body: string;
+  /**
+   * The lesson's 1-based ordinal in the course. When set, equations are
+   * numbered `‹chapter›.‹n›`; when omitted, the legacy `##`-section scheme.
+   */
+  readonly chapter?: number;
 }
 
 const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
@@ -90,7 +95,7 @@ export function validateEquations(
   )) {
     const seen = new Set<string>();
     const table: Record<string, string> = {};
-    for (const raw of scanEquationLabels(lesson.body) as {
+    for (const raw of scanEquationLabels(lesson.body, lesson.chapter) as {
       key: string;
       number: string;
       section: number;

package/src/reference/equations.mjs

@@ -1,9 +1,13 @@
 /**
  * Equation identity (Step D7, extended F3) — shared, framework-free helpers.
  *
- * Every display equation (`$$…$$`) in a lesson is numbered and given an
- * `id`, from appearance order scoped to the enclosing `##` section (`(2.4)` =
- * fourth display equation under the second section). An author additionally
+ * Every display equation (`$$…$$`) in a lesson is numbered and given an `id`
+ * from appearance order. When the caller supplies a `chapter` (the lesson's
+ * ordinal position in the course), the number is `‹chapter›.‹n›` — `n` counts
+ * every display equation in the lesson and `##` headings do not affect it
+ * (`(2.4)` = fourth display equation of the second lesson). With no `chapter`
+ * 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:
@@ -58,12 +62,28 @@ function equationNumber(section, index) {
   return section > 0 ? `${section}.${index}` : String(index);
 }
 
+/**
+ * The visible number for one display equation. With `chapter` (the lesson's
+ * course ordinal) the scheme is `‹chapter›.‹indexInLesson›` and `##` headings
+ * are ignored; without it, the legacy `##`-section scheme.
+ */
+export function displayEquationNumber({
+  chapter,
+  section,
+  indexInSection,
+  indexInLesson,
+}) {
+  return chapter == null
+    ? equationNumber(section, indexInSection)
+    : `${chapter}.${indexInLesson}`;
+}
+
 /** The positional anchor id for an unkeyed equation, e.g. `2.4` → `eq-2-4`. */
 export function equationAnchorId({ key, number }) {
   return key ? `eq-${key}` : `eq-${String(number).replace(/\./g, '-')}`;
 }
 
-function stripFencedCode(markdown) {
+export function stripFencedCode(markdown) {
   return String(markdown)
     .replace(/```[\s\S]*?```/g, (block) => block.replace(/[^\n]/g, ' '))
     .replace(/~~~[\s\S]*?~~~/g, (block) => block.replace(/[^\n]/g, ' '))
@@ -76,22 +96,28 @@ function stripFencedCode(markdown) {
  * (or an `<Aside>`, etc.) is not counted as a lesson-body equation. The
  * outermost match wins, so nested components are blanked in one pass;
  * newlines are kept so line/section structure is unchanged.
+ *
+ * `keep`, when given, leaves a component of that name untouched instead of
+ * blanking it — `keyed-jsx-floats.mjs` uses this to blank every *other*
+ * component while still finding `<Table>`/`<Figure>` tags at the top level.
  */
-function stripJsxComponents(markdown) {
+export function stripJsxComponents(markdown, keep) {
   return String(markdown).replace(
     /<([A-Z][A-Za-z0-9]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>/g,
-    (block) => block.replace(/[^\n]/g, ' '),
+    (block, name) => (name === keep ? block : block.replace(/[^\n]/g, ' ')),
   );
 }
 
 /**
  * Every keyed display equation in a Markdown body, in appearance order, with
- * its assigned number. `$$…$$` blocks only; `##` headings between them advance
- * the section counter. Every display block advances the in-section index, so a
- * keyed equation's number reflects its position among *all* display equations,
- * not only the keyed ones.
+ * its assigned number. `$$…$$` blocks only. With `chapter` (the lesson's
+ * course ordinal) the number is `‹chapter›.‹n›`, `n` sequential over every
+ * display block in the lesson; without it, `##` headings advance a section
+ * counter and the number is `‹section›.‹indexInSection›`. Either way every
+ * display block advances the index, so a keyed equation's number reflects its
+ * position among *all* display equations, not only the keyed ones.
  */
-export function scanEquationLabels(markdown) {
+export function scanEquationLabels(markdown, chapter) {
   const text = stripJsxComponents(stripFencedCode(markdown));
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
@@ -113,6 +139,7 @@ export function scanEquationLabels(markdown) {
   const labels = [];
   let section = 0;
   let indexInSection = 0;
+  let indexInLesson = 0;
   for (const token of tokens) {
     if (token.kind === 'section') {
       section += 1;
@@ -120,10 +147,16 @@ export function scanEquationLabels(markdown) {
       continue;
     }
     indexInSection += 1;
+    indexInLesson += 1;
     if (token.key == null) continue;
     labels.push({
       key: token.key,
-      number: equationNumber(section, indexInSection),
+      number: displayEquationNumber({
+        chapter,
+        section,
+        indexInSection,
+        indexInLesson,
+      }),
       section,
       indexInSection,
     });
@@ -135,12 +168,14 @@ export function scanEquationLabels(markdown) {
  * The mdast equivalent of `scanEquationLabels` for *every* display equation:
  * walk the tree in document order, advancing the section counter on every
  * depth-2 heading and emitting a record for every `math` node. `key` is the
- * `\label{eq:…}` payload when present, else `null`.
+ * `\label{eq:…}` payload when present, else `null`. `chapter` is threaded the
+ * same way as in `scanEquationLabels`.
  */
-export function collectDisplayEquations(tree) {
+export function collectDisplayEquations(tree, chapter) {
   const equations = [];
   let section = 0;
   let indexInSection = 0;
+  let indexInLesson = 0;
 
   // Only top-level blocks: a `$$…$$` nested in an MDX component (a
   // `<CompactExample>` worked example, an `<Aside>`) is illustrative, not part
@@ -155,11 +190,17 @@ export function collectDisplayEquations(tree) {
     }
     if (node.type === 'math') {
       indexInSection += 1;
+      indexInLesson += 1;
       EQ_LABEL_PATTERN.lastIndex = 0;
       const label = EQ_LABEL_PATTERN.exec(String(node.value ?? ''));
       equations.push({
         key: label ? label[1] : null,
-        number: equationNumber(section, indexInSection),
+        number: displayEquationNumber({
+          chapter,
+          section,
+          indexInSection,
+          indexInLesson,
+        }),
         section,
         indexInSection,
         node,
@@ -173,8 +214,8 @@ export function collectDisplayEquations(tree) {
  * The keyed subset of `collectDisplayEquations` — the tree-walk counterpart of
  * `scanEquationLabels`. Numbers reflect position among all display equations.
  */
-export function collectEquationLabels(tree) {
-  return collectDisplayEquations(tree).filter(
+export function collectEquationLabels(tree, chapter) {
+  return collectDisplayEquations(tree, chapter).filter(
     (equation) => equation.key != null,
   );
 }

package/src/reference/figures-validate.ts

@@ -0,0 +1,40 @@
+/** `validateKeyedFloats` for `<Figure>` — see `keyed-float-validate.ts`. */
+
+import {
+  validateKeyedFloats,
+  type KeyedFloatLabelRecord,
+  type KeyedFloatLessonInput,
+  type KeyedFloatValidation,
+} from './keyed-float-validate';
+
+export type FigureDiagnosticCode =
+  | 'fig-invalid-key'
+  | 'fig-duplicate-key'
+  | 'fig-ref-resolves'
+  | 'fig-key-unused';
+
+export interface FigureDiagnostic {
+  readonly code: FigureDiagnosticCode;
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+  readonly file?: string;
+  readonly lessonId?: string;
+  readonly key?: string;
+}
+
+export type FigureLabelRecord = KeyedFloatLabelRecord;
+export type FigureLessonInput = KeyedFloatLessonInput;
+
+export interface FigureValidation extends KeyedFloatValidation {
+  readonly diagnostics: readonly FigureDiagnostic[];
+}
+
+export function validateFigures(
+  lessons: readonly FigureLessonInput[],
+): FigureValidation {
+  return validateKeyedFloats(lessons, {
+    tagName: 'Figure',
+    prefix: 'fig',
+    noun: 'figure',
+  }) as FigureValidation;
+}