explico 0.3.0 → 0.5.0

package/dist/reference/equations.mjs

@@ -2,12 +2,17 @@
  * Equation identity (Step D7, extended F3) — shared, framework-free helpers.
  *
  * Every display equation (`$$…$$`) in a lesson is numbered and given an `id`
- * from appearance order. When the caller supplies a `chapter` (the lesson's
- * ordinal position in the course), the number is `‹chapter›.‹n›` — `n` counts
- * every display equation in the lesson and `##` headings do not affect it
- * (`(2.4)` = fourth display equation of the second lesson). With no `chapter`
- * the number falls back to the `##`-section scheme `‹section›.‹indexInSection›`
- * (used by hand-built test trees and non-lesson pages). An author additionally
+ * from appearance order. When the caller supplies `numbering`
+ * (`{ prefix, offset }` — see `resolveNumbering`), the number is
+ * `‹part›.‹offset + n›`: the prefix is the **part**'s ordinal among the sidebar
+ * groups, `n` counts every display equation in the lesson, and `offset` carries
+ * the count from earlier lessons of the same part so the sequence runs
+ * continuously across a part rather than restarting on every page. `##` and
+ * `###` headings never affect it — `(2.4)` is the fourth display equation of
+ * part 2, wherever in that part it sits. See `docs/authoring/structure.md` for
+ * the level names. With no `numbering` the number falls back to the
+ * `##`-section scheme `‹section›.‹indexInSection›` (used by hand-built test
+ * trees and non-lesson pages). An author additionally
  * marks an equation with a trailing `\label{eq:<key>}` inside its `$$…$$`
  * block (inside math, so the `:` is safe and the form matches amsmath) when
  * they want a *stable* anchor that survives edits and cross-page references:
@@ -63,19 +68,42 @@ function equationNumber(section, index) {
 }
 
 /**
- * The visible number for one display equation. With `chapter` (the lesson's
- * course ordinal) the scheme is `‹chapter›.‹indexInLesson›` and `##` headings
+ * Normalise the numbering input to `{ prefix, offset }`.
+ *
+ * `prefix` is the number before the dot — the **part**'s ordinal (its position
+ * among the sidebar groups). `offset` is how many display equations already
+ * appeared in earlier lessons of that same part, so `n` runs continuously
+ * across a part instead of restarting on every page. A bare number is the
+ * legacy per-lesson form (`prefix = n`, `offset = 0`) and is still accepted so
+ * hand-built trees and unit tests keep working. `undefined`/`null`/`0` ⇒ the
+ * `##`-section fallback for non-lesson pages.
+ */
+export function resolveNumbering(input) {
+  if (input == null) return { prefix: undefined, offset: 0 };
+  if (typeof input === 'number') {
+    return { prefix: input || undefined, offset: 0 };
+  }
+  return {
+    prefix: input.prefix || undefined,
+    offset: Number(input.offset) || 0,
+  };
+}
+
+/**
+ * The visible number for one display equation. With a `prefix` (the part's
+ * ordinal) the scheme is `‹part›.‹offset + indexInLesson›` and `##` headings
  * are ignored; without it, the legacy `##`-section scheme.
  */
 export function displayEquationNumber({
-  chapter,
+  prefix,
+  offset = 0,
   section,
   indexInSection,
   indexInLesson,
 }) {
-  return chapter == null
+  return prefix == null
     ? equationNumber(section, indexInSection)
-    : `${chapter}.${indexInLesson}`;
+    : `${prefix}.${offset + indexInLesson}`;
 }
 
 /** The positional anchor id for an unkeyed equation, e.g. `2.4` → `eq-2-4`. */
