explico 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -14,6 +14,175 @@ under **Breaking** below; a PATCH never breaks.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-09-19
+
+### Breaking
+
+- **Rule N17 is inverted: a nested delimiter is sized by the engine, never by
+  hand.** The engine now installs its own KaTeX delimiter sizing
+  (`src/reference/katex-delimiters.mjs`), changing one constant in
+  `makeLeftRightDelim` — `delimiterExtend`, TeX's `\delimitershortfall`, from
+  `5.0` to `-1.0` points.
+  Stock TeX and stock KaTeX let a `\left … \right` pair fall up to 5pt short of
+  its content, so two pairs at different depths around similar content round to
+  the same glyph and the nesting vanishes; N17 used to repair that by making
+  authors hand-pick `\bigl` → `\Bigl` → `\biggl` → `\Biggl` outward. Those are
+  *fixed* glyphs: they stop tracking the content they wrap, they run out after
+  four levels, and editing an inner expression silently invalidates every size
+  above it. With a negative shortfall a pair is always strictly taller than its
+  content, so each enclosing level grows on its own, at any depth, by exactly
+  what it needs. `\left … \right` at every level is now the rule, and
+  hand-sizing a pair inside a nest is the warning.
+
+  Consequences for a course:
+  - The Tier-3 diagnostic code is renamed `delimiter-size-hierarchy` →
+    **`delimiter-manual-size`**; a `lint-ignore.yml` entry or a script matching
+    the old code must be updated. Its diagnostic shape changed too: the
+    `outerSize`/`nestedSize` fields are replaced by a single `size` (the
+    hand-picked size found), and `suggestion` is now always present and always
+    a `\left`/`\right` pair — it no longer carries a `size` field.
+  - Math that was N17-compliant now warns. A ladder such as
+    `\Biggl[a+\biggl(b+\Bigl[c+\left(d+e\right)\Bigr]\biggr)\Biggr]` reports one
+    finding per hand-sized level; the repair is `\left`/`\right` at every level.
+    A *lone* hand-sized pair that is not part of a nest — `\bigl(x,\ y\bigr)`
+    for a tuple — is deliberately left alone.
+  - **A course needs no install step for this.** `delimiterExtend` is a
+    function-local `const`, so nothing KaTeX exports reaches it and the change
+    has to happen in the module's own source. Rather than a `patches/` file —
+    which pnpm records per project and so cannot travel inside the npm artifact
+    — the engine reads KaTeX's ESM bundle, rewrites that constant, and moves
+    the render entry points onto the shared `katex` object. `rehype-katex`
+    reads `katex.renderToString` at call time and KaTeX's default export is
+    mutable, so lesson-body math inherits it without the plugin being forked or
+    aliased. `astro.config.mjs` already imports
+    `explico/reference/katex-options.mjs`, which installs it, so an existing
+    course picks this up on upgrade with no edit. The installer verifies itself
+    — a KaTeX upgrade that moves the constant, or anything that renders first,
+    fails the build with an explicit message instead of silently reverting to
+    stock spacing. [`docs/katex-bracket-scaling.md`](docs/katex-bracket-scaling.md)
+    derives the change and documents the mechanism and its trade-offs.
+
+### Added
+
+- **A math diagnostic now names the equation it belongs to.** Every finding
+  the math gate reports from a `$$…$$` block that carries a `\label{eq:…}`
+  gains an `equation` field — `{ key, href }`, where `href` is the anchor the
+  rendered page gives that equation (`/l1-ar/ar1-basics/#eq-ar1-variance`) —
+  and `diagnosticLine()` appends it, so the console line, the run log, and
+  `pnpm content diagnostics` all read
+  `[code] file:line:column: message (eq:<key> -> <href>)`. A size-only
+  `delimiter-manual-size` finding inside a six-line `aligned` block was
+  otherwise anonymous: the message names delimiters, never the result they
+  belong to, so an author had to reconstruct which equation was meant from a
+  line number alone. `CliDiagnostic` carries the same optional field, so a
+  course's own `scripts/content.ts` gets it without change. The manifest
+  schema is now **v16** (additive: v15 → v16); nothing existing changed shape.
+
+- **The About panel publishes the identity it shows.** `AboutPanel.astro` now
+  stamps `data-knowledge-version`, `data-knowledge-date` (omitted when the
+  content changelog has no date) and `data-engine-version` on its
+  `details[data-about-panel]` element, and marks the rendered version line with
+  `data-knowledge-line`. The two versions the panel exists to publish were
+  readable only as prose — and as a `version · date` join — so a course's build
+  check had to match that text, which pins the check to one version string and
+  turns every routine bump into a test edit; this repo's own
+  `playground/tests/e2e/about.spec.ts` was asserting `0.4.0` against a
+  playground long since at `0.5.2`. A bare version substring is not scoped to
+  the panel either, so the engine version printed one row below can satisfy it.
+  The attributes are additive: nothing rendered changed, and the existing
+  `data-about-panel` hook is untouched.
+
+### Fixed
+
+- **A glossary heading's accessible name is the term again.** The notation
+  glossary's per-entry anchor link moved *inside* its `<h2>` when the entry
+  header was rebuilt for smooth scrolling, so the `aria-label` on that link
+  ("Link to “Velocity”") joined the heading's accessible name — a screen reader
+  announced "Velocity Link to Velocity", and any check for the heading by name
+  stopped matching. `NotationGlossary.astro` now wraps the heading and its
+  anchor in a `.glossary-heading` flex row, the shape
+  `rehype-heading-anchors` already gives a lesson heading (`<h2>` and
+  `a.sl-anchor-link` as siblings). Nothing visual changed; the anchor still
+  reveals on hover and focus.
+
+- **A diagnostic's `line` now addresses the file it names.** Every gate scans
+  `lesson.body`, which Astro's `parseFrontmatter` hands over with the
+  frontmatter already removed, but each finding is reported against
+  `lesson.source.file` — so every `file:line:column` the engine has ever
+  emitted for a lesson was short by the height of that lesson's frontmatter.
+  It failed silently in the worst way: the number stayed plausible, so an
+  editor, a VS Code problem matcher, or an author following
+  `pnpm content diagnostics` jumped confidently to the wrong line, and a
+  size-only N17 finding could not be located at all. `parseDocument` now
+  records the body's start line, `NotationLessonInput` carries it as an
+  optional `bodyLine`, and the new `lessonLine()` helper applies it — so
+  `gate-math` (including every `delimiter-manual-size` column),
+  `gate-prose-notation` (N9), `gate-abbreviations` (N14), and
+  `gate-heading-length` (S1) are all corrected at once. A hand-built lesson
+  input that omits `bodyLine` behaves exactly as before.
+
+- **`equationAnchorId({ key })` type-checks without a `number`.** Its JSDoc
+  required both properties although `number` is read only when there is no
+  `key`, so a keyed caller had to pass a value the function ignores.
+
+- **A notation `formula` can use a manual delimiter size, an accent, a box, or
+  a color without failing the build.** `render-notation-math.ts` sanitizes
+  KaTeX's output against an attribute allowlist that had only ever grown to
+  cover what the corpus happened to use, so ordinary math threw
+  `Unexpected KaTeX property` with no author-side workaround: `\Bigl`/`\biggl`/
+  `\Biggl` (`minsize`, `maxsize`), `\xrightarrow` (`minsize`), `\boxed`
+  (`notation`), and `\colorbox` (`voffset`, `mathbackground`). Rule N17 asks
+  authors for exactly those delimiter commands, so a card that followed the
+  engine's own advice could not build. The allowlist is now KaTeX's whole inert
+  presentation surface — `columnlines`, `depth`, `display`, `largeop`,
+  `linebreak`, `linethickness`, `mathbackground`, `mathcolor`, `mathsize`,
+  `maxsize`, `minsize`, `notation`, `rowlines`, `valign`, and `voffset` join the
+  set — with `alt`, `href`, `src`, and `title` explicitly denied, and a new test
+  scans KaTeX's own `setAttribute` calls so a KaTeX upgrade that adds an
+  attribute fails here instead of in a downstream course. Hex colors are
+  accepted in an attribute or style value; no attribute that can carry a URL is
+  allowed through.
+
+- **`\vec` (and every other accent) renders again.** The style sanitizer
+  required each CSS declaration to end in `;`, but KaTeX does not always
+  terminate the last one — `\vec` emits `style="width:0.471em"` — and the
+  rejection then fell through to the misleading
+  `Unexpected KaTeX property: style`. Declarations are now validated one at a
+  time, and an unsafe `style` or `d` value says so instead of reporting an
+  unknown property.
+
+- **A macro in a formula no longer invents a source span.** KaTeX gives a node
+  it produced by expanding a macro a `loc` from the lexer over the *macro
+  body*, so those offsets index that body and not the source being scanned —
+  and they are still valid indices into a longer source, so the glyph resolver
+  read them as a real span over unrelated text. `\vdots` expands to
+  `{\varvdots\rule{0pt}{15pt}}`, whose atom claims characters 1–10: in
+  `M=\begin{pmatrix}…` that is `"=\begin{p"`, and because no author can wrap
+  that slice in an `\explain`, a matrix showing a column ellipsis failed the
+  build with `Unresolved notation ""`. Where the stray span instead collided
+  with a glyph in scope, the binding was injected at the macro body's offsets
+  and split the source mid-command — `\varSigma=\operatorname{Cov}(X)` became
+  `\varSigm\explain{cov-matrix}{a=\ope}ratorname{Cov}(X)`, a corrupt formula no
+  gate rejected. `nodeSpan` now believes a `loc` only when it belongs to the
+  string this pass parsed. 79 of KaTeX's 282 macros emit such a node, among
+  them `\argmax`, `\argmin`, `\plim`, `\limsup`, `\liminf`, `\bmod`, `\pmod`,
+  `\R`, `\N`, `\Z` and every upright `\varGamma`-style capital. A macro's
+  *argument* keeps the author's own locs and still binds normally. One limit
+  remains: a macro-expanded glyph has no authored span, so canonical matching
+  and the completeness gate cannot see it — annotate it with an explicit
+  `\explain{key}{\varSigma}`, which works and is unaffected by this change.
+
+- **A malformed `\explain` / `\slot` key fails the build instead of reaching
+  the reader.** KaTeX does not treat a denied `trust` callback as a parse
+  error: it renders the command name in `errorColor` and continues, so
+  `\explain{Not A Key}{\Omega}` produced red `\htmlData` text on the page with
+  the build green. (Until now this was masked by `mathcolor` — the attribute
+  KaTeX's error rendering carries — not being in the allowlist.)
+  `renderNotationMath` now checks both marker macros against
+  `trustNotationMarker` before KaTeX runs and throws naming the offending key.
+  `renderNotationFormula` still degrades to inert-but-correct math rather than
+  costing a reader the equation.
+
 ## [0.7.0] - 2026-09-18
 
 ### Breaking
@@ -722,7 +891,8 @@ under **Breaking** below; a PATCH never breaks.
   system with its completeness gate, the curriculum-graph validator, the
   Astro/Starlight UI, the LMS / session / analytics seams, and the `content` CLI.
 
-[Unreleased]: https://github.com/danieltuzes/explico/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/danieltuzes/explico/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/danieltuzes/explico/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/danieltuzes/explico/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/danieltuzes/explico/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/danieltuzes/explico/compare/v0.4.0...v0.5.0

package/dist/compiler/cli.d.ts

@@ -1,4 +1,5 @@
 import { DiagnosticSeverity } from '../reference/types.js';
+import { EquationLink } from '../reference/gate-math.js';
 import { Manifest, ManifestLesson } from './manifest.js';
 import '../curriculum/validation.js';
 import '../reference/consistency.js';
@@ -12,7 +13,6 @@ import '../reference/figures-validate.js';
 import '../reference/diagrams-validate.js';
 import '../reference/knowledge-checks-validate.js';
 import '../reference/raw-floats-validate.js';
-import '../reference/gate-math.js';
 import '../reference/mixed-content.js';
 import '../reference/gloss.js';
 import './knowledge-version.js';
@@ -61,6 +61,13 @@ interface CliDiagnostic {
     readonly file?: string;
     readonly line?: number;
     readonly column?: number;
+    /**
+     * The keyed equation the finding sits in, when the math carries a
+     * `\label{eq:…}` — `{ key, href }`, the href being the anchor on the
+     * rendered page. A size-only finding inside a long `aligned` block is
+     * otherwise anonymous.
+     */
+    readonly equation?: EquationLink;
 }
 /**
  * Every manifest diagnostic that names this lesson (by id or file), normalized

package/dist/compiler/cli.js

@@ -76,7 +76,8 @@ function lessonDiagnostics(manifest, lesson) {
       message: diagnostic.message,
       file: diagnostic.file,
       ...diagnostic.line === void 0 ? {} : { line: diagnostic.line },
-      ...diagnostic.column === void 0 ? {} : { column: diagnostic.column }
+      ...diagnostic.column === void 0 ? {} : { column: diagnostic.column },
+      ...diagnostic.equation === void 0 ? {} : { equation: diagnostic.equation }
     });
   }
   for (const diagnostic of manifest.diagnostics.equations) {
@@ -365,6 +366,11 @@ function contentStatus(manifest) {
     }
   };
 }
+function equationLink(value) {
+  if (value === null || typeof value !== "object") return void 0;
+  const { key, href } = value;
+  return typeof key === "string" && typeof href === "string" ? { key, href } : void 0;
+}
 function numericLocation(value) {
   return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : void 0;
 }
@@ -394,13 +400,15 @@ function contentDiagnostics(manifest, minimumSeverity = "info") {
       const line = numericLocation(diagnostic.line) ?? numericLocation(source?.line);
       const column = numericLocation(diagnostic.column) ?? numericLocation(source?.column);
       const detail = typeof diagnostic.code === "string" ? diagnostic.code : typeof diagnostic.kind === "string" ? diagnostic.kind : "diagnostic";
+      const equation = equationLink(diagnostic.equation);
       diagnostics.push({
         code: `${group}:${detail}`,
         severity,
         message: String(diagnostic.message ?? detail),
         ...file === void 0 ? {} : { file },
         ...line === void 0 ? {} : { line },
-        ...column === void 0 ? {} : { column }
+        ...column === void 0 ? {} : { column },
+        ...equation === void 0 ? {} : { equation }
       });
     }
   }

package/dist/compiler/collections.js

@@ -25,12 +25,24 @@ function filesBelow(directory, extensions) {
     return entry.isFile() && extensions.some((extension) => entry.name.endsWith(extension)) ? [path] : [];
   }).sort();
 }
+function bodyStartLine(raw, body) {
+  const offset = raw.endsWith(body) ? raw.length - body.length : raw.indexOf(body);
+  if (offset <= 0) return 1;
+  let line = 1;
+  for (let index = 0; index < offset; index += 1) {
+    if (raw.charCodeAt(index) === 10) line += 1;
+  }
+  return line;
+}
 function parseDocument(path) {
-  const parsed = parseFrontmatter(readFileSync(path, "utf8"));
+  const raw = readFileSync(path, "utf8");
+  const parsed = parseFrontmatter(raw);
+  const body = parsed.content.replace(/^\n/, "");
   return {
     file: relative(REPOSITORY_ROOT, path),
     data: parsed.frontmatter ?? {},
-    body: parsed.content.replace(/^\n/, "")
+    body,
+    bodyLine: bodyStartLine(raw, body)
   };
 }
 function record(value, label) {
@@ -322,7 +334,7 @@ function notationLessonEntries() {
   for (const path of filesBelow(join(CONTENT_ROOT, "docs"), [".md", ".mdx"])) {
     const slug = docSlug(path);
     if (!isLessonSlug(slug)) continue;
-    const { file, data, body } = parseDocument(path);
+    const { file, data, body, bodyLine } = parseDocument(path);
     const notation = record(data.notation ?? {}, `${file} notation`);
     const local = Array.isArray(notation.local) ? notation.local : [];
     lessons.push({
@@ -333,6 +345,7 @@ function notationLessonEntries() {
       ),
       references: extractNotationReferences(body, file, void 0),
       body,
+      bodyLine,
       source: { file }
     });
   }

package/dist/compiler/logging.d.ts

@@ -67,6 +67,11 @@ interface AnyDiagnostic {
     readonly file?: string;
     readonly line?: number;
     readonly column?: number;
+    /** `{ key, href }` when the finding belongs to a `\label{eq:…}` equation. */
+    readonly equation?: {
+        readonly key: string;
+        readonly href: string;
+    };
 }
 /** `manifest.diagnostics`, structurally — one array per subsystem. */
 type DiagnosticGroups = Readonly<Record<string, readonly AnyDiagnostic[]>>;
