explico 0.6.0 → 0.8.0

package/src/reference/gate-math.ts

@@ -7,10 +7,16 @@
  * a single diagnostic shape; `astro build` re-runs the same resolver on the
  * render path as a backstop.
  *
- * Every failure names `file:line: "token"` and the fix.
+ * Every finding names its source and the fix. N17's size-only findings are
+ * 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';
 import type {
@@ -19,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';
   /**
@@ -45,9 +66,13 @@ export interface MathGateDiagnostic {
    * than adding a second array the CLI has to know about.
    */
   readonly severity: 'error' | 'warning';
+  readonly code?: string;
   readonly file: string;
   readonly line?: number;
+  readonly column?: number;
   readonly token?: string;
+  /** Present when the offending math carries a `\label{eq:…}`. */
+  readonly equation?: EquationLink;
   readonly message: string;
 }
 
@@ -92,6 +117,7 @@ function lineOf(text: string, index: number): number {
 interface MathSpan {
   readonly latex: string;
   readonly line: number;
+  readonly column: number;
 }
 
 function mathSpans(body: string): MathSpan[] {
@@ -101,10 +127,14 @@ function mathSpans(body: string): MathSpan[] {
     pattern.lastIndex = 0;
     let match: RegExpExecArray | null;
     while ((match = pattern.exec(searchable))) {
+      const latex = match[1] ?? '';
+      const latexOffset = match.index + match[0].indexOf(latex);
+      const before = body.slice(0, latexOffset);
+      const lastNewline = before.lastIndexOf('\n');
       spans.push({
-        // D7: `\label{eq:…}` is an identity marker, not math KaTeX parses.
-        latex: stripEquationLabels(match[1] ?? ''),
-        line: lineOf(body, match.index),
+        latex,
+        line: lineOf(body, latexOffset),
+        column: latexOffset - lastNewline,
       });
     }
   }
@@ -144,18 +174,62 @@ 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[],
   context: MathGateDiagnostic['context'],
   file: string,
   line: number | undefined,
+  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;
+    const locatedColumn =
+      column === undefined
+        ? undefined
+        : diagnostic.line === 1
+          ? column + diagnostic.column - 1
+          : diagnostic.column;
+    out.push({
+      context,
+      code: diagnostic.code,
+      severity: 'warning',
+      file,
+      ...(locatedLine === undefined ? {} : { line: locatedLine }),
+      ...(locatedColumn === undefined ? {} : { column: locatedColumn }),
+      ...at,
+      message: diagnostic.message,
+    });
+  }
+
   let result;
   try {
-    result = resolveMathGlyphs(latex, [...scope]);
+    // D7: `\label{eq:…}` is an identity marker, not math KaTeX parses.
+    result = resolveMathGlyphs(stripEquationLabels(latex), [...scope]);
   } catch (error) {
     out.push({
       context,
@@ -178,6 +252,7 @@ function resolveInto(
       file,
       line,
       token,
+      ...at,
       message: `Unresolved notation ${JSON.stringify(token)} in ${context} math. ${fix}`,
     });
   }
@@ -276,15 +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),
       );
     }
 
