explico 0.11.1 → 0.13.0

package/src/reference/rehype-heading-anchors.mjs

@@ -69,6 +69,11 @@ const HEADING_TAG = /^h([1-6])$/;
 const LINK_ICON_PATH =
   'm12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 1 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 0 0-1.42-1.42m8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 1 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 0 0 0 1.42 1 1 0 0 0 1.42 0l3.88-3.89a4.49 4.49 0 0 0 0-6.33M8.83 15.17a1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.92-4.92a1 1 0 1 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42';
 
+/**
+ * A heading's text as a reader hears it. KaTeX writes each formula twice —
+ * MathML, whose `<annotation>` holds the LaTeX, and the `aria-hidden` glyphs —
+ * so a formula is read once, from its MathML, without the LaTeX.
+ */
 function headingText(node) {
   let text = '';
   const walk = (current) => {
@@ -77,10 +82,15 @@ function headingText(node) {
       text += String(current.value ?? '');
       return;
     }
+    if (current.type === 'element') {
+      const classes = current.properties?.className;
+      if (current.tagName === 'annotation') return;
+      if (Array.isArray(classes) && classes.includes('katex-html')) return;
+    }
     if (Array.isArray(current.children)) current.children.forEach(walk);
   };
   walk(node);
-  return text.replace(/\s+/g, ' ').trim();
+  return text.replace(/[\u200b\u2061-\u2064]/g, '').replace(/\s+/g, ' ').trim();
 }
 
 // A heading's marker, e.g. `## Some title [collapsed]`, stripped from the

package/src/reference/remark-notation.mjs

@@ -35,9 +35,12 @@ export const NOTATION_KEY_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
 
 import {
   GlyphResolutionError,
+  baseSymbolLatex,
+  derivedNotationLatex,
   resolveMathGlyphs,
   stripNotationMarkers,
 } from './math-glyphs.mjs';
