explico 0.11.1 → 0.12.0

package/dist/reference/figure-symbols.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+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[];
+}
+/** The figures in `html` that draw a symbol with no card, and those symbols. */
+declare function unboundFigureSymbols(html: string): UnboundFigureSymbols[];
+/**
+ * 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.
+ */
+declare function assertFigureSymbolsBound(page: string, html: string): void;
+
+export { type UnboundFigureSymbols, assertFigureSymbolsBound, unboundFigureSymbols };

package/dist/reference/figure-symbols.js

@@ -0,0 +1,55 @@
+import { parse } from "parse5";
+const UPRIGHT = /* @__PURE__ */ new Set(["text", "mathrm", "textrm", "mop"]);
+const LETTER = new RegExp("\\p{L}", "u");
+function isElement(node) {
+  return "tagName" in node;
+}
+function attribute(node, name) {
+  return node.attrs.find((attr) => attr.name === name)?.value;
+}
+function classes(node) {
+  return (attribute(node, "class") ?? "").split(/\s+/u).filter(Boolean);
+}
+function childrenOf(node) {
+  if (isElement(node) && node.tagName === "template") {
+    return node.content.childNodes;
+  }
+  return "childNodes" in node ? node.childNodes : [];
+}
+function unboundFigureSymbols(html) {
+  if (!html.includes("keyed-figure") || !html.includes("katex-html")) return [];
+  const found = /* @__PURE__ */ new Map();
+  const visit = (node, figure, inKatex, covered) => {
+    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") !== void 0 || inKatex && names.some((name) => UPRIGHT.has(name))) {
+        covered = true;
+      }
+    } else if (node.nodeName === "#text" && figure !== void 0 && inKatex && !covered) {
+      const text = node.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), void 0, false, false);
+  return [...found].map(([figure, symbols]) => ({ figure, symbols }));
+}
+function assertFigureSymbolsBound(page, html) {
+  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{\u2026}`."
+  );
+}
+export {
+  assertFigureSymbolsBound,
+  unboundFigureSymbols
+};

package/dist/reference/gate-non-chapter-pages.d.ts

@@ -0,0 +1,39 @@
+import { MathGateDiagnostic } from './gate-math.js';
+import './types.js';
+
+/**
+ * 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.
+ */
+
+/** One non-chapter page, as the manifest compiler loads it. */
+interface NonChapterPageInput {
+    readonly file: string;
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly body: string;
+    readonly bodyLine: number;
+}
+/**
+ * Check every non-chapter page for what rule S10 keeps off it. Returns one
+ * `MathGateDiagnostic` (context `'structure'`, always an error) per finding.
+ */
+declare function gateNonChapterPages(pages: readonly NonChapterPageInput[]): MathGateDiagnostic[];
+
+export { type NonChapterPageInput, gateNonChapterPages };

package/dist/reference/gate-non-chapter-pages.js

@@ -0,0 +1,156 @@
+import { scannable } from "./gate-part-pages.js";
+import { lessonLine } from "./gate-prose-notation.js";
+const NUMBERED_BLOCKS = {
+  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 = /\$|\[\[/;
+function labComponentNames(text) {
+  const names = /* @__PURE__ */ new Set();
+  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) {
+  const findings = [];
+  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 = /* @__PURE__ */ new Set();
+  for (const name of labs) {
+    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\u2019s <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\u2019s <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\u2019s own with [[<chapter>#eq-<key>]].`
+    });
+  }
+  return findings;
+}
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function frontmatterFindings(data) {
+  const findings = [];
+  const notation = record(data.notation);
+  for (const field of ["local", "suspend"]) {
+    if (notation?.[field] === void 0) 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"]) {
+    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 $\u2026$ or [[\u2026]] prints literally (rule S10). Write the words here, and put the symbol in the page body, where it gets its card.`
+    });
+  }
+  return findings;
+}
+function chainFindings(text) {
+  const findings = [];
+  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 $\u2026$ or [[\u2026]] prints literally (rule S10). Write the step in words; a symbol with its card goes in <PartScope>."
+      });
+    }
+  }
+  return findings;
+}
+function gateNonChapterPages(pages) {
+  const diagnostics = [];
+  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;
+}
+export {
+  gateNonChapterPages
+};

package/dist/reference/gate-part-pages.d.ts

@@ -34,6 +34,8 @@ interface PartPageInput {
     readonly body: string;
     readonly bodyLine: number;
 }
+/** Blank MDX comments (`{/* … *\/}`) and code, keeping every newline. */
+declare function scannable(body: string): string;
 /**
  * Words a reader reads in a paragraph of MDX prose. A math span, a `[[key]]`
  * reference, or a link each count by what they render as: one token for the
@@ -47,4 +49,4 @@ declare function proseWordCount(markdown: string): number;
  */
 declare function gatePartPages(pages: readonly PartPageInput[], limits: NormalizedPartPages): MathGateDiagnostic[];
 
-export { type PartPageInput, gatePartPages, proseWordCount };
+export { type PartPageInput, gatePartPages, proseWordCount, scannable };

package/dist/reference/gate-part-pages.js

@@ -114,5 +114,6 @@ function gatePartPages(pages, limits) {
 }
 export {
   gatePartPages,
-  proseWordCount
+  proseWordCount,
+  scannable
 };

package/dist/reference/lab-katex-validate.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+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;
+}
+interface LabKatexLessonInput {
+    readonly lessonId: string;
+    /** Repository-relative path of the lesson file. */
+    readonly file: string;
+    readonly body: string;
+}
+/**
+ * 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.
+ */
+declare function importSpecifiers(source: string): string[];
+/**
+ * Each course file that a lesson's imports reach and that imports `katex`.
+ * `root` is the repository root the lesson paths are relative to.
+ */
+declare function validateLabKatexImports(lessons: readonly LabKatexLessonInput[], root?: string): LabKatexDiagnostic[];
+
+export { type LabKatexDiagnostic, type LabKatexLessonInput, importSpecifiers, validateLabKatexImports };

package/dist/reference/lab-katex-validate.js

@@ -0,0 +1,96 @@
+import { readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { stripFencedCode } from "./equations.mjs";
+const EXTENSIONS = [".astro", ".tsx", ".ts", ".jsx", ".js", ".mjs", ".mts", ".cjs"];
+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
+];
+function importSpecifiers(source) {
+  const found = [];
+  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);
+}
+function isKatexModule(specifier) {
+  if (specifier !== "katex" && !specifier.startsWith("katex/")) return false;
+  return !/\.(?:css|woff2?|ttf)$/u.test(specifier);
+}
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+function resolveRelative(fromFile, specifier) {
+  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);
+}
+function validateLabKatexImports(lessons, root = process.cwd()) {
+  const read = (path) => {
+    try {
+      return readFileSync(path, "utf8");
+    } catch {
+      return void 0;
+    }
+  };
+  const repoPath = (path) => relative(root, path).split(sep).join("/");
+  const diagnostics = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Set();
+  for (const lesson of [...lessons].sort((a, b) => a.lessonId.localeCompare(b.lessonId))) {
+    const lessonPath = join(root, lesson.file);
+    const queue = [
+      { 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(" \u2192 ")}). Render a lab's math with renderLabMath(template, scope) \u2014 { display: false } for a legend entry, an axis title or a label \u2014 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 === void 0) continue;
+        queue.push({ path: target, source: text, chain: [...chain, repoPath(target)] });
+      }
+    }
+  }
+  return [...diagnostics.values()].sort((a, b) => a.file.localeCompare(b.file));
+}
+export {
+  importSpecifiers,
+  validateLabKatexImports
+};

