explico 0.7.0 → 0.11.0

package/dist/reference/render-lab-math.d.ts

@@ -1,32 +1,10 @@
+import { RenderedLabMath } from './lab-math-slot.js';
+export { slotPlaceholder } from './lab-math-slot.js';
+
 interface LabMathScopeDefinition {
     readonly key: string;
     readonly notation: string;
 }
-interface RenderedLabMath {
-    /** KaTeX HTML+MathML with `data-notation-key` and `data-lab-slot` spans. */
-    readonly html: string;
-    /** Slot names, in template order, the island must supply at runtime. */
-    readonly slots: readonly string[];
-    /** Notation keys the template resolved to, for diagnostics. */
-    readonly keys: readonly string[];
-    /**
-     * Plain, copyable LaTeX — every explained glyph resolved to its bare
-     * symbol, every `\slot{name}{…}` replaced by `slotPlaceholder(name)` — so
-     * the island can substitute each slot's *current* live value in and keep
-     * `[data-notation-formula]`'s `data-latex` accurate as the reader drags a
-     * control, the same "click the equation to copy it" gesture a static
-     * lesson or glossary equation gets (`NotationLayer.astro`).
-     */
-    readonly plainLatexTemplate: string;
-}
-/**
- * A slot's placeholder inside `plainLatexTemplate` — distinct from the
- * numeric sentinel `sentinelFor` below uses internally (that one only has to
- * survive a single notation-binding pass at build time; this one is the
- * stable, name-keyed token an island substitutes with a live value at
- * runtime, so it's exported for that purpose).
- */
-declare function slotPlaceholder(name: string): string;
 /**
  * Compile a developer-authored lab math template the same way lesson `$$`
  * math is compiled: every identifier must resolve to a notation key in the
@@ -35,4 +13,4 @@ declare function slotPlaceholder(name: string): string;
  */
 declare function renderLabMath(template: string, scope: readonly LabMathScopeDefinition[]): RenderedLabMath;
 
-export { type LabMathScopeDefinition, type RenderedLabMath, renderLabMath, slotPlaceholder };
+export { type LabMathScopeDefinition, RenderedLabMath, renderLabMath };

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

@@ -1,9 +1,7 @@
-import katex from "katex";
+import katex from "./katex-delimiters.mjs";
 import { resolveMathGlyphs, stripNotationMarkers } from "./math-glyphs.mjs";
 import { createNotationKatexOptions } from "./katex-options.mjs";
