explico 0.12.0 → 0.13.1

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,9 +172,53 @@ function manifestDefinition(
     ...(definition.formula === undefined
       ? {}
       : { formula: definition.formula }),
+    ...(definition.range === undefined ? {} : { range: definition.range }),
   };
 }
 
+/**
+ * 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

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,23 @@ 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
@@ -201,7 +220,6 @@ export function buildNotationRegistry(
 
     bundles.push({
       lessonId: lesson.lessonId,
-      status: lesson.status,
       source: lesson.source,
       bindings: [...bindingByKey]
         .map(([key, definitionId]) => ({ key, definitionId }))
@@ -225,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({
@@ -295,6 +335,7 @@ function buildLessonIndex(
       );
       continue;
     }
+    diagnostics.push(...malformedReferences(lesson));
     const previous = lessons.get(lesson.lessonId);
     if (previous !== undefined) {
       diagnostics.push(
@@ -351,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,
@@ -474,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,
@@ -493,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,
@@ -554,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,
@@ -562,6 +621,7 @@ function toDefinitionRecord(
       resolvedReferences: candidate.resolvedReferences,
       ...(input.formula === undefined ? {} : { formula: input.formula }),
       ...(input.units === undefined ? {} : { units: input.units }),
+      ...indexRecordFields(input),
     };
     return record;
   }
@@ -579,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) => ({
@@ -623,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,
@@ -774,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;
 

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