explico 0.7.0 → 0.8.0

package/src/components/notation/render-notation-math.ts

@@ -1,5 +1,8 @@
 import rehypeKatex from 'rehype-katex';
-import { createNotationKatexOptions } from '../../reference/katex-options.mjs';
+import {
+  createNotationKatexOptions,
+  trustNotationMarker,
+} from '../../reference/katex-options.mjs';
 import { NOTATION_KEY_PATTERN } from '../../reference/remark-notation.mjs';
 import {
   GlyphResolutionError,
@@ -81,32 +84,96 @@ const allowedTags = new Set([
   'line',
 ]);
 
+/**
+ * Every inert presentation attribute KaTeX's MathML builder can set, sorted.
+ *
+ * This list is deliberately KaTeX's whole surface rather than the attributes
+ * the corpus happens to have hit: anything missing here is a hard build error
+ * on valid, ordinary math, and the author has no way to work around it. `\Bigl`
+ * (`minsize`/`maxsize`), `\boxed` (`notation`), and `\colorbox`
+ * (`voffset`/`mathbackground`) each used to fail that way.
+ * `tests/notation/render-notation-math.test.ts` scans KaTeX's own
+ * `setAttribute` calls and fails when a release adds a name that is in neither
+ * this set nor {@link deniedAttributeNames}, so a KaTeX upgrade cannot quietly
+ * reintroduce the gap.
+ */
 const simpleAttributeNames = new Set([
   'accent',
   'accentunder',
   'columnalign',
+  'columnlines',
   'columnspacing',
+  'depth',
+  'display',
   'displaystyle',
   'fence',
   'height',
+  'largeop',
+  'linebreak',
+  'linethickness',
   'lspace',
+  'mathbackground',
+  'mathcolor',
+  'mathsize',
   'mathvariant',
+  'maxsize',
+  'minsize',
+  'notation',
   'preserveaspectratio',
+  'rowlines',
   'rowspacing',
   'rspace',
   'scriptlevel',
   'separator',
   'stretchy',
+  'valign',
   'viewbox',
+  'voffset',
   'width',
 ]);
 
-const safeAttributeValue = /^[ A-Za-z0-9+.,()\-/%]*$/;
+/**
+ * The attributes KaTeX can set that must never reach the page, each one a
+ * navigation or external-resource target: `href` (`\href`), `src`/`alt`
+ * (`\includegraphics`), and `title` (`\htmlTitle`). Every command that
+ * produces one already needs KaTeX's `trust` callback and is refused earlier by
+ * {@link unsafeExtensionCommand}, so this set is the second line — and the
+ * reason the completeness scan above can tell "KaTeX added an attribute nobody
+ * classified" apart from "we decided against this one".
+ */
+const deniedAttributeNames = new Set(['alt', 'href', 'src', 'title']);
+
+// `#` is here for `mathcolor` / `mathbackground` / a `background-color:` style,
+// which KaTeX writes as a hex literal. No attribute reaching this point can
+// carry a URL — `href` and `src` are denied above — so it opens no target.
+const safeAttributeValue = /^[ A-Za-z0-9+.,()\-/%#]*$/;
 const safeClassName = /^[A-Za-z0-9_-]+$/;
-const safeStyle = /^(?:[a-z-]+:[ A-Za-z0-9+.,()\-/%]*;)*$/;
+const safeDeclaration = /^\s*[a-z-]+:[ A-Za-z0-9+.,()\-/%#]*$/;
 const safePathData = /^[\sA-Za-z0-9+.,\-]*$/;
 const unsafeExtensionCommand =
   /\\(?:href|url|includegraphics|htmlClass|htmlData|htmlId|htmlStyle)\b/;
+// `\explain{key}{latex}` and `\slot{name}{latex}`, the two macros that expand
+// to a trusted `\htmlData` marker. Only the first argument is captured.
+const MARKER_MACRO = /\\(explain|slot)\{([^{}]*)\}/g;
+
+/**
+ * A declaration list KaTeX generated: inert properties only, and no
+ * `url(...)`/`expression(...)` to fetch or evaluate anything.
+ *
+ * Validated per declaration rather than with one regex over the whole string,
+ * because KaTeX does not always terminate the last one — `\vec` emits
+ * `style="width:0.471em"` with no trailing `;`, which a
+ * `(?:declaration;)*`-shaped pattern rejects outright.
+ */
+function isSafeStyle(value: string): boolean {
+  if (/(?:expression|url)\s*\(/i.test(value)) return false;
+  return value
+    .split(';')
+    .every(
+      (declaration) =>
+        declaration.trim().length === 0 || safeDeclaration.test(declaration),
+    );
+}
 
 function attributeValue(value: unknown, propertyName: string): string {
   if (typeof value === 'boolean') return String(value);
@@ -170,22 +237,27 @@ function safeProperties(
       continue;
     }
 
-    if (
-      name === 'style' &&
-      typeof value === 'string' &&
-      safeStyle.test(value) &&
-      !/(?:expression|url)\s*\(/i.test(value)
-    ) {
+    if (name === 'style') {
+      if (typeof value !== 'string' || !isSafeStyle(value)) {
+        throw new Error('Unsafe KaTeX style value.');
+      }
       properties.style = value;
       continue;
     }
 
-    if (name === 'd' && typeof value === 'string' && safePathData.test(value)) {
+    if (name === 'd') {
+      if (typeof value !== 'string' || !safePathData.test(value)) {
+        throw new Error('Unsafe KaTeX path data.');
+      }
       properties.d = value;
       continue;
     }
 
     const normalizedName = name.toLowerCase();
+    if (deniedAttributeNames.has(normalizedName)) {
+      throw new Error(`Disallowed KaTeX property: ${name}.`);
+    }
+
     if (simpleAttributeNames.has(normalizedName)) {
       const outputName =
         normalizedName === 'viewbox'
@@ -228,6 +300,34 @@ function sanitizeNode(node: HastNode): SafeMathNode {
 // this module already imports from `remark-notation.mjs`.
 export { stripNotationMarkers };
 
+/**
+ * Refuse a marker argument the trust callback would reject, before KaTeX sees
+ * it.
+ *
+ * KaTeX does not treat a denied `trust` as a parse error: it renders the
+ * command name in `errorColor` and carries on, so `\explain{Not A Key}{\Omega}`
+ * would otherwise reach a reader as red `\htmlData` text with the build still
+ * green. `\htmlData` itself is already refused by {@link
+ * unsafeExtensionCommand}, so the two marker macros are the only way into that
+ * callback and this check covers all of them. It asks
+ * {@link trustNotationMarker} rather than re-deriving the key patterns, so the
+ * answer here cannot drift from the answer KaTeX gets.
+ */
+function assertTrustedMarkers(latex: string): void {
+  for (const [, macro, argument] of latex.matchAll(MARKER_MACRO)) {
+    const attribute =
+      macro === 'explain' ? 'data-notation-key' : 'data-lab-slot';
+    if (
+      !trustNotationMarker({
+        command: '\\htmlData',
+        attributes: { [attribute]: argument },
+      })
+    ) {
+      throw new Error(`Notation LaTeX has an invalid \\${macro} key: ${argument}`);
+    }
+  }
+}
+
 /**
  * Render repository-authored LaTeX through the same build-time KaTeX adapter
  * as lesson math, then expose a constrained structured tree to Astro. No HTML
@@ -240,6 +340,7 @@ export function renderNotationMath(latex: string): readonly SafeMathNode[] {
   if (unsafeExtensionCommand.test(latex)) {
     throw new Error('Notation LaTeX cannot use a trust-requiring extension.');
   }
+  assertTrustedMarkers(latex);
 
   const root: HastRoot = {
     type: 'root',

package/src/components/starlight/AboutPanel.astro

@@ -12,6 +12,15 @@
  * It is a plain `<details>` disclosure: the browser gives keyboard toggle and
  * `aria-expanded` for free; the inline script only adds Escape-to-close and
  * outside-click-to-close.
+ *
+ * The panel also *publishes* the identity it displays: the `data-knowledge-*`
+ * and `data-engine-version` attributes carry the same values as the rendered
+ * text. A build check that wants to confirm the shipped page really carries the
+ * configured version would otherwise have to match the panel's prose and its
+ * `version · date` join, which pins a course's test to one version string and
+ * makes the check fail on every bump; a bare version substring is not even
+ * scoped to the panel, so the engine's own version elsewhere on the page can
+ * satisfy it. These attributes are exact, scoped, and stable across a bump.
  */
 import { loadManifest } from '../../compiler/manifest';
 
@@ -32,7 +41,13 @@ const knowledgeLine = knowledge.date
   : knowledge.version;
 ---
 
-<details class="about" data-about-panel>
+<details
+  class="about"
+  data-about-panel
+  data-knowledge-version={knowledge.version}
+  data-knowledge-date={knowledge.date}
+  data-engine-version={engine.version}
+>
   <summary
     class="about-toggle"
     aria-label={`About ${material.name}`}
@@ -47,7 +62,7 @@ const knowledgeLine = knowledge.date
     <dl class="about-facts">
       <div>
         <dt>Knowledge version</dt>
-        <dd>{knowledgeLine}</dd>
+        <dd data-knowledge-line>{knowledgeLine}</dd>
       </div>
       <div>
         <dt>Engine</dt>

package/src/reference/delimiter-size.ts

@@ -1,5 +1,11 @@
 /**
- * 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
@@ -7,8 +13,7 @@
  * a review-only authoring concern.
  */
 
-export const DELIMITER_SIZE_DIAGNOSTIC_CODE =
-  'delimiter-size-hierarchy' as const;
+export const DELIMITER_SIZE_DIAGNOSTIC_CODE = 'delimiter-manual-size' as const;
 
 export type DelimiterSizeName =
   | 'automatic'
@@ -18,7 +23,6 @@ export type DelimiterSizeName =
   | 'Bigg';
 
 export interface DelimiterSizeSuggestion {
-  readonly size: Exclude<DelimiterSizeName, 'automatic' | 'big'>;
   readonly open: string;
   readonly close: string;
   readonly latex: string;
@@ -30,9 +34,9 @@ export 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;
 }
 
@@ -62,7 +66,6 @@ interface DelimiterPair {
   readonly open: DelimiterToken;
   close?: DelimiterToken;
   readonly children: DelimiterPair[];
-  requiredRank?: number;
 }
 
 const SIZE_SPECS: readonly SizeSpec[] = [
@@ -114,10 +117,6 @@ const COMMAND_SPECS: readonly CommandSpec[] = SIZE_SPECS.flatMap((spec) => [
   { ...spec, command: spec.closeCommand, tokenKind: 'close' as const },
 ]).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: string,
   offset: number,
@@ -226,31 +225,22 @@ function lineAndColumn(
   };
 }
 
-function sizeName(rank: number): DelimiterSizeName {
-  return SUGGESTION_BY_RANK.get(rank)?.name ?? 'Bigg';
-}
+const SPEC_BY_SIZE = new Map(SIZE_SPECS.map((spec) => [spec.name, spec]));
 
-function suggestionFor(
-  pair: DelimiterPair,
-  requiredRank: number,
-): DelimiterSizeSuggestion | undefined {
-  const close = pair.close;
-  const spec = SUGGESTION_BY_RANK.get(requiredRank);
-  if (!close || !spec || spec.name === 'automatic' || spec.name === 'big') {
-    return undefined;
-  }
-  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}`,
-  };
+function suggestionFor(pair: DelimiterPair): DelimiterSizeSuggestion {
+  const open = `\\left${pair.open.delimiter}`;
+  const close = `\\right${pair.close?.delimiter ?? pair.open.delimiter}`;
+  return { open, close, latex: `${open} ... ${close}` };
 }
 
 /**
- * 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
@@ -261,41 +251,29 @@ export function lintDelimiterSizes(latex: string): DelimiterSizeDiagnostic[] {
   if (!roots) return [];
   const diagnostics: DelimiterSizeDiagnostic[] = [];
 
-  const assess = (pair: DelimiterPair): number => {
-    let largestNestedRequirement = 0;
-    let representativeNestedSize: DelimiterSizeName = '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: DelimiterPair, nested: boolean): void => {
+    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 as Exclude<DelimiterSizeName, 'automatic'>,
+        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);
 }

package/src/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/src/reference/gate-abbreviations.ts

@@ -25,7 +25,7 @@ import { collectOperators, collectRomanLabels } from './math-glyphs.mjs';
 import { isBaseAbbreviation } from './base-abbreviations.mjs';
 import { pageScope } from './gate-math';
 import type { MathGateDiagnostic, ScopeEntry } from './gate-math';
-import { lineOf, proseOnly } from './gate-prose-notation';
+import { lessonLine, proseOnly } from './gate-prose-notation';
 import type {
   AbbreviationDefinitionInput,
   NotationRegistryInput,
@@ -117,7 +117,7 @@ export 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/src/reference/gate-heading-length.ts

@@ -21,7 +21,7 @@
  */
 import { stripFencedCode } from './equations.mjs';
 import type { MathGateDiagnostic } from './gate-math';
-import { lineOf } from './gate-prose-notation';
+import { lessonLine } from './gate-prose-notation';
 import type { NotationLessonInput } from './types';
 
 export const HEADING_LENGTH_LIMIT = 65;
@@ -120,7 +120,7 @@ export function gateHeadingLength(
         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/src/reference/gate-math.ts

@@ -11,7 +11,11 @@
  * warnings and include a column when the math came from lesson/assessment text.
  */
 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';
 import { formulaGlyphScope, unknownFormulaScopeKeys } from './gloss';
 import type { GlyphScopeEntry } from './gloss';
@@ -21,6 +25,21 @@ import type {
   SharedNotationDefinitionInput,
 } from './types';
 
+/**
+ * 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.
+ */
+export 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;
+}
+
 export interface MathGateDiagnostic {
   readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation' | 'structure';
   /**
@@ -52,6 +71,8 @@ export 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;
 }
 
@@ -153,6 +174,25 @@ export function pageScope(
   return scope;
 }
 
+/**
+ * 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.
+ */
+export function equationLinkFor(
+  lessonId: string,
+  latex: string,
+): EquationLink | undefined {
+  EQ_LABEL_PATTERN.lastIndex = 0;
+  const match = EQ_LABEL_PATTERN.exec(latex);
+  EQ_LABEL_PATTERN.lastIndex = 0;
+  if (!match) return undefined;
+
+  const key = match[1];
+  const slug = lessonId.replace(/\./g, '/');
+  return { key, href: `/${slug}/#${equationAnchorId({ key })}` };
+}
+
 function resolveInto(
   latex: string,
   scope: readonly ScopeEntry[],
@@ -162,7 +202,9 @@ function resolveInto(
   column: number | undefined,
   fix: string,
   out: MathGateDiagnostic[],
+  equation?: EquationLink,
 ): void {
+  const at = equation === undefined ? {} : { equation };
   for (const diagnostic of lintDelimiterSizes(latex)) {
     const locatedLine =
       line === undefined ? undefined : line + diagnostic.line - 1;
@@ -179,6 +221,7 @@ function resolveInto(
       file,
       ...(locatedLine === undefined ? {} : { line: locatedLine }),
       ...(locatedColumn === undefined ? {} : { column: locatedColumn }),
+      ...at,
       message: diagnostic.message,
     });
   }
@@ -209,6 +252,7 @@ function resolveInto(
       file,
       line,
       token,
+      ...at,
       message: `Unresolved notation ${JSON.stringify(token)} in ${context} math. ${fix}`,
     });
   }
@@ -307,16 +351,20 @@ export function gateContentMath(input: {
     const scope = pageScope(lesson, sharedByKey);
     const file = lesson.source.file;
 
+    // `mathSpans` indexes the body, which starts after the frontmatter, so
+    // every span line is short by the frontmatter's height until corrected.
+    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,
+        equationLinkFor(lesson.lessonId, span.latex),
       );
     }
 

package/src/reference/gate-prose-notation.ts

@@ -71,6 +71,20 @@ export function lineOf(text: string, index: number): number {
   return text.slice(0, index).split('\n').length;
 }
 
+/**
+ * {@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.
+ */
+export function lessonLine(
+  lesson: { readonly body: string; readonly bodyLine?: number },
+  index: number,
+): number {
+  return lineOf(lesson.body, index) + (lesson.bodyLine ?? 1) - 1;
+}
+
 // Symbolic/abbreviated unit tokens that must be typeset in `$…$`, longest
 // first so the alternation can't match a prefix of a longer unit.
 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`;
@@ -178,7 +192,7 @@ export function gateProseNotation(
         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,
       });