@@ -89,7 +94,12 @@ interface RunLog {
     /** Refreshes `latest` and reports what the run recorded. */
     close(): RunLogSummary;
 }
-/** `[code] message`, matching what the console has always printed. */
+/**
+ * `[code] file:line:column: message`, matching what the console has always
+ * printed, with ` (eq:<key> -> <href>)` appended when the finding belongs to a
+ * keyed equation — so a size-only finding inside a long `aligned` block names
+ * the result it is about, not just its coordinates.
+ */
 declare function diagnosticLine(diagnostic: AnyDiagnostic): string;
 interface RunLogOptions {
     /** Overridden in tests; defaults to `build/logs` under the repository root. */

package/dist/compiler/logging.js

@@ -38,7 +38,8 @@ function diagnosticLine(diagnostic) {
   const code = diagnostic.code ?? diagnostic.kind;
   const at = [diagnostic.file, diagnostic.line, diagnostic.column].filter((part) => part !== void 0).join(":");
   const prefix = code === void 0 ? "" : `[${code}] `;
-  return at === "" ? `${prefix}${diagnostic.message}` : `${prefix}${at}: ${diagnostic.message}`;
+  const equation = diagnostic.equation === void 0 ? "" : ` (eq:${diagnostic.equation.key} -> ${diagnostic.equation.href})`;
+  return at === "" ? `${prefix}${diagnostic.message}${equation}` : `${prefix}${at}: ${diagnostic.message}${equation}`;
 }
 function createRunLog(options = {}) {
   const root = options.root ?? LOGS_DIR;

package/dist/compiler/manifest.d.ts

@@ -101,7 +101,7 @@ import '../reference/keyed-float-validate.js';
  * from `warning` to `info`; their diagnostic codes and container fields stay
  * unchanged.
  */
-declare const MANIFEST_SCHEMA_VERSION = 15;
+declare const MANIFEST_SCHEMA_VERSION = 16;
 declare const MANIFEST_PATH: string;
 interface ManifestCitation {
     readonly id: string;

package/dist/compiler/manifest.js

@@ -75,7 +75,7 @@ import {
   isLessonSlug,
   lessonIdFromSlug
 } from "./lesson-derivation.js";
-const MANIFEST_SCHEMA_VERSION = 15;
+const MANIFEST_SCHEMA_VERSION = 16;
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 const MANIFEST_PATH = join(REPOSITORY_ROOT, "build", "manifest.json");

package/dist/reference/delimiter-size.d.ts

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

package/dist/reference/delimiter-size.js

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

package/dist/reference/equations.d.mts

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

package/dist/reference/equations.mjs

@@ -106,7 +106,13 @@ export function displayEquationNumber({
     : `${prefix}.${offset + indexInLesson}`;
 }
 
-/** The positional anchor id for an unkeyed equation, e.g. `2.4` → `eq-2-4`. */
+/**
+ * A display equation's anchor id: `eq-<key>` when it carries a
+ * `\label{eq:…}`, else the positional form, e.g. `2.4` → `eq-2-4`.
+ *
+ * @param {{ key?: string, number?: string | number }} equation - `number` is
+ *   read only when there is no `key`, so a keyed caller may omit it.
+ */
 export function equationAnchorId({ key, number }) {
   return key ? `eq-${key}` : `eq-${String(number).replace(/\./g, '-')}`;
 }

package/dist/reference/gate-abbreviations.js

@@ -1,7 +1,7 @@
 import { collectOperators, collectRomanLabels } from "./math-glyphs.mjs";
 import { isBaseAbbreviation } from "./base-abbreviations.mjs";
 import { pageScope } from "./gate-math.js";
-import { lineOf, proseOnly } from "./gate-prose-notation.js";
+import { lessonLine, proseOnly } from "./gate-prose-notation.js";
 const CAPS_RUN = /\b([A-Z]{2,})(?:'s|s)?\b/g;
 const DOTTED_ABBR = /\b(?:[A-Za-z]\.){2,}/g;
 function findAbbreviationLikeTokens(text) {
@@ -51,7 +51,7 @@ function gateAbbreviations(input) {
         context: "abbreviation",
         severity: "error",
         file: lesson.source.file,
-        line: lineOf(lesson.body, index),
+        line: lessonLine(lesson, index),
         token,
         message: `Unexplained abbreviation ${JSON.stringify(token)} outside math. ${FIX}`
       });

package/dist/reference/gate-heading-length.js

@@ -1,5 +1,5 @@
 import { stripFencedCode } from "./equations.mjs";
-import { lineOf } from "./gate-prose-notation.js";
+import { lessonLine } from "./gate-prose-notation.js";
 const HEADING_LENGTH_LIMIT = 65;
 const HEADING_LINE = /^[ \t]{0,3}(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/gm;
 const TITLE_ATTRIBUTE_BY_TAG = {
@@ -65,7 +65,7 @@ function gateHeadingLength(lessons) {
         context: "structure",
         severity: "error",
         file: lesson.source.file,
-        line: lineOf(lesson.body, finding.index),
+        line: lessonLine(lesson, finding.index),
         token: finding.token,
         message: finding.message
       });

package/dist/reference/gate-math.d.ts

@@ -1,5 +1,19 @@
 import { NotationRegistryInput, NotationLessonInput } from './types.js';
 
+/**
+ * The equation a finding sits in, when its math carries a `\label{eq:…}`.
+ *
+ * A location tells you where to edit; this tells you *what you are looking
+ * at*. A size-only N17 finding inside a six-line `aligned` block is otherwise
+ * anonymous — the message names delimiters, not the result they belong to —
+ * so the key and the rendered page's anchor both travel with the diagnostic.
+ */
+interface EquationLink {
+    /** The label's key, without the `eq:` prefix. */
+    readonly key: string;
+    /** Where the reader sees it, e.g. `/l1-ar/ar1-basics/#eq-ar1-variance`. */
+    readonly href: string;
+}
 interface MathGateDiagnostic {
     readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation' | 'structure';
     /**
@@ -31,6 +45,8 @@ interface MathGateDiagnostic {
     readonly line?: number;
     readonly column?: number;
     readonly token?: string;
+    /** Present when the offending math carries a `\label{eq:…}`. */
+    readonly equation?: EquationLink;
     readonly message: string;
 }
 interface AssessmentItemLike {
@@ -58,6 +74,12 @@ type ScopeEntry = {
  * hand and risk drifting from what the completeness gate actually checks.
  */
 declare function pageScope(lesson: NotationLessonInput, sharedByKey: ReadonlyMap<string, ScopeEntry>): ScopeEntry[];
+/**
+ * The `\label{eq:…}` a math source carries, as a key plus the anchor the
+ * rendered page gives it. `EQ_LABEL_PATTERN` is global, so its `lastIndex` is
+ * reset before use — a stale one would skip the first label of the next span.
+ */
+declare function equationLinkFor(lessonId: string, latex: string): EquationLink | undefined;
 /**
  * Resolve every rendered-math context against the page glyph table. Returns one
  * diagnostic per unresolved token; an empty array means the gate passed.
@@ -68,4 +90,4 @@ declare function gateContentMath(input: {
     readonly lessonAssessments: readonly LessonAssessmentLink[];
 }): MathGateDiagnostic[];
 
-export { type MathGateDiagnostic, type ScopeEntry, gateContentMath, pageScope };
+export { type EquationLink, type MathGateDiagnostic, type ScopeEntry, equationLinkFor, gateContentMath, pageScope };