+import { composeDerivedEntry } from './derived-notation.mjs';
 import {
   EQ_CAPTION_PATTERN,
   EQ_LABEL_PATTERN,
@@ -46,6 +49,7 @@ import {
   equationAnchorId,
   parseEquationRef,
   stripEquationLabels,
+  TRANSPARENT_COMPONENTS,
 } from './equations.mjs';
 import {
   collectKeyedJsxFloats,
@@ -184,6 +188,25 @@ function lessonIdFrom(file) {
   return typeof lessonId === 'string' ? lessonId : undefined;
 }
 
+/** True for any page under `content/docs/`; a lesson is one of them. */
+function isDocsPageFile(file) {
+  return [file?.path, file?.history?.[0], file?.data?.file].some(
+    (value) => typeof value === 'string' && LESSON_DOC_PATH.test(value),
+  );
+}
+
+/**
+ * The blocks a chapter numbers (`makeFloatCtx` below, and the knowledge
+ * check). Rule S10 keeps each off a page that is not a chapter.
+ */
+const NUMBERED_BLOCK_NAMES = new Set([
+  'Table',
+  'Figure',
+  'Diagram',
+  'CompactExamples',
+  'AssessmentSet',
+]);
+
 const ANY_TERM_KEY = /\[\[\s*([^\][]+?)\s*\]\]/g;
 const ANY_EXPLAIN_KEY = /\\explain\s*\{([^{}]+)\}/g;
 
@@ -214,6 +237,26 @@ function collectPageSharedKeys(tree) {
   return keys;
 }
 
+/**
+ * A derived card (rule N23) as the remark pass records it: the frontmatter of
+ * its base and index entries composed (`derived-notation.mjs`). Only an
+ * authored `label` is known here, so the title is composed when both entries
+ * author one, which is what a table header's label needs.
+ */
+function derivedResolution(key, base, index) {
+  const entry = composeDerivedEntry({
+    key,
+    notation: derivedNotationLatex(base.notation, index.notation),
+    baseLatex: baseSymbolLatex(base.notation),
+    base: { ...base, label: base.label ?? '' },
+    index: { ...index, label: index.label ?? '', summary: index.meaning },
+  });
+  const labelled =
+    typeof base.label === 'string' && typeof index.label === 'string';
+  const { label, ...rest } = entry;
+  return { ...rest, ...(labelled ? { label } : {}), scope: 'derived' };
+}
+
 function pageGlyphScope(localDefinitions, sharedDefinitions, pageSharedKeys) {
   return [
     ...localDefinitions.values(),
@@ -226,6 +269,8 @@ function pageGlyphScope(localDefinitions, sharedDefinitions, pageSharedKeys) {
   ].map((definition) => ({
     key: definition.key,
     notation: definition.notation,
+    // Rule N23: an entry whose index is a fixed label is no family.
+    ...(definition.fixedIndex === true ? { fixedIndex: true } : {}),
   }));
 }
 
@@ -385,8 +430,9 @@ function inlineEquationNode(mathNode) {
  * in a lesson is numbered; a keyed one anchors at `#eq-<key>`, an unkeyed one
  * at its positional `#eq-<section>-<index>`. The visible number is a focusable
  * `<a>` sibling — never authored, never inside KaTeX — so it survives print and
- * screen readers name it "Equation 2.4". A "Copy LaTeX" button sits beside it
- * (`.keyed-equation__controls`, styled in `global.css`; titled "Copy LaTeX —
+ * screen readers name it "Equation 2.4". A "Copy LaTeX" button sits on the
+ * equation's bottom border, under the number (`.keyed-equation__copy`, styled
+ * in `global.css` and placed by `float-toolbar.ts`; titled "Copy LaTeX —
  * ‹short›" when the equation has a `\caption{}`) — the equation's own
  * copy affordance, distinct from the notation popup card's (`NotationLayer.astro`),
  * which only exists for a symbol with a registry entry, not a bare display
@@ -431,19 +477,21 @@ function equationNode(mathNode, { key, number, short }) {
             },
           },
         },
-        el(
-          'button',
-          {
-            type: 'button',
-            className: ['keyed-equation__copy'],
-            'data-eq-copy': '',
-            'data-latex': latex,
-            'aria-label': `Copy LaTeX for Equation ${number}`,
-            title: short ? `Copy LaTeX — ${short}` : 'Copy LaTeX',
-          },
-          [copyIconNode()],
-        ),
       ]),
+      // On the block's border, not beside the number: the number's toolbar
+      // (`float-toolbar.ts`) takes the room around the number.
+      el(
+        'button',
+        {
+          type: 'button',
+          className: ['keyed-equation__copy'],
+          'data-eq-copy': '',
+          'data-latex': latex,
+          'aria-label': `Copy LaTeX for Equation ${number}`,
+          title: short ? `Copy LaTeX — ${short}` : 'Copy LaTeX',
+        },
+        [copyIconNode()],
+      ),
     ],
   };
 }
@@ -467,6 +515,137 @@ function injectFloatNumberAttributes(node, float, prefix) {
   });
 }
 
