explico 0.7.0 → 0.8.0

package/dist/reference/gate-math.js

@@ -1,5 +1,9 @@
 import { resolveMathGlyphs, GlyphResolutionError } from "./math-glyphs.mjs";
-import { stripEquationLabels } from "./equations.mjs";
+import {
+  EQ_LABEL_PATTERN,
+  equationAnchorId,
+  stripEquationLabels
+} from "./equations.mjs";
 import { lintDelimiterSizes } from "./delimiter-size.js";
 import { formulaGlyphScope, unknownFormulaScopeKeys } from "./gloss.js";
 const SEVERITY = {
@@ -58,7 +62,17 @@ function pageScope(lesson, sharedByKey) {
   }
   return scope;
 }
-function resolveInto(latex, scope, context, file, line, column, fix, out) {
+function equationLinkFor(lessonId, latex) {
+  EQ_LABEL_PATTERN.lastIndex = 0;
+  const match = EQ_LABEL_PATTERN.exec(latex);
+  EQ_LABEL_PATTERN.lastIndex = 0;
+  if (!match) return void 0;
+  const key = match[1];
+  const slug = lessonId.replace(/\./g, "/");
+  return { key, href: `/${slug}/#${equationAnchorId({ key })}` };
+}
+function resolveInto(latex, scope, context, file, line, column, fix, out, equation) {
+  const at = equation === void 0 ? {} : { equation };
   for (const diagnostic of lintDelimiterSizes(latex)) {
     const locatedLine = line === void 0 ? void 0 : line + diagnostic.line - 1;
     const locatedColumn = column === void 0 ? void 0 : diagnostic.line === 1 ? column + diagnostic.column - 1 : diagnostic.column;
@@ -69,6 +83,7 @@ function resolveInto(latex, scope, context, file, line, column, fix, out) {
       file,
       ...locatedLine === void 0 ? {} : { line: locatedLine },
       ...locatedColumn === void 0 ? {} : { column: locatedColumn },
+      ...at,
       message: diagnostic.message
     });
   }
@@ -92,6 +107,7 @@ function resolveInto(latex, scope, context, file, line, column, fix, out) {
       file,
       line,
       token,
+      ...at,
       message: `Unresolved notation ${JSON.stringify(token)} in ${context} math. ${fix}`
     });
   }
