explico 0.7.0 → 0.11.0

package/dist/reference/equations.mjs

@@ -4,23 +4,24 @@
  * Every display equation (`$$…$$`) in a lesson is numbered and given an `id`
  * 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
+ * `‹prefix›.‹offset + n›`: `n` counts every display equation in the lesson,
+ * and the course's `numbering.floats` scope decides the rest — `chapter` (the
+ * default) makes the prefix `‹part›.‹chapter›` with no offset, so `(2.2.4)` is
+ * the fourth display equation of part 2's second chapter; `part` makes it the
+ * part's ordinal alone, with `offset` carrying the count from earlier lessons
+ * of the part so the sequence runs on across it. `##` and `###` headings never
+ * affect it. 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:
  *
- *   [[eq-discount-factor-def]]           same page  → "(2.4)" linked to #eq-…
+ *   [[eq-discount-factor-def]]           same page  → "(2.2.4)" linked to #eq-…
  *   [[foundations/present-value#eq-pv]]  cross page → number from the manifest
  *
- * An unkeyed equation still gets a positional anchor (`#eq-2-4`) so it can be
+ * An unkeyed equation still gets a positional anchor (`#eq-2-2-4`) so it can be
  * deep-linked, but only a keyed equation is referenceable by name.
  *
  * `scanEquationLabels` (raw Markdown) and `collectEquationLabels` (mdast tree)
@@ -37,6 +38,28 @@ export const EQ_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 export const EQ_LABEL_PATTERN =
   /\\label\{\s*eq:([a-z0-9]+(?:-[a-z0-9]+)*)\s*\}/g;
 
+/**
+ * A `\caption{<short caption>}` anywhere in a math source — the equation's
+ * short caption, plain text with no nested braces. Global; the text in group
+ * 1. An equation takes only a short caption: it names the equation in the
+ * `[[eq-…]]` preview card and in the "Copy LaTeX — ‹caption›" tooltip, and is
+ * stripped before KaTeX exactly like `\label{}`.
+ */
+export const EQ_CAPTION_PATTERN = /\\caption\{([^{}]*)\}/g;
+
+/**
+ * The short caption a display equation carries, trimmed, or `null` when it
+ * has none. Only the first `\caption{}` counts; `remark-notation.mjs` fails a
+ * page that gives one equation two, or an empty one.
+ */
+export function equationCaption(latex) {
+  EQ_CAPTION_PATTERN.lastIndex = 0;
+  const match = EQ_CAPTION_PATTERN.exec(String(latex ?? ''));
+  EQ_CAPTION_PATTERN.lastIndex = 0;
+  const text = match?.[1]?.replace(/\s+/g, ' ').trim();
+  return text ? text : null;
+}
+
 /**
  * A `[[ … ]]` payload that targets an equation: `eq-<key>` on the current page,
  * or `<lesson-slug>#eq-<key>` across pages. `lesson` (group 1) is a `/`-slug.
@@ -52,10 +75,14 @@ export function parseEquationRef(raw) {
   return match[1] ? { lesson: match[1], key: match[2] } : { key: match[2] };
 }
 
-/** Remove every `\label{eq:…}` (and the whitespace it leaves) from a math source. */
+/**
+ * Remove every `\label{eq:…}` and `\caption{…}` (and the whitespace they
+ * leave) from a math source: both are identity markers, not math KaTeX parses.
+ */
 export function stripEquationLabels(latex) {
   return String(latex)
     .replace(EQ_LABEL_PATTERN, '')
+    .replace(EQ_CAPTION_PATTERN, '')
     .replace(/[ \t]+\n/g, '\n')
     .replace(/\n{3,}/g, '\n\n')
     .replace(/[ \t]{2,}/g, ' ')
@@ -70,13 +97,14 @@ function equationNumber(section, index) {
 /**
  * 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.
+ * `prefix` is everything before the last dot — `‹part›.‹chapter›` under the
+ * default `numbering.floats: "chapter"`, the part's ordinal under `"part"`.
+ * `offset` is how many items of the kind precede the lesson in that scope: 0
+ * for a chapter, the earlier chapters' count for a part, so `n` runs on
+ * across it. 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 };
@@ -90,9 +118,9 @@ export function resolveNumbering(input) {
 }
 
 /**
- * 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.
+ * The visible number for one display equation. With a `prefix` the scheme is
+ * `‹prefix›.‹offset + indexInLesson›` and `##` headings are ignored; without
+ * it, the legacy `##`-section scheme.
  */
 export function displayEquationNumber({
   prefix,
@@ -106,7 +134,13 @@ export function displayEquationNumber({
     : `${prefix}.${offset + indexInLesson}`;
 }
 
-/** The positional anchor id for an unkeyed equation, e.g. `2.4` → `eq-2-4`. */
+/**
+ * A display equation's anchor id: `eq-<key>` when it carries a
+ * `\label{eq:…}`, else the positional form, e.g. `2.4` → `eq-2-4`.
+ *
+ * @param {{ key?: string, number?: string | number }} equation - `number` is
+ *   read only when there is no `key`, so a keyed caller may omit it.
+ */
 export function equationAnchorId({ key, number }) {
   return key ? `eq-${key}` : `eq-${String(number).replace(/\./g, '-')}`;
 }
@@ -130,10 +164,8 @@ export function stripFencedCode(markdown) {
  * 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
+ * tags and exposes their body to the later blanking pass. The
+ * {@link TRANSPARENT_COMPONENTS} are the intentional uses. Section headings in
  * a transparent body do not change the surrounding page's section counter.
  */
 export function stripJsxComponents(markdown, keep, transparent = []) {
@@ -163,23 +195,35 @@ export function stripJsxComponents(markdown, keep, transparent = []) {
   );
 }
 
+/**
+ * The components whose bodies stay in the lesson's reading order: `<Memo>`,
+ * `<ShortNote>` and `<Fold>`. Unlike a worked-example/presentation wrapper,
+ * their bodies are details or folded stretches of the lesson itself, so a
+ * numbered equation or float in one stays in the official sequence. Every
+ * scan and tree walk that numbers equations or floats reads this list.
+ */
+export const TRANSPARENT_COMPONENTS = Object.freeze(['Memo', 'ShortNote', 'Fold']);
+
 /**
  * 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›`.
+ * with its assigned number and its `\caption{}` short caption (`short`, or
+ * `null`). `$$…$$` blocks only. With `numbering`
+ * (`{ prefix, offset }`, the lesson's float-number prefix and the count of
+ * display equations before it in that scope) the number is
+ * `‹prefix›.‹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 scanDisplayEquations(markdown, numbering) {
   const { prefix, offset } = resolveNumbering(numbering);
-  const text = stripJsxComponents(stripFencedCode(markdown), undefined, [
-    'Memo',
-    'ShortNote',
-  ]);
+  const text = stripJsxComponents(
+    stripFencedCode(markdown),
+    undefined,
+    TRANSPARENT_COMPONENTS,
+  );
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
   const display = /\$\$([\s\S]+?)\$\$/g;
@@ -193,6 +237,7 @@ export function scanDisplayEquations(markdown, numbering) {
       kind: 'equation',
       index: match.index,
       key: label ? label[1] : null,
+      short: equationCaption(match[1]),
     });
   }
   tokens.sort((a, b) => a.index - b.index);
@@ -218,6 +263,7 @@ export function scanDisplayEquations(markdown, numbering) {
         indexInSection,
         indexInLesson,
       }),
+      short: token.short,
       section,
       indexInSection,
     });
@@ -255,11 +301,11 @@ export function collectDisplayEquations(tree, numbering) {
   let indexInSection = 0;
   let indexInLesson = 0;
 
-  // 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.
+  // Top-level blocks plus the bodies of the `TRANSPARENT_COMPONENTS`: other
+  // MDX components (a `<CompactExample>` worked example, an `<Aside>`) remain
+  // illustrative and outside the lesson's official equation sequence. The
+  // transparent ones 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') {
@@ -269,6 +315,7 @@ export function collectDisplayEquations(tree, numbering) {
       const label = EQ_LABEL_PATTERN.exec(String(node.value ?? ''));
       equations.push({
         key: label ? label[1] : null,
+        short: equationCaption(node.value),
         number: displayEquationNumber({
           prefix,
           offset,
@@ -284,8 +331,7 @@ export function collectDisplayEquations(tree, numbering) {
     }
     if (
       node.type === 'mdxJsxFlowElement' &&
-      node.name !== 'Memo' &&
-      node.name !== 'ShortNote'
+      !TRANSPARENT_COMPONENTS.includes(node.name)
     ) {
       return;
     }
@@ -304,7 +350,7 @@ export function collectDisplayEquations(tree, numbering) {
     if (node.type === 'math') collectFromDetail(node);
     else if (
       node.type === 'mdxJsxFlowElement' &&
-      (node.name === 'Memo' || node.name === 'ShortNote')
+      TRANSPARENT_COMPONENTS.includes(node.name)
     ) {
       collectFromDetail(node);
     }

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

@@ -0,0 +1,31 @@
+import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } from './keyed-float-validate.js';
+
+/**
+ * `validateKeyedFloats` for `<CompactExamples>` — see
+ * `keyed-float-validate.ts`. A worked-example set is a numbered kind of its
+ * own, like a knowledge check (docs/plans/titles-and-containers.md Part 6,
+ * Q11): `Example ‹prefix›.‹n›`, anchored `#ex-‹id›`, cited with `[[ex-‹id›]]`.
+ *
+ * On top of the shared checks, both of the set's names are required
+ * (`ex-missing-prop`): the `id` its anchor and references need, and the
+ * `short` title its heading shows after the engine's "Example" badge. There is
+ * no default title to fall back on.
+ */
+
+type ExampleDiagnosticCode = 'ex-invalid-key' | 'ex-duplicate-key' | 'ex-ref-resolves' | 'ex-key-unused' | 'ex-removed-prop' | 'ex-missing-prop';
+interface ExampleDiagnostic {
+    readonly code: ExampleDiagnosticCode;
+    readonly severity: 'error' | 'warning' | 'info';
+    readonly message: string;
+    readonly file?: string;
+    readonly lessonId?: string;
+    readonly key?: string;
+}
+type ExampleLabelRecord = KeyedFloatLabelRecord;
+type ExampleLessonInput = KeyedFloatLessonInput;
+interface ExampleValidation extends KeyedFloatValidation {
+    readonly diagnostics: readonly ExampleDiagnostic[];
+}
+declare function validateExamples(lessons: readonly ExampleLessonInput[]): ExampleValidation;
+
+export { type ExampleDiagnostic, type ExampleDiagnosticCode, type ExampleLabelRecord, type ExampleLessonInput, type ExampleValidation, validateExamples };

package/dist/reference/examples-validate.js

@@ -0,0 +1,48 @@
+import {
+  validateKeyedFloats
+} from "./keyed-float-validate.js";
+import { scanKeyedJsxFloats } from "./keyed-jsx-floats.mjs";
+const REQUIRED_PROPS = {
+  id: "give it an `id` (lowercase letters, digits and hyphens): the set is anchored `#ex-\u2039id\u203A` and cited with `[[ex-\u2039id\u203A]]`.",
+  short: 'give it a `short` title naming the topic, e.g. "Converting between coordinate systems"; the engine draws "Example" and the number before it.'
+};
+function validateExamples(lessons) {
+  const shared = validateKeyedFloats(lessons, {
+    tagName: "CompactExamples",
+    prefix: "ex",
+    noun: "worked-example set",
+    removedProps: {
+      summary: 'rename it `short`: the set\u2019s topical title, shown after the engine\u2019s "Example" badge.'
+    }
+  });
+  const missing = [];
+  for (const lesson of lessons) {
+    const sets = scanKeyedJsxFloats(lesson.body, {
+      tagName: "CompactExamples",
+      numbering: lesson.numbering
+    });
+    for (const set of sets) {
+      for (const [prop, fix] of Object.entries(REQUIRED_PROPS)) {
+        if (set.props.includes(prop)) continue;
+        missing.push({
+          code: "ex-missing-prop",
+          severity: "error",
+          message: `${lesson.lessonId} has a <CompactExamples>${set.key ? ` (id="${set.key}")` : ""} with no \`${prop}\`: ${fix}`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          ...set.key ? { key: set.key } : {}
+        });
+      }
+    }
+  }
+  const diagnostics = [
+    ...shared.diagnostics,
+    ...missing
+  ].sort(
+    (a, b) => a.code.localeCompare(b.code) || (a.lessonId ?? "").localeCompare(b.lessonId ?? "") || (a.key ?? "").localeCompare(b.key ?? "") || a.message.localeCompare(b.message)
+  );
+  return { ...shared, diagnostics };
+}
+export {
+  validateExamples
+};

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

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

package/dist/reference/figures-validate.js

@@ -5,7 +5,10 @@ function validateFigures(lessons) {
   return validateKeyedFloats(lessons, {
     tagName: "Figure",
     prefix: "fig",
-    noun: "figure"
+    noun: "figure",
+    removedProps: {
+      title: "a figure is named by its `caption` (the long caption, shown below it with its number) and an optional `short` caption; move a short title to `short`."
+    }
   });
 }
 export {

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

@@ -0,0 +1,33 @@
+import { KeyedFloatLessonInput } from './keyed-float-validate.js';
+
+/**
+ * `<Fold>` validation, run inside `compileManifest()`
+ * (docs/plans/figures-and-short-captions.md, decision 11). A fold's bar is
+ * its `label` or, without one, the numbers and short captions of the floats
+ * it holds (`../components/float-name.ts`), so a fold needs one or the other:
+ *
+ * - `fold-unnamed` (error): a `<Fold>` with no `label` and no `<Figure>`,
+ *   `<Table>` or `<Diagram>` that takes a number inside it — its bar would
+ *   have nothing to show.
+ *
+ * `Fold.astro` throws on the same fold when it renders; this reports it
+ * earlier, at `validate:content`, with the lesson it is in. A float that a
+ * wrapper component renders counts when the lesson writes it under a float's
+ * tag name (`<Diagram id="…" />` for a wrapper imported as `Diagram`), the
+ * way the numbering scan sees it.
+ */
+
+type FoldDiagnosticCode = 'fold-unnamed';
+interface FoldDiagnostic {
+    readonly code: FoldDiagnosticCode;
+    readonly severity: 'error';
+    readonly message: string;
+    readonly file?: string;
+    readonly lessonId?: string;
+}
+interface FoldValidation {
+    readonly diagnostics: readonly FoldDiagnostic[];
+}
+declare function validateFolds(lessons: readonly KeyedFloatLessonInput[]): FoldValidation;
+
+export { type FoldDiagnostic, type FoldDiagnosticCode, type FoldValidation, validateFolds };

package/dist/reference/folds-validate.js

@@ -0,0 +1,32 @@
+import { stripFencedCode } from "./equations.mjs";
+import { scanKeyedJsxFloats } from "./keyed-jsx-floats.mjs";
+const ATTRIBUTES = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'])*`;
+const FOLD = new RegExp(`<Fold\\b(${ATTRIBUTES})>([\\s\\S]*?)<\\/Fold\\s*>`, "g");
+const NUMBERED_FLOATS = ["Figure", "Table", "Diagram"];
+function validateFolds(lessons) {
+  const diagnostics = [];
+  for (const lesson of [...lessons].sort(
+    (a, b) => a.lessonId.localeCompare(b.lessonId)
+  )) {
+    for (const [, attributes = "", body = ""] of stripFencedCode(lesson.body).matchAll(
+      FOLD
+    )) {
+      if (/(?:^|\s)label\s*=/.test(attributes)) continue;
+      const named = NUMBERED_FLOATS.some(
+        (tagName) => scanKeyedJsxFloats(body, { tagName, numbering: void 0 }).length > 0
+      );
+      if (named) continue;
+      diagnostics.push({
+        code: "fold-unnamed",
+        severity: "error",
+        message: `${lesson.lessonId} has a <Fold> with no \`label\` and no numbered <Figure>, <Table> or <Diagram> inside it, so its bar has nothing to name it by: give it a \`label\`, or fold a numbered float with it.`,
+        file: lesson.file,
+        lessonId: lesson.lessonId
+      });
+    }
+  }
+  return { diagnostics };
+}
+export {
+  validateFolds
+};

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

@@ -1,6 +1,8 @@
 import { MathGateDiagnostic } from './gate-math.js';
 import { NotationRegistryInput, AbbreviationDefinitionInput } from './types.js';
-import { CourseAbbreviations } from '../compiler/course-config.js';
+import { a as CourseAbbreviations } from '../course-config-Dsnri9Tk.js';
+import '../rules/catalog.js';
+import '../rules/course-rules.js';
 
 /**
  * Scan every lesson body for an abbreviation-shaped token outside `$…$` that

package/dist/reference/gate-abbreviations.js

@@ -1,7 +1,7 @@
 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";
+import { lessonLine, 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) {
@@ -49,9 +49,10 @@ function gateAbbreviations(input) {
       reported.add(token);
       diagnostics.push({
         context: "abbreviation",
+        code: "abbreviation-unexplained",
         severity: "error",
         file: lesson.source.file,
-        line: lineOf(lesson.body, index),
+        line: lessonLine(lesson, index),
         token,
         message: `Unexplained abbreviation ${JSON.stringify(token)} outside math. ${FIX}`
       });

package/dist/reference/gate-course-rules.d.ts

@@ -0,0 +1,32 @@
+import { MathGateDiagnostic } from './gate-math.js';
+import { NotationLessonInput } from './types.js';
+import { CourseRule } from '../rules/course-rules.js';
+import '../rules/catalog.js';
+
+/**
+ * The gate for a course's own rules (`courseRules` in `course.settings.json`,
+ * resolved by `src/rules/course-rules.ts`).
+ *
+ * One loop over every enabled course rule's `forbid` patterns, matched against
+ * the same "is this really prose" surface rule N9 uses — `proseOnly` blanks
+ * code fences, inline code, `$…$` / `$$…$$`, `[[key]]` references, `import`
+ * lines, JSX tags and MDX comments to spaces, so offsets still point at the
+ * source. A match becomes a `MathGateDiagnostic` with the rule's own ID as its
+ * code and a lesson `file` + `line`, which is what lets `{/* explico-allow X1:
+ * reason *\/}` waive one place.
+ *
+ * Nothing here knows what a rule *means*: the patterns come from the course,
+ * already validated (they compile, and none matches the empty string). The
+ * three scopes are the three units an author can reason about — a paragraph, a
+ * whole lesson's prose, a heading.
+ */
+
+/**
+ * Scan every lesson body for what the course's own rules forbid. Only enabled
+ * rules with at least one pattern do anything; a guide rule is not this gate's
+ * business. Findings carry the rule ID as `code`, so `ownerOf` / `ruleIdOf`
+ * name the rule and a waiver can target it.
+ */
+declare function gateCourseRules(lessons: readonly NotationLessonInput[], rules: readonly CourseRule[]): MathGateDiagnostic[];
+
+export { gateCourseRules };

package/dist/reference/gate-course-rules.js

@@ -0,0 +1,85 @@
+import { lessonLine, proseOnly } from "./gate-prose-notation.js";
+const HEADING = /^[ \t]{0,3}(#{1,6})[ \t]+(.*)$/;
+function paragraphs(text) {
+  const units = [];
+  let index = 0;
+  let start = -1;
+  const lines = text.split("\n");
+  lines.forEach((line, i) => {
+    const blank = line.trim() === "";
+    if (!blank && start === -1) start = index;
+    if ((blank || i === lines.length - 1) && start !== -1) {
+      const end = blank ? index : index + line.length;
+      units.push({ text: text.slice(start, end).replace(/\s+$/, ""), index: start });
+      start = -1;
+    }
+    index += line.length + 1;
+  });
+  return units.filter((unit) => unit.text !== "");
+}
+function headings(text) {
+  const units = [];
+  let index = 0;
+  for (const line of text.split("\n")) {
+    const match = HEADING.exec(line);
+    if (match !== null) {
+      const body = match[2].replace(/\s+#*\s*$/, "");
+      if (body !== "") {
+        units.push({ text: body, index: index + line.indexOf(body) });
+      }
+    }
+    index += line.length + 1;
+  }
+  return units;
+}
+function unitsFor(scope, prose) {
+  switch (scope) {
+    case "prose":
+      return [{ text: prose, index: 0 }];
+    case "heading":
+      return headings(prose);
+    case "paragraph":
+      return paragraphs(prose);
+  }
+}
+function* matches(pattern, unit) {
+  const regex = new RegExp(pattern.pattern, `${pattern.flags}g`);
+  let match;
+  while ((match = regex.exec(unit.text)) !== null) {
+    yield [unit.index + match.index, match[0]];
+    if (match.index === regex.lastIndex) regex.lastIndex += 1;
+  }
+}
+function gateCourseRules(lessons, rules) {
+  const active = rules.filter((rule) => rule.enabled && rule.forbid.length > 0);
+  if (active.length === 0) return [];
+  const diagnostics = [];
+  for (const lesson of lessons) {
+    const prose = proseOnly(lesson.body);
+    const cache = /* @__PURE__ */ new Map();
+    for (const rule of active) {
+      for (const pattern of rule.forbid) {
+        if (!cache.has(pattern.scope)) cache.set(pattern.scope, unitsFor(pattern.scope, prose));
+        for (const unit of cache.get(pattern.scope)) {
+          for (const [index, token] of matches(pattern, unit)) {
+            diagnostics.push({
+              context: "course",
+              code: rule.id,
+              severity: rule.severity,
+              file: lesson.source.file,
+              line: lessonLine(lesson, index),
+              // The matched text, trimmed — unless the pattern deliberately
+              // matched whitespace, in which case there is nothing else to show.
+              token: token.trim() || token,
+              message: `${pattern.message} (course rule ${rule.id})`
+            });
+          }
+        }
+      }
+    }
+  }
+  return diagnostics;
+}
+export {
+  gateCourseRules
+};

package/dist/reference/gate-heading-length.d.ts

@@ -1,12 +1,15 @@
 import { MathGateDiagnostic } from './gate-math.js';
 import { NotationLessonInput } from './types.js';
 
+/** Rule S1's default; a course sets its own with `rules.S1.maxLength`. */
 declare const HEADING_LENGTH_LIMIT = 65;
 /**
- * Scan every lesson body for a heading or a keyed float's title running past
+ * Scan every lesson body for a heading or a short caption running past
  * `HEADING_LENGTH_LIMIT` characters. Returns one `MathGateDiagnostic`
  * (context `'structure'`, always an error) per finding.
  */
-declare function gateHeadingLength(lessons: readonly NotationLessonInput[]): MathGateDiagnostic[];
+declare function gateHeadingLength(lessons: readonly NotationLessonInput[], options?: {
+    readonly maxLength?: number;
+}): MathGateDiagnostic[];
 
 export { HEADING_LENGTH_LIMIT, gateHeadingLength };