explico 0.3.0 → 0.5.0

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

@@ -20,15 +20,16 @@ export function parseKeyedFloatRef(raw: any, { prefix }: {
 /**
  * The raw-text equivalent of `collectKeyedJsxFloats`, mirroring
  * `scanEquationLabels`: every top-level `<TagName …>` in appearance order.
- * With `chapter` (the lesson's course ordinal) the number is `‹chapter›.‹n›`,
- * `n` sequential over the whole lesson; without it, `##` headings advance a
- * section counter. Other JSX components' bodies are blanked first so a
- * `<Table>` nested inside e.g. `<CompactExample>` (and any `##`-like text
- * inside an unrelated component) is never counted.
+ * With `numbering` (`{ prefix, offset }` — the part's ordinal and the count of
+ * this kind of float in earlier lessons of that part) the number is
+ * `‹part›.‹offset + n›`, `n` sequential over the whole lesson; without it, `##`
+ * headings advance a section counter. Other JSX components' bodies are blanked
+ * first so a `<Table>` nested inside e.g. `<CompactExample>` (and any `##`-like
+ * text inside an unrelated component) is never counted.
  */
-export function scanKeyedJsxFloats(markdown: any, { tagName, chapter }: {
+export function scanKeyedJsxFloats(markdown: any, { tagName, numbering }: {
     tagName: any;
-    chapter: any;
+    numbering: any;
 }): {
     key: string | null | undefined;
     number: string;
@@ -36,21 +37,23 @@ export function scanKeyedJsxFloats(markdown: any, { tagName, chapter }: {
     indexInSection: 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`. `chapter`
- * is threaded the same way as in `scanKeyedJsxFloats`.
+ * How many floats of this kind a lesson body holds — the input to the next
+ * lesson's `offset` within the same part.
  */
-export function collectKeyedJsxFloats(tree: any, { tagName, chapter }: {
+export function countKeyedJsxFloats(markdown: any, { tagName }: {
     tagName: any;
-    chapter: any;
-}): {
-    key: any;
-    number: string;
-    section: number;
-    indexInSection: number;
-    node: any;
-}[];
+}): number;
+/**
+ * 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;
+}): 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 —
@@ -22,7 +22,11 @@
  * `equations.test.ts` holds equations to.
  */
 
-import { stripFencedCode, stripJsxComponents } from './equations.mjs';
+import {
+  resolveNumbering,
+  stripFencedCode,
+  stripJsxComponents,
+} from './equations.mjs';
 
 /** Same shape as `EQ_KEY_PATTERN` — the notation-key grammar without dots. */
 export const KEYED_FLOAT_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -33,15 +37,22 @@ function floatNumber(section, index) {
 }
 
 /**
- * The visible number for one float. With `chapter` (the lesson's course
- * ordinal) the scheme is `‹chapter›.‹indexInLesson›` and `##` headings are
- * ignored; without it, the legacy `##`-section scheme. Mirrors
- * `displayEquationNumber` in `equations.mjs`.
+ * The visible number for one float. With a `prefix` (the part's ordinal) the
+ * 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>` or `<Diagram>` sequence — so `offset` is per kind too.
  */
-function keyedFloatNumber({ chapter, section, indexInSection, indexInLesson }) {
-  return chapter == null
+function keyedFloatNumber({
+  prefix,
+  offset = 0,
+  section,
+  indexInSection,
+  indexInLesson,
+}) {
+  return prefix == null
     ? floatNumber(section, indexInSection)
-    : `${chapter}.${indexInLesson}`;
+    : `${prefix}.${offset + indexInLesson}`;
 }
 
 /** The anchor id for a float, e.g. `{prefix:'tab', key:'foo'}` → `tab-foo`. */
@@ -71,14 +82,19 @@ function readIdAttribute(attributesSource) {
 /**
  * The raw-text equivalent of `collectKeyedJsxFloats`, mirroring
  * `scanEquationLabels`: every top-level `<TagName …>` in appearance order.
- * With `chapter` (the lesson's course ordinal) the number is `‹chapter›.‹n›`,
- * `n` sequential over the whole lesson; without it, `##` headings advance a
- * section counter. Other JSX components' bodies are blanked first so a
- * `<Table>` nested inside e.g. `<CompactExample>` (and any `##`-like text
- * inside an unrelated component) is never counted.
+ * With `numbering` (`{ prefix, offset }` — the part's ordinal and the count of
+ * this kind of float in earlier lessons of that part) the number is
+ * `‹part›.‹offset + n›`, `n` sequential over the whole lesson; without it, `##`
+ * headings advance a section counter. Other JSX components' bodies are blanked
+ * first so a `<Table>` nested inside e.g. `<CompactExample>` (and any `##`-like
+ * text inside an unrelated component) is never counted.
  */
-export function scanKeyedJsxFloats(markdown, { tagName, chapter }) {
-  const text = stripJsxComponents(stripFencedCode(markdown), tagName);
+export function scanKeyedJsxFloats(markdown, { tagName, numbering }) {
+  const { prefix, offset } = resolveNumbering(numbering);
+  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');
@@ -106,7 +122,8 @@ export function scanKeyedJsxFloats(markdown, { tagName, chapter }) {
     labels.push({
       key: token.key,
       number: keyedFloatNumber({
-        chapter,
+        prefix,
+        offset,
         section,
         indexInSection,
         indexInLesson,
@@ -119,26 +136,30 @@ export function scanKeyedJsxFloats(markdown, { tagName, chapter }) {
 }
 
 /**
- * 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`. `chapter`
- * is threaded the same way as in `scanKeyedJsxFloats`.
+ * How many floats of this kind a lesson body holds — the input to the next
+ * lesson's `offset` within the same part.
  */
-export function collectKeyedJsxFloats(tree, { tagName, chapter }) {
+export function countKeyedJsxFloats(markdown, { tagName }) {
+  return scanKeyedJsxFloats(markdown, { tagName }).length;
+}
+
+/**
+ * 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);
   const floats = [];
   let section = 0;
   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;
@@ -151,7 +172,8 @@ export function collectKeyedJsxFloats(tree, { tagName, chapter }) {
       floats.push({
         key: key ?? null,
         number: keyedFloatNumber({
-          chapter,
+          prefix,
+          offset,
           section,
           indexInSection,
           indexInLesson,
@@ -160,8 +182,35 @@ export function collectKeyedJsxFloats(tree, { tagName, chapter }) {
         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).
  *