package/dist/reference/lint-ignore.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 const IGNORE_PATH = join(process.cwd(), "lint-ignore.yml");
-const LINE = /^-\s*([a-z0-9-]+)(?::([^\s—-][^—-]*?))?\s*(?:—|--|\s-\s)\s*(.+?)\s*$/;
+const LINE = /^-\s*([a-z0-9-]+)(?::([^\s—][^—]*?))?\s*(?:—|--|\s-\s)\s*(.+?)\s*$/;
 function parseLintIgnore(text) {
   const entries = [];
   for (const rawLine of text.split("\n")) {

package/dist/reference/page-notation.d.ts

@@ -16,6 +16,7 @@ import './examples-validate.js';
 import './folds-validate.js';
 import './knowledge-checks-validate.js';
 import './raw-floats-validate.js';
+import './lab-katex-validate.js';
 import './gate-math.js';
 import './mixed-content.js';
 import './gloss.js';
@@ -44,10 +45,11 @@ declare function notationKeysInMathNodes(nodes: readonly {
     readonly children?: readonly unknown[];
 }[]): string[];
 /**
- * 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).
  */
-declare function notationDefinitionsForRenderedPage(manifest: Manifest, lessonId: string, dependencies: readonly PageNotationDependency[]): ManifestLessonNotation[];
+declare function notationDefinitionsForRenderedPage(manifest: Manifest, pageId: string, dependencies: readonly PageNotationDependency[]): ManifestLessonNotation[];
 /**
  * Structural backstop over final HTML: every trigger must have a source entry
  * from which the popup enhancer can populate a card.

package/dist/reference/page-notation.js

@@ -66,14 +66,14 @@ function manifestDefinition(definition, cardsByKey) {
     ...definition.formula === void 0 ? {} : { formula: definition.formula }
   };
 }
-function notationDefinitionsForRenderedPage(manifest, lessonId, dependencies) {
-  const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
-  if (!lesson) return [];
+function notationDefinitionsForRenderedPage(manifest, pageId, dependencies) {
+  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 = /* @__PURE__ */ new Map();
   for (const dependency of dependencies) {
     let contexts = contextsByKey.get(dependency.key);
@@ -84,12 +84,12 @@ function notationDefinitionsForRenderedPage(manifest, lessonId, dependencies) {
     contexts.add(dependency.context);
     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} emitted data-notation-key="${dependency.key}", but that key is not defined in this lesson or the shared notation registry.`
+        `Notation payload error on page "${pageId}": ${dependency.context} emitted data-notation-key="${dependency.key}", but that key is not defined on this page or in the shared notation registry.`
       );
     }
     ids.add(definitionId);
@@ -124,7 +124,7 @@ function notationDefinitionsForRenderedPage(manifest, lessonId, dependencies) {
     if (previous && previous !== id) {
       const context = [...contextsByKey.get(definition.key) ?? []].join(", ");
       throw new Error(
-        `Notation payload error in lesson "${lessonId}": key "${definition.key}" would have two meanings (${previous} and ${id})` + (context ? ` after ${context} emitted it.` : ".")
+        `Notation payload error on page "${pageId}": key "${definition.key}" would have two meanings (${previous} and ${id})` + (context ? ` after ${context} emitted it.` : ".")
       );
     }
     definitionIdByKey.set(definition.key, id);
@@ -138,7 +138,7 @@ function notationDefinitionsForRenderedPage(manifest, lessonId, dependencies) {
     });
   }
   const existingById = new Map(
-    lesson.notation.definitions.map((definition) => [definition.id, definition])
+    page.notation.definitions.map((definition) => [definition.id, definition])
   );
   return [...ids].sort().flatMap((id) => {
     const existing = existingById.get(id);

package/dist/reference/raw-floats.mjs

@@ -12,11 +12,13 @@
  *   `keyed-jsx-floats.mjs`'s top-level-only scan entirely, so it never even
  *   reaches diagram numbering.
  *
- * A raw table nested in `<Table>`/`<Figure>` is the intended, wrapped case
- * and is not flagged; nesting inside anything else (`<CompactExample>`,
- * `<Aside>`, `<Memo>`, …) still is, because a raw table has no numbering
- * scheme of its own to opt into the way a `<Diagram>`'s top-level/`<Memo>`-
- * transparent scan does.
+ * A raw table counts only where wrapping it would number it: at the top level
+ * of the lesson body or in a `TRANSPARENT_COMPONENTS` body (`<Memo>`,
+ * `<ShortNote>`, `<Fold>`), exactly where `keyed-jsx-floats.mjs` numbers a
+ * `<Table>`. A raw table in `<Table>`/`<Figure>` is the intended, wrapped
+ * case; one in any other component (a worked example's `<CompactExample>`,
+ * an `<Aside>`) is illustrative, like an equation there, and a `<Table>`
+ * there would get no number — so neither is flagged.
  *
  * `scanRawFloats` (raw Markdown, for the manifest builder) and
  * `collectRawFloats` (mdast, for `remark-notation.mjs`) MUST agree on counts
@@ -24,7 +26,11 @@
  * `keyed-jsx-floats.mjs` holds `scanKeyedJsxFloats`/`collectKeyedJsxFloats` to.
  */
 
-import { stripFencedCode } from './equations.mjs';
+import {
+  stripFencedCode,
+  stripJsxComponents,
+  TRANSPARENT_COMPONENTS,
+} from './equations.mjs';
 import { collectKeyedJsxFloats, scanKeyedJsxFloats } from './keyed-jsx-floats.mjs';
 
 /** Blank `<Table>…</Table>` and `<Figure>…</Figure>` bodies — legitimately wrapped, not raw. */
@@ -67,9 +73,16 @@ function findDiagramTags(text) {
 export function scanRawFloats(markdown) {
   const codeStripped = stripFencedCode(String(markdown));
   const withoutWrappedFloats = blankFloatWrappers(codeStripped);
+  // Every component body but a transparent one is blanked — `<Table>` and
+  // `<Figure>` among them — so only the tables a `<Table>` would number remain.
+  const numberableText = stripJsxComponents(
+    codeStripped,
+    undefined,
+    TRANSPARENT_COMPONENTS,
+  );
 
-  const markdownTableCount = findMarkdownTableStarts(withoutWrappedFloats).length;
-  const htmlTableCount = findHtmlTableTags(withoutWrappedFloats).length;
+  const markdownTableCount = findMarkdownTableStarts(numberableText).length;
+  const htmlTableCount = findHtmlTableTags(numberableText).length;
 
   const diagramsOutsideWrappers = findDiagramTags(withoutWrappedFloats).length;
   const visibleDiagrams = scanKeyedJsxFloats(markdown, { tagName: 'Diagram' });
@@ -95,7 +108,10 @@ export function collectRawFloats(tree) {
   const htmlTableNodes = [];
   const allDiagramNodes = [];
 
-  const walk = (node) => {
+  // `numberable`: a `<Table>` here would be numbered — the top level, or a
+  // transparent component's body. Any other MDX component (a capitalized
+  // name, the ones `stripJsxComponents` blanks) ends it for its subtree.
+  const walk = (node, numberable) => {
     if (!node || typeof node !== 'object') return;
     if (
       node.type === 'mdxJsxFlowElement' &&
@@ -103,18 +119,26 @@ export function collectRawFloats(tree) {
     ) {
       return; // legitimately wrapped — don't descend
     }
-    if (node.type === 'table') markdownTableNodes.push(node);
-    if (node.type === 'html' && /<table\b/i.test(String(node.value ?? ''))) {
+    if (numberable && node.type === 'table') markdownTableNodes.push(node);
+    if (
+      numberable &&
+      node.type === 'html' &&
+      /<table\b/i.test(String(node.value ?? ''))
+    ) {
       htmlTableNodes.push(node);
     }
     if (node.type === 'mdxJsxFlowElement' && node.name === 'Diagram') {
       allDiagramNodes.push(node);
     }
+    const component =
+      (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') &&
+      /^[A-Z]/.test(String(node.name ?? '')) &&
+      !TRANSPARENT_COMPONENTS.includes(node.name);
     if (Array.isArray(node.children)) {
-      for (const child of node.children) walk(child);
+      for (const child of node.children) walk(child, numberable && !component);
     }
   };
-  walk(tree);
+  walk(tree, true);
 
   const visibleDiagrams = collectKeyedJsxFloats(tree, { tagName: 'Diagram' });
   const visibleNodes = new Set(visibleDiagrams.map((diagram) => diagram.node));

package/dist/reference/registry.js

@@ -106,6 +106,13 @@ function buildNotationRegistry(rawInput) {
     );
   }
   detectCycles(definitions, edgeIndex, diagnostics);
+  const localIdsByLesson = /* @__PURE__ */ new Map();
+  for (const candidate of definitions.values()) {
+    if (candidate.kind !== "local") continue;
+    const ids = localIdsByLesson.get(candidate.lesson.lessonId) ?? [];
+    ids.push(candidate.id);
+    localIdsByLesson.set(candidate.lesson.lessonId, ids);
+  }
   const bundles = [];
   const backlinks = [];
   const reachableDefinitions = /* @__PURE__ */ new Set();
@@ -114,7 +121,10 @@ function buildNotationRegistry(rawInput) {
     const directIds = new Set(
       references.map((reference) => reference.definitionId)
     );
-    const definitionIds = transitiveClosure(directIds, edgeIndex);
+    const definitionIds = transitiveClosure(
+      /* @__PURE__ */ new Set([...directIds, ...localIdsByLesson.get(lesson.lessonId) ?? []]),
+      edgeIndex
+    );
     for (const id of definitionIds) reachableDefinitions.add(id);
     const bindingByKey = /* @__PURE__ */ new Map();
     for (const reference of references) {