explico 0.7.0 → 0.8.0

package/docs/authoring/notation.md

@@ -837,15 +837,16 @@ change to that file.
 ## N15
 
 **A nested visible delimiter — `(`, `[`, `\{`, or `|` inside another one of
-them — must use a scalable sizing form, not the bare character.**
+them — must use the scalable `\left`/`\right` form, not the bare
+character.**
 
 `(`, `[`, `\{` (an escaped, visible brace — bare `{`/`}` is invisible LaTeX
 grouping and out of scope here), and `|` may be written bare only when they
 are not nested — not inside one another, and not inside a second instance of
 themselves. The moment one of them sits inside another, **every level of that
-nest** uses either the auto-sizing form (`\left(`/`\right)`,
-`\left[`/`\right]`, `\left\{`/`\right\}`, `\left|`/`\right|`) or an explicit
-manual pair from [N17](#n17).
+nest** uses the auto-sizing form (`\left(`/`\right)`, `\left[`/`\right]`,
+`\left\{`/`\right\}`, `\left|`/`\right|`) — and, per [N17](#n17), only
+that form.
 
 ```text
 \sin(2(90\text{°}-\theta))                          ✗ two bare ( nested
@@ -874,10 +875,10 @@ author on a case that can render invisibly wrong.
 _How to apply._
 
 - Reach for `\left(`/`\right)` (or the bracket/brace/pipe equivalents) the
-  moment a second one of these four glyphs would end up inside the first, then
-  apply [N17](#n17)'s manual sizes where necessary. Sizing the outer pair does
-  not exempt an inner bare one; both levels of a two-level nest need a sizing
-  command.
+  moment a second one of these four glyphs would end up inside the first.
+  Sizing the outer pair does not exempt an inner bare one; both levels of a
+  two-level nest need a sizing command. [N17](#n17) then leaves every size to
+  the engine.
 - Mixing types counts as nesting too: `(a + [b])`, `\{a \mid (b)\}`, and
   `(|a|)` all need every level sized, exactly like nesting the same character
   twice.
@@ -949,35 +950,35 @@ mark from notation whose shape carries meaning. That judgment belongs to the
 authoring agent or reviewer, not a syntax linter.
 
 _How to apply._ Decide whether each pair is stylistic before choosing its
-shape. Alternate only the pairs that pass that test. Apply [N17](#n17)
-separately so the visual size still increases from the inside out; shape and
-size are independent decisions.
+shape. Alternate only the pairs that pass that test. Sizes are not your
+concern: [N17](#n17) hands every nested pair to the engine, which grows each
+level automatically. Shape is an authoring decision; size is not.
 
 ```text
-\Biggl[
+\left[
   a+
-  \biggl(
+  \left(
     b+
-    \Bigl[
+    \left[
       c+
       \left(d+e\right)
-    \Bigr]
-  \biggr)
-\Biggr]                                                   ✓
+    \right]
+  \right)
+\right]                                                   ✓
 ```
 
 Semantic notation stays intact even when stylistic grouping surrounds it:
 
 ```text
-\Biggl[
-  \mathbb{E}\!\Bigl[
+\left[
+  \mathbb{E}\!\left[
     f\!\left(X\right)
-  \Bigr]
+  \right]
   +
-  \biggl(
+  \left(
     a+b
-  \biggr)
-\Biggr]                                                   ✓
+  \right)
+\right]                                                   ✓
 ```
 
 In particular, never turn `\mathbb{E}[X]` into another delimiter type merely
@@ -985,7 +986,7 @@ to alternate shapes.
 
 _Enforcement._ Review-only. Delimiter semantics cannot be inferred reliably
 from LaTeX syntax, so no automated check enforces alternation. The N17 linter
-checks sizes only and never recommends changing a delimiter type.
+checks sizing syntax only and never recommends changing a delimiter type.
 
 _Exceptions._ Every conventional or semantically meaningful delimiter is
 outside the alternation preference. Preserving established mathematical
@@ -995,49 +996,66 @@ notation takes precedence over the stylistic cycle.
 
 ## N17
 
-**Every outer pair in a nest of scalable `()`, `[]`, or `\{\}` delimiters must
-be visibly larger than every pair inside it.**
+**A nest of scalable `()`, `[]`, or `\{\}` delimiters is sized by the engine:
+use `\left ... \right` at every level, and never hand-size a pair inside a nest
+with `\bigl`, `\Bigl`, `\biggl`, or `\Biggl`.**
 
-Use progressively larger standard manual sizes to make grouping depth visible
-without producing unnecessarily oversized marks:
-
-1. innermost baseline: `\left ... \right` (or `\bigl ... \bigr`);
-2. next: `\Bigl ... \Bigr`;
-3. next: `\biggl ... \biggr`;
-4. outermost: `\Biggl ... \Biggr`.
-
-The opening and closing commands change size only. Preserve each delimiter's
-shape: `[` remains `[`, `(` remains `(`, and `\{` remains `\{`.
+```text
+\left[a+\left(b+\left[c+\left(d+e\right)\right]\right)\right]     ✓
+\Biggl[a+\biggl(b+\Bigl[c+\left(d+e\right)\Bigr]\biggr)\Biggr]    ✗ hand-sized
+```
 
-_Rationale._ Two nested `\left...\right` pairs around similarly short content
-can render at the same apparent size, hiding the nesting that scalable
-delimiters were meant to clarify. A strict inside-to-outside hierarchy makes
-the depth legible and has an objective syntax-level repair through the four
-standard manual size levels.
+_Rationale._ In stock TeX and stock KaTeX a `\left ... \right` pair is allowed
+to fall up to `\delimitershortfall` (5pt) short of its content, so two pairs at
+different depths around similar content round to the *same* glyph and the
+nesting disappears. The historical repair was to hand-pick a larger size at
+each level, which trades one defect for another: `\bigl`–`\Biggl` are
+*fixed* glyphs, so they stop tracking the content they wrap, they run out after
+four levels, and an edit to the inner expression silently invalidates every
+size above it.
+
+This engine removes the cause instead. `src/reference/katex-delimiters.mjs`
+installs a KaTeX whose `\delimitershortfall` is `-1pt` — the same one-constant
+change an author would make in a LaTeX preamble — see
+[`docs/katex-bracket-scaling.md`](../katex-bracket-scaling.md) for the
+derivation. A pair is then always *strictly* taller than what it wraps, so each
+enclosing level grows on its own, by exactly as much as its content needs, at
+any depth. Hand-sizing is no longer a repair; it is an override that throws the
+automatic hierarchy away.
 
-_How to apply._ Start at the innermost scalable pair and assign each enclosing
-pair the next larger level. Four or fewer levels must have a strict increase at
-every level. If a valid expression needs more levels than the standard sizes
-can distinguish, restructure the expression rather than inventing a fifth
-size. This rule is independent of N16: semantic shapes stay semantic, but their
-sizes still increase when their scalable pairs are nested.
+_How to apply._
 
-_Enforcement._ Tier-3 warning `delimiter-size-hierarchy`, emitted by
+- Write `\left ... \right` at every level of a nest and leave the sizes alone.
+  With the patched engine there is nothing further to do.
+- Do not "help" the engine with a manual size. If a nest still looks wrong,
+  the expression is too deep to read — restructure it, or pull an inner group
+  into its own display, rather than hand-sizing it.
+- This rule is independent of [N16](#n16): shapes still alternate where they
+  are stylistic, and semantic shapes are still preserved. Only the *size*
+  decision moved to the engine.
+- A *lone* hand-sized pair that is not part of a nest is untouched — a tuple
+  written `\bigl(x(t),\ y(t)\bigr)` has no hierarchy to get wrong and stays a
+  deliberate typographic choice.
+- Nothing to install. The sizing rides along with the engine: a course's
+  `astro.config.mjs` already imports `explico/reference/katex-options.mjs`,
+  which installs it before anything renders. If it ever fails to install, the
+  build stops with an explicit error rather than quietly falling back to stock
+  KaTeX.
+
+_Enforcement._ Tier-3 warning `delimiter-manual-size`, emitted by
 `lintDelimiterSizes` (`src/reference/delimiter-size.ts`) through the normal
 math gate for lesson math, notation formulas, and assessment math. The linter
-uses a stack to parse arbitrarily deep `\left...\right`,
-`\bigl...\bigr`, `\Bigl...\Bigr`, `\biggl...\biggr`, and
-`\Biggl...\Biggr` pairs for `()`, `[]`, and `\{\}`. It reports the outer
-pair's source line and column and suggests the required larger manual size when
-one exists. Malformed pairs remain KaTeX syntax errors; the size linter does not
-guess at their structure.
+uses a stack to parse arbitrarily deep `\left...\right`, `\bigl...\bigr`,
+`\Bigl...\Bigr`, `\biggl...\biggr`, and `\Biggl...\Biggr` pairs for `()`, `[]`,
+and `\{\}`, and warns for each hand-sized pair that contains, or sits inside,
+another pair it tracks. It reports that pair's source line and column and
+suggests the `\left`/`\right` replacement, repeating the exact opening and
+closing delimiter shapes it found. Malformed pairs remain KaTeX syntax errors;
+the linter does not guess at their structure.
 
 The automated check deliberately does **not** infer mathematical semantics or
-lint delimiter-type alternation. Its suggestion repeats the exact opening and
-closing delimiter shapes it found.
-
-_Exceptions._ None for a valid nest of scalable pairs with four or fewer
-levels. Beyond four levels, the warning remains but has no automatic size
-replacement; restructure the expression. Bare, non-nested semantic notation
-such as `f(x)` or `\mathbb{E}[X]` is outside this linter and remains governed by
-the mathematical convention and [N15](#n15)'s separate bare-nesting rule.
+lint delimiter-type alternation.
+
+_Exceptions._ None inside a nest. Bare, non-nested semantic notation such as
+`f(x)` or `\mathbb{E}[X]` is outside this linter and remains governed by the
+mathematical convention and [N15](#n15)'s separate bare-nesting rule.

package/docs/katex-bracket-scaling.md

@@ -0,0 +1,191 @@
+# Auto-scaling brackets in KaTeX (and MathJax)
+
+> **Status in this repo.** Solution 2 is implemented, but as *code* rather than
+> as a `patches/` file: [`src/reference/katex-delimiters.mjs`](../src/reference/katex-delimiters.mjs)
+> applies the same one-constant change at import time, so it ships inside the
+> published `explico` package and a downstream course inherits it with no
+> install step. Rule [N17](authoring/notation.md#n17) depends on it. The
+> sections below are the derivation; see
+> [How this repo applies it](#how-this-repo-applies-it).
+
+## The problem
+
+In LaTeX, `\left[ ... \right]` sizes a bracket to fit its content — but nested brackets often come out **the same size**, because the sizing rule only requires the delimiter to be *close enough* to the content's height, not strictly bigger.
+
+Example:
+
+```latex
+$$\left[ \left[ \sqrt{\frac{\int\limits_0^{10}\sqrt{a^2+b^2}}{2}} \right] + 1 \right]$$
+```
+
+The outer `[` and inner `[` render at the same size, even though the outer one wraps strictly more content. The alternative — manually choosing `\bigl`, `\Bigl`, `\biggl`, `\Biggl` — fixes the sizing but abandons `\left`/`\right`'s automatic "match the height of everything inside" behavior, since those are fixed-size delimiters that don't adapt to content.
+
+So there are two properties you want simultaneously, and the two standard tools each give you only one:
+
+1. **Strict growth outward** — each nesting level's bracket must be visibly bigger than the one inside it.
+2. **Full coverage** — every bracket must span the full height of its content, with no gap.
+
+`\bigl`/`\Bigl`/`\biggl`/`\Biggl` give you (1) but not (2) (fixed sizes don't track arbitrary content). `\left`/`\right` give you (2) but not (1) (the sizing rule allows equal-looking sizes at different nesting depths).
+
+## Why it happens: the underlying rule
+
+TeX sizes a `\left`/`\right` pair using this rule (TeXbook, Appendix G, rule 19):
+
+```
+s_min = max( 2·δ₀ · f / 1000 , 2·δ₀ − l )
+```
+
+TeX then picks the smallest available delimiter glyph whose total size `s` satisfies `s ≥ s_min`.
+
+| Symbol | Meaning |
+|---|---|
+| `h` | height of the content: how far it reaches above the baseline |
+| `d` | depth of the content: how far it reaches below the baseline |
+| `a` | axis height — the line fraction bars and minus signs sit on; delimiters are centered on this line |
+| `δ₀` | `max(h − a, d + a)` — how far the content reaches from the axis, on whichever side is farther |
+| `f` | `\delimiterfactor`, default **901** |
+| `l` | `\delimitershortfall`, default **5pt** |
+| `s_min` | the smallest total bracket size TeX will accept |
+| `s` | the size of the delimiter TeX actually picks |
+
+With the default `l = 5pt`, `s_min` can be *smaller* than the content's own height (since `901/1000 ≈ 0.9`), so a delimiter that already matches the inner bracket's height passes the test for the outer bracket too — no forced growth. The same slack also means a delimiter can legally fall up to 5pt short of the content, i.e. requirement (2) isn't fully guaranteed by default either.
+
+**The fix in real LaTeX:** set `\delimitershortfall` to a *negative* value (e.g. `-1pt`). Then `s_min = 2δ₀ + 1pt`, which is always larger than the content's own extent — forcing outward growth at every level, automatically, with no per-formula work. This is a document-wide setting, not something you write per equation:
+
+```latex
+\delimitershortfall=-1pt
+\left[ \left[ \sqrt{\frac{\int\limits_0^{10}\sqrt{a^2+b^2}}{2}} \right] + 1 \right]
+```
+
+Verified by rendering with `pdflatex`: default nesting produces equal-sized brackets; the same source with `\delimitershortfall=-1pt` produces strictly increasing sizes at every depth, and small content (`(x)`, `((x))`, `(((x)))`) is unaffected since the correction is tiny relative to normal delimiter jumps.
+
+## Why it doesn't carry over to the web
+
+`\delimitershortfall` is a TeX engine primitive. **Neither KaTeX nor MathJax expose it or honor it** — I tested both directly:
+
+- KaTeX: `\delimitershortfall=-1pt` throws `ParseError: Expected group after '\delimitershortfall'` (undefined control sequence).
+- MathJax v3: the command is silently dropped/renders as an error span; no effect on sizing.
+
+So the web renderers need a different fix.
+
+## Solution 1: a `\grow` macro (portable, works in *any* KaTeX/MathJax page)
+
+Since neither engine's *rule* can be changed from user-level TeX, the workaround changes the **content** being measured instead. Wrap everything inside a bracket pair (except the innermost level) in an invisible padding macro that makes the content measure as slightly taller and deeper than it visually is. Then the normal `\left`/`\right` sizing — which *does* work correctly in both engines — is forced to pick a bigger glyph at each level, because the content it measures really is bigger.
+
+**Mechanism:** for content `#1`, stack a raised zero-width phantom copy 0.5em above it and a lowered zero-width phantom copy 0.5em below it. `\vphantom{#1}` takes zero horizontal space and is invisible, but claims the same height/depth as `#1`. Raising and lowering copies of it extends the *measured* bounding box by 0.5em on each side — 1em of forced growth per wrap — without changing what's visually drawn.
+
+**KaTeX** (verified — `\raisebox` only accepts a text-mode argument, so the phantom must be re-entered as math and forced to `\displaystyle`; without that it silently shrinks to inline size and the trick does nothing):
+
+```latex
+\newcommand{\grow}[1]{#1\raisebox{0.5em}{$\displaystyle\vphantom{#1}$}\raisebox{-0.5em}{$\displaystyle\vphantom{#1}$}}
+```
+
+**MathJax** (verified — `\raisebox` doesn't exist here; plain-TeX `\raise`/`\lower` take a math argument directly and preserve the current style):
+
+```latex
+\newcommand{\grow}[1]{#1\raise{0.5em}{\vphantom{#1}}\lower{0.5em}{\vphantom{#1}}}
+```
+
+**Usage** — wrap the content of every bracket pair except the innermost:
+
+```latex
+\left[ \grow{ \left[ \sqrt{\frac{\int\limits_0^{10}\sqrt{a^2+b^2}}{2}} \right] + 1 } \right]
+```
+
+Verified by rendering with real KaTeX 0.18.7 and MathJax 3.2.2 (headless Chromium screenshots): both show strictly increasing bracket sizes across 2–3 nesting levels, matching the pdfLaTeX reference.
+
+**Trade-offs:**
+- Manual — you place `\grow{}` yourself at each level; it isn't automatic like the LaTeX-engine setting.
+- The two spellings aren't interchangeable: `\raisebox` errors out in MathJax, `\raise`/`\lower` don't exist in KaTeX. Pick the one matching your renderer.
+- Can be defined once (in MathJax's `tex.macros` config, or KaTeX's `macros` render option) so you only write `\grow{...}` per formula, not the full definition each time.
+
+## Solution 2: patch KaTeX directly (better fit for a site you build/host yourself)
+
+Since you control the build (an Astro site rendering KaTeX server-side), you don't need the macro workaround at all — you can restore the actual `\delimitershortfall` behavior by editing the one place KaTeX hard-codes it.
+
+**The code.** KaTeX's delimiter-sizing function (`makeLeftRightDelim`, in the compiled bundle since no per-file TS source ships in the npm package) contains:
+
+```js
+const delimiterFactor = 901;                                   // TeX's \delimiterfactor
+const delimiterExtend = 5.0 / options.fontMetrics().ptPerEm;   // TeX's \delimitershortfall = 5pt
+```
+
+This is the exact same formula from the TeXbook rule above, with the same two constants. Changing `5.0` to `-1.0` is precisely `\delimitershortfall=-1pt` — `delimiterFactor` doesn't need to change, since a negative shortfall always makes the second term of the `max(...)` dominate anyway.
+
+**Verified:** I applied this one-line edit to the installed `katex` package and rendered plain, unmodified `\left[...\right]` source (no `\grow` macro anywhere) through the patched build. Result: strict growth across 4 nesting levels, small content (`(x)`, `((x))`, `(((x)))`) unaffected, and — critically — the LaTeX source embedded in KaTeX's output for copy/paste (`<annotation encoding="application/x-tex">`) stays exactly what you typed, since only the *sizing*, not the *content*, is touched.
+
+**Where the line lives** (npm package, KaTeX 0.16.47):
+
+| File | Used by | Patched here |
+|---|---|---|
+| `src/delimiter.ts` | the readable source the bundles are built from | yes |
+| `dist/katex.mjs` | ESM import — what an Astro/Vite build resolves to | yes |
+| `dist/katex.js` | CJS `require` | yes |
+| `dist/katex.min.js` | only if KaTeX is also loaded client-side via `<script>` | **no** — see below |
+
+`dist/katex.min.js` is left alone on purpose. explico renders every formula at
+build time and ships only `katex.min.css` plus fonts to the browser, so nothing
+here loads that bundle — and because it is a single ~270 KB line, including it
+turns a 2 KB patch into a 550 KB one that no reviewer can read and no KaTeX
+upgrade can rebase. A course that *does* render KaTeX in the browser has to
+patch it too; the minified form of the same line is
+`l=5/n.fontMetrics().ptPerEm` inside `makeLeftRightDelim`.
+
+## How this repo applies it
+
+A `pnpm patch` would work, and is what the section above describes, but it is
+**project-local**: pnpm records it in the consuming repo's
+`pnpm-workspace.yaml`, so it cannot travel inside the published `explico`
+package. Every downstream course would have to reapply it, and a course that
+forgot would render flat nests while its linter told authors the engine handled
+sizing. Documenting that in a migration guide only narrows the window for the
+mistake; it does not close it.
+
+So the engine does the same edit in code, at import time, in
+[`src/reference/katex-delimiters.mjs`](../src/reference/katex-delimiters.mjs):
+
+1. read KaTeX's own ESM bundle off disk (`katex/dist/katex.mjs`);
+2. rewrite that one constant, throwing if it is not found verbatim;
+3. `import()` the rewritten source as a `data:` URL — the bundle has no imports
+   of its own, so it needs no base to resolve against;
+4. move `render`, `renderToString`, `__renderToDomTree` and
+   `__renderToHTMLTree` onto the shared `katex` object every consumer in the
+   process already imported;
+5. render a known nest and throw unless the sizes actually grew.
+
+Step 4 is what makes it reach lesson-body math. `rehype-katex` does its own
+`import katex from 'katex'`, but it calls `katex.renderToString(...)` — a
+property read at call time — and KaTeX's default export is a plain mutable
+object. Replacing the function on that object is therefore enough; the plugin
+does not have to be forked or aliased.
+
+**A course inherits this with no changes.** `astro.config.mjs` already imports
+`createNotationKatexOptions` from `explico/reference/katex-options.mjs`, and
+that module imports the installer for its side effect, so the sizing is in
+place before Astro renders anything. The engine's own non-Astro paths
+(`math-glyphs.mjs`, `render-lab-math.ts`, and therefore `validate:content`)
+import it directly.
+
+**It cannot fail quietly.** Steps 2 and 5 throw. A KaTeX upgrade that moves the
+constant, or anything that renders before the installer runs, stops the build
+with an explicit message instead of silently reverting to stock spacing — which
+is the failure mode a patch file plus a migration note could not rule out.
+
+**Trade-offs.** It is a monkey-patch of a third-party module object, so it
+rests on three upstream properties: the constant is a literal in the shipped
+bundle, the bundle is self-contained, and the default export is mutable. All
+three are asserted at install time rather than assumed. It also holds a second
+copy of the KaTeX module in memory (~600 KB of source, ~50 ms to load) for the
+duration of a build, which is not worth optimising away.
+
+## Why the patch is the better fit here
+
+Your original idea — keep writing `\left[` everywhere, run a build-time preprocessing step that inserts `\grow{}` at each nesting level, then swap in the original source for a "copy" button — would work, but has two costs the patch avoids:
+
+1. **The preprocessor needs a real TeX parser**, not a regex. It has to track bracket nesting depth correctly across `\text{...}`, comments, `\right.` (null right delimiters), and — critically — macros. If you ever define something like `\norm{...}` that *expands* to `\left\lVert...\right\rVert`, a source-level preprocessor can't see the nesting hidden inside the macro and will miscount levels. The patch operates after macro expansion, inside KaTeX's own layout engine, so it can't miss anything.
+2. **The copy-button problem disappears.** KaTeX already embeds your literal input in the hidden MathML `<annotation>` tag — that's what the standard `copy-tex` extension reads. With preprocessing, that annotation would contain the `\grow`-polluted string, so you'd have to intercept the copy handler and substitute the original text yourself. With the patch, the *displayed* math and the *embedded source* never diverge in the first place, because nothing was ever inserted into the source.
+
+## Caveats
+
+- If your pipeline actually renders to **SVG** rather than HTML+CSS, you're using MathJax's `tex-svg` output, not KaTeX (KaTeX renders to HTML spans, not SVG). MathJax's stretchy-delimiter logic lives in the output stage rather than one constants block, so the equivalent patch would be far more invasive there — the `\grow` macro is the practical option for MathJax.
+- On an Astro build, KaTeX runs at build time (via `remark-math`/`rehype-katex` or similar) and only sends finished HTML + `katex.css` + fonts to the browser — the patched JS never ships to visitors, it only needs to be present in your build environment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Build-time engine for prerequisite-aware, notation-rigorous course content: one validated content model, a semantic notation/citation/equation system with a completeness gate, and a deterministic JSON manifest.",
   "type": "module",
   "license": "UNLICENSED",
@@ -30,6 +30,7 @@
     "README.md",
     "CHANGELOG.md",
     "docs/VERSIONING.md",
+    "docs/katex-bracket-scaling.md",
     "docs/authoring"
   ],
   "dependencies": {

package/src/compiler/cli.ts

@@ -49,6 +49,7 @@ import remarkNotation, {
 } from '../reference/remark-notation.mjs';
 import remarkShortNote from '../reference/remark-short-note.mjs';
 import type { DiagnosticSeverity } from '../reference/types';
+import type { EquationLink } from '../reference/gate-math';
 import type { Manifest, ManifestLesson } from './manifest';
 import { isLessonSlug, lessonIdFromSlug } from './lesson-derivation';
 
@@ -90,6 +91,13 @@ export 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;
 }
 
 function diagnosticSeverity(value: unknown): DiagnosticSeverity {
@@ -165,6 +173,9 @@ export function lessonDiagnostics(
       file: diagnostic.file,
       ...(diagnostic.line === undefined ? {} : { line: diagnostic.line }),
       ...(diagnostic.column === undefined ? {} : { column: diagnostic.column }),
+      ...(diagnostic.equation === undefined
+        ? {}
+        : { equation: diagnostic.equation }),
     });
   }
 
@@ -621,8 +632,18 @@ type DiagnosticRecord = Record<string, unknown> & {
   readonly line?: unknown;
   readonly column?: unknown;
   readonly source?: unknown;
+  readonly equation?: unknown;
 };
 
+/** `{ key, href }` as it survives the untyped manifest walk above. */
+function equationLink(value: unknown): EquationLink | undefined {
+  if (value === null || typeof value !== 'object') return undefined;
+  const { key, href } = value as Record<string, unknown>;
+  return typeof key === 'string' && typeof href === 'string'
+    ? { key, href }
+    : undefined;
+}
+
 function numericLocation(value: unknown): number | undefined {
   return typeof value === 'number' && Number.isInteger(value) && value > 0
     ? value
@@ -685,6 +706,7 @@ export function contentDiagnostics(
           : typeof diagnostic.kind === 'string'
             ? diagnostic.kind
             : 'diagnostic';
+      const equation = equationLink(diagnostic.equation);
       diagnostics.push({
         code: `${group}:${detail}`,
         severity,
@@ -692,6 +714,7 @@ export function contentDiagnostics(
         ...(file === undefined ? {} : { file }),
         ...(line === undefined ? {} : { line }),
         ...(column === undefined ? {} : { column }),
+        ...(equation === undefined ? {} : { equation }),
       });
     }
   }

package/src/compiler/collections.ts

@@ -80,6 +80,32 @@ interface ParsedDocument {
   readonly data: Record<string, unknown>;
   /** Markdown body, byte-identical to the previous `gray-matter` output. */
   readonly body: string;
+  /**
+   * 1-based line *in the file* where {@link body} starts — the frontmatter
+   * block's height plus one. Every gate scans the body, so a finding's index
+   * is body-relative while the `file` it is reported against is not; without
+   * this offset a `file:line:column` diagnostic points at the wrong line (by
+   * the height of the frontmatter) and no editor can jump to it.
+   */
+  readonly bodyLine: number;
+}
+
+/**
+ * The line `body` starts on in `raw`. `parseFrontmatter` returns the body as a
+ * suffix of the file, so the offset is what precedes it; the `indexOf` branch
+ * is a guard for a future parser that normalizes the text rather than slicing.
+ */
+function bodyStartLine(raw: string, body: string): number {
+  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;
 }
 
 /**
@@ -87,11 +113,14 @@ interface ParsedDocument {
  * did not; strip it so body offsets in diagnostics are unchanged.
  */
 function parseDocument(path: string): ParsedDocument {
-  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 ?? {}) as Record<string, unknown>,
-    body: parsed.content.replace(/^\n/, ''),
+    body,
+    bodyLine: bodyStartLine(raw, body),
   };
 }
 
@@ -484,7 +513,7 @@ function notationLessonEntries(): NotationLessonInput[] {
   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({
@@ -495,6 +524,7 @@ function notationLessonEntries(): NotationLessonInput[] {
       ),
       references: extractNotationReferences(body, file, undefined),
       body,
+      bodyLine,
       source: { file },
     });
   }

package/src/compiler/logging.ts

@@ -130,6 +130,8 @@ export 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. */
@@ -157,16 +159,25 @@ export interface RunLog {
   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.
+ */
 export function diagnosticLine(diagnostic: AnyDiagnostic): string {
   const code = diagnostic.code ?? diagnostic.kind;
   const at = [diagnostic.file, diagnostic.line, diagnostic.column]
     .filter((part) => part !== undefined)
     .join(':');
   const prefix = code === undefined ? '' : `[${code}] `;
+  const equation =
+    diagnostic.equation === undefined
+      ? ''
+      : ` (eq:${diagnostic.equation.key} -> ${diagnostic.equation.href})`;
   return at === ''
-    ? `${prefix}${diagnostic.message}`
-    : `${prefix}${at}: ${diagnostic.message}`;
+    ? `${prefix}${diagnostic.message}${equation}`
+    : `${prefix}${at}: ${diagnostic.message}${equation}`;
 }
 
 export interface RunLogOptions {

package/src/compiler/manifest.ts

@@ -191,7 +191,7 @@ import {
  * from `warning` to `info`; their diagnostic codes and container fields stay
  * unchanged.
  */
-export const MANIFEST_SCHEMA_VERSION = 15;
+export const MANIFEST_SCHEMA_VERSION = 16;
 
 const REPOSITORY_ROOT = process.cwd();
 // Content is the top-level `content/` folder; the build output is `build/`

package/src/components/notation/NotationGlossary.astro

@@ -159,13 +159,19 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
               <NotationMath class="glossary-symbol" latex={entry.data.latex} />
             </span>
             <div>
-              <h2>
-                <a
-                  class="glossary-term-link"
-                  href={`#notation-${entry.data.key}`}
-                >
-                  {labelOf(entry.data)}
-                </a>
+              {/* The anchor is a sibling of the heading, not a child — the
+                  same shape `rehype-heading-anchors` gives a lesson heading.
+                  Inside the `h2` its `aria-label` joins the heading's
+                  accessible name ("Velocity Link to “Velocity”"). */}
+              <div class="glossary-heading">
+                <h2>
+                  <a
+                    class="glossary-term-link"
+                    href={`#notation-${entry.data.key}`}
+                  >
+                    {labelOf(entry.data)}
+                  </a>
+                </h2>
                 <a
                   class="glossary-anchor"
                   href={`#notation-${entry.data.key}`}
@@ -177,7 +183,7 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
                     </svg>
                   </span>
                 </a>
-              </h2>
+              </div>
               <code>{entry.data.key}</code>
             </div>
             <span class="glossary-status">{entry.data.editorialStatus}</span>
@@ -330,6 +336,11 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
     font-size: var(--sl-text-xl);
   }
 
+  .glossary-heading {
+    display: flex;
+    align-items: center;
+  }
+
   .glossary-term-link {
     color: inherit;
     text-decoration: none;
@@ -396,8 +407,8 @@ const panelDefinitions: NotationLayerDefinition[] = notationEntries.map(
       opacity: 0;
     }
 
-    h2:hover .glossary-anchor,
-    h2:focus-within .glossary-anchor,
+    .glossary-heading:hover .glossary-anchor,
+    .glossary-heading:focus-within .glossary-anchor,
     .glossary-anchor:focus-visible {
       opacity: 1;
     }