@@ -305,6 +385,7 @@ export function gateContentMath(input: {
         'formula',
         file,
         undefined,
+        undefined,
         FORMULA_FIX,
         diagnostics,
       );
@@ -330,6 +411,7 @@ export function gateContentMath(input: {
       'formula',
       definition.source.file,
       undefined,
+      undefined,
       SHARED_FORMULA_FIX,
       diagnostics,
     );
@@ -358,7 +440,8 @@ export function gateContentMath(input: {
               scope,
               'assessment',
               `${assessmentId} (${item.id ?? '?'})`,
-              undefined,
+              span.line,
+              span.column,
               ASSESSMENT_FIX,
               diagnostics,
             );

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,
       });

package/src/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/src/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/src/reference/keyed-float-validate.ts

@@ -7,7 +7,7 @@
  * - `<prefix>-duplicate-key` (error): an `id` is unique per lesson.
  * - `<prefix>-ref-resolves` (error): every `[[<prefix>-key]]` /
  *   `[[slug#<prefix>-key]]` points at the matching keyed float with that `id`.
- * - `<prefix>-key-unused` (warning): a keyed float never referenced.
+ * - `<prefix>-key-unused` (info): a keyed float is never referenced.
  *
  * `tables-validate.ts`, `figures-validate.ts`, and `diagrams-validate.ts` are
  * thin wrappers over this so callers import a kind-specific validator with
@@ -48,7 +48,7 @@ export interface KeyedFloatRefRecord {
 
 export interface KeyedFloatDiagnostic {
   readonly code: string;
-  readonly severity: 'error' | 'warning';
+  readonly severity: 'error' | 'warning' | 'info';
   readonly message: string;
   readonly file?: string;
   readonly lessonId?: string;
@@ -190,7 +190,7 @@ export function validateKeyedFloats(
     if (referenced.has(`${label.slug}#${label.key}`)) continue;
     diagnostics.push({
       code: `${prefix}-key-unused`,
-      severity: 'warning',
+      severity: 'info',
       message: `${label.lessonId} has a ${noun} id="${label.key}" (${label.number}) but nothing references it with [[${prefix}-${label.key}]]`,
       file: label.slug,
       lessonId: label.lessonId,

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

@@ -78,5 +78,6 @@ export function compareDiagnostics(
 }
 
 function severityRank(severity: NotationDiagnostic['severity']): number {
-  return severity === 'error' ? 0 : 1;
+  if (severity === 'error') return 0;
+  return severity === 'warning' ? 1 : 2;
 }

package/src/reference/registry.ts

@@ -214,7 +214,7 @@ export function buildNotationRegistry(
     if (!reachableDefinitions.has(candidate.id)) {
       diagnostics.push({
         code: 'unused-definition',
-        severity: 'warning',
+        severity: 'info',
         message: `${candidate.id} is not reachable from any lesson reference`,
         key: candidate.input.key,
         lessonId:

package/src/reference/rehype-base-links.mjs

@@ -0,0 +1,40 @@
+/**
+ * Prefixes root-relative `<a href="/...">` links in rendered lesson content
+ * with the course's Astro `base` path.
+ *
+ * A course deployed under a subpath (any GitHub Pages *project* site, e.g.
+ * `base: '/my-course'`) gets that prefix applied automatically to Starlight's
+ * own generated navigation — sidebar, pagination, breadcrumbs — because those
+ * are rendered by Starlight's own `.astro` components, which call its
+ * internal `pathWithBase()` helper. They are **not** applied to anything
+ * produced by the Markdown/MDX → rehype pipeline: a lesson's own prose links
+ * (`[text](/other-lesson/)`), `remark-notation.mjs`'s equation cross-
+ * references, and `remark-citation.mjs`'s citation links are all root-
+ * relative absolute paths written or generated without the base in mind, so
+ * without this plugin every one of them 404s on a subpath deployment. A
+ * lesson's Starlight frontmatter (e.g. `hero.actions[].link`) is untouched
+ * either way — that YAML never enters this pipeline — so write those as
+ * paths relative to the current page instead.
+ *
+ * A no-op when the course has no base (`base` omitted or `'/'`, e.g. local
+ * dev or a GitHub *user/org* Pages site), so a course can wire this in
+ * unconditionally and it only does anything on the deployments that need it.
+ */
+export default function rehypeBaseLinks(base) {
+  const prefix = base && base !== '/' ? base.replace(/\/+$/, '') : '';
+
+  return function transform(tree) {
+    if (!prefix) return;
+    visit(tree);
+  };
+
+  function visit(node) {
+    if (node.type === 'element' && node.tagName === 'a') {
+      const href = node.properties?.href;
+      if (typeof href === 'string' && href.startsWith('/') && !href.startsWith('//')) {
+        node.properties.href = prefix + href;
+      }
+    }
+    if (Array.isArray(node.children)) node.children.forEach(visit);
+  }
+}

package/src/reference/remark-abbreviations.mjs

@@ -5,12 +5,15 @@
  * requires every abbreviation-shaped word in prose to either be universal or
  * carry a `content/abbreviations/*.md` entry, so the literal written form
  * (`abbr`, or one of its `aliases`) is itself the trigger. This plugin scans
- * ordinary prose for that literal text and wraps the **first** occurrence per
- * document in a real link (`/glossary/#abbr-<key>`, so it still navigates
- * with no JS) carrying the `data-abbr-key` an island script reads to render a
- * hover/click card, exactly the way `remarkCitation` wraps `[@id]` markers.
- * Later occurrences of the same term on the same page stay plain text, so a
- * common short word isn't turned into a link everywhere it appears.
+ * ordinary prose for that literal text and wraps **every** occurrence in a
+ * real link (`/glossary/#abbr-<key>`, so it still navigates with no JS)
+ * carrying the `data-abbr-key` an island script reads to render a hover/click
+ * card, exactly the way `remarkCitation` wraps `[@id]` markers. A reader who
+ * deep-links into a mid-page heading — the sidebar TOC, a heading anchor, an
+ * external link — sees the same hoverable cue no matter which occurrence they
+ * land on first, rather than only the earliest one in document order.
+ * `AbbreviationLayer.astro` already resolves every marker independently by
+ * `data-abbr-key`, so wrapping every occurrence needs no island-side change.
  *
  * Matches only ever come from the known table by construction, so unlike
  * citation's `[@id]` there is no "unknown id" failure path here.
@@ -118,10 +121,6 @@ export default function remarkAbbreviations(options = {}) {
     const { regex, keyByMatch } = buildMatcher(suppliedAbbreviations);
     if (!regex) return;
 
-    // Fresh per file, same lifetime as citation's own `pairs` Map: only the
-    // first occurrence of a given key on this page gets wrapped.
-    const usedKeys = new Set();
-
     const replaceText = (value) => {
       regex.lastIndex = 0;
       const output = [];
@@ -131,13 +130,12 @@ export default function remarkAbbreviations(options = {}) {
 
       while ((match = regex.exec(value))) {
         const key = keyByMatch.get(match[0]);
-        if (!key || usedKeys.has(key)) continue;
+        if (!key) continue;
 
         if (match.index > cursor) {
           output.push({ type: 'text', value: value.slice(cursor, match.index) });
         }
         output.push(termNode(key, match[0], base));
-        usedKeys.add(key);
         changed = true;
         cursor = match.index + match[0].length;
       }

package/src/reference/render-lab-math.ts

@@ -1,5 +1,5 @@
-import katex from 'katex';
-import { resolveMathGlyphs } from './math-glyphs.mjs';
+import katex from './katex-delimiters.mjs';
+import { resolveMathGlyphs, stripNotationMarkers } from './math-glyphs.mjs';
 import { createNotationKatexOptions } from './katex-options.mjs';
 
 export interface LabMathScopeDefinition {
@@ -14,6 +14,26 @@ export interface RenderedLabMath {
   readonly slots: readonly string[];
   /** Notation keys the template resolved to, for diagnostics. */
   readonly keys: readonly string[];
+  /**
+   * Plain, copyable LaTeX — every explained glyph resolved to its bare
+   * symbol, every `\slot{name}{…}` replaced by `slotPlaceholder(name)` — so
+   * the island can substitute each slot's *current* live value in and keep
+   * `[data-notation-formula]`'s `data-latex` accurate as the reader drags a
+   * control, the same "click the equation to copy it" gesture a static
+   * lesson or glossary equation gets (`NotationLayer.astro`).
+   */
+  readonly plainLatexTemplate: string;
+}
+
+/**
+ * A slot's placeholder inside `plainLatexTemplate` — distinct from the
+ * numeric sentinel `sentinelFor` below uses internally (that one only has to
+ * survive a single notation-binding pass at build time; this one is the
+ * stable, name-keyed token an island substitutes with a live value at
+ * runtime, so it's exported for that purpose).
+ */
+export function slotPlaceholder(name: string): string {
+  return `⟦${name}⟧`;
 }
 
 interface BindResult {
@@ -72,6 +92,7 @@ export function renderLabMath(
   }
 
   let bound = result.latex;
+  let copyBound = result.latex;
   slots.forEach(({ name, fallback }, index) => {
     const sentinel = sentinelFor(index);
     if (!bound.includes(sentinel)) {
@@ -84,6 +105,7 @@ export function renderLabMath(
       sentinel,
       `\\htmlData{lab-slot=${name}}{${fallback}}`,
     );
+    copyBound = copyBound.replace(sentinel, slotPlaceholder(name));
   });
 
   const html = katex.renderToString(
@@ -95,5 +117,6 @@ export function renderLabMath(
     html,
     slots: slots.map(({ name }) => name),
     keys: [...new Set(result.bindings.map(({ key }) => key))],
+    plainLatexTemplate: stripNotationMarkers(copyBound),
   };
 }

package/src/reference/tables-validate.ts

@@ -15,7 +15,7 @@ export type TableDiagnosticCode =
 
 export interface TableDiagnostic {
   readonly code: TableDiagnosticCode;
-  readonly severity: 'error' | 'warning';
+  readonly severity: 'error' | 'warning' | 'info';
   readonly message: string;
   readonly file?: string;
   readonly lessonId?: string;

package/src/reference/types.ts

@@ -88,6 +88,13 @@ export 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;
 }
 
@@ -127,7 +134,7 @@ export type NotationDiagnosticCode =
   | 'alignment-review-state'
   | 'gloss-collides-with-card';
 
-export type DiagnosticSeverity = 'error' | 'warning';
+export type DiagnosticSeverity = 'error' | 'warning' | 'info';
 
 export interface NotationDiagnostic {
   readonly code: NotationDiagnosticCode;