explico 0.8.0 → 0.11.0

package/src/reference/render-lab-math.ts

@@ -1,45 +1,21 @@
 import katex from './katex-delimiters.mjs';
 import { resolveMathGlyphs, stripNotationMarkers } from './math-glyphs.mjs';
 import { createNotationKatexOptions } from './katex-options.mjs';
+import { slotPlaceholder, type RenderedLabMath } from './lab-math-slot';
+
+// Re-exported so server code keeps one import. An island imports these from
+// `lab-math-slot` instead: this module is server-only.
+export { slotPlaceholder, type RenderedLabMath };
 
 export interface LabMathScopeDefinition {
   readonly key: string;
   readonly notation: string;
 }
 
-export 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).
- */
-export function slotPlaceholder(name: string): string {
-  return `⟦${name}⟧`;
-}
-
 interface BindResult {
   latex: string;
   bindings: ReadonlyArray<{ key: string }>;
-  unresolved: ReadonlyArray<{ token: string; start: number }>;
+  unresolved: ReadonlyArray<{ token: string; start: number; font?: string }>;
 }
 
 // `\slot{name}{fallback}` — `name` is a lab-slot id, `fallback` may contain one
@@ -84,10 +60,19 @@ export function renderLabMath(
 
   if (result.unresolved.length > 0) {
     const list = result.unresolved.map(({ token }) => `"${token}"`).join(', ');
+    // Rule N4: `\mathbf{v}` never borrows the card of a scalar `v` in scope.
+    const styled = result.unresolved.filter(({ font }) => font !== undefined);
+    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).\n  template: ${template.trim()}`,
+        `notation.local).${fontHint}\n  template: ${template.trim()}`,
     );
   }
 

package/src/reference/sections-validate.ts

@@ -0,0 +1,81 @@
+/**
+ * `[[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.
+ */
+import type { MathGateDiagnostic } from './gate-math';
+import { lessonLine } from './gate-prose-notation';
+import { parseSectionRef } from './sections.mjs';
+
+export 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[];
+}
+
+const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
+
+/** Code blanked in place, so an index still points into the body. */
+function withoutCode(text: string): string {
+  const blank = (block: string) => block.replace(/[^\n]/g, ' ');
+  return text
+    .replace(/```[\s\S]*?```/g, blank)
+    .replace(/~~~[\s\S]*?~~~/g, blank)
+    .replace(/`[^`\n]*`/g, blank);
+}
+
+function unresolved(
+  ref: { readonly lesson?: string; readonly key: string },
+  lessonExists: boolean,
+): string {
+  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]]`.'
+  );
+}
+
+/** One `sec-ref-resolves` error per `[[sec-…]]` that names no heading. */
+export function validateSectionRefs(
+  lessons: readonly SectionRefLessonInput[],
+): MathGateDiagnostic[] {
+  const headingsByLesson = new Map(
+    lessons.map((lesson) => [lesson.slug, new Set(lesson.headingSlugs)]),
+  );
+  const diagnostics: MathGateDiagnostic[] = [];
+  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 !== undefined),
+      });
+    }
+  }
+  return diagnostics;
+}

package/src/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/src/reference/tables-validate.ts

@@ -11,7 +11,8 @@ export type TableDiagnosticCode =
   | 'tab-invalid-key'
   | 'tab-duplicate-key'
   | 'tab-ref-resolves'
-  | 'tab-key-unused';
+  | 'tab-key-unused'
+  | 'tab-removed-prop';
 
 export interface TableDiagnostic {
   readonly code: TableDiagnosticCode;

package/src/reference/types.ts

@@ -80,10 +80,27 @@ export interface LocalNotationDefinitionInput {
   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.
+ */
+export 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;
+}
+
 export 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. */