+/**
+ * The URL path Starlight serves a docs page at: `motion/index.mdx` is
+ * `/motion/`, `motion/speed.mdx` is `/motion/speed/`, `index.mdx` is `/`.
+ */
+function pageUrlFrom(file) {
+  for (const value of [file?.path, file?.history?.[0], file?.data?.file]) {
+    if (typeof value !== 'string') continue;
+    const match = value.match(LESSON_DOC_PATH);
+    if (!match) continue;
+    const route = match[1].replace(/\\/g, '/').replace(/(?:^|\/)index$/, '');
+    return route ? `/${route}/` : '/';
+  }
+  return undefined;
+}
+
+/**
+ * The chapter slug a link's `href` names — `motion/speed` for
+ * `/motion/speed/#sec-x`, for `../speed/` from a sibling page, and for
+ * `/base/motion/speed/` under the course's `base` — or `undefined` for a
+ * same-page anchor, another site, or a scheme such as `mailto:`.
+ */
+function linkedSlug(href, pageUrl, base) {
+  if (typeof href !== 'string' || href === '' || href.startsWith('#')) return undefined;
+  if (href.startsWith('//') || /^[a-z][a-z0-9+.-]*:/i.test(href)) return undefined;
+  let url;
+  try {
+    url = new URL(href, `https://course.invalid${pageUrl ?? '/'}`);
+  } catch {
+    return undefined;
+  }
+  let path;
+  try {
+    path = decodeURIComponent(url.pathname);
+  } catch {
+    return undefined;
+  }
+  const prefix = base && base !== '/' ? base.replace(/\/+$/, '') : '';
+  if (prefix && (path === prefix || path.startsWith(`${prefix}/`))) {
+    path = path.slice(prefix.length);
+  }
+  return path.replace(/^\/+|\/+$/g, '');
+}
+
+/**
+ * A link the author wrote to another chapter shows that chapter's full title
+ * as its native tooltip (`title`): prose names a chapter any way it likes —
+ * "the previous chapter", "Chapter 1.2", "this derivation" — and a reader can
+ * see where the link goes before following it. A Markdown link and a JSX
+ * `<a href>` both get it; a link with a title of its own, or one to the page
+ * it is on, keeps what it has.
+ */
+function titleChapterLinks(tree, file, titleBySlug, base) {
+  if (titleBySlug.size === 0) return;
+  const pageUrl = pageUrlFrom(file);
+  const here = pageUrl?.replace(/^\/+|\/+$/g, '');
+  const titleOf = (href) => {
+    const slug = linkedSlug(href, pageUrl, base);
+    return slug !== undefined && slug !== here ? titleBySlug.get(slug) : undefined;
+  };
+  const walk = (node) => {
+    if (!node || typeof node !== 'object') return;
+    if (node.type === 'link' && !node.title) {
+      const title = titleOf(node.url);
+      if (title) node.title = title;
+    } else if (
+      (node.type === 'mdxJsxTextElement' || node.type === 'mdxJsxFlowElement') &&
+      node.name === 'a'
+    ) {
+      const attributes = node.attributes ?? [];
+      const named = (name) =>
+        attributes.find((attribute) => attribute?.type === 'mdxJsxAttribute' && attribute.name === name);
+      const title = named('title') ? undefined : titleOf(named('href')?.value);
+      if (title) {
+        node.attributes = [...attributes, { type: 'mdxJsxAttribute', name: 'title', value: title }];
+      }
+    }
+    if (Array.isArray(node.children)) node.children.forEach(walk);
+  };
+  walk(tree);
+}
+
+/**
+ * The innermost component around `target` that numbering does not see
+ * through — the reason a float in it has no number — or `undefined`.
+ */
+function blockingComponent(tree, target) {
+  const search = (node, blocking) => {
+    if (node === target) return blocking;
+    if (!node || typeof node !== 'object' || !Array.isArray(node.children)) return undefined;
+    const here =
+      node.type === 'mdxJsxFlowElement' &&
+      node.name &&
+      !TRANSPARENT_COMPONENTS.includes(node.name)
+        ? node.name
+        : node.type === 'containerDirective'
+          ? `:::${node.name ?? ''}`
+          : blocking;
+    for (const child of node.children) {
+      const found = search(child, here);
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  };
+  return search(tree, undefined);
+}
+
+/**
+ * Why a `<Table>`/`<Figure>` on a lesson page got no number: it sits in a
+ * component other than the `TRANSPARENT_COMPONENTS`, or in a `:::note`
+ * aside, where a float is illustrative, as an equation there is
+ * (`keyed-jsx-floats.mjs`).
+ */
+function unnumberedFloatMessage(tagName, component) {
+  const where = !component
+    ? 'another component'
+    : component.startsWith(':::')
+      ? `a ${component} aside`
+      : `<${component}>`;
+  const noun = tagName === 'Table' ? 'table' : 'figure';
+  const instead =
+    tagName === 'Table'
+      ? 'write it as a plain Markdown table (rule S3 does not flag one there)'
+      : 'show its content without <Figure>';
+  return (
+    `<${tagName}> inside ${where} gets no number: a lesson numbers a ${noun} ` +
+    `at its top level or in a <Memo>, <ShortNote> or <Fold>. A ${noun} in a ` +
+    `worked example or another component is illustrative, like an equation ` +
+    `there: ${instead}, or move the <${tagName}> out of ${where}.`
+  );
+}
+
 /** Resolve a `[[eq-key]]` / `[[slug#eq-key]]` reference to `{ number, href }`. */
 function resolveEquationRef(eqRef, eqCtx, file, node) {
   if (eqRef.lesson) {
@@ -1161,6 +1340,16 @@ function assertManifestNumberParity({
 
   for (const [key, number] of pageLabels) {
     const expected = published[key];
+    if (expected === undefined && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(key)) {
+      // The manifest left it out on purpose: `validate:content` reports the
+      // id (`<prefix>-invalid-key`), and recompiling changes nothing.
+      fail(
+        file,
+        `${slug}: the id in ${syntax(key)} is not a valid key — lowercase ` +
+          `letters, digits and hyphens only — so the manifest leaves it unnumbered. ` +
+          `Fix the id.`,
+      );
+    }
     if (expected === undefined) {
       fail(
         file,
@@ -1287,6 +1476,9 @@ export default function remarkNotation(options = {}) {
   // The manifest supplies every numbering input at once; an explicit option
   // still overrides it, so existing per-field wiring keeps working.
   const numbering = { ...numberingFromManifest(options.manifest), ...options };
+  const chapterTitleBySlug = new Map(
+    (options.manifest?.lessons ?? []).map((lesson) => [lesson.slug, lesson.title]),
+  );
   // Every lesson's headings by anchor, built once: `[[lesson#sec-…]]` reads
   // another page's, `[[sec-…]]` the page's own.
   const sectionSettings = { show: true, depth: 4, ...numbering.sectionNumbering };
@@ -1310,6 +1502,9 @@ export default function remarkNotation(options = {}) {
     const suspendedOperators = suspendedOperatorsFromFile(file);
     const lessonId = lessonIdFrom(file);
     const lessonSlug = lessonId ? lessonId.replace(/\./g, '/') : undefined;
+    // The landing page, a part's overview page (rule S10): its math binds
+    // like a chapter's, but it numbers nothing.
+    const nonChapterPage = !lessonId && isDocsPageFile(file);
     // `{ prefix, offset }` per kind of float — see the `numbering` option.
     // Missing ⇒ the legacy `##`-section numbering.
     const equationNumbering = pageNumbering(numbering, lessonSlug, 'equations');
@@ -1329,6 +1524,13 @@ export default function remarkNotation(options = {}) {
     const equationLabels = collectEquationLabels(tree, equationNumbering);
     const pageLabels = new Map();
     for (const label of equationLabels) {
+      if (nonChapterPage) {
+        fail(
+          file,
+          `\\label{eq:${label.key}} on a page that is not a chapter (rule S10): only a chapter numbers an equation. Drop the label to show the equation unnumbered, or link the chapter's own with [[<chapter>#eq-<key>]].`,
+          label.node,
+        );
+      }
       if (pageLabels.has(label.key)) {
         fail(
           file,
@@ -1568,20 +1770,28 @@ export default function remarkNotation(options = {}) {
 
         inspectExplainCalls(value, resolve, file, node, references);
 
-        const bindingScope = lessonId
-          ? mathScope
-          : registryFile
-            ? registryMathDefinitions
-            : undefined;
+        const bindingScope =
+          lessonId || nonChapterPage
+            ? mathScope
+            : registryFile
+              ? registryMathDefinitions
+              : undefined;
 
         if (bindingScope) {
-          const context = lessonId ? 'lesson math' : 'notation definition math';
+          const context = lessonId
+            ? 'lesson math'
+            : nonChapterPage
+              ? 'page math'
+              : 'notation definition math';
 
           let result;
           try {
             // Suspension (rule N22) is lesson-body scope only.
             result = resolveMathGlyphs(value, bindingScope, {
               suspended: lessonId ? suspendedOperators : [],
+              // Derived cards (rule N23) are a page's own, built by the
+              // manifest for its body math — not the registry page's.
+              derive: Boolean(lessonId || nonChapterPage),
             });
           } catch (error) {
             const message =
@@ -1596,28 +1806,46 @@ export default function remarkNotation(options = {}) {
           if (result.unresolved.length > 0) {
             const unresolved = result.unresolved
               .map(
-                ({ token, start, suspended, font }) =>
+                ({ token, start, suspended, font, lenders }) =>
                   `${tokenLocation(file, node, value, start)}: "${token}"${
                     suspended
                       ? ` (${suspended} is suspended on this page, so this form needs its own entry)`
                       : font
                         ? ' (a different symbol from the plain letter; it needs its own entry)'
-                        : ''
+                        : lenders
+                          ? ` (${lenders.join(', ')} explains only its own instances with a subscript, never a bare "${token}", rule N4: give it its own entry, or \\explain{${lenders[0]}}{${token}} if it is that entry's shorthand)`
+                          : ''
                   }`,
               )
               .join(', ');
             fail(
               file,
-              `Unresolved notation in ${context}: ${unresolved}. Introduce the symbol with [[key]], define it in notation.local, or wrap it in \\explain{key}{latex}.`,
+              nonChapterPage
+                ? `Unresolved notation in ${context}: ${unresolved}. Introduce the symbol with [[key]], or wrap it in \\explain{key}{latex}: a page that is not a chapter recalls shared notation and defines none (rule S10).`
+                : `Unresolved notation in ${context}: ${unresolved}. Introduce the symbol with [[key]], define it in notation.local, or wrap it in \\explain{key}{latex}.`,
               node,
             );
           }
 
           for (const binding of result.bindings) {
             if (binding.level === 'explicit') continue;
+            if (binding.match === 'derived') continue;
             resolve(binding.key, 'math', node);
             references.push({ key: binding.key, kind: 'math' });
           }
+          // A derived card (rule N23) uses its base and its index entry; it
+          // is recorded composed, so a table header reads its own label.
+          for (const derived of result.derived) {
+            const base = resolve(derived.base, 'math', node);
+            const index = resolve(derived.index, 'math', node);
+            references.push(
+              { key: derived.base, kind: 'math' },
+              { key: derived.index, kind: 'math' },
+            );
+            if (base && index) {
+              resolved.set(derived.key, derivedResolution(derived.key, base, index));
+            }
+          }
           replaceMathSource(node, result.latex);
         }
         return;
@@ -1668,6 +1896,27 @@ export default function remarkNotation(options = {}) {
           injectFloatNumberAttributes(child, diagramByNode.get(child), 'dia');
         } else if (child?.type === 'mdxJsxFlowElement' && exampleByNode.has(child)) {
           injectFloatNumberAttributes(child, exampleByNode.get(child), 'ex');
+        } else if (
+          nonChapterPage &&
+          child?.type === 'mdxJsxFlowElement' &&
+          NUMBERED_BLOCK_NAMES.has(child.name)
+        ) {
+          // `validate:content` reports this first (gate-non-chapter-pages.ts);
+          // this is the same message for a build that skipped it.
+          fail(
+            file,
+            `<${child.name}> on a page that is not a chapter (rule S10): only a chapter numbers it. Move it into the chapter it belongs to, and link it from here: the link shows it in its card.`,
+            child,
+          );
+        } else if (
+          lessonId &&
+          child?.type === 'mdxJsxFlowElement' &&
+          (child.name === 'Table' || child.name === 'Figure')
+        ) {
+          // Numbered everywhere a lesson numbers one, so this one is nested
+          // in a component that is not transparent. Say so here, at its
+          // line, before the component fails on its missing number.
+          fail(file, unnumberedFloatMessage(child.name, blockingComponent(tree, child)), child);
         }
       }
     };
@@ -1727,6 +1976,9 @@ export default function remarkNotation(options = {}) {
       }
     }
 
+    // Before `visit`, which writes the `[[…]]` reference links: each of
+    // those opens a card of its own.
+    titleChapterLinks(tree, file, chapterTitleBySlug, options.base);
     visit(tree);
 
     file.data.notationReferences = references;

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

@@ -2,6 +2,9 @@ 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';
+import { pageOfScope, registerPageDerivedNotation } from './page-notation';
+import { indexFindings } from './gate-indices';
+import type { DerivedUse, IndexedSymbol } from './types';
 
 // Re-exported so server code keeps one import. An island imports these from
 // `lab-math-slot` instead: this module is server-only.
@@ -10,12 +13,26 @@ export { slotPlaceholder, type RenderedLabMath };
 export interface LabMathScopeDefinition {
   readonly key: string;
   readonly notation: string;
+  /** Rule N23: the entry's index is a fixed label, so it is no family. */
+  readonly fixedIndex?: true;
+}
+
+export interface RenderLabMathOptions {
+  /**
+   * `false` renders the template as inline math — a `.katex` with no
+   * `.katex-display` — for a formula that sits in a line: a legend entry,
+   * an axis title, a control label. It never scrolls (`global.css`
+   * `.lab-math`). Default `true`, a display equation.
+   */
+  readonly display?: boolean;
 }
 
 interface BindResult {
   latex: string;
   bindings: ReadonlyArray<{ key: string }>;
   unresolved: ReadonlyArray<{ token: string; start: number; font?: string }>;
+  derived: readonly DerivedUse[];
+  indices: readonly IndexedSymbol[];
 }
 
 // `\slot{name}{fallback}` — `name` is a lab-slot id, `fallback` may contain one
@@ -36,6 +53,7 @@ const sentinelFor = (index: number): string => `909909${index}.909909`;
 export function renderLabMath(
   template: string,
   scope: readonly LabMathScopeDefinition[],
+  { display = true }: RenderLabMathOptions = {},
 ): RenderedLabMath {
   const slots: Array<{ name: string; fallback: string }> = [];
   const forBinding = template.replace(
@@ -47,9 +65,14 @@ export function renderLabMath(
     },
   );
 
+  // A table `labMathScope` built knows its page: its indexed symbols take
+  // derived cards there (rule N23), registered so the page ships them.
+  const page = pageOfScope(scope);
   let result: BindResult;
   try {
-    result = resolveMathGlyphs(forBinding, [...scope]) as BindResult;
+    result = resolveMathGlyphs(forBinding, [...scope], {
+      derive: page !== undefined,
+    }) as BindResult;
   } catch (error) {
     throw new Error(
       `Lab math failed to compile: ${
@@ -76,6 +99,17 @@ export function renderLabMath(
     );
   }
 
+  if (page?.checkIndices) {
+    const findings = indexFindings(result.indices);
+    if (findings.length > 0) {
+      throw new Error(
+        `Lab math has an index no card explains (rule N23, ${page.context}): ` +
+          `${findings.join('; ')}.\n  template: ${template.trim()}`,
+      );
+    }
+  }
+  if (page) registerPageDerivedNotation(page.locals, result.derived, page.context);
+
   let bound = result.latex;
   let copyBound = result.latex;
   slots.forEach(({ name, fallback }, index) => {
@@ -93,10 +127,11 @@ export function renderLabMath(
     copyBound = copyBound.replace(sentinel, slotPlaceholder(name));
   });
 
-  const html = katex.renderToString(
-    bound,
-    createNotationKatexOptions({ displayMode: true }),
-  );
+  // The site search indexes a formula's glyphs, not its MathML copy and the
+  // LaTeX annotation in it (`rehype-fail-katex-errors.mjs`).
+  const html = katex
+    .renderToString(bound, createNotationKatexOptions({ displayMode: display }))
+    .replaceAll('<span class="katex-mathml">', '<span class="katex-mathml" data-pagefind-ignore="">');
 
   return {
     html,

package/src/reference/sections-validate.ts

@@ -10,7 +10,7 @@
  */
 import type { MathGateDiagnostic } from './gate-math';
 import { lessonLine } from './gate-prose-notation';
-import { parseSectionRef } from './sections.mjs';
+import { parseSectionRef, scanOutlineBlocks } from './sections.mjs';
 
 export interface SectionRefLessonInput {
   /** Lesson slug, e.g. `motion/position-and-coordinates`. */
@@ -36,10 +36,19 @@ function withoutCode(text: string): string {
 function unresolved(
   ref: { readonly lesson?: string; readonly key: string },
   lessonExists: boolean,
+  pages: ReadonlySet<string>,
 ): string {
   const written = ref.lesson
     ? `[[${ref.lesson}#sec-${ref.key}]]`
     : `[[sec-${ref.key}]]`;
+  const page = ref.lesson?.replace(/\/index$/, '');
+  if (page !== undefined && !lessonExists && pages.has(page)) {
+    return (
+      `${written} names ${page}, a page that is not a chapter: a section reference ` +
+      `reaches a chapter's top-level headings only (rule S10). Link the heading ` +
+      `with a Markdown link instead, [its words](/${page}/#${ref.key}).`
+    );
+  }
   if (ref.lesson && !lessonExists) {
     return `${written} names lesson ${ref.lesson}, which does not exist.`;
   }
@@ -52,10 +61,17 @@ function unresolved(
   );
 }
 
-/** One `sec-ref-resolves` error per `[[sec-…]]` that names no heading. */
+/**
+ * One `sec-ref-resolves` error per `[[sec-…]]` that names no heading.
+ * `pageSlugs` are the pages that are not chapters (`motion/index`), which a
+ * section reference cannot reach; the message says so instead of calling the
+ * page missing.
+ */
 export function validateSectionRefs(
   lessons: readonly SectionRefLessonInput[],
+  pageSlugs: readonly string[] = [],
 ): MathGateDiagnostic[] {
+  const pages = new Set(pageSlugs.map((slug) => slug.replace(/\/index$/, '')));
   const headingsByLesson = new Map(
     lessons.map((lesson) => [lesson.slug, new Set(lesson.headingSlugs)]),
   );
@@ -73,9 +89,57 @@ export function validateSectionRefs(
         file: lesson.file,
         line: lessonLine(lesson, match.index ?? 0),
         token: match[0],
-        message: unresolved(ref, headings !== undefined),
+        message: unresolved(ref, headings !== undefined, pages),
       });
     }
   }
   return diagnostics;
 }
+
+export interface HeadingAnchorLessonInput {
+  readonly file: string;
+  readonly body: string;
+  readonly bodyLine?: number;
+  /** The lesson's outline headings in order (`manifest.lessons[].headings`). */
+  readonly headings: readonly { readonly slug: string; readonly text: string }[];
+  /** Every anchor the engine writes on the page, with what it belongs to. */
+  readonly anchors: ReadonlyMap<string, string>;
+}
+
+/**
+ * One `heading-anchor-collision` error per heading whose anchor the engine
+ * already gives something else on the page — `## References` on a page that
+ * cites (the generated References section is `#references`), or `## Tab x`
+ * beside `<Table id="x">` (`#tab-x`). Two elements with one id send every link
+ * to the first, and the LaTeX export defines the label twice.
+ */
+export function validateHeadingAnchors(
+  lessons: readonly HeadingAnchorLessonInput[],
+): MathGateDiagnostic[] {
+  const diagnostics: MathGateDiagnostic[] = [];
+  for (const lesson of lessons) {
+    const offsets = scanOutlineBlocks(lesson.body)
+      .filter((block) => block.kind === 'heading')
+      .map((block) => block.index);
+    lesson.headings.forEach((heading, index) => {
+      const owner = lesson.anchors.get(heading.slug);
+      if (owner === undefined) return;
+      const advice =
+        heading.slug === 'references'
+          ? 'Rename the heading, or drop it: the References section is generated from the page’s citations.'
+          : `Rename the heading, or give ${owner} another id.`;
+      diagnostics.push({
+        context: 'structure',
+        code: 'heading-anchor-collision',
+        severity: 'error',
+        file: lesson.file,
+        line: lessonLine(lesson, offsets[index] ?? 0),
+        token: heading.text,
+        message:
+          `The heading "${heading.text}" gets the anchor #${heading.slug}, which ${owner} ` +
+          `already has on this page, so a link to either lands on the first. ${advice}`,
+      });
+    });
+  }
+  return diagnostics;
+}