explico 0.11.1 → 0.12.0

package/src/reference/figure-symbols.ts

@@ -0,0 +1,117 @@
+/**
+ * Every symbol a figure shows opens its notation card (rule N4). Lesson
+ * math, lab math (`renderLabMath`), a diagram's formulas and a caption
+ * clause's `{ math }` run all go through the glyph resolver, which binds
+ * each symbol to its key: KaTeX then wraps it in a `[data-notation-key]`
+ * span. KaTeX that a course renders itself — `katex.renderToString` in a
+ * lab's legend, axis title or slider label — skips the resolver, so its
+ * symbols have no card and nothing else would report them.
+ *
+ * `unboundFigureSymbols` reads rendered HTML: inside each
+ * `figure.keyed-figure` (a lab's tools included), every letter KaTeX draws
+ * must sit in a `[data-notation-key]`. Upright text is not a symbol:
+ * `\text{…}`, `\mathrm{…}` (the resolver skips its body, rule N10) and a
+ * named operator (`\sin`, `\max`). `compiler/astro.ts` runs it on every
+ * built page, and a course's browser test can run it on a hydrated figure's
+ * `outerHTML`, which also holds what an island draws only in the browser.
+ */
+
+import { parse, type DefaultTreeAdapterMap } from 'parse5';
+
+type HtmlNode = DefaultTreeAdapterMap['node'];
+type HtmlElement = DefaultTreeAdapterMap['element'];
+
+export interface UnboundFigureSymbols {
+  /** The figure's anchor id, e.g. `fig-latent-factor-model`. */
+  readonly figure: string;
+  /** Each unbound symbol's text, in document order, once. */
+  readonly symbols: readonly string[];
+}
+
+/** KaTeX classes of upright text, which is never a symbol. */
+const UPRIGHT = new Set(['text', 'mathrm', 'textrm', 'mop']);
+const LETTER = /\p{L}/u;
+
+function isElement(node: HtmlNode): node is HtmlElement {
+  return 'tagName' in node;
+}
+
+function attribute(node: HtmlElement, name: string): string | undefined {
+  return node.attrs.find((attr) => attr.name === name)?.value;
+}
+
+function classes(node: HtmlElement): string[] {
+  return (attribute(node, 'class') ?? '').split(/\s+/u).filter(Boolean);
+}
+
+function childrenOf(node: HtmlNode): readonly HtmlNode[] {
+  // A `<template>`'s content is a fragment of its own in parse5.
+  if (isElement(node) && node.tagName === 'template') {
+    return (node as HtmlElement & { content: { childNodes: HtmlNode[] } }).content
+      .childNodes;
+  }
+  return 'childNodes' in node ? node.childNodes : [];
+}
+
+/** The figures in `html` that draw a symbol with no card, and those symbols. */
+export function unboundFigureSymbols(html: string): UnboundFigureSymbols[] {
+  // Most pages have no figure; they need no parse.
+  if (!html.includes('keyed-figure') || !html.includes('katex-html')) return [];
+  const found = new Map<string, string[]>();
+
+  const visit = (
+    node: HtmlNode,
+    figure: string | undefined,
+    inKatex: boolean,
+    covered: boolean,
+  ): void => {
+    if (isElement(node)) {
+      const names = classes(node);
+      if (node.tagName === 'figure' && names.includes('keyed-figure')) {
+        figure = attribute(node, 'id') ?? '(a figure with no id)';
+      }
+      if (names.includes('katex-html')) inKatex = true;
+      if (
+        attribute(node, 'data-notation-key') !== undefined ||
+        (inKatex && names.some((name) => UPRIGHT.has(name)))
+      ) {
+        covered = true;
+      }
+    } else if (
+      node.nodeName === '#text' &&
+      figure !== undefined &&
+      inKatex &&
+      !covered
+    ) {
+      const text = (node as DefaultTreeAdapterMap['textNode']).value.trim();
+      if (LETTER.test(text)) {
+        const symbols = found.get(figure) ?? [];
+        if (!symbols.includes(text)) symbols.push(text);
+        found.set(figure, symbols);
+      }
+    }
+    for (const child of childrenOf(node)) visit(child, figure, inKatex, covered);
+  };
+
+  visit(parse(html), undefined, false, false);
+  return [...found].map(([figure, symbols]) => ({ figure, symbols }));
+}
+
+/**
+ * Fail a build whose rendered page shows a symbol in a figure that opens no
+ * card, naming the figure, the symbols, and the way to bind them.
+ */
+export function assertFigureSymbolsBound(page: string, html: string): void {
+  const unbound = unboundFigureSymbols(html);
+  if (unbound.length === 0) return;
+  throw new Error(
+    `Explico figure symbols without a notation card on rendered page "${page}": ` +
+      unbound
+        .map(({ figure, symbols }) => `#${figure} shows ${symbols.map((s) => `"${s}"`).join(', ')}`)
+        .join('; ') +
+      '. Every symbol a figure shows opens its card (rule N4): render its math ' +
+      'with renderLabMath (`{ display: false }` for a legend, an axis title or ' +
+      'a label; a `{ math }` run for the caption clause), never with katex ' +
+      'directly. Write a unit as `\\text{…}`.',
+  );
+}

