explico 0.4.0 → 0.5.0

package/dist/reference/gate-prose-notation.js

@@ -0,0 +1,125 @@
+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;
+const IMPORT_LINE = /^[ \t]*import\b[^\n]*$/gm;
+const KEY_REFERENCE = /\[\[[^\]\n]*\]\]/g;
+const JSX_TAG = /<\/?[A-Za-z][^<>]*>/g;
+function proseOnly(body) {
+  const blank = (match) => match.replace(/[^\n]/g, " ");
+  return body.replace(CODE_FENCE, blank).replace(INLINE_CODE, (match, lead) => 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);
+}
+function lineOf(text, index) {
+  return text.slice(0, index).split("\n").length;
+}
+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");
+const SLASH_IDIOMS = /* @__PURE__ */ 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;
+const FAKE_SCRIPT = /[A-Za-z0-9][_^][A-Za-z0-9{]/g;
+function findAll(text, pattern, toFinding) {
+  const out = [];
+  const re = new RegExp(pattern.source, pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`);
+  let match;
+  while (match = re.exec(text)) {
+    out.push(toFinding(match));
+    if (match[0].length === 0) re.lastIndex++;
+  }
+  return out;
+}
+const FIX = "Wrap it in $\u2026$ (or $$\u2026$$) instead \u2014 see docs/authoring/notation.md#n9.";
+function findingsIn(text) {
+  return [
+    ...findAll(text, /\\\|/g, (m) => ({
+      index: m.index,
+      token: m[0],
+      message: `Escaped pipe ${JSON.stringify(m[0])} outside math. Use \\lvert\u2026\\rvert for an absolute value or norm inside $\u2026$, 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;
+      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)
+  ];
+}
+function gateProseNotation(lessons) {
+  const diagnostics = [];
+  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;
+}
+function gateProseNotationInAssessments(assessments) {
+  const diagnostics = [];
+  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;
+}
+export {
+  gateProseNotation,
+  gateProseNotationInAssessments,
+  lineOf,
+  proseOnly
+};

package/dist/reference/keyed-float-validate.d.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.
  */
 interface KeyedFloatKind {
     /** The MDX component tag, e.g. `Table` or `Figure`. */

package/dist/reference/keyed-jsx-floats.d.mts

@@ -44,21 +44,16 @@ export function countKeyedJsxFloats(markdown: any, { tagName }: {
     tagName: any;
 }): number;
 /**
- * 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: any, { tagName, numbering }: {
     tagName: any;
     numbering: any;
-}): {
-    key: any;
-    number: string;
-    section: number;
-    indexInSection: number;
-    node: any;
-}[];
+}): any[];
 /** Same shape as `EQ_KEY_PATTERN` — the notation-key grammar without dots. */
 export const KEYED_FLOAT_KEY_PATTERN: RegExp;

package/dist/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/dist/reference/knowledge-checks-validate.d.ts

@@ -0,0 +1,35 @@
+/** Build-time identity and reference validation for knowledge checks. */
+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;
+    };
+}
+interface KnowledgeCheckLabelRecord {
+    readonly key: string;
+    readonly number: string;
+    readonly lessonId: string;
+    readonly slug: string;
+    readonly indexInLesson: number;
+}
+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;
+}
+interface KnowledgeCheckValidation {
+    readonly labels: readonly KnowledgeCheckLabelRecord[];
+    readonly numbersBySlug: Record<string, Record<string, string>>;
+    readonly diagnostics: readonly KnowledgeCheckDiagnostic[];
+}
+declare function validateKnowledgeChecks(lessons: readonly KnowledgeCheckLessonInput[]): KnowledgeCheckValidation;
+
+export { type KnowledgeCheckDiagnostic, type KnowledgeCheckLabelRecord, type KnowledgeCheckLessonInput, type KnowledgeCheckValidation, validateKnowledgeChecks };

package/dist/reference/knowledge-checks-validate.js