-function slotPlaceholder(name) {
-  return `\u27E6${name}\u27E7`;
-}
+import { slotPlaceholder } from "./lab-math-slot.js";
 const SLOT_PATTERN = /\\slot\{([a-z][a-z0-9]*)\}\{((?:[^{}]|\{[^{}]*\})*)\}/g;
 const sentinelFor = (index) => `909909${index}.909909`;
 function renderLabMath(template, scope) {
@@ -27,8 +25,10 @@ function renderLabMath(template, scope) {
   }
   if (result.unresolved.length > 0) {
     const list = result.unresolved.map(({ token }) => `"${token}"`).join(", ");
+    const styled = result.unresolved.filter(({ font }) => font !== void 0);
+    const fontHint = styled.length === 0 ? "" : ` ${styled.map(({ token }) => token).join(", ")} ${styled.length === 1 ? "is a different symbol" : "are different symbols"} from the plain letter and need${styled.length === 1 ? "s" : ""} an entry of ${styled.length === 1 ? "its" : "their"} own.`;
     throw new Error(
-      `Lab math uses undefined notation ${list}. Every symbol must resolve to a notation entry in this page's glyph scope (a [[key]] reference or notation.local).
+      `Lab math uses undefined notation ${list}. Every symbol must resolve to a notation entry in this page's glyph scope (a [[key]] reference or notation.local).${fontHint}
   template: ${template.trim()}`
     );
   }

package/dist/reference/sections-validate.d.ts

@@ -0,0 +1,27 @@
+import { MathGateDiagnostic } from './gate-math.js';
+import './types.js';
+
+/**
+ * `[[sec-…]]` references (docs/plans/titles-and-containers.md Part 1): every
+ * `[[sec-slug]]` and `[[lesson/slug#sec-slug]]` must name a top-level heading
+ * of that lesson — `sec-ref-resolves`, an error owned by the `keyed-floats`
+ * invariant, the same promise `[[eq-…]]` and `[[fig-…]]` make.
+ *
+ * The finding goes into `manifest.diagnostics.math` with context `structure`,
+ * like S1 and S2 (see `MathGateDiagnostic`), so every reporter that already
+ * reads that array fails the build on it without learning a new one.
+ */
+
+interface SectionRefLessonInput {
+    /** Lesson slug, e.g. `motion/position-and-coordinates`. */
+    readonly slug: string;
+    readonly file: string;
+    readonly body: string;
+    readonly bodyLine?: number;
+    /** The anchors of the lesson's top-level headings (`manifest.lessons[].headings`). */
+    readonly headingSlugs: readonly string[];
+}
+/** One `sec-ref-resolves` error per `[[sec-…]]` that names no heading. */
+declare function validateSectionRefs(lessons: readonly SectionRefLessonInput[]): MathGateDiagnostic[];
+
+export { type SectionRefLessonInput, validateSectionRefs };

package/dist/reference/sections-validate.js

@@ -0,0 +1,41 @@
+import { lessonLine } from "./gate-prose-notation.js";
+import { parseSectionRef } from "./sections.mjs";
+const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
+function withoutCode(text) {
+  const blank = (block) => block.replace(/[^\n]/g, " ");
+  return text.replace(/```[\s\S]*?```/g, blank).replace(/~~~[\s\S]*?~~~/g, blank).replace(/`[^`\n]*`/g, blank);
+}
+function unresolved(ref, lessonExists) {
+  const written = ref.lesson ? `[[${ref.lesson}#sec-${ref.key}]]` : `[[sec-${ref.key}]]`;
+  if (ref.lesson && !lessonExists) {
+    return `${written} names lesson ${ref.lesson}, which does not exist.`;
+  }
+  return `${written} names no heading: ${ref.lesson ? `lesson ${ref.lesson}` : "this lesson"} has no top-level heading anchored #${ref.key}. A heading's anchor is its text in lowercase with spaces as hyphens and punctuation dropped: \`## Two ways to name the same point\` is \`[[sec-two-ways-to-name-the-same-point]]\`.`;
+}
+function validateSectionRefs(lessons) {
+  const headingsByLesson = new Map(
+    lessons.map((lesson) => [lesson.slug, new Set(lesson.headingSlugs)])
+  );
+  const diagnostics = [];
+  for (const lesson of lessons) {
+    for (const match of withoutCode(lesson.body).matchAll(BRACKET_REF)) {
+      const ref = parseSectionRef(match[1] ?? "");
+      if (!ref) continue;
+      const headings = headingsByLesson.get(ref.lesson ?? lesson.slug);
+      if (headings?.has(ref.key)) continue;
+      diagnostics.push({
+        context: "structure",
+        code: "sec-ref-resolves",
+        severity: "error",
+        file: lesson.file,
+        line: lessonLine(lesson, match.index ?? 0),
+        token: match[0],
+        message: unresolved(ref, headings !== void 0)
+      });
+    }
+  }
+  return diagnostics;
+}
+export {
+  validateSectionRefs
+};

package/dist/reference/sections.d.mts

@@ -0,0 +1,97 @@
+export function parseSectionRef(raw: any): {
+    lesson: string;
+    key: string;
+} | {
+    key: string;
+    lesson?: undefined;
+} | undefined;
+/**
+ * The number each heading takes, from its level alone: `##` counts within the
+ * chapter, `###` within its `##`, and so on, each deeper counter restarting
+ * when a shallower heading appears. A level a heading skipped counts as 0
+ * (`##` then `####` is `…1.0.1`), the way LaTeX numbers a skipped level. An
+ * `#` in a lesson body is never numbered and resets nothing. Headings deeper
+ * than `depth`, or any heading when there is no `prefix`, get `undefined`.
+ * `unnumbered[i]` marks heading `i` as outside the outline (a meta section):
+ * it and the deeper headings under it get `undefined` and move no counter.
+ */
+export function sectionNumbers(levels: any, { prefix, depth, unnumbered }?: {
+    depth?: number | undefined;
+    unnumbered?: never[] | undefined;
+}): any;
+/**
+ * The text a heading's source renders as, near enough to slug it the way
+ * Astro would: markup goes, the words stay. Inline code and math keep their
+ * source (math renders as KaTeX, whose text is no use as a slug); a notation
+ * term keeps its key; a link keeps its text; an image, a citation and an MDX
+ * expression contribute nothing; the authoring marker is dropped.
+ */
+export function headingPlainText(source: any): string;
+/**
+ * Anchors for a page's headings, in order, from Astro's own `rehypeHeadingIds`
+ * run over their plain text: the same slugger with the same duplicate
+ * counters (`foo`, `foo-1`) the page would otherwise get.
+ */
+export function slugHeadings(texts: any): any;
+/**
+ * Every top-level heading of a lesson body in document order, as the
+ * manifest records it: `{ level, text, slug, number? }`. `prefix` is the
+ * chapter's `‹part›.‹chapter›`; without one nothing is numbered.
+ */
+export function scanSectionHeadings(markdown: any, options?: {}): {
+    number?: any;
+    level: number;
+    text: string;
+    slug: any;
+}[];
+/**
+ * The top-level blocks of a lesson body in document order, as the heading
+ * rules see them (S6, S7 — `gate-heading-structure.ts`): each outline heading
+ * `scanSectionHeadings` numbers, each JSX element by name, and every other
+ * line of content. An MDX comment and an `import` / `export` line render
+ * nothing, so they are not blocks. `index` is the offset in `markdown`; a
+ * heading's `text` is what the manifest records for it.
+ *
+ * @returns {Array<
+ *   | { kind: 'heading', level: number, text: string, index: number }
+ *   | { kind: 'element', name: string, index: number }
+ *   | { kind: 'content', index: number }
+ * >}
+ */
+export function scanOutlineBlocks(markdown: any): Array<{
+    kind: "heading";
+    level: number;
+    text: string;
+    index: number;
+} | {
+    kind: "element";
+    name: string;
+    index: number;
+} | {
+    kind: "content";
+    index: number;
+}>;
+/**
+ * The top-level blocks named in `names` — components that draw a heading of
+ * their own where their tag stands, a knowledge check's `<AssessmentSet />`
+ * and a worked-example set's `<CompactExamples>` — in document order: each
+ * with its tag `name`, the literal `id` its tag sets (if any), and `heading`,
+ * the position in `scanSectionHeadings`' list of the outline heading it
+ * follows (`-1` before the first). The manifest reads this to place the
+ * block's heading in "On this page".
+ *
+ * @returns {Array<{ name: string, heading: number, id?: string }>}
+ */
+export function scanTitledBlocks(markdown: any, names: any): Array<{
+    name: string;
+    heading: number;
+    id?: string;
+}>;
+/**
+ * The mdast counterpart of `scanSectionHeadings`: the lesson root's own
+ * `heading` children, with the number each takes. Slugs are not computed here
+ * — the render path takes them from the manifest.
+ */
+export function collectSectionHeadings(tree: any, options?: {}): any;
+/** The deepest heading level numbered when a course sets nothing (`####`). */
+export const DEFAULT_SECTION_DEPTH: 4;

package/dist/reference/sections.mjs

@@ -0,0 +1,306 @@
+/**
+ * Outline numbering (docs/plans/titles-and-containers.md Part 1): every `##`
+ * to `######` heading at the top level of a lesson is numbered
+ * `‹part›.‹chapter›.‹section›[.‹subsection›…]`, down to the course's
+ * `numbering.sections.depth`, and is citable as `[[sec-‹slug›]]`. A
+ * `[card=meta]` section is logistics, not a step of the lesson, so it and
+ * every heading inside it stay unnumbered — LaTeX's `\section*`, and what
+ * References already is — and take no number from the sections after it.
+ *
+ * Numbers are for a reader to say and see; the anchor stays the heading's
+ * slug (`#two-ways-to-name-the-same-point`), never the number.
+ *
+ * Two walks, same contract as `equations.mjs` and `keyed-jsx-floats.mjs`:
+ * `scanSectionHeadings` reads raw Markdown for the manifest, and
+ * `collectSectionHeadings` walks the mdast for `remark-notation.mjs`. Both see
+ * the same headings — top level only; a heading inside a component (`<Memo>`,
+ * `<CompactExample>`, …) is part of that component, not of the outline — and
+ * number them with the one `sectionNumbers` below, so the two agree whenever
+ * they agree on the level sequence. `remark-notation.mjs` checks exactly that
+ * before it trusts the manifest's slugs and numbers.
+ *
+ * The manifest is where a heading's slug is decided: `headingPlainText` reads
+ * the heading's source text and `slugHeadings` slugs it with Astro's own
+ * `rehypeHeadingIds`, so a plain-text heading keeps the id it always had. The
+ * render path then gives each heading that id before Astro's pass would have
+ * picked one, so `[[sec-…]]`, the page, and the alias map cannot disagree.
+ */
+
+import { rehypeHeadingIds } from '@astrojs/markdown-remark';
+import { headingCardTier, stripHeadingMarker } from './rehype-heading-anchors.mjs';
+
+/** The deepest heading level numbered when a course sets nothing (`####`). */
+export const DEFAULT_SECTION_DEPTH = 4;
+
+/**
+ * `[[sec-slug]]`, or `[[lesson/slug#sec-slug]]` across pages. The slug part
+ * is whatever the heading's anchor is: github-slugger keeps letters, digits,
+ * `_` and `-` from any script, and can double a hyphen.
+ */
+const SECTION_REF =
+  /^(?:([a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*)#)?sec-([\p{L}\p{N}_-]+)$/u;
+
+export function parseSectionRef(raw) {
+  const match = SECTION_REF.exec(String(raw).trim());
+  if (!match) return undefined;
+  return match[1] ? { lesson: match[1], key: match[2] } : { key: match[2] };
+}
+
+/**
+ * The number each heading takes, from its level alone: `##` counts within the
+ * chapter, `###` within its `##`, and so on, each deeper counter restarting
+ * when a shallower heading appears. A level a heading skipped counts as 0
+ * (`##` then `####` is `…1.0.1`), the way LaTeX numbers a skipped level. An
+ * `#` in a lesson body is never numbered and resets nothing. Headings deeper
+ * than `depth`, or any heading when there is no `prefix`, get `undefined`.
+ * `unnumbered[i]` marks heading `i` as outside the outline (a meta section):
+ * it and the deeper headings under it get `undefined` and move no counter.
+ */
+export function sectionNumbers(
+  levels,
+  { prefix, depth = DEFAULT_SECTION_DEPTH, unnumbered = [] } = {},
+) {
+  const counters = [0, 0, 0, 0, 0, 0, 0];
+  // A heading deeper than this level sits inside an unnumbered section.
+  let outside = 7;
+  return levels.map((level, index) => {
+    if (level < 2) return undefined;
+    if (level <= outside) outside = 7;
+    if (unnumbered[index]) outside = level;
+    if (outside < 7) return undefined;
+    counters[level] += 1;
+    for (let deeper = level + 1; deeper <= 6; deeper++) counters[deeper] = 0;
+    if (!prefix || level > depth) return undefined;
+    return [prefix, ...counters.slice(2, level + 1)].join('.');
+  });
+}
+
+// --- raw Markdown ------------------------------------------------------------
+
+const blank = (block) => block.replace(/[^\n]/g, ' ');
+
+// An MDX attribute may be a quoted string, a brace expression (one level of
+// nesting), or unquoted source — the same breadth `stripJsxComponents` allows.
+const ATTRIBUTES = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'])*`;
+const JSX_BLOCK = new RegExp(
+  String.raw`<([A-Za-z][\w.:-]*)(?:\s${ATTRIBUTES})?>[\s\S]*?<\/\1\s*>`,
+  'g',
+);
+
+/**
+ * The body with everything that is not outline blanked, newlines kept: fenced
+ * code, MDX comments, and every JSX element's children (a heading in there is
+ * not an outline heading). A self-closing element has no children to blank.
+ * With `markers`, a code block keeps its opening backtick or tilde and an
+ * element its `<Name`, so `scanOutlineBlocks` can see that something stands
+ * there; neither can start a heading line, so both forms find the same
+ * headings.
+ */
+function outlineSource(markdown, { markers = false } = {}) {
+  const fence = markers ? (block) => block[0] + blank(block.slice(1)) : blank;
+  const element = markers
+    ? (block, name) => `<${name}${blank(block.slice(name.length + 1))}`
+    : blank;
+  return String(markdown)
+    .replace(/```[\s\S]*?```/g, fence)
+    .replace(/~~~[\s\S]*?~~~/g, fence)
+    .replace(/\{\/\*[\s\S]*?\*\/\}/g, blank)
+    .replace(JSX_BLOCK, element);
+}
+
+const ATX_HEADING = /^[ \t]{0,3}(#{1,6})(?:[ \t]+([^\n]*?))?(?:[ \t]+#+)?[ \t]*$/gm;
+
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
+
+/**
+ * The text a heading's source renders as, near enough to slug it the way
+ * Astro would: markup goes, the words stay. Inline code and math keep their
+ * source (math renders as KaTeX, whose text is no use as a slug); a notation
+ * term keeps its key; a link keeps its text; an image, a citation and an MDX
+ * expression contribute nothing; the authoring marker is dropped.
+ */
+export function headingPlainText(source) {
+  const literals = [];
+  const keep = (value) => `\u0000${literals.push(value) - 1}\u0000`;
+  let text = stripHeadingMarker(source ?? '')
+    .replace(/(`+)([\s\S]*?[^`])\1(?!`)/g, (_, _ticks, code) => keep(code.trim()))
+    .replace(/\$([^$\n]+)\$/g, (_, latex) => keep(latex.trim()))
+    .replace(/\[\[\s*([^\][]+?)\s*\]\]/g, (_, key) => keep(key))
+    .replace(/\[@[^\]]*\]/g, '')
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/\[([^\]]*)\]\[[^\]]*\]/g, '$1')
+    .replace(/<(https?:\/\/[^>\s]+)>/g, (_, url) => keep(url))
+    .replace(/\{[^{}]*\}/g, '')
+    .replace(/<\/?[A-Za-z][^>]*>/g, '')
+    .replace(/(\*\*|__)(?=\S)([\s\S]*?\S)\1/g, '$2')
+    .replace(/(^|[^\w*])\*(?=\S)([\s\S]*?\S)\*(?![\w*])/g, '$1$2')
+    .replace(/(^|[^\w])_(?=\S)([\s\S]*?\S)_(?!\w)/g, '$1$2')
+    .replace(/~~(?=\S)([\s\S]*?\S)~~/g, '$1')
+    .replace(/\\([!-/:-@[-`{-~])/g, '$1')
+    .replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (entity, name) => {
+      if (name[0] !== '#') return ENTITIES[name.toLowerCase()] ?? entity;
+      const code = name[1] === 'x' || name[1] === 'X'
+        ? Number.parseInt(name.slice(2), 16)
+        : Number.parseInt(name.slice(1), 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : entity;
+    });
+  text = text.replace(/\u0000(\d+)\u0000/g, (_, index) => literals[Number(index)]);
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Anchors for a page's headings, in order, from Astro's own `rehypeHeadingIds`
+ * run over their plain text: the same slugger with the same duplicate
+ * counters (`foo`, `foo-1`) the page would otherwise get.
+ */
+export function slugHeadings(texts) {
+  const tree = {
+    type: 'root',
+    children: texts.map((value) => ({
+      type: 'element',
+      tagName: 'h2',
+      properties: {},
+      children: [{ type: 'text', value }],
+    })),
+  };
+  rehypeHeadingIds()(tree, { history: ['headings.mdx'], data: {} });
+  return tree.children.map((node) => String(node.properties.id));
+}
+
+/**
+ * Every top-level heading of a lesson body in document order, as the
+ * manifest records it: `{ level, text, slug, number? }`. `prefix` is the
+ * chapter's `‹part›.‹chapter›`; without one nothing is numbered.
+ */
+export function scanSectionHeadings(markdown, options = {}) {
+  const found = [];
+  for (const match of outlineSource(markdown).matchAll(ATX_HEADING)) {
+    found.push({
+      level: match[1].length,
+      text: headingPlainText(match[2] ?? ''),
+      meta: headingCardTier(match[2] ?? '') === 'meta',
+    });
+  }
+  const slugs = slugHeadings(found.map((heading) => heading.text));
+  const numbers = sectionNumbers(
+    found.map((heading) => heading.level),
+    { ...options, unnumbered: found.map((heading) => heading.meta) },
+  );
+  return found.map((heading, index) => ({
+    level: heading.level,
+    text: heading.text,
+    slug: slugs[index],
+    ...(numbers[index] === undefined ? {} : { number: numbers[index] }),
+  }));
+}
+
+const ELEMENT_START = /^[ \t]*<([A-Za-z][\w.:-]*)/;
+const ESM_LINE = /^(?:import|export)\s/;
+
+/**
+ * The top-level blocks of a lesson body in document order, as the heading
+ * rules see them (S6, S7 — `gate-heading-structure.ts`): each outline heading
+ * `scanSectionHeadings` numbers, each JSX element by name, and every other
+ * line of content. An MDX comment and an `import` / `export` line render
+ * nothing, so they are not blocks. `index` is the offset in `markdown`; a
+ * heading's `text` is what the manifest records for it.
+ *
+ * @returns {Array<
+ *   | { kind: 'heading', level: number, text: string, index: number }
+ *   | { kind: 'element', name: string, index: number }
+ *   | { kind: 'content', index: number }
+ * >}
+ */
+export function scanOutlineBlocks(markdown) {
+  // Same length, same lines: headings come from the form `scanSectionHeadings`
+  // reads, everything else from the one that keeps its markers.
+  const plain = outlineSource(markdown).split('\n');
+  const marked = outlineSource(markdown, { markers: true }).split('\n');
+  const heading = new RegExp(ATX_HEADING.source);
+  const blocks = [];
+  let index = 0;
+  marked.forEach((line, row) => {
+    const at = index;
+    index += line.length + 1;
+    const match = heading.exec(plain[row]);
+    if (match) {
+      blocks.push({
+        kind: 'heading',
+        level: match[1].length,
+        text: headingPlainText(match[2] ?? ''),
+        index: at,
+      });
+    } else if (line.trim() !== '' && !ESM_LINE.test(line)) {
+      const element = ELEMENT_START.exec(line);
+      blocks.push(element ? { kind: 'element', name: element[1], index: at } : { kind: 'content', index: at });
+    }
+  });
+  return blocks;
+}
+
+const OPENING_TAG = new RegExp(String.raw`^[ \t]*<[A-Za-z][\w.:-]*(${ATTRIBUTES})\/?>`);
+const ID_ATTRIBUTE = /(?:^|\s)id\s*=\s*(?:"([^"]*)"|'([^']*)')/;
+
+/**
+ * The top-level blocks named in `names` — components that draw a heading of
+ * their own where their tag stands, a knowledge check's `<AssessmentSet />`
+ * and a worked-example set's `<CompactExamples>` — in document order: each
+ * with its tag `name`, the literal `id` its tag sets (if any), and `heading`,
+ * the position in `scanSectionHeadings`' list of the outline heading it
+ * follows (`-1` before the first). The manifest reads this to place the
+ * block's heading in "On this page".
+ *
+ * @returns {Array<{ name: string, heading: number, id?: string }>}
+ */
+export function scanTitledBlocks(markdown, names) {
+  const wanted = new Set(names);
+  const source = String(markdown);
+  const blocks = [];
+  let heading = -1;
+  for (const block of scanOutlineBlocks(source)) {
+    if (block.kind === 'heading') {
+      heading += 1;
+    } else if (block.kind === 'element' && wanted.has(block.name)) {
+      const attributes = OPENING_TAG.exec(source.slice(block.index))?.[1] ?? '';
+      const id = ID_ATTRIBUTE.exec(attributes);
+      blocks.push({
+        name: block.name,
+        heading,
+        ...(id ? { id: id[1] ?? id[2] } : {}),
+      });
+    }
+  }
+  return blocks;
+}
+
+// --- mdast -------------------------------------------------------------------
+
+/** A node's literal text, markers included (`[card=meta]` is plain text here). */
+function mdastText(node) {
+  if (typeof node?.value === 'string') return node.value;
+  return Array.isArray(node?.children) ? node.children.map(mdastText).join('') : '';
+}
+
+/**
+ * The mdast counterpart of `scanSectionHeadings`: the lesson root's own
+ * `heading` children, with the number each takes. Slugs are not computed here
+ * — the render path takes them from the manifest.
+ */
+export function collectSectionHeadings(tree, options = {}) {
+  const nodes = (Array.isArray(tree?.children) ? tree.children : []).filter(
+    (node) => node?.type === 'heading',
+  );
+  const numbers = sectionNumbers(
+    nodes.map((node) => node.depth),
+    {
+      ...options,
+      unnumbered: nodes.map((node) => headingCardTier(mdastText(node)) === 'meta'),
+    },
+  );
+  return nodes.map((node, index) => ({
+    node,
+    level: node.depth,
+    ...(numbers[index] === undefined ? {} : { number: numbers[index] }),
+  }));
+}

package/dist/reference/tables-validate.d.ts

@@ -2,7 +2,7 @@ import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } fr
 
 /** `validateKeyedFloats` for `<Table>` — see `keyed-float-validate.ts`. */
 
-type TableDiagnosticCode = 'tab-invalid-key' | 'tab-duplicate-key' | 'tab-ref-resolves' | 'tab-key-unused';
+type TableDiagnosticCode = 'tab-invalid-key' | 'tab-duplicate-key' | 'tab-ref-resolves' | 'tab-key-unused' | 'tab-removed-prop';
 interface TableDiagnostic {
     readonly code: TableDiagnosticCode;
     readonly severity: 'error' | 'warning' | 'info';

package/dist/reference/types.d.ts

@@ -70,14 +70,37 @@ interface LocalNotationDefinitionInput {
     readonly glosses: readonly NotationGlossEntry[];
     readonly source: SourceSpan;
 }
+/**
+ * One `notation.suspend` item: a decoration (`'`, `\hat`, …) this page says
+ * is not an operator (rule N22). Every decorated form of it on the page then
+ * needs its own entry.
+ */
+interface NotationSuspension {
+    /** A canonical name from `DECORATION_NAMES` (`math-glyphs.mjs`). */
+    readonly operator: string;
+    /** Why; a suspension without one is an `operator-suspension-reason` warning. */
+    readonly reason?: string;
+}
 interface NotationLessonInput {
     readonly lessonId: string;
     readonly status: EditorialStatus;
     readonly localDefinitions: readonly LocalNotationDefinitionInput[];
+    /**
+     * Decorations this page suspends (`notation.suspend`, rule N22). Optional
+     * so a hand-built input (a test, an adapter) stays valid.
+     */
+    readonly suspended?: readonly NotationSuspension[];
     /** References harvested from lesson prose and equations, excluding definitions. */
     readonly references: readonly NotationReferenceInput[];
     /** Original lesson body, retained for lossless loader adapters. */
     readonly body: string;
+    /**
+     * 1-based line in `source.file` where `body` starts. Gates scan the body, so
+     * every finding's index is body-relative; this is what turns one into a real
+     * location in the file. Optional so a hand-built input (a test, an adapter)
+     * stays valid — it then behaves as 1, the pre-0.7.1 behavior.
+     */
+    readonly bodyLine?: number;
     readonly source: SourceSpan;
 }
 interface NotationRegistryInput {
@@ -186,4 +209,4 @@ interface NotationRegistry {
     readonly diagnostics: readonly NotationDiagnostic[];
 }
 
-export type { AbbreviationDefinitionInput, DiagnosticSeverity, EditorialStatus, LocalNotationDefinitionInput, LocalNotationDefinitionRecord, NotationAlignment, NotationBacklink, NotationBinding, NotationDefinitionRecord, NotationDefinitionScope, NotationDiagnostic, NotationDiagnosticCode, NotationGlossEntry, NotationLessonInput, NotationPageBundle, NotationReferenceInput, NotationReferenceKind, NotationRegistry, NotationRegistryInput, ResolvedNotationReference, SharedNotationDefinitionInput, SharedNotationDefinitionRecord, SourceSpan };
+export type { AbbreviationDefinitionInput, DiagnosticSeverity, EditorialStatus, LocalNotationDefinitionInput, LocalNotationDefinitionRecord, NotationAlignment, NotationBacklink, NotationBinding, NotationDefinitionRecord, NotationDefinitionScope, NotationDiagnostic, NotationDiagnosticCode, NotationGlossEntry, NotationLessonInput, NotationPageBundle, NotationReferenceInput, NotationReferenceKind, NotationRegistry, NotationRegistryInput, NotationSuspension, ResolvedNotationReference, SharedNotationDefinitionInput, SharedNotationDefinitionRecord, SourceSpan };

package/dist/reference/unit-words.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Units written out as English words — "2 meters per second squared",
+ * "30 degrees", "$x = 3$ meters" — for rule N9's `spelled-unit` check
+ * (`gate-prose-notation.ts`). A unit is an upright symbol inside `$…$`
+ * (`$2\ \text{m/s}^2$`, `$30^{\circ}$`, `$x = 3\ \text{m}$`), so a spelled-out
+ * unit that quantifies something is the same mistake as `45 m/s` in plain
+ * text.
+ *
+ * A unit word on its own is not flagged — "measured in meters" names the
+ * unit, it does not state a quantity. What is flagged is a unit word
+ *
+ * - after a number, written in digits or as a word, in prose or typeset
+ *   (`2 meters`, `two-meter`, `$x = 3$ meters`);
+ * - after `per`, or before it (`rotations per second`, `meters per unit`);
+ * - with `square` / `cubic` before it or `squared` / `cubed` after it.
+ *
+ * "Degrees of freedom" is not a unit. Calendar time (day, week, month, year)
+ * and currency are left out on purpose: they are ordinary words in a finance
+ * course's prose, not SI units. `notation` `units:` strings are a different
+ * vocabulary (`units-vocab.ts`, rule N19) and are never scanned here.
+ */
+interface SpelledUnit {
+    readonly index: number;
+    readonly token: string;
+    /** What to write instead, as `$…$`. */
+    readonly suggestion: string;
+}
+/**
+ * Every spelled-out unit in a lesson or assessment text. `prose` has code,
+ * math, references, JSX tags and comments blanked (`proseOnly`); `withMath`
+ * is the same text with math left in, for the `$x = 3$ meters` shape. Both
+ * must share offsets. A phrase whose unit words are all in `allow`
+ * (`rules.N9.allow`, singular or plural) is skipped.
+ */
+declare function findSpelledUnits(prose: string, withMath: string, allow?: readonly string[]): SpelledUnit[];
+
+export { type SpelledUnit, findSpelledUnits };