@@ -156,16 +172,18 @@ function gateContentMath(input) {
   for (const lesson of notationInput.lessons) {
     const scope = pageScope(lesson, sharedByKey);
     const file = lesson.source.file;
+    const bodyOffset = (lesson.bodyLine ?? 1) - 1;
     for (const span of mathSpans(lesson.body)) {
       resolveInto(
         span.latex,
         scope,
         "body",
         file,
-        span.line,
+        span.line + bodyOffset,
         span.column,
         BODY_FIX,
-        diagnostics
+        diagnostics,
+        equationLinkFor(lesson.lessonId, span.latex)
       );
     }
     for (const definition of lesson.localDefinitions) {
@@ -243,6 +261,7 @@ function gateContentMath(input) {
   return diagnostics;
 }
 export {
+  equationLinkFor,
   gateContentMath,
   pageScope
 };

package/dist/reference/gate-prose-notation.d.ts

@@ -39,6 +39,17 @@ interface AssessmentLike {
 declare function proseOnly(body: string): string;
 /** Exported for the same reason as {@link proseOnly}. */
 declare function lineOf(text: string, index: number): number;
+/**
+ * {@link lineOf} corrected to the file the lesson came from. A gate scans
+ * `lesson.body`, which starts *after* the frontmatter, so a raw body line is
+ * short by the frontmatter's height and points at the wrong source line —
+ * silently, because the number is still plausible. Every gate that reports a
+ * `line` against `lesson.source.file` must go through this.
+ */
+declare function lessonLine(lesson: {
+    readonly body: string;
+    readonly bodyLine?: number;
+}, index: number): number;
 /**
  * Scan every lesson body for plain-text math notation outside `$…$`. Returns
  * one `MathGateDiagnostic` (context `'prose'`, always an error — N9 has no
@@ -57,4 +68,4 @@ declare function gateProseNotation(lessons: readonly NotationLessonInput[]): Mat
  */
 declare function gateProseNotationInAssessments(assessments: readonly AssessmentLike[]): MathGateDiagnostic[];
 
-export { gateProseNotation, gateProseNotationInAssessments, lineOf, proseOnly };
+export { gateProseNotation, gateProseNotationInAssessments, lessonLine, lineOf, proseOnly };

package/dist/reference/gate-prose-notation.js

@@ -12,6 +12,9 @@ function proseOnly(body) {
 function lineOf(text, index) {
   return text.slice(0, index).split("\n").length;
 }
+function lessonLine(lesson, index) {
+  return lineOf(lesson.body, index) + (lesson.bodyLine ?? 1) - 1;
+}
 const UNIT = String.raw`m/s²|m/s|km/h|rad/s|m²/s²|J/kg|m²|s⁻¹|kg|N|J|W|Hz|deg|°|rad|m|s`;
 const NUMERAL_UNIT = new RegExp(
   String.raw`(?<![\w.])-?\d+(?:\.\d+)?\s?(?:${UNIT})(?![A-Za-z])`,
@@ -89,7 +92,7 @@ function gateProseNotation(lessons) {
         context: "prose",
         severity: "error",
         file: lesson.source.file,
-        line: lineOf(lesson.body, finding.index),
+        line: lessonLine(lesson, finding.index),
         token: finding.token,
         message: finding.message
       });
@@ -120,6 +123,7 @@ function gateProseNotationInAssessments(assessments) {
 export {
   gateProseNotation,
   gateProseNotationInAssessments,
+  lessonLine,
   lineOf,
   proseOnly
 };

package/dist/reference/katex-delimiters.d.mts

@@ -0,0 +1,15 @@
+/**
+ * Exported for the test that pins both failure messages — a KaTeX upgrade that
+ * moves the constant, and a leftover `patches/` file, are the two ways this
+ * stops being able to install itself.
+ */
+export function rewriteBundle(source: any): any;
+/**
+ * Render a known nest and confirm the outer pair really is larger than the
+ * inner one. Cheap, and it turns every way this could go wrong — an upstream
+ * refactor, a frozen export, an import that beat us to it — into one loud
+ * failure at the point of installation.
+ */
+export function assertDelimiterGrowth(instance?: typeof katex): void;
+export default katex;
+import katex from 'katex';

package/dist/reference/katex-delimiters.mjs

@@ -0,0 +1,125 @@
+/**
+ * Rule N17's engine half: make `\left`/`\right` grow strictly outward.
+ *
+ * Importing this module for its side effect installs a KaTeX whose
+ * `\delimitershortfall` is `-1pt` instead of the stock `5pt`, so a scalable
+ * delimiter pair is always *strictly* taller than what it wraps and nesting
+ * depth shows up on its own. See `docs/katex-bracket-scaling.md` for the
+ * derivation and `docs/authoring/notation.md#n17` for the authoring rule.
+ *
+ * ## Why this is not a `patches/` file
+ *
+ * `delimiterExtend` is a function-local `const` inside `makeLeftRightDelim`.
+ * Nothing KaTeX exports reaches it — `__defineMacro`, `__defineFunction`,
+ * `__defineSymbol`, `__setFontMetrics` and the settings schema all sit above
+ * the layout engine — so the constant can only be changed in the module's own
+ * source. A `pnpm patch` does that, but a patch is project-local: it cannot
+ * travel inside the published `explico` artifact, so every downstream course
+ * would have to reapply it or silently render flat nests.
+ *
+ * So the engine does it in code instead. It reads KaTeX's own ESM bundle,
+ * rewrites that one constant, imports the result as a module, and moves the
+ * rendering entry points onto the shared `katex` object every consumer in the
+ * process already imported. KaTeX's default export is a plain mutable object
+ * and `rehype-katex` reads `katex.renderToString` at call time, so the swap
+ * reaches lesson-body math without forking the plugin.
+ *
+ * ## Why this is safe to rely on
+ *
+ * The assumptions above (a matching constant, a mutable export, a bundle with
+ * no imports of its own) are all checked here, and `assertDelimiterGrowth()`
+ * renders a known nest afterwards and throws when the sizes do not actually
+ * increase. A course therefore either renders with engine-sized delimiters or
+ * fails its build saying so — it cannot quietly get the stock behaviour.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import katex from 'katex';
+
+/** TeX's `\delimitershortfall`, in points, as KaTeX hard-codes it. */
+const STOCK_SHORTFALL = '5.0';
+/** The negative shortfall that forces strict outward growth. */
+const GROWN_SHORTFALL = '-1.0';
+
+const needle = (points) =>
+  `var delimiterExtend = ${points} / options.fontMetrics().ptPerEm;`;
+
+/** The entry points that build a delimiter and must come from the rewrite. */
+const RENDER_EXPORTS = [
+  'render',
+  'renderToString',
+  '__renderToDomTree',
+  '__renderToHTMLTree',
+];
+
+/**
+ * Exported for the test that pins both failure messages — a KaTeX upgrade that
+ * moves the constant, and a leftover `patches/` file, are the two ways this
+ * stops being able to install itself.
+ */
+export function rewriteBundle(source) {
+  const stock = needle(STOCK_SHORTFALL);
+  if (!source.includes(stock)) {
+    // Either the constant moved or someone already rewrote it. Both mean the
+    // assumption this module rests on no longer holds for this KaTeX build.
+    const alreadyGrown = source.includes(needle(GROWN_SHORTFALL));
+    throw new Error(
+      alreadyGrown
+        ? `explico: katex ${katex.version} already carries the -1pt delimiter ` +
+          'shortfall (a patches/ file?). Remove that patch — the engine ' +
+          'installs it in code (src/reference/katex-delimiters.mjs).'
+        : `explico: cannot install the N17 delimiter sizing into katex ` +
+          `${katex.version}: the \\delimitershortfall constant ` +
+          `(${stock}) is not in its ESM bundle. Re-derive the one-line ` +
+          'change against the new bundle — see docs/katex-bracket-scaling.md.',
+    );
+  }
+  return source.replace(stock, needle(GROWN_SHORTFALL));
+}
+
+async function loadGrownKatex() {
+  const require = createRequire(import.meta.url);
+  const source = readFileSync(require.resolve('katex/dist/katex.mjs'), 'utf8');
+  // The bundle is self-contained, so it can be re-imported from a data URL
+  // with no base to resolve relative specifiers against.
+  const rewritten = rewriteBundle(source);
+  const module = await import(
+    `data:text/javascript;base64,${Buffer.from(rewritten).toString('base64')}`
+  );
+  return module.default;
+}
+
+/**
+ * Render a known nest and confirm the outer pair really is larger than the
+ * inner one. Cheap, and it turns every way this could go wrong — an upstream
+ * refactor, a frozen export, an import that beat us to it — into one loud
+ * failure at the point of installation.
+ */
+export function assertDelimiterGrowth(instance = katex) {
+  const html = instance.renderToString(
+    String.raw`\left[1+\left(\frac{a}{b}\right)\right]`,
+    { displayMode: true, output: 'html' },
+  );
+  const sizes = [...html.matchAll(/delimsizing size(\d)/g)].map((m) =>
+    Number(m[1]),
+  );
+  // Two pairs, so four glyphs: outer, inner, inner, outer.
+  const grew = sizes.length === 4 && sizes[0] > sizes[1];
+  if (!grew) {
+    throw new Error(
+      'explico: the N17 delimiter sizing did not take effect — a nested ' +
+        `\\left…\\right pair rendered as [${sizes.join(', ')}] instead of ` +
+        'growing outward. Something rendered math before ' +
+        "'explico/reference/katex-delimiters.mjs' was imported, or katex " +
+        'changed shape. See docs/katex-bracket-scaling.md.',
+    );
+  }
+}
+
+const grown = await loadGrownKatex();
+for (const name of RENDER_EXPORTS) {
+  if (typeof grown[name] === 'function') katex[name] = grown[name];
+}
+assertDelimiterGrowth();
+
+export default katex;

package/dist/reference/katex-options.mjs

@@ -1,3 +1,7 @@
+// Side-effect import: installs rule N17's delimiter sizing onto the shared
+// `katex` module before anything renders. A course wires this file into its
+// `astro.config.mjs`, so `rehype-katex` inherits it without a patch.
+import './katex-delimiters.mjs';
 import { NOTATION_KEY_PATTERN } from './remark-notation.mjs';
 
 export const EXPLAIN_MACRO = String.raw`\htmlData{notation-key=#1}{#2}`;

package/dist/reference/math-glyphs.mjs

@@ -1,4 +1,4 @@
-import katex from 'katex';
+import katex from './katex-delimiters.mjs';
 
 import { BASE_LIBRARY } from './base-library.mjs';
 import { PARENTHESIZED_FUNCTIONS } from './base-operators.mjs';
@@ -386,6 +386,19 @@ function trimTrailingWhitespace(latex, start, end) {
   return trimmed;
 }
 
+/**
+ * KaTeX gives a node it produced by expanding a macro a `loc` from the lexer
+ * over the *macro body*, not over the source being scanned: `\vdots` expands
+ * to `{\varvdots\rule{0pt}{15pt}}`, and its `\varvdots` atom arrives with
+ * `loc.start = 1`, `loc.end = 10` — offsets into that 27-character body.
+ * Those numbers are valid indices into any longer source, so they read as a
+ * real span pointing at unrelated text. Every `loc` therefore has to prove it
+ * belongs to the string this pass parsed before its offsets are believed.
+ */
+function isAuthoredLocation(loc, latex) {
+  return loc?.lexer?.input === latex;
+}
+
 function nodeSpan(node, latex) {
   let start = Number.POSITIVE_INFINITY;
   let end = Number.NEGATIVE_INFINITY;
@@ -397,7 +410,8 @@ function nodeSpan(node, latex) {
     if (
       value.loc &&
       Number.isInteger(value.loc.start) &&
-      Number.isInteger(value.loc.end)
+      Number.isInteger(value.loc.end) &&
+      isAuthoredLocation(value.loc, latex)
     ) {
       start = Math.min(start, value.loc.start);
       end = Math.max(end, value.loc.end);

package/dist/reference/render-lab-math.js

@@ -1,4 +1,4 @@
-import katex from "katex";
+import katex from "./katex-delimiters.mjs";
 import { resolveMathGlyphs, stripNotationMarkers } from "./math-glyphs.mjs";
 import { createNotationKatexOptions } from "./katex-options.mjs";
 function slotPlaceholder(name) {

package/dist/reference/types.d.ts

@@ -78,6 +78,13 @@ interface NotationLessonInput {
     readonly references: readonly NotationReferenceInput[];
     /** Original lesson body, retained for lossless loader adapters. */
     readonly body: string;
+    /**
+     * 1-based line in `source.file` where `body` starts. Gates scan the body, so
+     * every finding's index is body-relative; this is what turns one into a real
+     * location in the file. Optional so a hand-built input (a test, an adapter)
+     * stays valid — it then behaves as 1, the pre-0.7.1 behavior.
+     */
+    readonly bodyLine?: number;
     readonly source: SourceSpan;
 }
 interface NotationRegistryInput {

package/docs/authoring/README.md

@@ -106,7 +106,7 @@ file table.
 | [N14](notation.md#n14)          | An abbreviation-shaped word in prose is universal, or explained    | Build-enforced (`gate-abbreviations.ts`)    |
 | [N15](notation.md#n15)          | A nested `(`, `[`, `{`, or `\|` must use scalable sizing            | Build-enforced (`resolveMathGlyphs`)        |
 | [N16](notation.md#n16)          | AI-generated stylistic grouping alternates delimiter types           | Review-only                                 |
-| [N17](notation.md#n17)          | Nested scalable delimiters grow strictly from inside to outside      | Tier-3 warning (`delimiter-size-hierarchy`) |
+| [N17](notation.md#n17)          | A nested delimiter is sized by the engine, never by hand             | Tier-3 warning (`delimiter-manual-size`)    |
 | [V1](visualizations.md#v1)      | Graphs and flowcharts use the `Diagram` component                 | Review-only                                 |
 | [V2](visualizations.md#v2)      | Static charts: SVG → D3 → Observable Plot, chosen per figure       | Review-only                                 |
 | [V3](visualizations.md#v3)      | Interactive figures: island + `renderLabMath` seam + text alt      | Review-only                                 |

package/docs/authoring/migrating.md

@@ -33,6 +33,234 @@ required config block throws with the section of this file to read.
 
 ---
 
+## 0.7.0 → 0.8.0
+
+### 1. Rule N17 is inverted: delimiters are sized by the engine (`\left`/`\right` everywhere)
+
+The engine now installs its own KaTeX delimiter sizing, so a `\left … \right`
+pair is always strictly taller than its content and a nest shows its depth
+without help. Hand-picking `\bigl` → `\Bigl` → `\biggl` → `\Biggl` outward —
+which rule N17 previously *required* — is now the thing the linter warns about.
+
+**There is no install step.** `astro.config.mjs` already imports
+`explico/reference/katex-options.mjs`, and that module now imports
+`explico/reference/katex-delimiters.mjs` for its side effect. Confirm the import
+is still there; a course that inlined its own KaTeX options object instead must
+add, as the **first** import in `astro.config.mjs`:
+
+```js
+import 'explico/reference/katex-delimiters.mjs';
+```
+
+Order matters: the installer moves KaTeX's render entry points onto the shared
+`katex` object, so anything that renders math before the import would keep stock
+spacing. It refuses to fail quietly — it renders a known nest at install time and
+throws if the sizes did not grow.
+
+Two course-side conditions make the build throw, both with an explicit message:
+
+- **A `patches/katex@*.patch` file that already applies a negative
+  `\delimitershortfall`.** Delete the patch and its `pnpm.patchedDependencies`
+  entry; the engine does this in code now, and a patch is project-local anyway
+  so it never reached a consumer.
+- **A `katex` whose bundle no longer holds the constant where the engine looks
+  for it.** The rewrite targets one line in KaTeX's ESM bundle, so keep `katex`
+  on the declared peer version (`0.16.47`). An upgrade that moves or reformats
+  that line fails the build asking you to re-derive the change against
+  [`../katex-bracket-scaling.md`](../katex-bracket-scaling.md), which is
+  shipped in the package. The failure is loud and immediate, not a silent
+  return to stock spacing.
+
+### 2. Diagnostic renamed: `delimiter-size-hierarchy` → `delimiter-manual-size`
+
+The old code string no longer exists. Update every place that names it:
+
+- `lint-ignore.yml` — a stale line is inert and silently stops suppressing.
+- Course scripts, tests, and type narrowings over the diagnostic union;
+  `astro check` flags a comparison against a non-member.
+
+Its payload changed shape too. A consumer reading the fields, rather than just
+the `code` and `message`, needs this edit:
+
+```diff
+-// outerSize / nestedSize described the mismatch between two levels
+-const found = diagnostic.outerSize;
+-const suggested = diagnostic.suggestion?.size;
++// `size` is the hand-picked size found; `suggestion` is always present and is
++// always a \left/\right pair, so it no longer carries a `size` of its own.
++const found = diagnostic.size;
++const suggested = diagnostic.suggestion.latex;
+```
+
+`DelimiterSizeSuggestion` keeps `open`, `close`, and `latex`, and drops `size`.
+`DelimiterSizeDiagnostic` drops `outerSize` and `nestedSize`, gains a required
+`size`, and `suggestion` is no longer optional.
+
+### 3. Content: hand-sized nests now warn
+
+Math that was N17-compliant under 0.7.0 reports one `delimiter-manual-size`
+finding per hand-sized level. This is a Tier-3 warning — it does not fail a
+build — so it can be worked through at your own pace, but the findings are real
+and the repair improves the rendering.
+
+Find them with:
+
+```
+pnpm content warnings --json
+```
+
+The repair is mechanical: replace the hand-picked pair with `\left`/`\right`,
+keeping the delimiter shapes.
+
+```diff
+-\Biggl[a+\biggl(b+\Bigl[c+\left(d+e\right)\Bigr]\biggr)\Biggr]
++\left[a+\left(b+\left[c+\left(d+e\right)\right]\right)\right]
+```
+
+A **lone** hand-sized pair that is not part of a nest — `\bigl(x,\ y\bigr)`
+around a tuple, for instance — is a single-level typographic choice with no
+hierarchy to get wrong, and is deliberately left alone. Do not convert those.
+
+Expect a small visual change everywhere a nest is rendered: each level is now
+strictly larger than the one inside it, so outer delimiters grow by roughly one
+size step. A course holding screenshot or bounding-box baselines over math
+should re-record them.
+
+### 4. Manifest schema is now v16: a math diagnostic can name its equation
+
+`MANIFEST_SCHEMA_VERSION` is 16 (v15 → v16). The bump is **additive** — nothing
+existing changed shape — so the only required edit is to a client that asserts
+the number by exact equality, which now expects 16.
+
+What was added: a finding the math gate reports from a `$$…$$` block carrying a
+`\label{eq:…}` gains an optional `equation` field, `{ key, href }`. `href` is
+the rendered page's anchor for that equation
+(`/l1-ar/ar1-basics/#eq-ar1-variance`). `CliDiagnostic` carries the same
+optional field, so a course's own `scripts/content.ts` picks it up with no
+change.
+
+`diagnosticLine()` now appends it, so console output, the run log, and
+`pnpm content diagnostics` read:
+
+```
+[code] file:line:column: message (eq:<key> -> <href>)
+```
+
+A course script that parses that line with an anchored regex must tolerate the
+optional trailing ` (eq:… -> …)`. One that just prints the string needs nothing.
+
+### 5. Diagnostic line numbers are corrected — re-record anything that stored them
+
+Every gate scans the lesson body, which Astro hands over with the frontmatter
+already stripped, but findings are reported against the lesson *file* — so every
+`file:line:column` the engine has emitted for a lesson was short by the height
+of that lesson's frontmatter. `gate-math` (every `delimiter-manual-size`
+column), `gate-prose-notation` (rule N9), `gate-abbreviations` (rule N14), and
+`gate-heading-length` (S1) are all corrected at once.
+
+Nothing to edit in content, but line numbers move, so:
+
+- Re-check any suppression, snapshot, or problem matcher keyed to a line number.
+  Line numbers were wrong before; they now point at the real line.
+- `pnpm validate:content` (twice) regenerates `build/resolution/*` with the
+  corrected positions. Commit the result.
+
+### 6. Malformed `\explain` / `\slot` keys now fail the build
+
+Previously a key that did not match the notation key pattern —
+`\explain{Not A Key}{\Omega}` — was not a KaTeX parse error: KaTeX rendered the
+command name in its error color and carried on, so the page shipped red
+`\htmlData` text with a green build. `renderNotationMath` now checks both marker
+macros before KaTeX runs and throws, naming the offending key.
+
+**This can newly fail a build that passed on 0.7.0.** If it does, the page was
+already broken for readers. Fix the key to match the notation key pattern
+(lower-case, hyphen-separated) and make sure it resolves to a real entry.
+`renderNotationFormula` still degrades to inert-but-correct math rather than
+costing a reader the equation.
+
+### 7. Glossary entry heading markup: the anchor is now a sibling of the `<h2>`
+
+The per-entry anchor link moved out of the `<h2>` and into a new
+`.glossary-heading` flex row wrapping both — the same shape
+`rehype-heading-anchors` gives a lesson heading. This restores the heading's
+accessible name (a screen reader was announcing "Velocity Link to Velocity").
+
+Nothing visual changed, but update course-owned CSS and end-to-end tests that
+assumed the nesting:
+
+```diff
+-h2:hover .glossary-anchor,
+-h2:focus-within .glossary-anchor {
++.glossary-heading:hover .glossary-anchor,
++.glossary-heading:focus-within .glossary-anchor {
+```
+
+A test locating the anchor as a descendant of the heading must target
+`.glossary-heading .glossary-anchor` instead. A check for the heading *by
+accessible name* now matches the term alone, which is the point of the fix — if
+such a test was written against the broken name ("Velocity Link to Velocity"),
+it needs the term.
+
+### 8. The About panel publishes its versions as data attributes
+
+Additive; no course edit is required. `details[data-about-panel]` now carries
+`data-knowledge-version`, `data-knowledge-date` (omitted when the content
+changelog has no date), and `data-engine-version`, and the rendered version line
+is marked `data-knowledge-line`.
+
+This exists so a build check does not have to match prose. A course asserting
+the panel's contents by text is pinned to one version string and turns every
+routine bump into a test edit — this repo's own `about.spec.ts` was asserting
+`0.4.0` against a playground long since past it. Prefer:
+
+```diff
+-await expect(panel).toContainText('0.6.0');
++await expect(panel).toHaveAttribute('data-knowledge-version', knowledgeVersion);
+```
+
+reading the expected value from `content/course.config.ts` rather than hard-coding
+it. A bare version substring is not scoped to the panel either — the engine
+version printed one row below can satisfy it.
+
+### 9. Fixes that need no action
+
+These remove build failures; they never require a content edit. Formulas you
+previously worked around may now be written directly.
+
+- **A notation `formula` can use a manual delimiter size, an accent, a box, or
+  a color.** `render-notation-math.ts`'s attribute allowlist is now KaTeX's
+  whole inert presentation surface, so `\Bigl`/`\biggl`/`\Biggl`,
+  `\xrightarrow`, `\boxed`, and `\colorbox` no longer throw
+  `Unexpected KaTeX property`. `alt`, `href`, `src`, and `title` are explicitly
+  denied; no attribute that can carry a URL is allowed through.
+- **`\vec` and every other accent renders.** The style sanitizer no longer
+  requires a trailing `;` on the last CSS declaration. `\mathbf` remains the
+  house style for a vector; `\vec` simply works now.
+- **A macro in a formula no longer invents a source span.** `\vdots`,
+  `\varSigma`, `\argmax`, `\bmod`, `\R`/`\N`/`\Z` and 79 of KaTeX's 282 macros
+  produce nodes whose `loc` indexes the macro body, which the glyph resolver
+  read as a span over unrelated text — failing with `Unresolved notation ""`,
+  or worse, silently splitting a formula mid-command. Fixed. An existing
+  explicit `\explain{key}{\varSigma}` annotation still works and is still the
+  way to bind a macro-expanded glyph, since it has no authored span for
+  canonical matching to see.
+- **`equationAnchorId({ key })` type-checks without a `number`.** Its JSDoc
+  required a property the function ignores when a `key` is given.
+
+### 10. Verify
+
+```
+pnpm add -D explico@0.8.0
+pnpm validate:content   # twice — the first run regenerates build/resolution/*
+pnpm content check --changed
+pnpm content warnings   # expect new delimiter-manual-size findings (item 3)
+astro check
+astro build
+```
+
+Commit the regenerated `build/resolution/*` (items 4 and 5 both change it).
+
 ## 0.6.0 → 0.7.0
 
 ### 1. Manifest schema is now v15: diagnostic severity has three levels