explico 0.12.0 → 0.13.1

package/dist/reference/equations.d.mts

@@ -74,6 +74,27 @@ export function stripFencedCode(markdown: any): string;
  * a transparent body do not change the surrounding page's section counter.
  */
 export function stripJsxComponents(markdown: any, keep: any, transparent?: any[]): string;
+/**
+ * Blank the body of every `:::name … :::` container directive — a Starlight
+ * aside (`:::note`, `:::tip`, …) — keeping newlines, the text-scan twin of a
+ * tree walk that never enters a `containerDirective`. An aside is a callout,
+ * like `<Aside>`: what it holds is illustrative and numbers nothing. A fence
+ * of more colons closes only on as many; one left open runs to the end.
+ */
+export function stripContainerDirectives(markdown: any): string;
+/**
+ * Every `$$` display block in a Markdown text the way remark-math reads one:
+ * an opening fence of two or more `$` that starts a line — inside a list item
+ * or a blockquote too — with nothing but a `$`-free meta after it, up to a
+ * closing fence of at least as many `$` on a line of its own (or the end of
+ * the text). `$$x$$` inside a paragraph, or on one line, is inline math and
+ * is not a display block. Each block is `{ index, body }`: the offset of its
+ * opening line and the text between the fences.
+ */
+export function displayMathBlocks(markdown: any): {
+    index: number;
+    body: string;
+}[];
 /**
  * Every display equation in a Markdown body, keyed or not, in appearance order
  * with its assigned number and its `\caption{}` short caption (`short`, or
@@ -94,6 +115,12 @@ export function scanDisplayEquations(markdown: any, numbering: any): {
     section: number;
     indexInSection: number;
 }[];
+/**
+ * The keys of each display block that carries more than one `\label{eq:…}`,
+ * in order. A block is one numbered equation: its first label names it, and
+ * a later one would name nothing.
+ */
+export function repeatedEquationLabels(markdown: any): string[][];
 /** The keyed subset of `scanDisplayEquations` — the manifest builder's view. */
 export function scanEquationLabels(markdown: any, numbering: any): {
     key: string | null | undefined;

package/dist/reference/equations.mjs

@@ -204,6 +204,87 @@ export function stripJsxComponents(markdown, keep, transparent = []) {
  */
 export const TRANSPARENT_COMPONENTS = Object.freeze(['Memo', 'ShortNote', 'Fold']);
 
+/**
+ * Blank the body of every `:::name … :::` container directive — a Starlight
+ * aside (`:::note`, `:::tip`, …) — keeping newlines, the text-scan twin of a
+ * tree walk that never enters a `containerDirective`. An aside is a callout,
+ * like `<Aside>`: what it holds is illustrative and numbers nothing. A fence
+ * of more colons closes only on as many; one left open runs to the end.
+ */
+export function stripContainerDirectives(markdown) {
+  const lines = String(markdown).split('\n');
+  let fence = 0;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index] ?? '';
+    if (fence === 0) {
+      const open = /^[ \t]{0,3}(:{3,})[A-Za-z]/.exec(line);
+      if (!open) continue;
+      fence = open[1].length;
+      lines[index] = line.replace(/[^\n]/g, ' ');
+      continue;
+    }
+    const close = /^[ \t]{0,3}(:{3,})[ \t]*$/.exec(line);
+    if (close && close[1].length >= fence) fence = 0;
+    lines[index] = line.replace(/[^\n]/g, ' ');
+  }
+  return lines.join('\n');
+}
+
+/** A line with its blockquote markers, list marker and indentation removed. */
+function containerContent(line) {
+  let rest = String(line);
+  for (;;) {
+    const next = rest
+      .replace(/^[ \t]*>[ \t]?/, '')
+      .replace(/^[ \t]*(?:[-*+]|\d{1,9}[.)])[ \t]+/, '');
+    if (next === rest) return rest.replace(/^[ \t]+/, '');
+    rest = next;
+  }
+}
+
+/**
+ * Every `$$` display block in a Markdown text the way remark-math reads one:
+ * an opening fence of two or more `$` that starts a line — inside a list item
+ * or a blockquote too — with nothing but a `$`-free meta after it, up to a
+ * closing fence of at least as many `$` on a line of its own (or the end of
+ * the text). `$$x$$` inside a paragraph, or on one line, is inline math and
+ * is not a display block. Each block is `{ index, body }`: the offset of its
+ * opening line and the text between the fences.
+ */
+export function displayMathBlocks(markdown) {
+  const text = String(markdown);
+  const lines = text.split('\n');
+  const starts = [];
+  let offset = 0;
+  for (const line of lines) {
+    starts.push(offset);
+    offset += line.length + 1;
+  }
+  const blocks = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const open = /^(\${2,})[ \t]*[^$]*$/.exec(containerContent(lines[index]));
+    if (!open) continue;
+    const size = open[1].length;
+    let end = lines.length;
+    for (let next = index + 1; next < lines.length; next += 1) {
+      const close = /^(\${2,})[ \t]*$/.exec(containerContent(lines[next]));
+      if (close && close[1].length >= size) {
+        end = next;
+        break;
+      }
+    }
+    blocks.push({
+      index: starts[index],
+      body: lines
+        .slice(index + 1, end)
+        .map((line) => containerContent(line))
+        .join('\n'),
+    });
+    index = end;
+  }
+  return blocks;
+}
+
 /**
  * Every display equation in a Markdown body, keyed or not, in appearance order
  * with its assigned number and its `\caption{}` short caption (`short`, or
@@ -219,25 +300,20 @@ export const TRANSPARENT_COMPONENTS = Object.freeze(['Memo', 'ShortNote', 'Fold'
  */
 export function scanDisplayEquations(markdown, numbering) {
   const { prefix, offset } = resolveNumbering(numbering);
-  const text = stripJsxComponents(
-    stripFencedCode(markdown),
-    undefined,
-    TRANSPARENT_COMPONENTS,
-  );
+  const text = equationText(markdown);
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
-  const display = /\$\$([\s\S]+?)\$\$/g;
   for (const match of text.matchAll(heading)) {
     tokens.push({ kind: 'section', index: match.index });
   }
-  for (const match of text.matchAll(display)) {
+  for (const block of displayMathBlocks(text)) {
     EQ_LABEL_PATTERN.lastIndex = 0;
-    const label = EQ_LABEL_PATTERN.exec(match[1]);
+    const label = EQ_LABEL_PATTERN.exec(block.body);
     tokens.push({
       kind: 'equation',
-      index: match.index,
+      index: block.index,
       key: label ? label[1] : null,
-      short: equationCaption(match[1]),
+      short: equationCaption(block.body),
     });
   }
   tokens.sort((a, b) => a.index - b.index);
@@ -271,6 +347,31 @@ export function scanDisplayEquations(markdown, numbering) {
   return labels;
 }
 
+/**
+ * A lesson body as the equation scans read it: no fenced code, no component
+ * but the transparent ones, no `:::` directive body.
+ */
+function equationText(markdown) {
+  return stripContainerDirectives(
+    stripJsxComponents(stripFencedCode(markdown), undefined, TRANSPARENT_COMPONENTS),
+  );
+}
+
+/**
+ * The keys of each display block that carries more than one `\label{eq:…}`,
+ * in order. A block is one numbered equation: its first label names it, and
+ * a later one would name nothing.
+ */
+export function repeatedEquationLabels(markdown) {
+  return displayMathBlocks(equationText(markdown))
+    // A copy: `matchAll` starts at the shared pattern's `lastIndex`, which
+    // `scanDisplayEquations`' `exec` leaves past the label it found.
+    .map((block) =>
+      [...block.body.matchAll(new RegExp(EQ_LABEL_PATTERN.source, 'g'))].map((match) => match[1]),
+    )
+    .filter((keys) => keys.length > 1);
+}
+
 /** The keyed subset of `scanDisplayEquations` — the manifest builder's view. */
 export function scanEquationLabels(markdown, numbering) {
   return scanDisplayEquations(markdown, numbering).filter(
@@ -301,13 +402,16 @@ export function collectDisplayEquations(tree, numbering) {
   let indexInSection = 0;
   let indexInLesson = 0;
 
-  // 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.
+  // The lesson's flow — top-level blocks, list items, blockquotes — plus the
+  // bodies of the `TRANSPARENT_COMPONENTS`: other MDX components (a
+  // `<CompactExample>` worked example, an `<Aside>`) and `:::note`-style
+  // asides 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. `scanDisplayEquations` reads the
+  // same set from the text.
   const collectFromDetail = (node) => {
     if (!node || typeof node !== 'object') return;
+    if (node.type === 'containerDirective') return;
     if (node.type === 'math') {
       indexInSection += 1;
       indexInLesson += 1;
@@ -347,13 +451,7 @@ export function collectDisplayEquations(tree, numbering) {
       indexInSection = 0;
       continue;
     }
-    if (node.type === 'math') collectFromDetail(node);
-    else if (
-      node.type === 'mdxJsxFlowElement' &&
-      TRANSPARENT_COMPONENTS.includes(node.name)
-    ) {
-      collectFromDetail(node);
-    }
+    collectFromDetail(node);
   }
   return equations;
 }

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

@@ -12,7 +12,7 @@ import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } fr
  * 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';
+type ExampleDiagnosticCode = 'ex-invalid-key' | 'ex-duplicate-key' | 'ex-ref-resolves' | 'ex-key-unused' | 'ex-removed-prop' | 'ex-unread-prop' | 'ex-missing-prop';
 interface ExampleDiagnostic {
     readonly code: ExampleDiagnosticCode;
     readonly severity: 'error' | 'warning' | 'info';

package/dist/reference/figure-fit.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Rule V7 — a figure's picture fits on one screen.
+ *
+ * A picture's height is only known once the browser has laid the page out and
+ * hydrated its islands, so this check runs in a course's Playwright suite, not
+ * in the build: open each lesson that has a figure, call
+ * {@link checkFigureFit}, and expect no findings. The pure half,
+ * {@link figureFitFindings}, turns measured heights into findings and is what
+ * the unit tests pin.
+ */
+/** The share of the screen height a picture may take unless the course sets `rules.V7.maxPercent`. */
+declare const FIGURE_FIT_MAX_PERCENT = 80;
+/** One `<Figure>` as measured on a rendered page. */
+interface FigureMeasurement {
+    /** The figure's anchor, `fig-<key>`. */
+    readonly anchor: string;
+    /** Its number, `2.1.3`. */
+    readonly number: string;
+    /** Height of the picture — the figure's default slot — in CSS pixels. */
+    readonly height: number;
+}
+interface FigureFitFinding {
+    readonly code: 'figure-too-tall';
+    readonly severity: 'warning';
+    readonly rule: 'V7';
+    readonly anchor: string;
+    readonly number: string;
+    readonly height: number;
+    /** The tallest picture the budget allows at this screen height, in CSS pixels. */
+    readonly limit: number;
+    readonly message: string;
+}
+/**
+ * The pictures taller than `maxPercent` of a `screenHeight`-pixel screen.
+ * A picture of height zero is skipped: nothing was drawn to judge.
+ */
+declare function figureFitFindings(measured: readonly FigureMeasurement[], screenHeight: number, maxPercent?: number): FigureFitFinding[];
+/** The part of a Playwright `Page` the check uses. */
+interface FigureFitPage {
+    evaluate<R>(pageFunction: () => R | Promise<R>): Promise<R>;
+    viewportSize(): {
+        readonly width: number;
+        readonly height: number;
+    } | null;
+}
+/**
+ * Measure every `<Figure>` on the open page and report the pictures that break
+ * rule V7 at the page's current viewport. A figure inside a closed `<Fold>` or
+ * `<details>` is opened first, since a reader can open it; each figure is
+ * scrolled into view and waits for its islands to hydrate and its height to
+ * settle before it is measured.
+ */
+declare function checkFigureFit(page: FigureFitPage, options?: {
+    readonly maxPercent?: number;
+    /** Figures exempt from the budget, by anchor (`fig-<key>`), each with the reason it may be taller. */
+    readonly allow?: Readonly<Record<string, string>>;
+}): Promise<FigureFitFinding[]>;
+/**
+ * The lesson paths whose manifest entry has at least one figure — the pages a
+ * course's V7 test opens. Pass the manifest the build wrote
+ * (`build/manifest.json`).
+ */
+declare function lessonsWithFigures(manifest: {
+    readonly lessons: readonly {
+        readonly slug: string;
+        readonly figures: readonly unknown[];
+    }[];
+}): string[];
+
+export { FIGURE_FIT_MAX_PERCENT, type FigureFitFinding, type FigureFitPage, type FigureMeasurement, checkFigureFit, figureFitFindings, lessonsWithFigures };

package/dist/reference/figure-fit.js

@@ -0,0 +1,60 @@
+const FIGURE_FIT_MAX_PERCENT = 80;
+function figureFitFindings(measured, screenHeight, maxPercent = FIGURE_FIT_MAX_PERCENT) {
+  const limit = Math.floor(screenHeight * maxPercent / 100);
+  return measured.filter((figure) => figure.height > limit).map((figure) => ({
+    code: "figure-too-tall",
+    severity: "warning",
+    rule: "V7",
+    anchor: figure.anchor,
+    number: figure.number,
+    height: figure.height,
+    limit,
+    message: `Figure ${figure.number} (#${figure.anchor}): its picture is ${figure.height}px tall, ${Math.round(figure.height / screenHeight * 100)}% of a ${screenHeight}px screen; rule V7 allows ${maxPercent}% (${limit}px). Give a square or tall plot a fixed width instead of the full column, or split stacked panels.`
+  }));
+}
+async function checkFigureFit(page, options = {}) {
+  const viewport = page.viewportSize();
+  if (!viewport) throw new Error("checkFigureFit needs a page with a fixed viewport size.");
+  const measured = await page.evaluate(measureFigures);
+  const allow = options.allow ?? {};
+  for (const [anchor, reason] of Object.entries(allow)) {
+    if (!reason.trim()) throw new Error(`checkFigureFit: the exemption for #${anchor} needs a reason.`);
+  }
+  return figureFitFindings(
+    measured.filter((figure) => !(figure.anchor in allow)),
+    viewport.height,
+    options.maxPercent
+  );
+}
+function lessonsWithFigures(manifest) {
+  return manifest.lessons.filter((lesson) => lesson.figures.length > 0).map((lesson) => `/${lesson.slug}/`);
+}
+async function measureFigures() {
+  const nextFrame = () => new Promise((resolve) => requestAnimationFrame(() => resolve()));
+  const out = [];
+  for (const figure of document.querySelectorAll("figure.keyed-figure")) {
+    for (let fold = figure.parentElement?.closest("details"); fold; fold = fold.parentElement?.closest("details")) {
+      fold.open = true;
+    }
+    const body = figure.querySelector(":scope > .keyed-figure__body");
+    if (!body) continue;
+    figure.scrollIntoView({ block: "start" });
+    const deadline = performance.now() + 5e3;
+    while (body.querySelector("astro-island[ssr]") && performance.now() < deadline) await nextFrame();
+    let height = -1;
+    for (let still = 0, frames = 0; still < 5 && frames < 120; frames++) {
+      await nextFrame();
+      const now = body.getBoundingClientRect().height;
+      still = Math.abs(now - height) < 0.5 ? still + 1 : 0;
+      height = now;
+    }
+    out.push({ anchor: figure.id, number: figure.dataset.figNumber ?? "", height: Math.round(height) });
+  }
+  return out;
+}
+export {
+  FIGURE_FIT_MAX_PERCENT,
+  checkFigureFit,
+  figureFitFindings,
+  lessonsWithFigures
+};

package/dist/reference/figure-pictures.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Every figure has its picture in the built page (rule V3). A lab draws its
+ * plot in the browser, after the page loads, so without a copy drawn at
+ * build time the page holds an empty box until then: a reference card made
+ * from the page (from another page, or before the figure scrolls into view)
+ * has only the caption, and so do print without JavaScript and the
+ * standalone HTML export. A lab draws its default picture at build time and
+ * hands it to its island as children (`still-plot.ts` in the playground).
+ *
+ * `undrawnFigurePictures` reads rendered HTML: a `figure.keyed-figure` whose
+ * picture (`.keyed-figure__body`) holds an `<astro-island>` but nothing drawn
+ * (`svg`, `img`, `picture`, `canvas`, `video` or `table`) is reported.
+ * `compiler/astro.ts` runs it on every built page and warns; it is a
+ * warning, not an error, since the figure still works once hydrated.
+ */
+/** The diagnostic a built page with an undrawn picture gets. */
+interface UndrawnFigurePicture {
+    readonly code: 'lab-picture-undrawn';
+    /** The figure's anchor id, e.g. `fig-launch-angle-explorer`. */
+    readonly figure: string;
+}
+/** The figures in `html` whose picture is an island with nothing drawn. */
+declare function undrawnFigurePictures(html: string): UndrawnFigurePicture[];
+/** The build's warning for one page, naming each figure and what to do. */
+declare function undrawnFigureWarning(page: string, figures: readonly UndrawnFigurePicture[]): string;
+
+export { type UndrawnFigurePicture, undrawnFigurePictures, undrawnFigureWarning };

package/dist/reference/figure-pictures.js

@@ -0,0 +1,49 @@
+import { parse } from "parse5";
+const DRAWN = /* @__PURE__ */ new Set(["svg", "img", "picture", "canvas", "video", "table"]);
+function isElement(node) {
+  return "tagName" in node;
+}
+function attribute(node, name) {
+  return node.attrs.find((attr) => attr.name === name)?.value;
+}
+function hasClass(node, name) {
+  return (attribute(node, "class") ?? "").split(/\s+/u).includes(name);
+}
+function childrenOf(node) {
+  if (isElement(node) && node.tagName === "template") return [];
+  return "childNodes" in node ? node.childNodes : [];
+}
+function find(node, test) {
+  for (const child of childrenOf(node)) {
+    if (!isElement(child)) continue;
+    if (test(child)) return child;
+    const inner = find(child, test);
+    if (inner) return inner;
+  }
+  return void 0;
+}
+function undrawnFigurePictures(html) {
+  if (!html.includes("keyed-figure") || !html.includes("astro-island")) return [];
+  const found = [];
+  const visit = (node) => {
+    for (const child of childrenOf(node)) {
+      if (!isElement(child)) continue;
+      if (child.tagName === "figure" && hasClass(child, "keyed-figure")) {
+        const body = find(child, (el) => hasClass(el, "keyed-figure__body"));
+        if (body && find(body, (el) => el.tagName === "astro-island") && !find(body, (el) => DRAWN.has(el.tagName))) {
+          found.push({ code: "lab-picture-undrawn", figure: attribute(child, "id") ?? "" });
+        }
+      }
+      visit(child);
+    }
+  };
+  visit(parse(html));
+  return found;
+}
+function undrawnFigureWarning(page, figures) {
+  return `lab-picture-undrawn (rule V3): on rendered page "${page}", ` + figures.map(({ figure }) => `#${figure}`).join(", ") + " draw nothing until the browser runs the island, so a preview card, print without JavaScript and the HTML export show no picture. Draw the default picture at build time and pass it to the island as its children.";
+}
+export {
+  undrawnFigurePictures,
+  undrawnFigureWarning
+};

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' | 'fig-removed-prop';
+type FigureDiagnosticCode = 'fig-invalid-key' | 'fig-duplicate-key' | 'fig-ref-resolves' | 'fig-key-unused' | 'fig-removed-prop' | 'fig-unread-prop';
 interface FigureDiagnostic {
     readonly code: FigureDiagnosticCode;
     readonly severity: 'error' | 'warning' | 'info';

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

@@ -1,6 +1,6 @@
 import { MathGateDiagnostic } from './gate-math.js';
 import { NotationRegistryInput, AbbreviationDefinitionInput } from './types.js';
-import { a as CourseAbbreviations } from '../course-config-Dsnri9Tk.js';
+import { h as CourseAbbreviations } from '../course-config-rRtME5UV.js';
 import '../rules/catalog.js';
 import '../rules/course-rules.js';
 

package/dist/reference/gate-abbreviations.js

@@ -14,7 +14,7 @@ function findAbbreviationLikeTokens(text) {
   }
   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.";
+const FIX = "Add it to an abbreviations-table entry (content/abbreviations/*.md), allowlist it in rules.N14.allow in the course config (course.config.ts, or the course.settings.json it reads) 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();

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

@@ -9,9 +9,10 @@ import '../rules/catalog.js';
  *
  * 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 fences, inline code, `$…$` / `$$…$$`, `[[key]]` references, link
+ * addresses, `import` lines, JSX tags and MDX comments to spaces, so offsets
+ * still point at the source — plus the text of each visible prop (`caption`,
+ * `short`, `title`, `label`) as a paragraph of its own. 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.
  *

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

@@ -1,4 +1,5 @@
 import { lessonLine, proseOnly } from "./gate-prose-notation.js";
+import { propStrings } from "./gate-prop-text.js";
 const HEADING = /^[ \t]{0,3}(#{1,6})[ \t]+(.*)$/;
 function paragraphs(text) {
   const units = [];
@@ -32,14 +33,18 @@ function headings(text) {
   }
   return units;
 }
-function unitsFor(scope, prose) {
+const VISIBLE_PROPS = /* @__PURE__ */ new Set(["caption", "short", "title", "label"]);
+function visibleProps(body) {
+  return propStrings(body).filter((prop) => VISIBLE_PROPS.has(prop.name) && prop.value.trim() !== "").map((prop) => ({ text: prop.value, index: prop.offset }));
+}
+function unitsFor(scope, prose, body) {
   switch (scope) {
     case "prose":
-      return [{ text: prose, index: 0 }];
+      return [{ text: prose, index: 0 }, ...visibleProps(body)];
     case "heading":
       return headings(prose);
     case "paragraph":
-      return paragraphs(prose);
+      return [...paragraphs(prose), ...visibleProps(body)];
   }
 }
 function* matches(pattern, unit) {
@@ -59,7 +64,7 @@ function gateCourseRules(lessons, rules) {
     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));
+        if (!cache.has(pattern.scope)) cache.set(pattern.scope, unitsFor(pattern.scope, prose, lesson.body));
         for (const unit of cache.get(pattern.scope)) {
           for (const [index, token] of matches(pattern, unit)) {
             diagnostics.push({

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

@@ -10,6 +10,8 @@ declare const HEADING_LENGTH_LIMIT = 65;
  */
 declare function gateHeadingLength(lessons: readonly NotationLessonInput[], options?: {
     readonly maxLength?: number;
+    /** A `[[key]]` term's label on a lesson's page, as a heading shows it. */
+    readonly labelFor?: (lessonId: string, key: string) => string | undefined;
 }): MathGateDiagnostic[];
 
 export { HEADING_LENGTH_LIMIT, gateHeadingLength };

package/dist/reference/gate-heading-length.js

@@ -1,5 +1,6 @@
 import { EQ_CAPTION_PATTERN, stripFencedCode } from "./equations.mjs";
 import { stripHeadingMarker } from "./rehype-heading-anchors.mjs";
+import { headingDisplayText } from "./sections.mjs";
 import { lessonLine } from "./gate-prose-notation.js";
 const HEADING_LENGTH_LIMIT = 65;
 const HEADING_LINE = /^[ \t]{0,3}(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/gm;
@@ -20,13 +21,13 @@ function readAttribute(attributesSource, name) {
 function overLimitMessage(kind, text, limit) {
   return `${kind} ${JSON.stringify(text)} is ${text.length} characters, over the ${limit}-character limit (rule S1, rules.S1.maxLength in the course settings). Shorten it and move the rest into the paragraph or caption that follows.`;
 }
-function headingFindings(text, limit) {
+function headingFindings(text, limit, labelFor) {
   const out = [];
   const re = new RegExp(HEADING_LINE.source, HEADING_LINE.flags);
   let match;
   while (match = re.exec(text)) {
     const level = match[1]?.length ?? 1;
-    const title = stripHeadingMarker(match[2] ?? "").trim();
+    const title = headingDisplayText(stripHeadingMarker(match[2] ?? ""), { labelFor });
     if (title.length > limit) {
       out.push({
         index: match.index,
@@ -71,9 +72,9 @@ function equationCaptionFindings(text, limit) {
   }
   return out;
 }
-function findingsIn(text, limit) {
+function findingsIn(text, limit, labelFor) {
   return [
-    ...headingFindings(text, limit),
+    ...headingFindings(text, limit, labelFor),
     ...floatTitleFindings(text, limit),
     ...equationCaptionFindings(text, limit)
   ].sort((a, b) => a.index - b.index);
@@ -83,7 +84,8 @@ function gateHeadingLength(lessons, options = {}) {
   const limit = options.maxLength ?? HEADING_LENGTH_LIMIT;
   for (const lesson of lessons) {
     const text = stripFencedCode(lesson.body);
-    for (const finding of findingsIn(text, limit)) {
+    const labelFor = options.labelFor ? (key) => options.labelFor?.(lesson.lessonId, key) : void 0;
+    for (const finding of findingsIn(text, limit, labelFor)) {
       diagnostics.push({
         context: "structure",
         code: "title-length",

package/dist/reference/gate-heading-structure.js

@@ -67,6 +67,31 @@ function skipFindings(blocks) {
   }
   return out;
 }
+const HOSTS = ["Memo", "ShortNote"];
+function nestedFindings(body) {
+  const blank = (match) => match.replace(/[^\n]/g, " ");
+  const text = body.replace(/```[\s\S]*?```/g, blank).replace(/\{\/\*[\s\S]*?\*\/\}/g, blank);
+  const out = [];
+  for (const host of HOSTS) {
+    const opening = new RegExp(`<${host}\\b(?:[^>"']|"[^"]*"|'[^']*')*(?<!/)>`, "g");
+    for (const open of text.matchAll(opening)) {
+      const start = (open.index ?? 0) + open[0].length;
+      const end = text.indexOf(`</${host}>`, start);
+      if (end === -1) continue;
+      for (const inner of text.slice(start, end).matchAll(/<(AssessmentSet|CompactExamples)\b/g)) {
+        const name = inner[1];
+        const what = name === "CompactExamples" ? "set of worked examples" : "knowledge check";
+        out.push({
+          code: "heading-nested",
+          index: start + (inner.index ?? 0),
+          token: `<${name}>`,
+          message: `\`<${name}>\` sits inside a \`<${host}>\`, ${TITLED_COMPONENTS[name].what}, ${host === "Memo" ? "under the memo\u2019s own `<h6>`" : "in the middle of the note"}: the heading order jumps, and "On this page" never lists it (rule S6). A ${what} is a section of the lesson: put it at the top level, after the ${host === "Memo" ? "memo" : "paragraph"}.`
+        });
+      }
+    }
+  }
+  return out;
+}
 function adjacentFindings(blocks, lesson) {
   const out = [];
   blocks.forEach((block, position) => {
@@ -92,6 +117,7 @@ function gateHeadingStructure(lessons, options = {}) {
     const blocks = blocksOf(lesson.body);
     const findings = [
       ...levels ? skipFindings(blocks) : [],
+      ...levels ? nestedFindings(lesson.body) : [],
       ...adjacency ? adjacentFindings(blocks, lesson) : []
     ].sort((a, b) => a.index - b.index);
     for (const finding of findings) {

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

@@ -0,0 +1,35 @@
+import { ScopeEntry, AssessmentLike, LessonAssessmentLink, MathGateDiagnostic } from './gate-math.js';
+import { ResolvedGloss } from './gloss.js';
+import { NotationLessonInput, DerivedUse, IndexedSymbol } from './types.js';
+
+/** What the check needs of an entry besides its glyph-table row. */
+interface IndexEntryFacts extends ScopeEntry {
+    readonly range?: string;
+    readonly formula?: string;
+    readonly glosses?: readonly ResolvedGloss[];
+    readonly source?: {
+        readonly file: string;
+    };
+}
+/**
+ * Run rule N23 over every lesson (and non-chapter page) body, every notation
+ * formula and every assessment, and collect the derived cards each body
+ * uses. `entries` holds every shared entry by key; a lesson's own come from
+ * its `localDefinitions`. The index-set check (`index-range`) reads lesson
+ * bodies only: a letter's set is stated on its card or on the page.
+ */
+declare function gateIndices(lessons: readonly NotationLessonInput[], entries: ReadonlyMap<string, IndexEntryFacts>, extras?: {
+    readonly assessments?: readonly AssessmentLike[];
+    readonly lessonAssessments?: readonly LessonAssessmentLink[];
+}): {
+    diagnostics: MathGateDiagnostic[];
+    derivedByLesson: Map<string, DerivedUse[]>;
+};
+/**
+ * Rule N23's findings in one math source rendered outside a lesson body — a
+ * lab's or a diagram's, which fail the build as they render — as one line
+ * each: the form, what explains none of it, and the fix.
+ */
+declare function indexFindings(indices: readonly IndexedSymbol[]): string[];
+
+export { DerivedUse, type IndexEntryFacts, gateIndices, indexFindings };