@@ -0,0 +1,78 @@
+import {
+  collectKnowledgeChecks,
+  KNOWLEDGE_CHECK_KEY_PATTERN,
+  parseKnowledgeCheckRef
+} from "./knowledge-checks.mjs";
+const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
+function stripCode(text) {
+  return text.replace(/```[\s\S]*?```/g, " ").replace(/~~~[\s\S]*?~~~/g, " ").replace(/`[^`\n]*`/g, " ");
+}
+function validateKnowledgeChecks(lessons) {
+  const labels = [];
+  const diagnostics = [];
+  const numbersBySlug = {};
+  for (const lesson of [...lessons].sort(
+    (a, b) => a.lessonId.localeCompare(b.lessonId)
+  )) {
+    const seen = /* @__PURE__ */ new Set();
+    const table = {};
+    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] !== void 0) 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 };
+}
+export {
+  validateKnowledgeChecks
+};

package/dist/reference/knowledge-checks.d.mts

@@ -0,0 +1,25 @@
+/** `[[check-id]]`, or `[[lesson/slug#check-id]]` across pages. */
+export function parseKnowledgeCheckRef(raw: any): {
+    lesson: string;
+    key: string;
+} | {
+    key: string;
+    lesson?: undefined;
+} | undefined;
+/** The stable DOM fragment for a knowledge check. */
+export function knowledgeCheckAnchorId(key: any): string;
+/**
+ * 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: any, numbering: any): any;
+/**
+ * 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: RegExp;

package/dist/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/dist/reference/lab-math-scope.d.ts

@@ -15,7 +15,15 @@ interface LessonNotationFrontmatter {
  *
  * 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.
  */
-declare function labMathScope(notation: LessonNotationFrontmatter | undefined, body?: string): Promise<LabMathScopeDefinition[]>;
+declare function labMathScope(notation: LessonNotationFrontmatter | undefined, body?: string, component?: {
+    readonly locals: object;
+    readonly context: string;
+}): Promise<LabMathScopeDefinition[]>;
 
 export { labMathScope };

package/dist/reference/lab-math-scope.js

@@ -1,25 +1,53 @@
 import { loadManifest } from "../compiler/manifest.js";
+import {
+  registerPageNotationDependencies,
+  routeIdFromLocals
+} from "./page-notation.js";
 const TERM_KEY = /\[\[\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\]\]/g;
 const EXPLAIN_KEY = /\\explain\s*\{([a-z0-9]+(?:[.-][a-z0-9]+)*)\}/g;
-async function labMathScope(notation, body = "") {
+async function labMathScope(notation, body = "", component) {
   const local = notation?.local ?? [];
   const scope = local.map((definition) => ({
     key: definition.key,
     notation: definition.latex
   }));
   const referenced = /* @__PURE__ */ new Set();
+  const explicitlyExplained = /* @__PURE__ */ new Set();
   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));
   const manifest = await loadManifest();
   const sharedByKey = new Map(
     manifest.notation.definitions.filter((definition) => definition.kind === "shared").map((definition) => [definition.key, definition])
   );
+  const resolvedKeys = /* @__PURE__ */ new Set();
   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;
+    }
+    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;
 }

package/dist/reference/math-glyphs.d.mts

@@ -1,3 +1,16 @@
+/**
+ * Strip Explico's own `\explain{key}{latex}` / `\slot{key}{latex}` markers
+ * (see `katex-options.mjs`) down to the LaTeX they wrap, recursively. Lesson
+ * math — both a notation card's `formula` and an equation written directly
+ * in prose — carries these markers inline so every symbol is hoverable; a
+ * reader copying the equation out of this system wants the plain math
+ * underneath, not internal notation-key plumbing that means nothing to
+ * KaTeX, MathJax, or LaTeX anywhere else. Shared by `render-notation-math.ts`
+ * (a notation card's copy button) and `remark-notation.mjs` (a numbered
+ * display equation's copy button) — kept here, rather than in either, so
+ * neither module has to import the other.
+ */
+export function stripNotationMarkers(latex: any): string;
 /**
  * Resolve and annotate one KaTeX expression against a page's flat glyph table.
  * Source offsets in the result always refer to the original, unmodified LaTeX.
@@ -36,6 +49,23 @@ export function collectOperators(latex: string): Array<{
     name: string;
     source: "named" | "operatorname";
 }>;
+/**
+ * Every multi-letter `\mathrm{…}` label in one KaTeX expression (`KE`, `PV`,
+ * `opt`) — the upright-label counterpart to {@link collectOperators}. A
+ * single-letter body (`\mathrm{d}`, the N7 differential) is not collected:
+ * that one is a fixed typographic operator, not a named quantity a reader
+ * would need explained.
+ *
+ * Pure read: nothing here rewrites the source. Used by the
+ * `roman-label-explained` consistency check (rule N10); the glyph resolver
+ * still skips `\mathrm{…}` bodies whole ([N3](../../docs/authoring/notation.md#n3)).
+ *
+ * @param {string} latex
+ * @returns {Array<{ name: string }>}
+ */
+export function collectRomanLabels(latex: string): Array<{
+    name: string;
+}>;
 /**
  * Page-level glyph-map resolver (cleanup plan, D1 decision 2026-09-02).
  *