explico 0.11.1 → 0.13.0

package/src/reference/mixed-content.ts

@@ -20,6 +20,7 @@
  */
 import { resolveMathGlyphs } from './math-glyphs.mjs';
 import type { ScopeEntry } from './gate-math';
+import type { DerivedUse } from './types';
 
 export type ContentSegment =
   | { readonly type: 'text'; readonly value: string }
@@ -35,11 +36,17 @@ const MATH_SPAN =
 
 /**
  * Split `text` into ordered segments, resolving each math span's glyphs
- * against `scope`. Never throws.
+ * against `scope`. Never throws. With `derive` (an assessment, which is page
+ * math), an indexed symbol takes its derived card (rule N23), and each one
+ * used is added to `derived`.
  */
 export function splitMixedContent(
   text: string,
   scope: readonly ScopeEntry[],
+  options: {
+    readonly derive?: boolean;
+    readonly derived?: Map<string, DerivedUse>;
+  } = {},
 ): ContentSegment[] {
   const segments: ContentSegment[] = [];
   let cursor = 0;
@@ -53,7 +60,9 @@ export function splitMixedContent(
     const raw = match[1] ?? match[2] ?? '';
     let latex = raw;
     try {
-      latex = resolveMathGlyphs(raw, [...scope]).latex;
+      const result = resolveMathGlyphs(raw, [...scope], { derive: options.derive === true });
+      latex = result.latex;
+      for (const use of result.derived) options.derived?.set(use.key, use);
     } catch {
       latex = raw;
     }

package/src/reference/page-notation.ts

@@ -1,11 +1,16 @@
-import type { Manifest, ManifestLessonNotation } from '../compiler/manifest';
+import type {
+  Manifest,
+  ManifestDerivedNotation,
+  ManifestLessonNotation,
+} from '../compiler/manifest';
 import {
   formulaExplainKeys,
   formulaGlyphScope,
   type GlyphScopeEntry,
 } from './gloss';
 import { resolveReferenceId } from './references';
-import type { NotationDefinitionRecord } from './types';
+import { derivedNotationEntries } from './derived-entries';
+import type { DerivedUse, NotationDefinitionRecord } from './types';
 
 export interface PageNotationDependency {
   readonly key: string;
@@ -47,6 +52,55 @@ export function registerPageNotationDependencies(
   }
 }
 
+const derivedByLocals = new WeakMap<object, Map<string, DerivedUse>>();
+
+/**
+ * Record the derived cards (rule N23) a nested server component's math uses —
+ * a lab's or a diagram's — so the page ships them with its own, and their
+ * base and index entries, which a derived card's formula opens. Keyed by
+ * `Astro.locals`, like {@link registerPageNotationDependencies}.
+ */
+export function registerPageDerivedNotation(
+  locals: object,
+  uses: Iterable<DerivedUse>,
+  context: string,
+): void {
+  let byKey = derivedByLocals.get(locals);
+  if (!byKey) {
+    byKey = new Map();
+    derivedByLocals.set(locals, byKey);
+  }
+  const entries: string[] = [];
+  for (const use of uses) {
+    byKey.set(use.key, use);
+    entries.push(use.base, use.index);
+  }
+  registerPageNotationDependencies(locals, entries, context);
+}
+
+/** The page a glyph table was built for, and whether rule N23 is on there. */
+export interface ScopePage {
+  readonly locals: object;
+  readonly context: string;
+  readonly checkIndices: boolean;
+}
+
+const pageByScope = new WeakMap<object, ScopePage>();
+
+/**
+ * Tie a lab's glyph table to the page it renders on (`labMathScope` does), so
+ * `renderLabMath` can give its indexed symbols derived cards and register
+ * them, and knows whether to hold them to rule N23. A table a course copies
+ * loses the tie: its math then composes no derived card.
+ */
+export function bindScopeToPage(scope: object, page: ScopePage): void {
+  pageByScope.set(scope, page);
+}
+
+export function pageOfScope(scope: object): ScopePage | undefined {
+  return pageByScope.get(scope);
+}
+
 export function pageNotationDependencies(
   locals: object,
 ): PageNotationDependency[] {
@@ -103,7 +157,6 @@ function manifestDefinition(
     notation: definition.notation,
     label: definition.label,
     summary: definition.summary,
-    editorialStatus: definition.status,
     seeAlso: [...definition.seeAlso],
     glosses: [...definition.glosses],
     formulaScope: formulaGlyphScope({
@@ -119,26 +172,73 @@ function manifestDefinition(
     ...(definition.formula === undefined
       ? {}
       : { formula: definition.formula }),
+    ...(definition.range === undefined ? {} : { range: definition.range }),
   };
 }
 
 /**
- * Extend one compiled lesson bundle with only the definitions requested by
- * components rendered on that page (plus those definitions' normal closure).
+ * The derived cards (rule N23) a page uses: the ones its body and assessment
+ * math use, as the manifest composed them, and the ones a lab or a diagram on
+ * it registered while rendering (`locals`), composed here the same way. They
+ * travel with the page as hidden sources; their base and index entries are
+ * in its payload already.
+ */
+export function derivedNotationForPage(
+  manifest: Manifest,
+  pageId: string,
+  locals?: object,
+): readonly ManifestDerivedNotation[] {
+  const page =
+    manifest.lessons.find((entry) => entry.id === pageId) ??
+    manifest.pages.find((entry) => entry.id === pageId);
+  const compiled = page?.notation.derived ?? [];
+  const registered = [...((locals && derivedByLocals.get(locals)?.values()) ?? [])].filter(
+    (use) => !compiled.some((entry) => entry.key === use.key),
+  );
+  if (registered.length === 0) return compiled;
+
+  const definitionsById = new Map(
+    manifest.notation.definitions.map((definition) => [definition.id, definition]),
+  );
+  const availableIds = new Set(definitionsById.keys());
+  const records = new Map<string, NotationDefinitionRecord>();
+  for (const use of registered) {
+    for (const key of [use.base, use.index]) {
+      const id = resolveReferenceId(key, { kind: 'page', lessonId: pageId }, availableIds);
+      const record = id === undefined ? undefined : definitionsById.get(id);
+      if (record) records.set(key, record);
+    }
+  }
+  const cardsByKey = new Map<string, GlyphScopeEntry>(
+    manifest.notation.definitions
+      .filter((definition) => definition.kind === 'shared')
+      .map((definition) => [definition.key, { key: definition.key, notation: definition.notation }]),
+  );
+  return [...compiled, ...derivedNotationEntries(registered, records, cardsByKey)].sort(
+    (left, right) => left.key.localeCompare(right.key),
+  );
+}
+
+/**
+ * Extend one compiled page bundle — a lesson's, or a non-chapter page's
+ * (rule S10) — with only the definitions requested by components rendered on
+ * that page (plus those definitions' normal closure).
  */
 export function notationDefinitionsForRenderedPage(
   manifest: Manifest,
-  lessonId: string,
+  pageId: string,
   dependencies: readonly PageNotationDependency[],
 ): ManifestLessonNotation[] {
-  const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
-  if (!lesson) return [];
+  const page =
+    manifest.lessons.find((entry) => entry.id === pageId) ??
+    manifest.pages.find((entry) => entry.id === pageId);
+  if (!page) return [];
 
   const definitionsById = new Map(
     manifest.notation.definitions.map((definition) => [definition.id, definition]),
   );
   const availableIds = new Set(definitionsById.keys());
-  const ids = new Set(lesson.notation.definitionIds);
+  const ids = new Set(page.notation.definitionIds);
   const contextsByKey = new Map<string, Set<string>>();
 
   for (const dependency of dependencies) {
@@ -151,14 +251,14 @@ export function notationDefinitionsForRenderedPage(
 
     const definitionId = resolveReferenceId(
       dependency.key,
-      { kind: 'page', lessonId },
+      { kind: 'page', lessonId: pageId },
       availableIds,
     );
     if (!definitionId) {
       throw new Error(
-        `Notation payload error in lesson "${lessonId}": ${dependency.context} ` +
+        `Notation payload error on page "${pageId}": ${dependency.context} ` +
           `emitted data-notation-key="${dependency.key}", but that key is not ` +
-          `defined in this lesson or the shared notation registry.`,
+          `defined on this page or in the shared notation registry.`,
       );
     }
     ids.add(definitionId);
@@ -202,7 +302,7 @@ export function notationDefinitionsForRenderedPage(
     if (previous && previous !== id) {
       const context = [...(contextsByKey.get(definition.key) ?? [])].join(', ');
       throw new Error(
-        `Notation payload error in lesson "${lessonId}": key "${definition.key}" ` +
+        `Notation payload error on page "${pageId}": key "${definition.key}" ` +
           `would have two meanings (${previous} and ${id})` +
           (context ? ` after ${context} emitted it.` : '.'),
       );
@@ -220,7 +320,7 @@ export function notationDefinitionsForRenderedPage(
   }
 
   const existingById = new Map(
-    lesson.notation.definitions.map((definition) => [definition.id, definition]),
+    page.notation.definitions.map((definition) => [definition.id, definition]),
   );
   return [...ids]
     .sort()

package/src/reference/raw-floats.mjs

@@ -12,11 +12,13 @@
  *   `keyed-jsx-floats.mjs`'s top-level-only scan entirely, so it never even
  *   reaches diagram numbering.
  *
- * A raw table nested in `<Table>`/`<Figure>` is the intended, wrapped case
- * and is not flagged; nesting inside anything else (`<CompactExample>`,
- * `<Aside>`, `<Memo>`, …) still is, because a raw table has no numbering
- * scheme of its own to opt into the way a `<Diagram>`'s top-level/`<Memo>`-
- * transparent scan does.
+ * A raw table counts only where wrapping it would number it: at the top level
+ * of the lesson body or in a `TRANSPARENT_COMPONENTS` body (`<Memo>`,
+ * `<ShortNote>`, `<Fold>`), exactly where `keyed-jsx-floats.mjs` numbers a
+ * `<Table>`. A raw table in `<Table>`/`<Figure>` is the intended, wrapped
+ * case; one in any other component (a worked example's `<CompactExample>`,
+ * an `<Aside>`) is illustrative, like an equation there, and a `<Table>`
+ * there would get no number — so neither is flagged.
  *
  * `scanRawFloats` (raw Markdown, for the manifest builder) and
  * `collectRawFloats` (mdast, for `remark-notation.mjs`) MUST agree on counts
@@ -24,7 +26,11 @@
  * `keyed-jsx-floats.mjs` holds `scanKeyedJsxFloats`/`collectKeyedJsxFloats` to.
  */
 
-import { stripFencedCode } from './equations.mjs';
+import {
+  stripFencedCode,
+  stripJsxComponents,
+  TRANSPARENT_COMPONENTS,
+} from './equations.mjs';
 import { collectKeyedJsxFloats, scanKeyedJsxFloats } from './keyed-jsx-floats.mjs';
 
 /** Blank `<Table>…</Table>` and `<Figure>…</Figure>` bodies — legitimately wrapped, not raw. */
@@ -67,9 +73,16 @@ function findDiagramTags(text) {
 export function scanRawFloats(markdown) {
   const codeStripped = stripFencedCode(String(markdown));
   const withoutWrappedFloats = blankFloatWrappers(codeStripped);
+  // Every component body but a transparent one is blanked — `<Table>` and
+  // `<Figure>` among them — so only the tables a `<Table>` would number remain.
+  const numberableText = stripJsxComponents(
+    codeStripped,
+    undefined,
+    TRANSPARENT_COMPONENTS,
+  );
 
-  const markdownTableCount = findMarkdownTableStarts(withoutWrappedFloats).length;
-  const htmlTableCount = findHtmlTableTags(withoutWrappedFloats).length;
+  const markdownTableCount = findMarkdownTableStarts(numberableText).length;
+  const htmlTableCount = findHtmlTableTags(numberableText).length;
 
   const diagramsOutsideWrappers = findDiagramTags(withoutWrappedFloats).length;
   const visibleDiagrams = scanKeyedJsxFloats(markdown, { tagName: 'Diagram' });
@@ -95,7 +108,10 @@ export function collectRawFloats(tree) {
   const htmlTableNodes = [];
   const allDiagramNodes = [];
 
-  const walk = (node) => {
+  // `numberable`: a `<Table>` here would be numbered — the top level, or a
+  // transparent component's body. Any other MDX component (a capitalized
+  // name, the ones `stripJsxComponents` blanks) ends it for its subtree.
+  const walk = (node, numberable) => {
     if (!node || typeof node !== 'object') return;
     if (
       node.type === 'mdxJsxFlowElement' &&
@@ -103,18 +119,26 @@ export function collectRawFloats(tree) {
     ) {
       return; // legitimately wrapped — don't descend
     }
-    if (node.type === 'table') markdownTableNodes.push(node);
-    if (node.type === 'html' && /<table\b/i.test(String(node.value ?? ''))) {
+    if (numberable && node.type === 'table') markdownTableNodes.push(node);
+    if (
+      numberable &&
+      node.type === 'html' &&
+      /<table\b/i.test(String(node.value ?? ''))
+    ) {
       htmlTableNodes.push(node);
     }
     if (node.type === 'mdxJsxFlowElement' && node.name === 'Diagram') {
       allDiagramNodes.push(node);
     }
+    const component =
+      (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') &&
+      /^[A-Z]/.test(String(node.name ?? '')) &&
+      !TRANSPARENT_COMPONENTS.includes(node.name);
     if (Array.isArray(node.children)) {
-      for (const child of node.children) walk(child);
+      for (const child of node.children) walk(child, numberable && !component);
     }
   };
-  walk(tree);
+  walk(tree, true);
 
   const visibleDiagrams = collectKeyedJsxFloats(tree, { tagName: 'Diagram' });
   const visibleNodes = new Set(visibleDiagrams.map((diagram) => diagram.node));

package/src/reference/references.ts

@@ -10,6 +10,20 @@ export function isNotationKey(value: string): boolean {
   return NOTATION_KEY_PATTERN.test(value);
 }
 
+/**
+ * The `[[…]]` prefixes that name something other than a notation entry: an
+ * equation, a table, a figure, a diagram, a worked-example set, a knowledge
+ * check, a section, a memo. `remark-notation.mjs` and `remark-memo.mjs` route
+ * a reference by its prefix before notation keys are looked at, so a key
+ * that starts with one could never be reached.
+ */
+export const RESERVED_KEY_PREFIXES = ['eq-', 'tab-', 'fig-', 'dia-', 'ex-', 'check-', 'sec-', 'memo-'] as const;
+
+/** The reserved prefix `key` starts with, if any. */
+export function reservedKeyPrefix(key: string): string | undefined {
+  return RESERVED_KEY_PREFIXES.find((prefix) => key.startsWith(prefix));
+}
+
 export function sharedDefinitionId(key: string): string {
   return `shared:${key}`;
 }

package/src/reference/registry.ts

@@ -3,9 +3,12 @@ import {
   compareSourceSpans,
   isNotationKey,
   localDefinitionId,
+  RESERVED_KEY_PREFIXES,
+  reservedKeyPrefix,
   resolveReferenceId,
   sharedDefinitionId,
 } from './references';
+import { lineOf, proseOnly } from './gate-prose-notation';
 import type {
   LocalNotationDefinitionInput,
   LocalNotationDefinitionRecord,
@@ -165,7 +168,35 @@ export function buildNotationRegistry(
       ),
     );
   }
-  detectCycles(definitions, edgeIndex, diagnostics);
+  // A formula's references bring their cards onto the page (above) but are
+  // no dependency: formulas may name each other, as `confidence-level`
+  // (γ = 1 − α) and `significance-level` (α = 1 − γ) do. A cycle through
+  // meanings and bodies is still an error.
+  const dependencyEdges = new Map<string, readonly string[]>();
+  for (const candidate of definitions.values()) {
+    dependencyEdges.set(
+      candidate.id,
+      uniqueSorted(
+        candidate.resolvedReferences
+          .filter((reference) => reference.kind !== 'formula')
+          .map((reference) => reference.definitionId)
+          .filter((definitionId) => definitionId !== candidate.id),
+      ),
+    );
+  }
+  detectCycles(definitions, dependencyEdges, diagnostics);
+
+  // A page's own `notation.local` entries are in its scope by construction:
+  // its math binds to one by shape — an operator entry `{}'` for `w'`, the
+  // fix rule N22 itself suggests — even where no `[[key]]` or `\explain`
+  // names it. Each seeds its page's bundle, so the page renders its card.
+  const localIdsByLesson = new Map<string, string[]>();
+  for (const candidate of definitions.values()) {
+    if (candidate.kind !== 'local') continue;
+    const ids = localIdsByLesson.get(candidate.lesson.lessonId) ?? [];
+    ids.push(candidate.id);
+    localIdsByLesson.set(candidate.lesson.lessonId, ids);
+  }
 
   const bundles: NotationPageBundle[] = [];
   const backlinks: NotationBacklink[] = [];
@@ -176,7 +207,10 @@ export function buildNotationRegistry(
     const directIds = new Set(
       references.map((reference) => reference.definitionId),
     );
-    const definitionIds = transitiveClosure(directIds, edgeIndex);
+    const definitionIds = transitiveClosure(
+      new Set([...directIds, ...(localIdsByLesson.get(lesson.lessonId) ?? [])]),
+      edgeIndex,
+    );
     for (const id of definitionIds) reachableDefinitions.add(id);
 
     const bindingByKey = new Map<string, string>();
@@ -186,7 +220,6 @@ export function buildNotationRegistry(
 
     bundles.push({
       lessonId: lesson.lessonId,
-      status: lesson.status,
       source: lesson.source,
       bindings: [...bindingByKey]
         .map(([key, definitionId]) => ({ key, definitionId }))
@@ -210,6 +243,28 @@ export function buildNotationRegistry(
     }
   }
 
+  // A page-local entry under a shared entry's key wins on its page, so the
+  // one key means two things in the course: the glossary's, and the page's.
+  for (const candidate of definitions.values()) {
+    if (candidate.kind !== 'local') continue;
+    const shared = definitions.get(sharedDefinitionId(candidate.input.key));
+    if (shared === undefined) continue;
+    diagnostics.push({
+      code: 'local-shadows-shared',
+      severity: 'warning',
+      message:
+        `${candidate.lesson.lessonId} defines notation.local ${JSON.stringify(candidate.input.key)}, ` +
+        `which is also a shared entry (${shared.input.source.file}): on this page ` +
+        `[[${candidate.input.key}]] means "${candidate.input.label}", everywhere else ` +
+        `"${shared.input.label}". Give the local entry a key of its own, or use the shared one.`,
+      key: candidate.input.key,
+      lessonId: candidate.lesson.lessonId,
+      definitionId: candidate.id,
+      source: candidate.input.source,
+      relatedSources: [shared.input.source],
+    });
+  }
+
   for (const candidate of definitions.values()) {
     if (!reachableDefinitions.has(candidate.id)) {
       diagnostics.push({
@@ -280,6 +335,7 @@ function buildLessonIndex(
       );
       continue;
     }
+    diagnostics.push(...malformedReferences(lesson));
     const previous = lessons.get(lesson.lessonId);
     if (previous !== undefined) {
       diagnostics.push(
@@ -336,7 +392,26 @@ function buildDefinitionIndex(
       diagnostics.push(
         diagnostic({
           code: 'invalid-key',
-          message: `${candidate.id} has invalid notation key ${JSON.stringify(candidate.input.key)}`,
+          message: `${candidate.id} has invalid notation key ${JSON.stringify(candidate.input.key)}${keyHint(candidate.input.key)}`,
+          key: candidate.input.key,
+          lessonId:
+            candidate.kind === 'local' ? candidate.lesson.lessonId : undefined,
+          definitionId: candidate.id,
+          source: candidate.input.source,
+        }),
+      );
+      continue;
+    }
+    const reserved = reservedKeyPrefix(candidate.input.key);
+    if (reserved !== undefined) {
+      diagnostics.push(
+        diagnostic({
+          code: 'invalid-key',
+          message:
+            `${candidate.id} has notation key ${JSON.stringify(candidate.input.key)}, which starts with ` +
+            `the reserved \`${reserved}\`: [[${candidate.input.key}]] is read as a reference to that kind ` +
+            `of float and never reaches this entry. Rename the key; none may start with ` +
+            `${RESERVED_KEY_PREFIXES.map((prefix) => `\`${prefix}\``).join(', ')}.`,
           key: candidate.input.key,
           lessonId:
             candidate.kind === 'local' ? candidate.lesson.lessonId : undefined,
@@ -459,7 +534,7 @@ function validateReferenceKey(
   diagnostics.push(
     diagnostic({
       code: 'invalid-key',
-      message: `${owner.id} references invalid notation key ${JSON.stringify(reference.key)}`,
+      message: `${owner.id} references invalid notation key ${JSON.stringify(reference.key)}${keyHint(reference.key)}`,
       key: reference.key,
       lessonId: owner.kind === 'local' ? owner.lesson.lessonId : undefined,
       definitionId: owner.id,
@@ -478,7 +553,7 @@ function validatePageReferenceKey(
   diagnostics.push(
     diagnostic({
       code: 'invalid-key',
-      message: `${lesson.lessonId} references invalid notation key ${JSON.stringify(reference.key)}`,
+      message: `${lesson.lessonId} references invalid notation key ${JSON.stringify(reference.key)}${keyHint(reference.key)}`,
       key: reference.key,
       lessonId: lesson.lessonId,
       source: reference.source,
@@ -539,7 +614,6 @@ function toDefinitionRecord(
       sources: input.sources,
       seeAlso: input.seeAlso,
       alignment: input.alignment,
-      status: input.status,
       aiAssisted: input.aiAssisted,
       body: input.body,
       glosses: input.glosses,
@@ -547,6 +621,7 @@ function toDefinitionRecord(
       resolvedReferences: candidate.resolvedReferences,
       ...(input.formula === undefined ? {} : { formula: input.formula }),
       ...(input.units === undefined ? {} : { units: input.units }),
+      ...indexRecordFields(input),
     };
     return record;
   }
@@ -564,16 +639,33 @@ function toDefinitionRecord(
     sources: input.sources,
     seeAlso: input.seeAlso,
     alignment: input.alignment,
-    status: candidate.lesson.status,
     glosses: input.glosses,
     source: input.source,
     resolvedReferences: candidate.resolvedReferences,
     ...(input.formula === undefined ? {} : { formula: input.formula }),
     ...(input.units === undefined ? {} : { units: input.units }),
+    ...indexRecordFields(input),
   };
   return record;
 }
 
+/** Rule N23's optional fields, carried from the input to the record as is. */
+function indexRecordFields(input: {
+  readonly reads?: string;
+  readonly range?: string;
+  readonly fixedIndex?: true;
+  readonly formulaTemplate?: string;
+}): { reads?: string; range?: string; fixedIndex?: true; formulaTemplate?: string } {
+  return {
+    ...(input.reads === undefined ? {} : { reads: input.reads }),
+    ...(input.range === undefined ? {} : { range: input.range }),
+    ...(input.fixedIndex === undefined ? {} : { fixedIndex: input.fixedIndex }),
+    ...(input.formulaTemplate === undefined
+      ? {}
+      : { formulaTemplate: input.formulaTemplate }),
+  };
+}
+
 function definitionFingerprint(candidate: DefinitionCandidate): string {
   const references = sortedReferences(candidate.input.references).map(
     (reference) => ({
@@ -608,7 +700,6 @@ function definitionFingerprint(candidate: DefinitionCandidate): string {
       sources: [...input.sources].sort(),
       seeAlso: [...input.seeAlso].sort(),
       alignment,
-      status: input.status,
       aiAssisted: input.aiAssisted,
       body: normalizeText(input.body),
       glosses: input.glosses,
@@ -759,6 +850,76 @@ function sortedSources(values: readonly SourceSpan[]): SourceSpan[] {
   return [...values].sort(compareSourceSpans);
 }
 
+/**
+ * A `[[` that never closes. remark-notation fails the page on one ("Malformed
+ * notation reference near …"), but nothing before the render said so. Each
+ * `[[` in the prose (code, math and JSX blanked) must open a reference that
+ * closes on its line, with no `[` or `]` inside.
+ */
+function malformedReferences(lesson: NotationLessonInput): NotationDiagnostic[] {
+  if (!lesson.body?.includes('[[')) return [];
+  const prose = proseOnly(lesson.body, { keepReferences: true });
+  const found: NotationDiagnostic[] = [];
+  for (let at = prose.indexOf('[['); at !== -1; at = prose.indexOf('[[', at + 2)) {
+    if (lesson.body[at - 1] === '\\') continue;
+    const closed = /^\[\[[^[\]\n]*\]\]/.exec(prose.slice(at));
+    if (closed) {
+      at += closed[0].length - 2;
+      continue;
+    }
+    const near = lesson.body.slice(at, at + 40).split('\n')[0];
+    const line = lineOf(lesson.body, at) + (lesson.bodyLine ?? 1) - 1;
+    found.push(
+      diagnostic({
+        code: 'malformed-reference',
+        message:
+          `${lesson.lessonId} opens a reference that never closes, near ${JSON.stringify(near)}: ` +
+          'close it with ]], as [[semantic.key]], on the same line.',
+        lessonId: lesson.lessonId,
+        source: { ...lesson.source, line },
+      }),
+    );
+  }
+  return found;
+}
+
+/** What each reserved `[[…]]` prefix names. */
+const FLOAT_KINDS: Readonly<Record<string, string>> = {
+  'eq-': 'an equation',
+  'tab-': 'a table',
+  'fig-': 'a figure',
+  'dia-': 'a diagram',
+  'ex-': 'a worked-example set',
+  'check-': 'a knowledge check',
+  'sec-': 'a section',
+  'memo-': 'a memo',
+};
+
+/**
+ * What a malformed key most likely meant, after its message: a wiki-style
+ * `[[key|text]]` link text, or anything else outside the key grammar.
+ */
+function keyHint(key: string): string {
+  // `[[dia-My_Diagram]]`: a float reference whose id breaks the grammar falls
+  // through to the notation keys, which it never was.
+  const reserved = reservedKeyPrefix(key);
+  if (reserved !== undefined) {
+    return (
+      `: [[${reserved}…]] names ${FLOAT_KINDS[reserved]}, whose id is lower-case words and digits ` +
+      `joined by "-"; ${JSON.stringify(key.slice(reserved.length))} is not one.`
+    );
+  }
+  const bar = key.indexOf('|');
+  if (bar > 0) {
+    const target = key.slice(0, bar).trim();
+    return (
+      `: a [[…]] reference takes no link text of its own — it reads as the entry's label. ` +
+      `Write [[${target}]], with the words around it.`
+    );
+  }
+  return ': a key is lower-case words and digits joined by "-" or "." (motion.launch-speed).';
+}
+
 function diagnostic(
   input: Omit<NotationDiagnostic, 'severity'>,
 ): NotationDiagnostic {

package/src/reference/rehype-fail-katex-errors.mjs

@@ -31,13 +31,32 @@ function katexErrors(node, output = []) {
   return output;
 }
 
+/**
+ * KaTeX writes each formula twice: as MathML, whose `<annotation>` holds the
+ * LaTeX source, for assistive technology, and as the visible glyphs. Mark the
+ * MathML copy `data-pagefind-ignore`, so the site search indexes a formula
+ * once, as it reads, and never its LaTeX (`\explain{…}{…}`, `\dfrac`).
+ */
+export function markMathmlForSearch(node) {
+  if (!node || typeof node !== 'object') return;
+  const classes = node.properties?.className;
+  if (node.type === 'element' && Array.isArray(classes) && classes.includes('katex-mathml')) {
+    node.properties.dataPagefindIgnore = '';
+    return;
+  }
+  if (Array.isArray(node.children)) node.children.forEach(markMathmlForSearch);
+}
+
 /**
  * rehype-katex reports parse failures as non-fatal VFile messages and renders
  * a `.katex-error` fallback. Turn those recovered failures into compiler
  * errors so Astro cannot successfully build a lesson containing broken math.
+ * The pass every course runs right after KaTeX, it also keeps the LaTeX
+ * annotations out of the site search (`markMathmlForSearch`).
  */
 export default function rehypeFailKatexErrors() {
   return function failOnKatexErrors(tree, file) {
+    markMathmlForSearch(tree);
     const errors = katexErrors(tree);
     if (errors.length === 0) return;