explico 0.4.0 → 0.5.0

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

@@ -0,0 +1,224 @@
+/**
+ * The plain-text-notation gate (rule N9), run from the CLI alongside the
+ * completeness gate (`gate-math.ts`). Where that gate asks "does every glyph
+ * *inside* `$…$` resolve", this one asks the complementary question: "is
+ * anything that reads as math sitting *outside* `$…$` in the first place" —
+ * a unit abbreviation, a division of two variable-like symbols, an escaped
+ * absolute-value bar, a hand-typed sub/superscript. Both gates share one
+ * `MathGateDiagnostic` shape and one output array (`manifest.diagnostics.math`)
+ * so the CLI needs no separate wiring.
+ *
+ * Two entry points, one set of checks (`findingsIn`): `gateProseNotation`
+ * scans `lesson.body` with fenced/inline code and every `$…$` / `$$…$$` span
+ * already blanked out (same `stripCode` + math-span erasure `gate-math.ts`
+ * uses), so it only ever sees prose and table cells. `gateProseNotationInAssessments`
+ * scans an assessment item's `prompt` / `explanation` the same way — a plain
+ * JSON string field, not Markdown, but one that renders through the same
+ * KaTeX pipeline as a lesson body since `AssessmentRunner` picked it up
+ * (`mixed-content.ts`), so the same rule applies.
+ */
+import type { MathGateDiagnostic } from './gate-math';
+import type { NotationLessonInput } from './types';
+
+interface AssessmentItemLike {
+  readonly id?: string;
+  readonly prompt?: string;
+  readonly explanation?: string;
+}
+interface AssessmentLike {
+  readonly id: string;
+  readonly items?: readonly AssessmentItemLike[];
+}
+
+const CODE_FENCE = /```[\s\S]*?```/g;
+const INLINE_CODE = /(^|[^`])`[^`\n]*`/g;
+const DISPLAY_MATH = /\$\$([\s\S]+?)\$\$/g;
+const INLINE_MATH = /(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/g;
+// MDX `import … from '…/…'` lines: the path's `/` is a module separator, not
+// a division of two symbols.
+const IMPORT_LINE = /^[ \t]*import\b[^\n]*$/gm;
+// `[[key]]` / `[[slug/lesson#anchor]]` reference syntax: never prose math,
+// and a cross-page slug legitimately contains a `/`.
+const KEY_REFERENCE = /\[\[[^\]\n]*\]\]/g;
+// A JSX tag, opening through its matching `>` — may span several lines when
+// each prop is on its own line. Component prop strings (`caption="…"`,
+// `title="…"`) are plain display text with no math rendering at all (Figure
+// and Table hand their `caption` straight to the DOM as a string), so N9
+// does not apply inside one — enforcing "use $…$" somewhere it can't render
+// would just break the caption instead of fixing it.
+const JSX_TAG = /<\/?[A-Za-z][^<>]*>/g;
+
+/**
+ * Blank code, math, reference, and JSX-tag spans so offsets don't shift.
+ * Exported so `gate-abbreviations.ts` (N14) scans exactly the same "is this
+ * really prose" surface as N9, instead of drifting with a second copy of
+ * these regexes.
+ */
+export function proseOnly(body: string): string {
+  const blank = (match: string) => match.replace(/[^\n]/g, ' ');
+  return body
+    .replace(CODE_FENCE, blank)
+    .replace(INLINE_CODE, (match, lead: string) => lead + blank(match.slice(lead.length)))
+    .replace(DISPLAY_MATH, blank)
+    .replace(INLINE_MATH, blank)
+    .replace(IMPORT_LINE, blank)
+    .replace(KEY_REFERENCE, blank)
+    .replace(JSX_TAG, blank);
+}
+
+/** Exported for the same reason as {@link proseOnly}. */
+export function lineOf(text: string, index: number): number {
+  return text.slice(0, index).split('\n').length;
+}
+
+// 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`;
+
+const NUMERAL_UNIT = new RegExp(
+  String.raw`(?<![\w.])-?\d+(?:\.\d+)?\s?(?:${UNIT})(?![A-Za-z])`,
+  'g',
+);
+const BARE_UNIT_PARENS = new RegExp(String.raw`\((?:${UNIT})\)`, 'g');
+
+// Idiomatic English slash constructs that are prose, not a division of two
+// symbols — reviewed and extended in the same PR that adds a new one, not by
+// a per-page suppression (there is no lint-ignore.yml entry for this gate;
+// see N9's "everything, no exceptions" scope).
+const SLASH_IDIOMS = new Set([
+  'and/or',
+  'his/her',
+  'him/her',
+  'he/she',
+  'she/he',
+  'on/off',
+  'yes/no',
+  'pass/fail',
+  'input/output',
+  'output/input',
+  'read/write',
+  'either/or',
+  'client/server',
+  'pre/post',
+  'a/b',
+]);
+const SLASH_TOKENS = /\b([A-Za-z]{1,6})\/([A-Za-z]{1,6})\b/g;
+
+// A `_` or `^` sitting directly between two alphanumerics reads as a
+// hand-typed sub/superscript that was never wrapped in `$…$`.
+const FAKE_SCRIPT = /[A-Za-z0-9][_^][A-Za-z0-9{]/g;
+
+interface Finding {
+  readonly index: number;
+  readonly token: string;
+  readonly message: string;
+}
+
+function findAll(text: string, pattern: RegExp, toFinding: (m: RegExpExecArray) => Finding): Finding[] {
+  const out: Finding[] = [];
+  const re = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`);
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(text))) {
+    out.push(toFinding(match));
+    if (match[0].length === 0) re.lastIndex++;
+  }
+  return out;
+}
+
+const FIX = 'Wrap it in $…$ (or $$…$$) instead — see docs/authoring/notation.md#n9.';
+
+/** Every N9 finding in one already-prose-only string, in source order. */
+function findingsIn(text: string): Finding[] {
+  return [
+    ...findAll(text, /\\\|/g, (m) => ({
+      index: m.index,
+      token: m[0],
+      message: `Escaped pipe ${JSON.stringify(m[0])} outside math. Use \\lvert…\\rvert for an absolute value or norm inside $…$, not an escaped table pipe. ${FIX}`,
+    })),
+    ...findAll(text, NUMERAL_UNIT, (m) => ({
+      index: m.index,
+      token: m[0].trim(),
+      message: `Numeral with a plain-text unit ${JSON.stringify(m[0].trim())} outside math. ${FIX}`,
+    })),
+    ...findAll(text, BARE_UNIT_PARENS, (m) => ({
+      index: m.index,
+      token: m[0],
+      message: `Plain-text unit ${JSON.stringify(m[0])} outside math. ${FIX}`,
+    })),
+    ...findAll(text, FAKE_SCRIPT, (m) => ({
+      index: m.index,
+      token: m[0],
+      message: `${JSON.stringify(m[0])} looks like a hand-typed sub/superscript outside math. ${FIX}`,
+    })),
+    ...findAll(text, SLASH_TOKENS, (m) => {
+      if (SLASH_IDIOMS.has(m[0].toLowerCase())) return null as unknown as Finding;
+      return {
+        index: m.index,
+        token: m[0],
+        message: `${JSON.stringify(m[0])} outside math reads as a division of two symbols/units, not English prose. If it really is prose, add the idiom to SLASH_IDIOMS in gate-prose-notation.ts (reviewed like any other rule change). ${FIX}`,
+      };
+    }).filter(Boolean),
+  ];
+}
+
+/**
+ * Scan every lesson body for plain-text math notation outside `$…$`. Returns
+ * one `MathGateDiagnostic` (context `'prose'`, always an error — N9 has no
+ * escape hatch) per finding.
+ */
+export function gateProseNotation(
+  lessons: readonly NotationLessonInput[],
+): MathGateDiagnostic[] {
+  const diagnostics: MathGateDiagnostic[] = [];
+
+  for (const lesson of lessons) {
+    const text = proseOnly(lesson.body);
+    for (const finding of findingsIn(text)) {
+      diagnostics.push({
+        context: 'prose',
+        severity: 'error',
+        file: lesson.source.file,
+        line: lineOf(lesson.body, finding.index),
+        token: finding.token,
+        message: finding.message,
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+/**
+ * Scan every assessment `prompt` / `explanation` for the same plain-text
+ * notation N9 forbids in a lesson body — `AssessmentRunner` renders both
+ * through the same KaTeX pipeline now (`mixed-content.ts`), so text sitting
+ * outside `$…$` there is just as invisible to the reader's hover cards as it
+ * would be in a lesson. No line number: an assessment item is one JSON string
+ * field, not a multi-line source file, so `file` names the item instead —
+ * same `"<assessmentId> (<itemId>)"` shape `gate-math.ts` already uses for
+ * this context.
+ */
+export function gateProseNotationInAssessments(
+  assessments: readonly AssessmentLike[],
+): MathGateDiagnostic[] {
+  const diagnostics: MathGateDiagnostic[] = [];
+
+  for (const assessment of assessments) {
+    for (const item of assessment.items ?? []) {
+      for (const field of [item.prompt, item.explanation]) {
+        if (typeof field !== 'string') continue;
+        for (const finding of findingsIn(proseOnly(field))) {
+          diagnostics.push({
+            context: 'prose',
+            severity: 'error',
+            file: `${assessment.id} (${item.id ?? '?'})`,
+            token: finding.token,
+            message: finding.message,
+          });
+        }
+      }
+    }
+  }
+
+  return diagnostics;
+}

package/src/reference/keyed-float-validate.ts

@@ -6,13 +6,13 @@
  * - `<prefix>-invalid-key` (error): an `id` must match the key grammar.
  * - `<prefix>-duplicate-key` (error): an `id` is unique per lesson.
  * - `<prefix>-ref-resolves` (error): every `[[<prefix>-key]]` /
- *   `[[slug#<prefix>-key]]` points at a `<Table>`/`<Figure>` with that `id`.
+ *   `[[slug#<prefix>-key]]` points at the matching keyed float with that `id`.
  * - `<prefix>-key-unused` (warning): a keyed float never referenced.
  *
- * `tables-validate.ts` and `figures-validate.ts` are thin wrappers over this
- * so callers import `validateTables` / `validateFigures` with their own
- * narrow diagnostic-code types, while `equations-validate.ts` stays
- * untouched — equations predate this and keep their own dedicated path.
+ * `tables-validate.ts`, `figures-validate.ts`, and `diagrams-validate.ts` are
+ * thin wrappers over this so callers import a kind-specific validator with
+ * narrow diagnostic-code types, while `equations-validate.ts` stays untouched
+ * — equations predate this and keep their own dedicated path.
  */
 
 import {

package/src/reference/keyed-jsx-floats.mjs

@@ -1,20 +1,20 @@
 /**
- * Keyed-float identity for a JSX-wrapped table or figure, shared between
- * `<Table>` and `<Figure>` (Step F-tables-figures).
+ * Keyed-float identity for a JSX-wrapped table, figure, or diagram, shared
+ * between `<Table>`, `<Figure>`, and `<Diagram>`.
  *
  * This mirrors `equations.mjs`, but the key comes from a plain `id` prop on
  * the wrapper component rather than a `\label{eq:key}` embedded in shared
- * LaTeX source — a `<Table>`/`<Figure>` is purpose-built, so there is no
+ * LaTeX source — a `<Table>`/`<Figure>`/`<Diagram>` is purpose-built, so there is no
  * ambiguity an embedded marker would need to resolve. An author writes the
  * bare key (`id="kinematics-summary"`); the rendered DOM id and the `[[…]]`
  * reference prefix are computed the same way `\label{eq:key}` becomes
- * `#eq-key` — `keyedFloatAnchorId` prepends `tab-`/`fig-`.
+ * `#eq-key` — `keyedFloatAnchorId` prepends `tab-`/`fig-`/`dia-`.
  *
- * Only top-level occurrences count, exactly like `collectDisplayEquations`:
- * a `<Table>` nested inside a `<CompactExample>` (or any other component) is
- * illustrative, not part of the lesson's official sequence, so both the
- * mdast walker and the raw-text scanner only look at the document's direct
- * top-level blocks.
+ * Only top-level occurrences count, exactly like `collectDisplayEquations`,
+ * except that `<Memo>` is transparent: a float in a memo remains a side-note
+ * in the lesson's reading order. A keyed float nested inside a
+ * `<CompactExample>` (or any other component) is illustrative, not part of the
+ * official sequence.
  *
  * `scanKeyedJsxFloats` (raw Markdown, for the manifest builder) and
  * `collectKeyedJsxFloats` (mdast, for `remark-notation.mjs`) MUST agree —
@@ -41,7 +41,7 @@ function floatNumber(section, index) {
  * scheme is `‹part›.‹offset + indexInLesson›` and `##` headings are ignored;
  * without it, the legacy `##`-section scheme. Mirrors `displayEquationNumber`
  * in `equations.mjs`. Each kind of float counts on its own — a `<Table>` never
- * advances the `<Figure>` sequence — so `offset` is per kind too.
+ * advances the `<Figure>` or `<Diagram>` sequence — so `offset` is per kind too.
  */
 function keyedFloatNumber({
   prefix,
@@ -91,7 +91,10 @@ function readIdAttribute(attributesSource) {
  */
 export function scanKeyedJsxFloats(markdown, { tagName, numbering }) {
   const { prefix, offset } = resolveNumbering(numbering);
-  const text = stripJsxComponents(stripFencedCode(markdown), tagName);
+  const text = stripJsxComponents(stripFencedCode(markdown), tagName, [
+    'Memo',
+    'ShortNote',
+  ]);
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
   const opening = new RegExp(`<${tagName}\\b([^>]*)>`, 'g');
@@ -141,11 +144,12 @@ export function countKeyedJsxFloats(markdown, { tagName }) {
 }
 
 /**
- * The mdast equivalent of `scanKeyedJsxFloats`: walk the tree's *top-level*
- * children in document order, advancing the section counter on every
- * depth-2 heading and emitting a record for every `mdxJsxFlowElement` named
- * `tagName` — keyed or not, exactly like `collectDisplayEquations`. `numbering`
- * is threaded the same way as in `scanKeyedJsxFloats`.
+ * The mdast equivalent of `scanKeyedJsxFloats`: walk the tree's top-level
+ * children (and through `<Memo>` bodies) in document order, advancing the
+ * section counter on every top-level depth-2 heading and emitting a record for
+ * every `mdxJsxFlowElement` named `tagName` — keyed or not, exactly like
+ * `collectDisplayEquations`. `numbering` is threaded the same way as in
+ * `scanKeyedJsxFloats`.
  */
 export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
   const { prefix, offset } = resolveNumbering(numbering);
@@ -154,14 +158,8 @@ export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
   let indexInSection = 0;
   let indexInLesson = 0;
 
-  const children = Array.isArray(tree?.children) ? tree.children : [];
-  for (const node of children) {
-    if (!node || typeof node !== 'object') continue;
-    if (node.type === 'heading' && node.depth === 2) {
-      section += 1;
-      indexInSection = 0;
-      continue;
-    }
+  const collectFromDetail = (node) => {
+    if (!node || typeof node !== 'object') return;
     if (node.type === 'mdxJsxFlowElement' && node.name === tagName) {
       indexInSection += 1;
       indexInLesson += 1;
@@ -184,8 +182,35 @@ export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
         indexInSection,
         node,
       });
+      return;
+    }
+    if (
+      node.type === 'mdxJsxFlowElement' &&
+      node.name !== 'Memo' &&
+      node.name !== 'ShortNote'
+    ) {
+      return;
+    }
+    if (!Array.isArray(node.children)) return;
+    for (const child of node.children) collectFromDetail(child);
+  };
+
+  const children = Array.isArray(tree?.children) ? tree.children : [];
+  for (const node of children) {
+    if (!node || typeof node !== 'object') continue;
+    if (node.type === 'heading' && node.depth === 2) {
+      section += 1;
+      indexInSection = 0;
+      continue;
+    }
+    if (node.type === 'mdxJsxFlowElement' && node.name === tagName) {
+      collectFromDetail(node);
+    } else if (
+      node.type === 'mdxJsxFlowElement' &&
+      (node.name === 'Memo' || node.name === 'ShortNote')
+    ) {
+      collectFromDetail(node);
     }
   }
   return floats;
 }
-

package/src/reference/knowledge-checks-validate.ts

@@ -0,0 +1,130 @@
+/** Build-time identity and reference validation for knowledge checks. */
+
+import {
+  collectKnowledgeChecks,
+  KNOWLEDGE_CHECK_KEY_PATTERN,
+  parseKnowledgeCheckRef,
+} from './knowledge-checks.mjs';
+
+export interface KnowledgeCheckLessonInput {
+  readonly lessonId: string;
+  readonly slug: string;
+  readonly file: string;
+  readonly body: string;
+  readonly assessmentIds: readonly string[];
+  readonly numbering?: { readonly prefix: number; readonly offset: number };
+}
+
+export interface KnowledgeCheckLabelRecord {
+  readonly key: string;
+  readonly number: string;
+  readonly lessonId: string;
+  readonly slug: string;
+  readonly indexInLesson: number;
+}
+
+export interface KnowledgeCheckDiagnostic {
+  readonly code:
+    | 'check-invalid-key'
+    | 'check-duplicate-key'
+    | 'check-ref-resolves';
+  readonly severity: 'error';
+  readonly message: string;
+  readonly file?: string;
+  readonly lessonId?: string;
+  readonly key?: string;
+}
+
+export interface KnowledgeCheckValidation {
+  readonly labels: readonly KnowledgeCheckLabelRecord[];
+  readonly numbersBySlug: Record<string, Record<string, string>>;
+  readonly diagnostics: readonly KnowledgeCheckDiagnostic[];
+}
+
+const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
+
+function stripCode(text: string): string {
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/~~~[\s\S]*?~~~/g, ' ')
+    .replace(/`[^`\n]*`/g, ' ');
+}
+
+export function validateKnowledgeChecks(
+  lessons: readonly KnowledgeCheckLessonInput[],
+): KnowledgeCheckValidation {
+  const labels: KnowledgeCheckLabelRecord[] = [];
+  const diagnostics: KnowledgeCheckDiagnostic[] = [];
+  const numbersBySlug: Record<string, Record<string, string>> = {};
+
+  for (const lesson of [...lessons].sort((a, b) =>
+    a.lessonId.localeCompare(b.lessonId),
+  )) {
+    const seen = new Set<string>();
+    const table: Record<string, string> = {};
+    for (const check of collectKnowledgeChecks(
+      lesson.assessmentIds,
+      lesson.numbering,
+    )) {
+      if (!KNOWLEDGE_CHECK_KEY_PATTERN.test(check.key)) {
+        diagnostics.push({
+          code: 'check-invalid-key',
+          severity: 'error',
+          message: `${lesson.lessonId} has a knowledge-check id "${check.key}" that is not a valid content key.`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          key: check.key,
+        });
+        continue;
+      }
+      if (seen.has(check.key)) {
+        diagnostics.push({
+          code: 'check-duplicate-key',
+          severity: 'error',
+          message: `${lesson.lessonId} lists knowledge check "${check.key}" twice; an assessment id is unique per lesson.`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          key: check.key,
+        });
+        continue;
+      }
+      seen.add(check.key);
+      table[check.key] = check.number;
+      labels.push({
+        ...check,
+        lessonId: lesson.lessonId,
+        slug: lesson.slug,
+      });
+    }
+    numbersBySlug[lesson.slug] = table;
+  }
+
+  for (const lesson of lessons) {
+    for (const match of stripCode(lesson.body).matchAll(BRACKET_REF)) {
+      const ref = parseKnowledgeCheckRef((match[1] ?? '').trim());
+      if (!ref) continue;
+      const targetSlug = ref.lesson ?? lesson.slug;
+      if (numbersBySlug[targetSlug]?.[ref.key] !== undefined) continue;
+      diagnostics.push({
+        code: 'check-ref-resolves',
+        severity: 'error',
+        message: ref.lesson
+          ? `${lesson.lessonId} references [[${ref.lesson}#check-${ref.key}]] but that lesson has no knowledge check "${ref.key}"`
+          : `${lesson.lessonId} references [[check-${ref.key}]] but its .checks.yml does not list "${ref.key}"`,
+        file: lesson.file,
+        lessonId: lesson.lessonId,
+        key: ref.key,
+      });
+    }
+  }
+
+  diagnostics.sort(
+    (a, b) =>
+      a.code.localeCompare(b.code) ||
+      (a.lessonId ?? '').localeCompare(b.lessonId ?? '') ||
+      (a.key ?? '').localeCompare(b.key ?? '') ||
+      a.message.localeCompare(b.message),
+  );
+
+  return { labels, numbersBySlug, diagnostics };
+}

package/src/reference/knowledge-checks.mjs

@@ -0,0 +1,45 @@
+/**
+ * Stable identity and numbering helpers for lesson knowledge checks.
+ *
+ * A course owns check titles and questions in `content/assessments/*.json`,
+ * then places their ids in a lesson's colocated `.checks.yml`. That ordered
+ * list is the check sequence: numbers run independently across each part,
+ * exactly like the equation/table/figure/diagram streams.
+ */
+
+/** Assessment ids use the content key grammar, including optional dots. */
+export const KNOWLEDGE_CHECK_KEY_PATTERN =
+  /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+
+/** `[[check-id]]`, or `[[lesson/slug#check-id]]` across pages. */
+export function parseKnowledgeCheckRef(raw) {
+  const match =
+    /^(?:([a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*)#)?check-([a-z0-9]+(?:[.-][a-z0-9]+)*)$/.exec(
+      String(raw).trim(),
+    );
+  if (!match) return undefined;
+  return match[1] ? { lesson: match[1], key: match[2] } : { key: match[2] };
+}
+
+/** The stable DOM fragment for a knowledge check. */
+export function knowledgeCheckAnchorId(key) {
+  return `check-${key}`;
+}
+
+/**
+ * Number an ordered assessment-id list. With manifest placement, the number
+ * is `part.offset + index`; without it, the list remains usefully page-local.
+ */
+export function collectKnowledgeChecks(assessmentIds, numbering) {
+  const prefix = Number.isInteger(numbering?.prefix) && numbering.prefix > 0
+    ? numbering.prefix
+    : undefined;
+  const offset = Number.isInteger(numbering?.offset) && numbering.offset >= 0
+    ? numbering.offset
+    : 0;
+  return assessmentIds.map((key, index) => ({
+    key,
+    number: prefix == null ? String(index + 1) : `${prefix}.${offset + index + 1}`,
+    indexInLesson: index + 1,
+  }));
+}

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

@@ -1,5 +1,9 @@
 import { loadManifest } from '../compiler/manifest';
 import type { LabMathScopeDefinition } from './render-lab-math';
+import {
+  registerPageNotationDependencies,
+  routeIdFromLocals,
+} from './page-notation';
 
 interface LessonNotationFrontmatter {
   readonly local?: ReadonlyArray<{
@@ -20,10 +24,16 @@ const EXPLAIN_KEY = /\\explain\s*\{([a-z0-9]+(?:[.-][a-z0-9]+)*)\}/g;
  *
  * Shared definitions are read from the one compiler manifest (Phase D5); this
  * module never re-reads the content tree.
+ *
+ * A nested component whose `body` contains notation absent from lesson MDX
+ * passes `{ locals: Astro.locals, context: 'Component formula name' }`. That
+ * request-local declaration lets `LessonFooter` ship just those extra cards and
+ * gives an unknown `\explain` key an actionable render-time diagnostic.
  */
 export async function labMathScope(
   notation: LessonNotationFrontmatter | undefined,
   body = '',
+  component?: { readonly locals: object; readonly context: string },
 ): Promise<LabMathScopeDefinition[]> {
   const local = notation?.local ?? [];
   const scope: LabMathScopeDefinition[] = local.map((definition) => ({
@@ -32,8 +42,12 @@ export async function labMathScope(
   }));
 
   const referenced = new Set<string>();
+  const explicitlyExplained = new Set<string>();
   for (const pattern of [TERM_KEY, EXPLAIN_KEY]) {
-    for (const match of body.matchAll(pattern)) referenced.add(match[1]);
+    for (const match of body.matchAll(pattern)) {
+      referenced.add(match[1]);
+      if (pattern === EXPLAIN_KEY) explicitlyExplained.add(match[1]);
+    }
   }
 
   const localKeys = new Set(local.map((definition) => definition.key));
@@ -44,10 +58,38 @@ export async function labMathScope(
       .map((definition) => [definition.key, definition]),
   );
 
+  const resolvedKeys = new Set<string>();
   for (const key of referenced) {
-    if (localKeys.has(key)) continue;
+    if (localKeys.has(key)) {
+      resolvedKeys.add(key);
+      continue;
+    }
     const shared = sharedByKey.get(key);
-    if (shared) scope.push({ key: shared.key, notation: shared.notation });
+    if (shared) {
+      scope.push({ key: shared.key, notation: shared.notation });
+      resolvedKeys.add(key);
+      continue;
+    }
+    // `[[...]]` also carries equation/table/figure/diagram references. The
+    // manifest validates those namespaces; an explicit \explain is always a
+    // notation dependency and can be diagnosed here without ambiguity.
+    if (explicitlyExplained.has(key)) {
+      throw new Error(
+        `Notation dependency error${
+          component
+            ? ` in lesson "${routeIdFromLocals(component.locals) ?? 'unknown'}" (${component.context})`
+            : ''
+        }: unknown key "${key}". Define it in notation.local or the shared notation registry.`,
+      );
+    }
+  }
+
+  if (component) {
+    registerPageNotationDependencies(
+      component.locals,
+      resolvedKeys,
+      component.context,
+    );
   }
 
   return scope;