package/src/reference/gate-non-chapter-pages.ts

@@ -0,0 +1,241 @@
+/**
+ * The non-chapter page gate (rule S10). A page that is not a chapter — the
+ * landing page, a part's overview page, any other page outside a part
+ * directory — explains its symbols like a chapter does, but numbers nothing:
+ *
+ * - no numbered block: `<Table>`, `<Figure>`, `<Diagram>`, `<CompactExamples>`,
+ *   `<AssessmentSet>`, and no lab (a component imported from a `labs/` module,
+ *   or any hydrated `client:*` island) — code `non-chapter-float`;
+ * - no `\label{eq:…}` on a display equation — the same code;
+ * - no `notation.local` / `notation.suspend`: the page recalls symbols and
+ *   defines none — code `non-chapter-local-notation`;
+ * - no `$…$` or `[[…]]` in the plain-text strings a page shows outside its
+ *   Markdown body (`hero.title`, `hero.tagline`, a `<PartOverview chain>`
+ *   step), where they would print literally — code `non-chapter-plain-text`.
+ *
+ * A float needs a chapter number, which such a page does not have; linking
+ * the chapter's float (`[[lesson#tab-key]]`) shows it in the reference card
+ * instead. The rule is locked: turning it off would not give the page a
+ * number, so each finding is an error with no waiver. See
+ * docs/authoring/structure-rules.md#s10.
+ */
+import type { MathGateDiagnostic } from './gate-math';
+import { scannable } from './gate-part-pages';
+import { lessonLine } from './gate-prose-notation';
+
+/** One non-chapter page, as the manifest compiler loads it. */
+export interface NonChapterPageInput {
+  readonly file: string;
+  readonly data: Readonly<Record<string, unknown>>;
+  readonly body: string;
+  readonly bodyLine: number;
+}
+
+/** A numbered block, with the reference prefix of the float a chapter would give it. */
+const NUMBERED_BLOCKS: Readonly<Record<string, { noun: string; ref: string }>> = {
+  Table: { noun: 'a table', ref: 'tab' },
+  Figure: { noun: 'a figure', ref: 'fig' },
+  Diagram: { noun: 'a diagram', ref: 'dia' },
+  CompactExamples: { noun: 'a worked-example set', ref: 'ex' },
+  AssessmentSet: { noun: 'a knowledge check', ref: 'check' },
+};
+
+const NUMBERED_BLOCK_TAG = new RegExp(
+  `<(${Object.keys(NUMBERED_BLOCKS).join('|')})(?=[\\s/>])`,
+  'g',
+);
+const EQUATION_LABEL = /\\label\s*\{\s*eq:([^}]*)\}/g;
+const CLIENT_DIRECTIVE = /<([A-Z][\w.]*)\b[^<>]*?\sclient:[a-z]+/g;
+const IMPORT = /^\s*import\s+([\s\S]*?)\s+from\s+['"]([^'"]+)['"]/gm;
+const PLAIN_TEXT_MARKUP = /\$|\[\[/;
+
+interface Finding {
+  readonly index: number;
+  readonly code: 'non-chapter-float' | 'non-chapter-local-notation' | 'non-chapter-plain-text';
+  readonly token: string;
+  readonly message: string;
+  /** Frontmatter findings have no body offset; they report the file's first line. */
+  readonly inFrontmatter?: true;
+}
+
+/** Local names an `import … from '<…>labs/…'` binds, e.g. `{ A, B as C }` → A, C. */
+function labComponentNames(text: string): Set<string> {
+  const names = new Set<string>();
+  for (const match of text.matchAll(IMPORT)) {
+    const [, clause, source] = match;
+    if (!/(^|\/)labs\//.test(source)) continue;
+    const named = /\{([^}]*)\}/.exec(clause);
+    const defaultName = clause.replace(/\{[^}]*\}/, '').replace(/,/g, ' ').trim();
+    if (/^[A-Za-z_$][\w$]*$/.test(defaultName)) names.add(defaultName);
+    for (const part of named?.[1].split(',') ?? []) {
+      const alias = part.trim().split(/\s+as\s+/).pop()?.trim();
+      if (alias) names.add(alias);
+    }
+  }
+  return names;
+}
+
+function floatFindings(text: string): Finding[] {
+  const findings: Finding[] = [];
+
+  for (const match of text.matchAll(NUMBERED_BLOCK_TAG)) {
+    const tag = match[1];
+    const { noun, ref } = NUMBERED_BLOCKS[tag];
+    findings.push({
+      index: match.index ?? 0,
+      code: 'non-chapter-float',
+      token: `<${tag}>`,
+      message:
+        `<${tag}> on a page that is not a chapter (rule S10): only a chapter ` +
+        `numbers ${noun}. Move it into the chapter it belongs to, and link it ` +
+        `from here with [[<chapter>#${ref}-<key>]]: the link shows it in its card.`,
+    });
+  }
+
+  const labs = labComponentNames(text);
+  const flagged = new Set<number>();
+  for (const name of labs) {
+    // A lab bound to a numbered block's name (`import Diagram from
+    // '../labs/…'`) was reported above, under that name.
+    if (name in NUMBERED_BLOCKS) continue;
+    const usage = new RegExp(`<${name.replace(/\./g, '\\.')}(?=[\\s/>])`, 'g');
+    for (const match of text.matchAll(usage)) {
+      const index = match.index ?? 0;
+      flagged.add(index);
+      findings.push({
+        index,
+        code: 'non-chapter-float',
+        token: `<${name}>`,
+        message:
+          `<${name}> is a lab, on a page that is not a chapter (rule S10): a ` +
+          'plot belongs in a chapter’s <Figure>. Move it there, and link it ' +
+          'from here with [[<chapter>#fig-<key>]]: the link shows it in its card.',
+      });
+    }
+  }
+  for (const match of text.matchAll(CLIENT_DIRECTIVE)) {
+    const index = match.index ?? 0;
+    if (flagged.has(index) || match[1] in NUMBERED_BLOCKS) continue;
+    findings.push({
+      index,
+      code: 'non-chapter-float',
+      token: `<${match[1]}>`,
+      message:
+        `<${match[1]}> is an interactive island, on a page that is not a ` +
+        'chapter (rule S10): an interactive figure belongs in a chapter’s ' +
+        '<Figure>. Move it there, and link it from here with ' +
+        '[[<chapter>#fig-<key>]]: the link shows it in its card.',
+    });
+  }
+
+  for (const match of text.matchAll(EQUATION_LABEL)) {
+    const key = match[1].trim();
+    findings.push({
+      index: match.index ?? 0,
+      code: 'non-chapter-float',
+      token: `\\label{eq:${key}}`,
+      message:
+        `\\label{eq:${key}} on a page that is not a chapter (rule S10): only a ` +
+        'chapter numbers an equation. Drop the label to show the equation ' +
+        'unnumbered, or link the chapter’s own with [[<chapter>#eq-<key>]].',
+    });
+  }
+
+  return findings;
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function frontmatterFindings(data: Readonly<Record<string, unknown>>): Finding[] {
+  const findings: Finding[] = [];
+  const notation = record(data.notation);
+  for (const field of ['local', 'suspend'] as const) {
+    if (notation?.[field] === undefined) continue;
+    findings.push({
+      index: 0,
+      inFrontmatter: true,
+      code: 'non-chapter-local-notation',
+      token: `notation.${field}`,
+      message:
+        `notation.${field} on a page that is not a chapter (rule S10): the ` +
+        'page recalls symbols and defines none. Move the entry to the chapter ' +
+        'that introduces the symbol, or to shared notation, and name it here ' +
+        'with [[key]].',
+    });
+  }
+
+  const hero = record(data.hero);
+  for (const field of ['title', 'tagline'] as const) {
+    const value = hero?.[field];
+    if (typeof value !== 'string' || !PLAIN_TEXT_MARKUP.test(value)) continue;
+    findings.push({
+      index: 0,
+      inFrontmatter: true,
+      code: 'non-chapter-plain-text',
+      token: `hero.${field}`,
+      message:
+        `hero.${field} is plain text, so its $…$ or [[…]] prints literally ` +
+        '(rule S10). Write the words here, and put the symbol in the page ' +
+        'body, where it gets its card.',
+    });
+  }
+  return findings;
+}
+
+/** `<PartOverview chain={[ '…', "…" ]}>`: each quoted step is plain text. */
+function chainFindings(text: string): Finding[] {
+  const findings: Finding[] = [];
+  const overview = /<PartOverview\b[\s\S]*?\bchain=\{\s*\[([\s\S]*?)\]\s*\}/g;
+  for (const match of text.matchAll(overview)) {
+    const listStart = (match.index ?? 0) + match[0].indexOf(match[1]);
+    const step = /'((?:[^'\\]|\\.)*)'|"((?:[^"\\]|\\.)*)"|`((?:[^`\\]|\\.)*)`/g;
+    for (const item of match[1].matchAll(step)) {
+      const value = item[1] ?? item[2] ?? item[3] ?? '';
+      if (!PLAIN_TEXT_MARKUP.test(value)) continue;
+      findings.push({
+        index: listStart + (item.index ?? 0),
+        code: 'non-chapter-plain-text',
+        token: 'chain',
+        message:
+          'A <PartOverview chain> step is plain text, so its $…$ or [[…]] ' +
+          'prints literally (rule S10). Write the step in words; a symbol ' +
+          'with its card goes in <PartScope>.',
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Check every non-chapter page for what rule S10 keeps off it. Returns one
+ * `MathGateDiagnostic` (context `'structure'`, always an error) per finding.
+ */
+export function gateNonChapterPages(
+  pages: readonly NonChapterPageInput[],
+): MathGateDiagnostic[] {
+  const diagnostics: MathGateDiagnostic[] = [];
+  for (const page of pages) {
+    const text = scannable(page.body);
+    const findings = [
+      ...frontmatterFindings(page.data),
+      ...floatFindings(text),
+      ...chainFindings(text),
+    ].sort((a, b) => a.index - b.index);
+    for (const finding of findings) {
+      diagnostics.push({
+        context: 'structure',
+        severity: 'error',
+        code: finding.code,
+        file: page.file,
+        line: finding.inFrontmatter ? 1 : lessonLine(page, finding.index),
+        token: finding.token,
+        message: finding.message,
+      });
+    }
+  }
+  return diagnostics;
+}

package/src/reference/gate-part-pages.ts

@@ -52,7 +52,7 @@ interface Occurrence {
 }
 
 /** Blank MDX comments (`{/* … *\/}`) and code, keeping every newline. */
-function scannable(body: string): string {
+export function scannable(body: string): string {
   return stripFencedCode(body).replace(/\{\/\*[\s\S]*?\*\/\}/g, (comment) =>
     comment.replace(/[^\n]/g, ' '),
   );

package/src/reference/lab-katex-validate.ts

@@ -0,0 +1,156 @@
+/**
+ * Rule V3's seam, checked in the source: a component a lesson renders draws
+ * its math through `renderLabMath`, which binds every symbol to the page's
+ * notation, never by calling KaTeX itself — a legend helper around
+ * `katex.renderToString` binds none, so its symbols open no card.
+ *
+ * Starting at each lesson's own imports, this follows every relative import
+ * — the course's visuals, wherever they live — and reports each file that
+ * imports `katex` as `lab-katex-direct`, with the chain of imports that
+ * reaches it. A package import (`explico/…`, `react`) is not followed:
+ * explico's own KaTeX use is the seam. A type-only import and the KaTeX
+ * stylesheet draw nothing and are not reported.
+ *
+ * `figure-symbols.ts` checks the same promise on the rendered page, which
+ * also catches math a lab draws some other way.
+ */
+
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+
+import { stripFencedCode } from './equations.mjs';
+
+export interface LabKatexDiagnostic {
+  readonly code: 'lab-katex-direct';
+  readonly severity: 'error';
+  readonly message: string;
+  /** The file that imports `katex`, repository-relative. */
+  readonly file: string;
+  /** The first lesson (by id) whose imports reach it. */
+  readonly lessonId: string;
+}
+
+export interface LabKatexLessonInput {
+  readonly lessonId: string;
+  /** Repository-relative path of the lesson file. */
+  readonly file: string;
+  readonly body: string;
+}
+
+/** Extensions tried, in order, for an import written without one. */
+const EXTENSIONS = ['.astro', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.mts', '.cjs'];
+/** Files worth reading for imports: scripts, components and MDX. */
+const SOURCE_FILE = /\.(?:astro|tsx|ts|jsx|js|mjs|mts|cjs|mdx)$/u;
+
+const IMPORT_PATTERNS = [
+  // import x from 'y' · import { x } from 'y' · import 'y' · import type … from 'y'
+  /\bimport\s+(type\s+)?(?:[\w*{}\s,$]+?\s+from\s+)?(['"])([^'"\n]+)\2/gu,
+  // export { x } from 'y' · export * from 'y' · export type { x } from 'y'
+  /\bexport\s+(type\s+)?(?:\*(?:\s+as\s+[\w$]+)?|\{[^}]*\})\s+from\s+(['"])([^'"\n]+)\2/gu,
+  // import('y') · require('y')
+  /\b(?:import|require)\s*\(\s*()(['"])([^'"\n]+)\2\s*\)/gu,
+];
+
+/**
+ * Every module a source file imports at run time, in order: static, re-exported,
+ * dynamic and `require`d. A type-only import is left out.
+ */
+export function importSpecifiers(source: string): string[] {
+  const found: { index: number; specifier: string }[] = [];
+  for (const pattern of IMPORT_PATTERNS) {
+    for (const match of source.matchAll(pattern)) {
+      if (match[1]) continue;
+      found.push({ index: match.index ?? 0, specifier: match[3]! });
+    }
+  }
+  return found.sort((a, b) => a.index - b.index).map(({ specifier }) => specifier);
+}
+
+/** `katex`, or a script inside it — not its stylesheet or its fonts. */
+function isKatexModule(specifier: string): boolean {
+  if (specifier !== 'katex' && !specifier.startsWith('katex/')) return false;
+  return !/\.(?:css|woff2?|ttf)$/u.test(specifier);
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** The file a relative import names, trying the extensions a bundler would. */
+function resolveRelative(fromFile: string, specifier: string): string | undefined {
+  const base = join(dirname(fromFile), specifier);
+  const candidates = [
+    base,
+    // `./chart.js` written for `./chart.ts`, the TypeScript ESM convention.
+    ...(/\.[cm]?js$/u.test(base) ? ['.ts', '.tsx', '.mts', '.cts'].map((ext) => base.replace(/\.[cm]?js$/u, ext)) : []),
+    ...EXTENSIONS.map((ext) => `${base}${ext}`),
+    ...EXTENSIONS.map((ext) => join(base, `index${ext}`)),
+  ];
+  return candidates.find(isFile);
+}
+
+/**
+ * Each course file that a lesson's imports reach and that imports `katex`.
+ * `root` is the repository root the lesson paths are relative to.
+ */
+export function validateLabKatexImports(
+  lessons: readonly LabKatexLessonInput[],
+  root: string = process.cwd(),
+): LabKatexDiagnostic[] {
+  const read = (path: string): string | undefined => {
+    try {
+      return readFileSync(path, 'utf8');
+    } catch {
+      return undefined;
+    }
+  };
+  const repoPath = (path: string) => relative(root, path).split(sep).join('/');
+
+  const diagnostics = new Map<string, LabKatexDiagnostic>();
+  const seen = new Set<string>();
+  for (const lesson of [...lessons].sort((a, b) => a.lessonId.localeCompare(b.lessonId))) {
+    const lessonPath = join(root, lesson.file);
+    // Breadth first, so a reported chain is the shortest one.
+    const queue: { path: string; source: string; chain: readonly string[] }[] = [
+      { path: lessonPath, source: stripFencedCode(lesson.body), chain: [lesson.file] },
+    ];
+    while (queue.length > 0) {
+      const { path, source, chain } = queue.shift()!;
+      for (const specifier of importSpecifiers(source)) {
+        if (isKatexModule(specifier)) {
+          const file = repoPath(path);
+          if (!diagnostics.has(file)) {
+            diagnostics.set(file, {
+              code: 'lab-katex-direct',
+              severity: 'error',
+              file,
+              lessonId: lesson.lessonId,
+              message:
+                `${file} imports '${specifier}' and draws math whose symbols open no ` +
+                `notation card (reached by ${chain.join(' → ')}). Render a lab's math ` +
+                `with renderLabMath(template, scope) — { display: false } for a legend ` +
+                `entry, an axis title or a label — so every symbol is bound to the ` +
+                `page's notation (rule V3).`,
+            });
+          }
+          continue;
+        }
+        if (!specifier.startsWith('.')) continue;
+        const target = resolveRelative(path, specifier);
+        if (!target || !SOURCE_FILE.test(target) || target.includes(`${sep}node_modules${sep}`)) {
+          continue;
+        }
+        if (seen.has(target)) continue;
+        seen.add(target);
+        const text = read(target);
+        if (text === undefined) continue;
+        queue.push({ path: target, source: text, chain: [...chain, repoPath(target)] });
+      }
+    }
+  }
+  return [...diagnostics.values()].sort((a, b) => a.file.localeCompare(b.file));
+}

package/src/reference/lint-ignore.ts

@@ -34,8 +34,11 @@ export interface LintIgnore {
   matches(code: string, detail?: string): boolean;
 }
 
+// `<detail>` may hold a hyphen — a notation key is kebab-case — since the
+// separator is an em dash, `--`, or a spaced ` - `, none of which a key's
+// single, unspaced hyphens can form.
 const LINE =
-  /^-\s*([a-z0-9-]+)(?::([^\s—-][^—-]*?))?\s*(?:—|--|\s-\s)\s*(.+?)\s*$/;
+  /^-\s*([a-z0-9-]+)(?::([^\s—][^—]*?))?\s*(?:—|--|\s-\s)\s*(.+?)\s*$/;
 
 export function parseLintIgnore(text: string): LintIgnoreEntry[] {
   const entries: LintIgnoreEntry[] = [];

package/src/reference/page-notation.ts

@@ -123,22 +123,25 @@ function manifestDefinition(
 }
 
 /**
- * Extend one compiled lesson bundle with only the definitions requested by
- * components rendered on that page (plus those definitions' normal closure).
+ * Extend one compiled page bundle — a lesson's, or a non-chapter page's
+ * (rule S10) — with only the definitions requested by components rendered on
+ * that page (plus those definitions' normal closure).
  */
 export function notationDefinitionsForRenderedPage(
   manifest: Manifest,
-  lessonId: string,
+  pageId: string,
   dependencies: readonly PageNotationDependency[],
 ): ManifestLessonNotation[] {
-  const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
-  if (!lesson) return [];
+  const page =
+    manifest.lessons.find((entry) => entry.id === pageId) ??
+    manifest.pages.find((entry) => entry.id === pageId);
+  if (!page) return [];
 
   const definitionsById = new Map(
     manifest.notation.definitions.map((definition) => [definition.id, definition]),
   );
   const availableIds = new Set(definitionsById.keys());
-  const ids = new Set(lesson.notation.definitionIds);
+  const ids = new Set(page.notation.definitionIds);
   const contextsByKey = new Map<string, Set<string>>();
 
   for (const dependency of dependencies) {
@@ -151,14 +154,14 @@ export function notationDefinitionsForRenderedPage(
 
     const definitionId = resolveReferenceId(
       dependency.key,
-      { kind: 'page', lessonId },
+      { kind: 'page', lessonId: pageId },
       availableIds,
     );
     if (!definitionId) {
       throw new Error(
-        `Notation payload error in lesson "${lessonId}": ${dependency.context} ` +
+        `Notation payload error on page "${pageId}": ${dependency.context} ` +
           `emitted data-notation-key="${dependency.key}", but that key is not ` +
-          `defined in this lesson or the shared notation registry.`,
+          `defined on this page or in the shared notation registry.`,
       );
     }
     ids.add(definitionId);
@@ -202,7 +205,7 @@ export function notationDefinitionsForRenderedPage(
     if (previous && previous !== id) {
       const context = [...(contextsByKey.get(definition.key) ?? [])].join(', ');
       throw new Error(
-        `Notation payload error in lesson "${lessonId}": key "${definition.key}" ` +
+        `Notation payload error on page "${pageId}": key "${definition.key}" ` +
           `would have two meanings (${previous} and ${id})` +
           (context ? ` after ${context} emitted it.` : '.'),
       );
@@ -220,7 +223,7 @@ export function notationDefinitionsForRenderedPage(
   }
 
   const existingById = new Map(
-    lesson.notation.definitions.map((definition) => [definition.id, definition]),
+    page.notation.definitions.map((definition) => [definition.id, definition]),
   );
   return [...ids]
     .sort()