@@ -100,25 +128,58 @@ export function stripFencedCode(markdown) {
  * `keep`, when given, leaves a component of that name untouched instead of
  * blanking it — `keyed-jsx-floats.mjs` uses this to blank every *other*
  * component while still finding `<Table>`/`<Figure>` tags at the top level.
+ *
+ * `transparent`, when given, removes only those components' opening/closing
+ * tags and exposes their body to the later blanking pass. `<Memo>` and
+ * `<ShortNote>` are intentional uses: unlike a worked-example/presentation
+ * wrapper, their bodies are details in the lesson's reading order, so numbered
+ * equations/floats in them stay in the official sequence. Section headings in
+ * a transparent body do not change the surrounding page's section counter.
  */
-export function stripJsxComponents(markdown, keep) {
-  return String(markdown).replace(
+export function stripJsxComponents(markdown, keep, transparent = []) {
+  let source = String(markdown);
+  const attributes = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'])*`;
+  for (const name of transparent) {
+    const component = new RegExp(
+      `<${name}\\b${attributes}>([\\s\\S]*?)<\\/${name}\\s*>`,
+      'g',
+    );
+    source = source.replace(component, (block, body) => {
+      const bodyStart = block.indexOf(body);
+      const visibleBody = body.replace(
+        /(^|\n)([ \t]{0,3})##(?=[ \t]+\S)/g,
+        (match) => match.replace(/#/g, ' '),
+      );
+      return (
+        block.slice(0, bodyStart).replace(/[^\n]/g, ' ') +
+        visibleBody +
+        block.slice(bodyStart + body.length).replace(/[^\n]/g, ' ')
+      );
+    });
+  }
+  return source.replace(
     /<([A-Z][A-Za-z0-9]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>/g,
     (block, name) => (name === keep ? block : block.replace(/[^\n]/g, ' ')),
   );
 }
 
 /**
- * Every keyed display equation in a Markdown body, in appearance order, with
- * its assigned number. `$$…$$` blocks only. With `chapter` (the lesson's
- * course ordinal) the number is `‹chapter›.‹n›`, `n` sequential over every
- * display block in the lesson; without it, `##` headings advance a section
- * counter and the number is `‹section›.‹indexInSection›`. Either way every
- * display block advances the index, so a keyed equation's number reflects its
- * position among *all* display equations, not only the keyed ones.
+ * Every display equation in a Markdown body, keyed or not, in appearance order
+ * with its assigned number. `$$…$$` blocks only. With `numbering`
+ * (`{ prefix, offset }`, the part's ordinal and the count of display equations
+ * in earlier lessons of that part) the number is `‹part›.‹offset + n›`, `n`
+ * sequential over every display block in the lesson; without it, `##` headings
+ * advance a section counter and the number is `‹section›.‹indexInSection›`.
+ * Either way every display block advances the index, so a keyed equation's
+ * number reflects its position among *all* display equations, not only the
+ * keyed ones.
  */
-export function scanEquationLabels(markdown, chapter) {
-  const text = stripJsxComponents(stripFencedCode(markdown));
+export function scanDisplayEquations(markdown, numbering) {
+  const { prefix, offset } = resolveNumbering(numbering);
+  const text = stripJsxComponents(stripFencedCode(markdown), undefined, [
+    'Memo',
+    'ShortNote',
+  ]);
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
   const display = /\$\$([\s\S]+?)\$\$/g;
@@ -148,11 +209,11 @@ export function scanEquationLabels(markdown, chapter) {
     }
     indexInSection += 1;
     indexInLesson += 1;
-    if (token.key == null) continue;
     labels.push({
       key: token.key,
       number: displayEquationNumber({
-        chapter,
+        prefix,
+        offset,
         section,
         indexInSection,
         indexInLesson,
@@ -164,30 +225,43 @@ export function scanEquationLabels(markdown, chapter) {
   return labels;
 }
 
+/** The keyed subset of `scanDisplayEquations` — the manifest builder's view. */
+export function scanEquationLabels(markdown, numbering) {
+  return scanDisplayEquations(markdown, numbering).filter(
+    (equation) => equation.key != null,
+  );
+}
+
+/**
+ * How many display equations a lesson body holds. This is what makes `n` run
+ * continuously across a part: a lesson's `offset` is the sum of this over every
+ * earlier lesson in the same part.
+ */
+export function countDisplayEquations(markdown) {
+  return scanDisplayEquations(markdown).length;
+}
+
 /**
  * The mdast equivalent of `scanEquationLabels` for *every* display equation:
  * walk the tree in document order, advancing the section counter on every
  * depth-2 heading and emitting a record for every `math` node. `key` is the
- * `\label{eq:…}` payload when present, else `null`. `chapter` is threaded the
+ * `\label{eq:…}` payload when present, else `null`. `numbering` is threaded the
  * same way as in `scanEquationLabels`.
  */
-export function collectDisplayEquations(tree, chapter) {
+export function collectDisplayEquations(tree, numbering) {
+  const { prefix, offset } = resolveNumbering(numbering);
   const equations = [];
   let section = 0;
   let indexInSection = 0;
   let indexInLesson = 0;
 
-  // Only top-level blocks: a `$$…$$` nested in an MDX component (a
-  // `<CompactExample>` worked example, an `<Aside>`) is illustrative, not part
-  // of the lesson's equation sequence, and its container may be collapsed.
-  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;
-    }
+  // Top-level blocks plus the bodies of `<Memo>` and `<ShortNote>`: other MDX
+  // components (a `<CompactExample>` worked example, an `<Aside>`) remain
+  // illustrative and outside the lesson's official equation sequence. These
+  // two detail components are deliberately transparent because they occupy an
+  // exact point in the reading order, even while visually collapsed.
+  const collectFromDetail = (node) => {
+    if (!node || typeof node !== 'object') return;
     if (node.type === 'math') {
       indexInSection += 1;
       indexInLesson += 1;
@@ -196,7 +270,8 @@ export function collectDisplayEquations(tree, chapter) {
       equations.push({
         key: label ? label[1] : null,
         number: displayEquationNumber({
-          chapter,
+          prefix,
+          offset,
           section,
           indexInSection,
           indexInLesson,
@@ -205,6 +280,33 @@ export function collectDisplayEquations(tree, 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 === 'math') collectFromDetail(node);
+    else if (
+      node.type === 'mdxJsxFlowElement' &&
+      (node.name === 'Memo' || node.name === 'ShortNote')
+    ) {
+      collectFromDetail(node);
     }
   }
   return equations;
@@ -214,8 +316,8 @@ export function collectDisplayEquations(tree, chapter) {
  * The keyed subset of `collectDisplayEquations` — the tree-walk counterpart of
  * `scanEquationLabels`. Numbers reflect position among all display equations.
  */
-export function collectEquationLabels(tree, chapter) {
-  return collectDisplayEquations(tree, chapter).filter(
+export function collectEquationLabels(tree, numbering) {
+  return collectDisplayEquations(tree, numbering).filter(
     (equation) => equation.key != null,
   );
 }

package/dist/reference/gate-abbreviations.d.ts

@@ -0,0 +1,17 @@
+import { MathGateDiagnostic } from './gate-math.js';
+import { NotationRegistryInput, AbbreviationDefinitionInput } from './types.js';
+import { CourseAbbreviations } from '../compiler/course-config.js';
+
+/**
+ * Scan every lesson body for an abbreviation-shaped token outside `$…$` that
+ * is neither universal nor explained. Returns one `MathGateDiagnostic`
+ * (context `'abbreviation'`, always an error) per unresolved token, deduped
+ * per lesson so a term used many times on one page is reported once.
+ */
+declare function gateAbbreviations(input: {
+    readonly notationInput: NotationRegistryInput;
+    readonly abbreviations: readonly AbbreviationDefinitionInput[];
+    readonly courseAbbreviations?: CourseAbbreviations;
+}): MathGateDiagnostic[];
+
+export { gateAbbreviations };

package/dist/reference/gate-abbreviations.js

@@ -0,0 +1,64 @@
+import { collectOperators, collectRomanLabels } from "./math-glyphs.mjs";
+import { isBaseAbbreviation } from "./base-abbreviations.mjs";
+import { pageScope } from "./gate-math.js";
+import { lineOf, proseOnly } from "./gate-prose-notation.js";
+const CAPS_RUN = /\b([A-Z]{2,})(?:'s|s)?\b/g;
+const DOTTED_ABBR = /\b(?:[A-Za-z]\.){2,}/g;
+function findAbbreviationLikeTokens(text) {
+  const out = [];
+  for (const match of text.matchAll(CAPS_RUN)) {
+    out.push({ token: match[1] ?? match[0], index: match.index ?? 0 });
+  }
+  for (const match of text.matchAll(DOTTED_ABBR)) {
+    out.push({ token: match[0], index: match.index ?? 0 });
+  }
+  return out.sort((a, b) => a.index - b.index);
+}
+const FIX = "Add it to an abbreviations-table entry (content/abbreviations/*.md), allowlist it in abbreviations.allow in course.config.ts if it is common, non-technical usage, or \u2014 if it names a math quantity \u2014 introduce it as \\mathrm{\u2026} (or \\operatorname{\u2026}) bound to a notation entry the reader can hover. See docs/authoring/notation.md#n14.";
+function gateAbbreviations(input) {
+  const { notationInput, abbreviations, courseAbbreviations } = input;
+  const tableTokens = /* @__PURE__ */ new Set();
+  for (const entry of abbreviations) {
+    tableTokens.add(entry.abbr);
+    for (const alias of entry.aliases) tableTokens.add(alias);
+  }
+  const sharedByKey = new Map(
+    notationInput.sharedDefinitions.map((definition) => [
+      definition.key,
+      { key: definition.key, notation: definition.notation }
+    ])
+  );
+  const diagnostics = [];
+  for (const lesson of notationInput.lessons) {
+    const mathQuantityNames = /* @__PURE__ */ new Set();
+    for (const entry of pageScope(lesson, sharedByKey)) {
+      for (const label of collectRomanLabels(entry.notation)) {
+        mathQuantityNames.add(label.name);
+      }
+      for (const operator of collectOperators(entry.notation)) {
+        mathQuantityNames.add(operator.name);
+      }
+    }
+    const text = proseOnly(lesson.body);
+    const reported = /* @__PURE__ */ new Set();
+    for (const { token, index } of findAbbreviationLikeTokens(text)) {
+      if (reported.has(token)) continue;
+      if (isBaseAbbreviation(token, courseAbbreviations)) continue;
+      if (tableTokens.has(token)) continue;
+      if (mathQuantityNames.has(token)) continue;
+      reported.add(token);
+      diagnostics.push({
+        context: "abbreviation",
+        severity: "error",
+        file: lesson.source.file,
+        line: lineOf(lesson.body, index),
+        token,
+        message: `Unexplained abbreviation ${JSON.stringify(token)} outside math. ${FIX}`
+      });
+    }
+  }
+  return diagnostics;
+}
+export {
+  gateAbbreviations
+};

package/dist/reference/gate-math.d.ts

@@ -1,14 +1,25 @@
-import { NotationRegistryInput } from './types.js';
+import { NotationRegistryInput, NotationLessonInput } from './types.js';
 
 interface MathGateDiagnostic {
-    readonly context: 'body' | 'formula' | 'assessment';
+    readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation';
     /**
      * Body / component-slot math blocks the build (the render path needs every
      * glyph resolved for the KaTeX trust callback). `formula` joined it at D15:
      * a formula's glyphs are now rendered live and explorable, so an unresolved
      * one is a hole the reader can see, and the corpus was brought to zero when
-     * the tier was promoted. `assessment` math stays a Tier-3 warning until its
-     * own reviewed content pass (D6/D13/D14).
+     * the tier was promoted. `assessment` joined the same way when
+     * `AssessmentRunner` started rendering `prompt` / `explanation` through
+     * KaTeX (`mixed-content.ts`) instead of showing them as raw text: an
+     * unresolved glyph is now a visible hole in the assessment UI, not an
+     * invisible warning, so the corpus was brought to zero and the tier
+     * promoted in the same change — see `CHANGELOG.md`. `prose` (N9,
+     * `gate-prose-notation.ts`) is the complementary direction — plain-text
+     * notation sitting *outside* `$…$` — and ships straight as an error: it has
+     * no partial corpus to absorb, since every prior instance was fixed in the
+     * same change that introduced the check. `abbreviation` (N14,
+     * `gate-abbreviations.ts`) is the same "ships straight as an error" story
+     * for a different shape of plain-text token — an unexplained acronym or
+     * dotted abbreviation, rather than a mis-typed quantity/unit.
      */
     readonly severity: 'error' | 'warning';
     readonly file: string;
@@ -29,6 +40,18 @@ interface LessonAssessmentLink {
     readonly lessonId: string;
     readonly assessmentIds: readonly string[];
 }
+type ScopeEntry = {
+    key: string;
+    notation: string;
+};
+/**
+ * A lesson's flat glyph table: its own `notation.local` entries plus every
+ * shared card it introduces with `[[key]]` / `\explain{key}`. Exported so a
+ * caller that needs the *same* scope for a different purpose — rendering an
+ * assessment's math (`mixed-content.ts`), say — doesn't reconstruct it by
+ * hand and risk drifting from what the completeness gate actually checks.
+ */
+declare function pageScope(lesson: NotationLessonInput, sharedByKey: ReadonlyMap<string, ScopeEntry>): ScopeEntry[];
 /**
  * Resolve every rendered-math context against the page glyph table. Returns one
  * diagnostic per unresolved token; an empty array means the gate passed.
@@ -39,4 +62,4 @@ declare function gateContentMath(input: {
     readonly lessonAssessments: readonly LessonAssessmentLink[];
 }): MathGateDiagnostic[];
 
-export { type MathGateDiagnostic, gateContentMath };
+export { type MathGateDiagnostic, type ScopeEntry, gateContentMath, pageScope };

package/dist/reference/gate-math.js

@@ -4,7 +4,9 @@ import { formulaGlyphScope, unknownFormulaScopeKeys } from "./gloss.js";
 const SEVERITY = {
   body: "error",
   formula: "error",
-  assessment: "warning"
+  assessment: "error",
+  prose: "error",
+  abbreviation: "error"
 };
 const TERM_KEY = /\[\[\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\]\]/g;
 const EXPLAIN_KEY = /\\explain\s*\{([a-z0-9]+(?:[.-][a-z0-9]+)*)\}/g;
@@ -218,5 +220,6 @@ function gateContentMath(input) {
   return diagnostics;
 }
 export {
-  gateContentMath
+  gateContentMath,
+  pageScope
 };

package/dist/reference/gate-prose-notation.d.ts

@@ -0,0 +1,60 @@
+import { MathGateDiagnostic } from './gate-math.js';
+import { NotationLessonInput } from './types.js';
+
+/**
+ * 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.
+ */
+
+interface AssessmentItemLike {
+    readonly id?: string;
+    readonly prompt?: string;
+    readonly explanation?: string;
+}
+interface AssessmentLike {
+    readonly id: string;
+    readonly items?: readonly AssessmentItemLike[];
+}
+/**
+ * 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.
+ */
+declare function proseOnly(body: string): string;
+/** Exported for the same reason as {@link proseOnly}. */
+declare function lineOf(text: string, index: number): number;
+/**
+ * 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.
+ */
+declare function gateProseNotation(lessons: readonly NotationLessonInput[]): MathGateDiagnostic[];
+/**
+ * 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.
+ */
+declare function gateProseNotationInAssessments(assessments: readonly AssessmentLike[]): MathGateDiagnostic[];
+
+export { gateProseNotation, gateProseNotationInAssessments, lineOf, proseOnly };

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`. */
@@ -57,10 +57,16 @@ interface KeyedFloatLessonInput {
     readonly file: string;
     readonly body: string;
     /**
-     * The lesson's 1-based ordinal in the course. When set, floats are numbered
-     * `‹chapter›.‹n›`; when omitted, the legacy `##`-section scheme.
+     * `{ prefix, offset }` — the part's 1-based ordinal among the sidebar groups,
+     * and how many floats of this kind earlier lessons of that part already used.
+     * When set, floats are numbered `‹part›.‹offset + n›`; when omitted, the
+     * legacy `##`-section scheme. Each kind counts on its own, so the caller
+     * passes a different `offset` for `<Table>` than for `<Figure>`.
      */
-    readonly chapter?: number;
+    readonly numbering?: {
+        readonly prefix: number;
+        readonly offset: number;
+    };
 }
 declare function validateKeyedFloats(lessons: readonly KeyedFloatLessonInput[], kind: KeyedFloatKind): KeyedFloatValidation;
 

package/dist/reference/keyed-float-validate.js

@@ -32,7 +32,7 @@ function validateKeyedFloats(lessons, kind) {
     const table = {};
     for (const raw of scanKeyedJsxFloats(lesson.body, {
       tagName,
-      chapter: lesson.chapter
+      numbering: lesson.numbering
     })) {
       if (raw.key == null) continue;
       if (!KEYED_FLOAT_KEY_PATTERN.test(raw.key)) {