explico 0.11.1 → 0.13.0

package/dist/reference/mixed-content.d.ts

@@ -1,5 +1,5 @@
 import { ScopeEntry } from './gate-math.js';
-import './types.js';
+import { DerivedUse } from './types.js';
 
 type ContentSegment = {
     readonly type: 'text';
@@ -10,8 +10,13 @@ type ContentSegment = {
 };
 /**
  * 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`.
  */
-declare function splitMixedContent(text: string, scope: readonly ScopeEntry[]): ContentSegment[];
+declare function splitMixedContent(text: string, scope: readonly ScopeEntry[], options?: {
+    readonly derive?: boolean;
+    readonly derived?: Map<string, DerivedUse>;
+}): ContentSegment[];
 
 export { type ContentSegment, splitMixedContent };

package/dist/reference/mixed-content.js

@@ -1,6 +1,6 @@
 import { resolveMathGlyphs } from "./math-glyphs.mjs";
 const MATH_SPAN = /\$\$([\s\S]+?)\$\$|(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/g;
-function splitMixedContent(text, scope) {
+function splitMixedContent(text, scope, options = {}) {
   const segments = [];
   let cursor = 0;
   const pattern = new RegExp(MATH_SPAN);
@@ -12,7 +12,9 @@ function splitMixedContent(text, scope) {
     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/dist/reference/page-notation.d.ts

@@ -1,11 +1,12 @@
-import { Manifest, ManifestLessonNotation } from '../compiler/manifest.js';
+import { Manifest, ManifestDerivedNotation, ManifestLessonNotation } from '../compiler/manifest.js';
+import { DerivedUse } from './types.js';
 import '../curriculum/validation.js';
 import './consistency.js';
-import '../course-config-Dsnri9Tk.js';
+import '../course-config-rRtME5UV.js';
 import '../rules/catalog.js';
 import '../rules/course-rules.js';
 import '../compiler/collections.js';
-import './types.js';
+import './gate-retired-keys.js';
 import './lint-ignore.js';
 import './equations-validate.js';
 import './tables-validate.js';
@@ -16,6 +17,7 @@ import './examples-validate.js';
 import './folds-validate.js';
 import './knowledge-checks-validate.js';
 import './raw-floats-validate.js';
+import './lab-katex-validate.js';
 import './gate-math.js';
 import './mixed-content.js';
 import './gloss.js';
@@ -34,6 +36,27 @@ interface PageNotationDependency {
  * between lessons and defeat page-local notation scope.
  */
 declare function registerPageNotationDependencies(locals: object, keys: Iterable<string>, context: string): void;
+/**
+ * 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}.
+ */
+declare function registerPageDerivedNotation(locals: object, uses: Iterable<DerivedUse>, context: string): void;
+/** The page a glyph table was built for, and whether rule N23 is on there. */
+interface ScopePage {
+    readonly locals: object;
+    readonly context: string;
+    readonly checkIndices: boolean;
+}
+/**
+ * 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.
+ */
+declare function bindScopeToPage(scope: object, page: ScopePage): void;
+declare function pageOfScope(scope: object): ScopePage | undefined;
 declare function pageNotationDependencies(locals: object): PageNotationDependency[];
 /** Starlight's route id as exposed to nested Astro components. */
 declare function routeIdFromLocals(locals: object): string | undefined;
@@ -44,14 +67,23 @@ declare function notationKeysInMathNodes(nodes: readonly {
     readonly children?: readonly unknown[];
 }[]): string[];
 /**
- * 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.
+ */
+declare function derivedNotationForPage(manifest: Manifest, pageId: string, locals?: object): readonly ManifestDerivedNotation[];
+/**
+ * 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).
  */
-declare function notationDefinitionsForRenderedPage(manifest: Manifest, lessonId: string, dependencies: readonly PageNotationDependency[]): ManifestLessonNotation[];
+declare function notationDefinitionsForRenderedPage(manifest: Manifest, pageId: string, dependencies: readonly PageNotationDependency[]): ManifestLessonNotation[];
 /**
  * Structural backstop over final HTML: every trigger must have a source entry
  * from which the popup enhancer can populate a card.
  */
 declare function missingNotationPayloadKeys(html: string): string[];
 
-export { type PageNotationDependency, missingNotationPayloadKeys, notationDefinitionsForRenderedPage, notationKeysInMathNodes, pageNotationDependencies, registerPageNotationDependencies, routeIdFromLocals };
+export { type PageNotationDependency, type ScopePage, bindScopeToPage, derivedNotationForPage, missingNotationPayloadKeys, notationDefinitionsForRenderedPage, notationKeysInMathNodes, pageNotationDependencies, pageOfScope, registerPageDerivedNotation, registerPageNotationDependencies, routeIdFromLocals };

package/dist/reference/page-notation.js

@@ -3,6 +3,7 @@ import {
   formulaGlyphScope
 } from "./gloss.js";
 import { resolveReferenceId } from "./references.js";
+import { derivedNotationEntries } from "./derived-entries.js";
 const dependenciesByLocals = /* @__PURE__ */ new WeakMap();
 function registerPageNotationDependencies(locals, keys, context) {
   let byKey = dependenciesByLocals.get(locals);
@@ -19,6 +20,27 @@ function registerPageNotationDependencies(locals, keys, context) {
     contexts.add(context);
   }
 }
+const derivedByLocals = /* @__PURE__ */ new WeakMap();
+function registerPageDerivedNotation(locals, uses, context) {
+  let byKey = derivedByLocals.get(locals);
+  if (!byKey) {
+    byKey = /* @__PURE__ */ new Map();
+    derivedByLocals.set(locals, byKey);
+  }
+  const entries = [];
+  for (const use of uses) {
+    byKey.set(use.key, use);
+    entries.push(use.base, use.index);
+  }
+  registerPageNotationDependencies(locals, entries, context);
+}
+const pageByScope = /* @__PURE__ */ new WeakMap();
+function bindScopeToPage(scope, page) {
+  pageByScope.set(scope, page);
+}
+function pageOfScope(scope) {
+  return pageByScope.get(scope);
+}
 function pageNotationDependencies(locals) {
   const byKey = dependenciesByLocals.get(locals);
   if (!byKey) return [];
@@ -52,7 +74,6 @@ function manifestDefinition(definition, cardsByKey) {
     notation: definition.notation,
     label: definition.label,
     summary: definition.summary,
-    editorialStatus: definition.status,
     seeAlso: [...definition.seeAlso],
     glosses: [...definition.glosses],
     formulaScope: formulaGlyphScope({
@@ -63,17 +84,44 @@ function manifestDefinition(definition, cardsByKey) {
       ...definition.formula === void 0 ? {} : { formula: definition.formula }
     }),
     ...definition.units === void 0 ? {} : { units: definition.units },
-    ...definition.formula === void 0 ? {} : { formula: definition.formula }
+    ...definition.formula === void 0 ? {} : { formula: definition.formula },
+    ...definition.range === void 0 ? {} : { range: definition.range }
   };
 }
-function notationDefinitionsForRenderedPage(manifest, lessonId, dependencies) {
-  const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
-  if (!lesson) return [];
+function derivedNotationForPage(manifest, pageId, locals) {
+  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 = /* @__PURE__ */ new Map();
+  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 === void 0 ? void 0 : definitionsById.get(id);
+      if (record) records.set(key, record);
+    }
+  }
+  const cardsByKey = new Map(
+    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)
+  );
+}
+function notationDefinitionsForRenderedPage(manifest, pageId, dependencies) {
+  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 = /* @__PURE__ */ new Map();
   for (const dependency of dependencies) {
     let contexts = contextsByKey.get(dependency.key);
@@ -84,12 +132,12 @@ function notationDefinitionsForRenderedPage(manifest, lessonId, dependencies) {
     contexts.add(dependency.context);
     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} emitted data-notation-key="${dependency.key}", but that key is not defined in this lesson or the shared notation registry.`
+        `Notation payload error on page "${pageId}": ${dependency.context} emitted data-notation-key="${dependency.key}", but that key is not defined on this page or in the shared notation registry.`
       );
     }
     ids.add(definitionId);
@@ -124,7 +172,7 @@ function notationDefinitionsForRenderedPage(manifest, lessonId, dependencies) {
     if (previous && previous !== id) {
       const context = [...contextsByKey.get(definition.key) ?? []].join(", ");
       throw new Error(
-        `Notation payload error in lesson "${lessonId}": key "${definition.key}" would have two meanings (${previous} and ${id})` + (context ? ` after ${context} emitted it.` : ".")
+        `Notation payload error on page "${pageId}": key "${definition.key}" would have two meanings (${previous} and ${id})` + (context ? ` after ${context} emitted it.` : ".")
       );
     }
     definitionIdByKey.set(definition.key, id);
@@ -138,7 +186,7 @@ function notationDefinitionsForRenderedPage(manifest, lessonId, dependencies) {
     });
   }
   const existingById = new Map(
-    lesson.notation.definitions.map((definition) => [definition.id, definition])
+    page.notation.definitions.map((definition) => [definition.id, definition])
   );
   return [...ids].sort().flatMap((id) => {
     const existing = existingById.get(id);
@@ -162,10 +210,14 @@ function missingNotationPayloadKeys(html) {
   return [...triggers].filter((key) => !entries.has(key)).sort();
 }
 export {
+  bindScopeToPage,
+  derivedNotationForPage,
   missingNotationPayloadKeys,
   notationDefinitionsForRenderedPage,
   notationKeysInMathNodes,
   pageNotationDependencies,
+  pageOfScope,
+  registerPageDerivedNotation,
   registerPageNotationDependencies,
   routeIdFromLocals
 };

package/dist/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/dist/reference/references.d.ts

@@ -2,6 +2,16 @@ import { NotationDiagnostic, SourceSpan, NotationDefinitionScope } from './types
 
 declare const NOTATION_KEY_PATTERN: RegExp;
 declare function isNotationKey(value: string): boolean;
+/**
+ * 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.
+ */
+declare const RESERVED_KEY_PREFIXES: readonly ["eq-", "tab-", "fig-", "dia-", "ex-", "check-", "sec-", "memo-"];
+/** The reserved prefix `key` starts with, if any. */
+declare function reservedKeyPrefix(key: string): string | undefined;
 declare function sharedDefinitionId(key: string): string;
 declare function localDefinitionId(lessonId: string, key: string): string;
 declare function definitionId(scope: NotationDefinitionScope, key: string): string;
@@ -14,4 +24,4 @@ declare function resolveReferenceId(key: string, scope: NotationDefinitionScope,
 declare function compareSourceSpans(left: SourceSpan | undefined, right: SourceSpan | undefined): number;
 declare function compareDiagnostics(left: NotationDiagnostic, right: NotationDiagnostic): number;
 
-export { NOTATION_KEY_PATTERN, compareDiagnostics, compareSourceSpans, definitionId, isNotationKey, localDefinitionId, resolveReferenceId, sharedDefinitionId };
+export { NOTATION_KEY_PATTERN, RESERVED_KEY_PREFIXES, compareDiagnostics, compareSourceSpans, definitionId, isNotationKey, localDefinitionId, reservedKeyPrefix, resolveReferenceId, sharedDefinitionId };

package/dist/reference/references.js

@@ -2,6 +2,10 @@ const NOTATION_KEY_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
 function isNotationKey(value) {
   return NOTATION_KEY_PATTERN.test(value);
 }
+const RESERVED_KEY_PREFIXES = ["eq-", "tab-", "fig-", "dia-", "ex-", "check-", "sec-", "memo-"];
+function reservedKeyPrefix(key) {
+  return RESERVED_KEY_PREFIXES.find((prefix) => key.startsWith(prefix));
+}
 function sharedDefinitionId(key) {
   return `shared:${key}`;
 }
@@ -33,11 +37,13 @@ function severityRank(severity) {
 }
 export {
   NOTATION_KEY_PATTERN,
+  RESERVED_KEY_PREFIXES,
   compareDiagnostics,
   compareSourceSpans,
   definitionId,
   isNotationKey,
   localDefinitionId,
+  reservedKeyPrefix,
   resolveReferenceId,
   sharedDefinitionId
 };

package/dist/reference/registry.js

@@ -3,9 +3,12 @@ import {
   compareSourceSpans,
   isNotationKey,
   localDefinitionId,
+  RESERVED_KEY_PREFIXES,
+  reservedKeyPrefix,
   resolveReferenceId,
   sharedDefinitionId
 } from "./references.js";
+import { lineOf, proseOnly } from "./gate-prose-notation.js";
 function buildNotationRegistry(rawInput) {
   const diagnostics = [];
   const lessons = buildLessonIndex(rawInput.lessons, diagnostics);
@@ -105,7 +108,23 @@ function buildNotationRegistry(rawInput) {
       )
     );
   }
-  detectCycles(definitions, edgeIndex, diagnostics);
+  const dependencyEdges = /* @__PURE__ */ new Map();
+  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);
+  const localIdsByLesson = /* @__PURE__ */ new Map();
+  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 = [];
   const backlinks = [];
   const reachableDefinitions = /* @__PURE__ */ new Set();
@@ -114,7 +133,10 @@ function buildNotationRegistry(rawInput) {
     const directIds = new Set(
       references.map((reference) => reference.definitionId)
     );
-    const definitionIds = transitiveClosure(directIds, edgeIndex);
+    const definitionIds = transitiveClosure(
+      /* @__PURE__ */ new Set([...directIds, ...localIdsByLesson.get(lesson.lessonId) ?? []]),
+      edgeIndex
+    );
     for (const id of definitionIds) reachableDefinitions.add(id);
     const bindingByKey = /* @__PURE__ */ new Map();
     for (const reference of references) {
@@ -122,7 +144,6 @@ function buildNotationRegistry(rawInput) {
     }
     bundles.push({
       lessonId: lesson.lessonId,
-      status: lesson.status,
       source: lesson.source,
       bindings: [...bindingByKey].map(([key, definitionId]) => ({ key, definitionId })).sort(
         (left, right) => left.key.localeCompare(right.key) || left.definitionId.localeCompare(right.definitionId)
@@ -140,6 +161,21 @@ function buildNotationRegistry(rawInput) {
       });
     }
   }
+  for (const candidate of definitions.values()) {
+    if (candidate.kind !== "local") continue;
+    const shared = definitions.get(sharedDefinitionId(candidate.input.key));
+    if (shared === void 0) 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({
@@ -193,6 +229,7 @@ function buildLessonIndex(rawLessons, diagnostics) {
       );
       continue;
     }
+    diagnostics.push(...malformedReferences(lesson));
     const previous = lessons.get(lesson.lessonId);
     if (previous !== void 0) {
       diagnostics.push(
@@ -241,7 +278,21 @@ function buildDefinitionIndex(rawShared, lessons, diagnostics) {
       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 : void 0,
+          definitionId: candidate.id,
+          source: candidate.input.source
+        })
+      );
+      continue;
+    }
+    const reserved = reservedKeyPrefix(candidate.input.key);
+    if (reserved !== void 0) {
+      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 : void 0,
           definitionId: candidate.id,
@@ -324,7 +375,7 @@ function validateReferenceKey(reference, owner, diagnostics) {
   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 : void 0,
       definitionId: owner.id,
@@ -338,7 +389,7 @@ function validatePageReferenceKey(reference, lesson, diagnostics) {
   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
@@ -389,14 +440,14 @@ function toDefinitionRecord(candidate) {
       sources: input2.sources,
       seeAlso: input2.seeAlso,
       alignment: input2.alignment,
-      status: input2.status,
       aiAssisted: input2.aiAssisted,
       body: input2.body,
       glosses: input2.glosses,
       source: input2.source,
       resolvedReferences: candidate.resolvedReferences,
       ...input2.formula === void 0 ? {} : { formula: input2.formula },
-      ...input2.units === void 0 ? {} : { units: input2.units }
+      ...input2.units === void 0 ? {} : { units: input2.units },
+      ...indexRecordFields(input2)
     };
     return record2;
   }
@@ -413,15 +464,23 @@ function toDefinitionRecord(candidate) {
     sources: input.sources,
     seeAlso: input.seeAlso,
     alignment: input.alignment,
-    status: candidate.lesson.status,
     glosses: input.glosses,
     source: input.source,
     resolvedReferences: candidate.resolvedReferences,
     ...input.formula === void 0 ? {} : { formula: input.formula },
-    ...input.units === void 0 ? {} : { units: input.units }
+    ...input.units === void 0 ? {} : { units: input.units },
+    ...indexRecordFields(input)
   };
   return record;
 }
+function indexRecordFields(input) {
+  return {
+    ...input.reads === void 0 ? {} : { reads: input.reads },
+    ...input.range === void 0 ? {} : { range: input.range },
+    ...input.fixedIndex === void 0 ? {} : { fixedIndex: input.fixedIndex },
+    ...input.formulaTemplate === void 0 ? {} : { formulaTemplate: input.formulaTemplate }
+  };
+}
 function definitionFingerprint(candidate) {
   const references = sortedReferences(candidate.input.references).map(
     (reference) => ({
@@ -452,7 +511,6 @@ function definitionFingerprint(candidate) {
       sources: [...input2.sources].sort(),
       seeAlso: [...input2.seeAlso].sort(),
       alignment,
-      status: input2.status,
       aiAssisted: input2.aiAssisted,
       body: normalizeText(input2.body),
       glosses: input2.glosses,
@@ -564,6 +622,52 @@ function uniqueSorted(values) {
 function sortedSources(values) {
   return [...values].sort(compareSourceSpans);
 }
+function malformedReferences(lesson) {
+  if (!lesson.body?.includes("[[")) return [];
+  const prose = proseOnly(lesson.body, { keepReferences: true });
+  const found = [];
+  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;
+}
+const FLOAT_KINDS = {
+  "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"
+};
+function keyHint(key) {
+  const reserved = reservedKeyPrefix(key);
+  if (reserved !== void 0) {
+    return `: [[${reserved}\u2026]] 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 [[\u2026]] reference takes no link text of its own \u2014 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) {
   return { ...input, severity: "error" };
 }

package/dist/reference/rehype-fail-katex-errors.d.mts

@@ -1,6 +1,15 @@
+/**
+ * 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: any): void;
 /**
  * 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(): (tree: any, file: any) => void;