explico 0.1.0

package/dist/reference/prose.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Under-specification safeguard for notation `meaning` prose (Phase C1b).
+ *
+ * A page-local symbol must not get a glossary-style panel for a throwaway
+ * definition, so `meaning` has to be real prose: at least four words and not a
+ * placeholder phrase. Used by the content schema (`src/content.config.ts`) and
+ * the loader so a bad entry fails both `astro check` and `validate:content`.
+ */
+/** Placeholder phrases that do not count as a substantive `meaning`. */
+declare const PLACEHOLDER_PROSE: RegExp;
+/** Minimum words for a `meaning` to read as a definition rather than a label. */
+declare const MEANING_MIN_WORDS = 4;
+declare function isSubstantiveMeaning(value: string): boolean;
+
+export { MEANING_MIN_WORDS, PLACEHOLDER_PROSE, isSubstantiveMeaning };

package/dist/reference/prose.js

@@ -0,0 +1,12 @@
+const PLACEHOLDER_PROSE = /^(?:a\s+(?:variable|value|quantity|constant|parameter|symbol)|tbd|todo|fixme|see\s+above|as\s+above|placeholder|n\/a)\.?$/i;
+const MEANING_MIN_WORDS = 4;
+function isSubstantiveMeaning(value) {
+  const trimmed = value.trim();
+  if (PLACEHOLDER_PROSE.test(trimmed)) return false;
+  return trimmed.split(/\s+/).filter(Boolean).length >= MEANING_MIN_WORDS;
+}
+export {
+  MEANING_MIN_WORDS,
+  PLACEHOLDER_PROSE,
+  isSubstantiveMeaning
+};

package/dist/reference/references.d.ts

@@ -0,0 +1,17 @@
+import { NotationDiagnostic, SourceSpan, NotationDefinitionScope } from './types.js';
+
+declare const NOTATION_KEY_PATTERN: RegExp;
+declare function isNotationKey(value: string): boolean;
+declare function sharedDefinitionId(key: string): string;
+declare function localDefinitionId(lessonId: string, key: string): string;
+declare function definitionId(scope: NotationDefinitionScope, key: string): string;
+/**
+ * Resolve by lexical scope. Page content and page-local definition bodies see
+ * local definitions first, then shared definitions. Shared definition bodies
+ * can only see shared definitions, so their meaning cannot change by caller.
+ */
+declare function resolveReferenceId(key: string, scope: NotationDefinitionScope, availableDefinitionIds: ReadonlySet<string>): string | undefined;
+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 };

package/dist/reference/references.js

@@ -0,0 +1,42 @@
+const NOTATION_KEY_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+function isNotationKey(value) {
+  return NOTATION_KEY_PATTERN.test(value);
+}
+function sharedDefinitionId(key) {
+  return `shared:${key}`;
+}
+function localDefinitionId(lessonId, key) {
+  return `page:${lessonId}:${key}`;
+}
+function definitionId(scope, key) {
+  return scope.kind === "shared" ? sharedDefinitionId(key) : localDefinitionId(scope.lessonId, key);
+}
+function resolveReferenceId(key, scope, availableDefinitionIds) {
+  if (scope.kind === "page") {
+    const localId = localDefinitionId(scope.lessonId, key);
+    if (availableDefinitionIds.has(localId)) return localId;
+  }
+  const sharedId = sharedDefinitionId(key);
+  return availableDefinitionIds.has(sharedId) ? sharedId : void 0;
+}
+function compareSourceSpans(left, right) {
+  if (left === void 0) return right === void 0 ? 0 : 1;
+  if (right === void 0) return -1;
+  return left.file.localeCompare(right.file) || (left.line ?? 0) - (right.line ?? 0) || (left.column ?? 0) - (right.column ?? 0) || (left.endLine ?? 0) - (right.endLine ?? 0) || (left.endColumn ?? 0) - (right.endColumn ?? 0);
+}
+function compareDiagnostics(left, right) {
+  return severityRank(left.severity) - severityRank(right.severity) || left.code.localeCompare(right.code) || (left.lessonId ?? "").localeCompare(right.lessonId ?? "") || (left.key ?? "").localeCompare(right.key ?? "") || (left.definitionId ?? "").localeCompare(right.definitionId ?? "") || compareSourceSpans(left.source, right.source) || left.message.localeCompare(right.message);
+}
+function severityRank(severity) {
+  return severity === "error" ? 0 : 1;
+}
+export {
+  NOTATION_KEY_PATTERN,
+  compareDiagnostics,
+  compareSourceSpans,
+  definitionId,
+  isNotationKey,
+  localDefinitionId,
+  resolveReferenceId,
+  sharedDefinitionId
+};

package/dist/reference/registry.d.ts

@@ -0,0 +1,6 @@
+import { NotationRegistry, NotationRegistryInput } from './types.js';
+
+declare function buildNotationRegistry(rawInput: NotationRegistryInput): NotationRegistry;
+declare function assertValidNotation(registry: NotationRegistry): void;
+
+export { assertValidNotation, buildNotationRegistry };

package/dist/reference/registry.js

@@ -0,0 +1,548 @@
+import {
+  compareDiagnostics,
+  compareSourceSpans,
+  isNotationKey,
+  localDefinitionId,
+  resolveReferenceId,
+  sharedDefinitionId
+} from "./references";
+function buildNotationRegistry(rawInput) {
+  const diagnostics = [];
+  const lessons = buildLessonIndex(rawInput.lessons, diagnostics);
+  const definitions = buildDefinitionIndex(
+    rawInput.sharedDefinitions,
+    lessons,
+    diagnostics
+  );
+  const availableDefinitionIds = new Set(definitions.keys());
+  for (const candidate of definitions.values()) {
+    const references = sortedReferences(candidate.input.references);
+    const resolved = [];
+    for (const reference of references) {
+      if (!validateReferenceKey(reference, candidate, diagnostics)) continue;
+      if (candidate.kind === "local") {
+        const lessonId = candidate.lesson.lessonId;
+        const definitionId2 = resolveReferenceId(
+          reference.key,
+          candidate.scope,
+          availableDefinitionIds
+        );
+        if (definitionId2 === void 0) {
+          diagnostics.push(
+            diagnostic({
+              code: "undefined-reference",
+              message: `${candidate.id} references unknown notation ${reference.key}`,
+              key: reference.key,
+              lessonId,
+              definitionId: candidate.id,
+              source: reference.source
+            })
+          );
+          continue;
+        }
+        resolved.push({ ...reference, definitionId: definitionId2 });
+        continue;
+      }
+      const definitionId = resolveReferenceId(
+        reference.key,
+        candidate.scope,
+        availableDefinitionIds
+      );
+      if (definitionId === void 0) {
+        diagnostics.push(
+          diagnostic({
+            code: "undefined-reference",
+            message: `${candidate.id} references unknown notation ${reference.key}`,
+            key: reference.key,
+            definitionId: candidate.id,
+            source: reference.source
+          })
+        );
+        continue;
+      }
+      resolved.push({ ...reference, definitionId });
+    }
+    candidate.resolvedReferences = sortResolvedReferences(resolved);
+    validateSeeAlsoReferences(candidate, availableDefinitionIds, diagnostics);
+  }
+  const directReferences = /* @__PURE__ */ new Map();
+  for (const lesson of lessons.values()) {
+    const resolved = [];
+    const scope = {
+      kind: "page",
+      lessonId: lesson.lessonId
+    };
+    for (const reference of sortedReferences(lesson.references)) {
+      if (!validatePageReferenceKey(reference, lesson, diagnostics)) continue;
+      const definitionId = resolveReferenceId(
+        reference.key,
+        scope,
+        availableDefinitionIds
+      );
+      if (definitionId === void 0) {
+        diagnostics.push(
+          diagnostic({
+            code: "undefined-reference",
+            message: `${lesson.lessonId} references unknown notation ${reference.key}`,
+            key: reference.key,
+            lessonId: lesson.lessonId,
+            source: reference.source
+          })
+        );
+        continue;
+      }
+      resolved.push({ ...reference, definitionId });
+    }
+    directReferences.set(lesson.lessonId, sortResolvedReferences(resolved));
+  }
+  const edgeIndex = /* @__PURE__ */ new Map();
+  for (const candidate of definitions.values()) {
+    edgeIndex.set(
+      candidate.id,
+      uniqueSorted(
+        candidate.resolvedReferences.map((reference) => reference.definitionId).filter((definitionId) => definitionId !== candidate.id)
+      )
+    );
+  }
+  detectCycles(definitions, edgeIndex, diagnostics);
+  const bundles = [];
+  const backlinks = [];
+  const reachableDefinitions = /* @__PURE__ */ new Set();
+  for (const lesson of lessons.values()) {
+    const references = directReferences.get(lesson.lessonId) ?? [];
+    const directIds = new Set(
+      references.map((reference) => reference.definitionId)
+    );
+    const definitionIds = transitiveClosure(directIds, edgeIndex);
+    for (const id of definitionIds) reachableDefinitions.add(id);
+    const bindingByKey = /* @__PURE__ */ new Map();
+    for (const reference of references) {
+      bindingByKey.set(reference.key, reference.definitionId);
+    }
+    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)
+      ),
+      definitionIds
+    });
+    for (const definitionId of definitionIds) {
+      const definition = definitions.get(definitionId);
+      if (definition === void 0) continue;
+      backlinks.push({
+        definitionId,
+        key: definition.input.key,
+        lessonId: lesson.lessonId,
+        direct: directIds.has(definitionId)
+      });
+    }
+  }
+  for (const candidate of definitions.values()) {
+    if (!reachableDefinitions.has(candidate.id)) {
+      diagnostics.push({
+        code: "unused-definition",
+        severity: "warning",
+        message: `${candidate.id} is not reachable from any lesson reference`,
+        key: candidate.input.key,
+        lessonId: candidate.kind === "local" ? candidate.lesson.lessonId : void 0,
+        definitionId: candidate.id,
+        source: candidate.input.source
+      });
+    }
+  }
+  return {
+    definitions: [...definitions.values()].map(toDefinitionRecord).sort((left, right) => left.id.localeCompare(right.id)),
+    bundles: bundles.sort(
+      (left, right) => left.lessonId.localeCompare(right.lessonId)
+    ),
+    backlinks: backlinks.sort(
+      (left, right) => left.definitionId.localeCompare(right.definitionId) || left.lessonId.localeCompare(right.lessonId) || Number(right.direct) - Number(left.direct)
+    ),
+    diagnostics: diagnostics.sort(compareDiagnostics)
+  };
+}
+function assertValidNotation(registry) {
+  const errors = registry.diagnostics.filter(
+    (item) => item.severity === "error"
+  );
+  if (errors.length === 0) return;
+  throw new Error(
+    `Invalid notation registry:
+${errors.map((item) => `- [${item.code}] ${item.message}`).join("\n")}`
+  );
+}
+function buildLessonIndex(rawLessons, diagnostics) {
+  const lessons = /* @__PURE__ */ new Map();
+  const sorted = [...rawLessons].sort(
+    (left, right) => left.lessonId.localeCompare(right.lessonId) || compareSourceSpans(left.source, right.source)
+  );
+  for (const rawLesson of sorted) {
+    const lesson = normalizeLesson(rawLesson);
+    if (!isNotationKey(lesson.lessonId)) {
+      diagnostics.push(
+        diagnostic({
+          code: "invalid-key",
+          message: `lesson has invalid id ${JSON.stringify(lesson.lessonId)}`,
+          key: lesson.lessonId,
+          lessonId: lesson.lessonId,
+          source: lesson.source
+        })
+      );
+      continue;
+    }
+    const previous = lessons.get(lesson.lessonId);
+    if (previous !== void 0) {
+      diagnostics.push(
+        diagnostic({
+          code: "duplicate-page",
+          message: `duplicate notation lesson ${lesson.lessonId}`,
+          lessonId: lesson.lessonId,
+          source: lesson.source,
+          relatedSources: sortedSources([previous.source, lesson.source])
+        })
+      );
+      continue;
+    }
+    lessons.set(lesson.lessonId, lesson);
+  }
+  return lessons;
+}
+function buildDefinitionIndex(rawShared, lessons, diagnostics) {
+  const candidates = [
+    ...rawShared.map((raw) => {
+      const input = normalizeSharedDefinition(raw);
+      return {
+        kind: "shared",
+        id: sharedDefinitionId(input.key),
+        scope: { kind: "shared" },
+        input,
+        resolvedReferences: []
+      };
+    }),
+    ...[...lessons.values()].flatMap(
+      (lesson) => lesson.localDefinitions.map((input) => ({
+        kind: "local",
+        id: localDefinitionId(lesson.lessonId, input.key),
+        scope: { kind: "page", lessonId: lesson.lessonId },
+        lesson,
+        input,
+        resolvedReferences: []
+      }))
+    )
+  ].sort(
+    (left, right) => left.id.localeCompare(right.id) || compareSourceSpans(left.input.source, right.input.source)
+  );
+  const definitions = /* @__PURE__ */ new Map();
+  for (const candidate of candidates) {
+    if (!isNotationKey(candidate.input.key)) {
+      diagnostics.push(
+        diagnostic({
+          code: "invalid-key",
+          message: `${candidate.id} has invalid notation key ${JSON.stringify(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 previous = definitions.get(candidate.id);
+    if (previous === void 0) {
+      definitions.set(candidate.id, candidate);
+      continue;
+    }
+    const duplicate = definitionFingerprint(previous) === definitionFingerprint(candidate);
+    diagnostics.push(
+      diagnostic({
+        code: duplicate ? "duplicate-definition" : "conflicting-definition",
+        message: duplicate ? `${candidate.id} is declared more than once` : `${candidate.id} has conflicting declarations`,
+        key: candidate.input.key,
+        lessonId: candidate.kind === "local" ? candidate.lesson.lessonId : void 0,
+        definitionId: candidate.id,
+        source: candidate.input.source,
+        relatedSources: sortedSources([
+          previous.input.source,
+          candidate.input.source
+        ])
+      })
+    );
+  }
+  return definitions;
+}
+function normalizeLesson(lesson) {
+  return {
+    ...lesson,
+    localDefinitions: lesson.localDefinitions.map(normalizeLocalDefinition).sort(
+      (left, right) => left.key.localeCompare(right.key) || compareSourceSpans(left.source, right.source)
+    ),
+    references: sortedReferences(lesson.references)
+  };
+}
+function normalizeSharedDefinition(input) {
+  return {
+    ...input,
+    aliases: [...input.aliases].sort(),
+    sources: [...input.sources].sort(),
+    seeAlso: [...input.seeAlso].sort(),
+    references: sortedReferences(input.references)
+  };
+}
+function normalizeLocalDefinition(input) {
+  return {
+    ...input,
+    sources: [...input.sources].sort(),
+    seeAlso: [...input.seeAlso].sort(),
+    references: sortedReferences(input.references)
+  };
+}
+function validateReferenceKey(reference, owner, diagnostics) {
+  if (isNotationKey(reference.key)) return true;
+  diagnostics.push(
+    diagnostic({
+      code: "invalid-key",
+      message: `${owner.id} references invalid notation key ${JSON.stringify(reference.key)}`,
+      key: reference.key,
+      lessonId: owner.kind === "local" ? owner.lesson.lessonId : void 0,
+      definitionId: owner.id,
+      source: reference.source
+    })
+  );
+  return false;
+}
+function validatePageReferenceKey(reference, lesson, diagnostics) {
+  if (isNotationKey(reference.key)) return true;
+  diagnostics.push(
+    diagnostic({
+      code: "invalid-key",
+      message: `${lesson.lessonId} references invalid notation key ${JSON.stringify(reference.key)}`,
+      key: reference.key,
+      lessonId: lesson.lessonId,
+      source: reference.source
+    })
+  );
+  return false;
+}
+function validateSeeAlsoReferences(candidate, availableDefinitionIds, diagnostics) {
+  for (const key of uniqueSorted(candidate.input.seeAlso)) {
+    const reference = {
+      key,
+      kind: "definition",
+      source: candidate.input.source
+    };
+    if (!validateReferenceKey(reference, candidate, diagnostics)) continue;
+    const definitionId = resolveReferenceId(
+      key,
+      candidate.scope,
+      availableDefinitionIds
+    );
+    if (definitionId === void 0) {
+      diagnostics.push(
+        diagnostic({
+          code: "undefined-reference",
+          message: `${candidate.id} has unknown seeAlso target ${key}`,
+          key,
+          lessonId: candidate.kind === "local" ? candidate.lesson.lessonId : void 0,
+          definitionId: candidate.id,
+          source: candidate.input.source
+        })
+      );
+    }
+  }
+}
+function toDefinitionRecord(candidate) {
+  if (candidate.kind === "shared") {
+    const input2 = candidate.input;
+    const record2 = {
+      kind: "shared",
+      id: candidate.id,
+      key: input2.key,
+      scope: candidate.scope,
+      notation: input2.notation,
+      label: input2.label,
+      summary: input2.summary,
+      aliases: input2.aliases,
+      domain: input2.domain,
+      sources: input2.sources,
+      seeAlso: input2.seeAlso,
+      alignment: input2.alignment,
+      status: input2.status,
+      aiAssisted: input2.aiAssisted,
+      body: input2.body,
+      source: input2.source,
+      resolvedReferences: candidate.resolvedReferences,
+      ...input2.formula === void 0 ? {} : { formula: input2.formula },
+      ...input2.units === void 0 ? {} : { units: input2.units }
+    };
+    return record2;
+  }
+  const input = candidate.input;
+  const record = {
+    kind: "local",
+    id: candidate.id,
+    key: input.key,
+    scope: candidate.scope,
+    lessonId: candidate.lesson.lessonId,
+    notation: input.notation,
+    label: input.label,
+    summary: input.summary,
+    sources: input.sources,
+    seeAlso: input.seeAlso,
+    alignment: input.alignment,
+    status: candidate.lesson.status,
+    source: input.source,
+    resolvedReferences: candidate.resolvedReferences,
+    ...input.formula === void 0 ? {} : { formula: input.formula },
+    ...input.units === void 0 ? {} : { units: input.units }
+  };
+  return record;
+}
+function definitionFingerprint(candidate) {
+  const references = sortedReferences(candidate.input.references).map(
+    (reference) => ({
+      key: reference.key,
+      kind: reference.kind
+    })
+  );
+  const inputAlignment = candidate.input.alignment;
+  const alignment = inputAlignment.kind === "general" ? {
+    kind: inputAlignment.kind,
+    rationale: normalizeText(inputAlignment.rationale)
+  } : {
+    kind: inputAlignment.kind,
+    introducedByCompetency: inputAlignment.introducedByCompetency,
+    introducedInLesson: inputAlignment.introducedInLesson
+  };
+  if (candidate.kind === "shared") {
+    const input2 = candidate.input;
+    return JSON.stringify({
+      kind: candidate.kind,
+      key: input2.key,
+      notation: input2.notation,
+      label: normalizeText(input2.label),
+      summary: normalizeText(input2.summary),
+      aliases: [...input2.aliases].sort(),
+      domain: input2.domain,
+      units: input2.units,
+      sources: [...input2.sources].sort(),
+      seeAlso: [...input2.seeAlso].sort(),
+      alignment,
+      status: input2.status,
+      aiAssisted: input2.aiAssisted,
+      body: normalizeText(input2.body),
+      references
+    });
+  }
+  const input = candidate.input;
+  return JSON.stringify({
+    kind: candidate.kind,
+    key: input.key,
+    notation: input.notation,
+    label: normalizeText(input.label),
+    summary: normalizeText(input.summary),
+    formula: input.formula,
+    units: input.units,
+    sources: [...input.sources].sort(),
+    seeAlso: [...input.seeAlso].sort(),
+    alignment,
+    references
+  });
+}
+function normalizeText(value) {
+  return value.replace(/\r\n?/g, "\n").split("\n").map((line) => line.trimEnd()).join("\n").trim();
+}
+function detectCycles(definitions, edgeIndex, diagnostics) {
+  const states = /* @__PURE__ */ new Map();
+  const stack = [];
+  const reported = /* @__PURE__ */ new Set();
+  const visit = (definitionId) => {
+    states.set(definitionId, "visiting");
+    stack.push(definitionId);
+    for (const dependencyId of edgeIndex.get(definitionId) ?? []) {
+      const state = states.get(dependencyId);
+      if (state === void 0) {
+        visit(dependencyId);
+      } else if (state === "visiting") {
+        const start = stack.lastIndexOf(dependencyId);
+        const path = canonicalCycle([...stack.slice(start), dependencyId]);
+        const key = path.join(">");
+        if (!reported.has(key)) {
+          reported.add(key);
+          const first = definitions.get(path[0] ?? "");
+          diagnostics.push({
+            code: "reference-cycle",
+            severity: "error",
+            message: `notation reference cycle: ${path.join(" -> ")}`,
+            key: first?.input.key,
+            lessonId: first?.kind === "local" ? first.lesson.lessonId : void 0,
+            definitionId: path[0],
+            source: first?.input.source,
+            path
+          });
+        }
+      }
+    }
+    stack.pop();
+    states.set(definitionId, "visited");
+  };
+  for (const id of [...definitions.keys()].sort()) {
+    if (states.get(id) === void 0) visit(id);
+  }
+}
+function canonicalCycle(path) {
+  const nodes = path.slice(0, -1);
+  if (nodes.length === 0) return path;
+  let best = [...nodes];
+  let bestKey = best.join("\0");
+  for (let index = 1; index < nodes.length; index += 1) {
+    const rotation = [...nodes.slice(index), ...nodes.slice(0, index)];
+    const key = rotation.join("\0");
+    if (key < bestKey) {
+      best = rotation;
+      bestKey = key;
+    }
+  }
+  return [...best, best[0]];
+}
+function transitiveClosure(roots, edgeIndex) {
+  const reached = /* @__PURE__ */ new Set();
+  const pending = [...roots].sort().reverse();
+  while (pending.length > 0) {
+    const id = pending.pop();
+    if (id === void 0 || reached.has(id)) continue;
+    reached.add(id);
+    const dependencies = edgeIndex.get(id) ?? [];
+    for (let index = dependencies.length - 1; index >= 0; index -= 1) {
+      const dependency = dependencies[index];
+      if (dependency !== void 0 && !reached.has(dependency)) {
+        pending.push(dependency);
+      }
+    }
+  }
+  return [...reached].sort();
+}
+function sortedReferences(references) {
+  return [...references].sort(
+    (left, right) => compareSourceSpans(left.source, right.source) || left.key.localeCompare(right.key) || left.kind.localeCompare(right.kind)
+  );
+}
+function sortResolvedReferences(references) {
+  return [...references].sort(
+    (left, right) => compareSourceSpans(left.source, right.source) || left.key.localeCompare(right.key) || left.kind.localeCompare(right.kind) || left.definitionId.localeCompare(right.definitionId)
+  );
+}
+function uniqueSorted(values) {
+  return [...new Set(values)].sort();
+}
+function sortedSources(values) {
+  return [...values].sort(compareSourceSpans);
+}
+function diagnostic(input) {
+  return { ...input, severity: "error" };
+}
+export {
+  assertValidNotation,
+  buildNotationRegistry
+};

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

@@ -0,0 +1,55 @@
+function textContent(node) {
+  if (!node || typeof node !== 'object') return '';
+  if (node.type === 'text' && typeof node.value === 'string') return node.value;
+  if (!Array.isArray(node.children)) return '';
+  return node.children.map(textContent).join('');
+}
+
+function katexErrors(node, output = []) {
+  if (!node || typeof node !== 'object') return output;
+
+  const classes = node.properties?.className;
+  if (
+    node.type === 'element' &&
+    Array.isArray(classes) &&
+    classes.includes('katex-error')
+  ) {
+    output.push({
+      source: textContent(node).trim(),
+      detail:
+        typeof node.properties?.title === 'string'
+          ? node.properties.title
+          : 'Unknown KaTeX parse error',
+      position: node.position,
+    });
+  }
+
+  if (Array.isArray(node.children)) {
+    for (const child of node.children) katexErrors(child, output);
+  }
+
+  return output;
+}
+
+/**
+ * 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.
+ */
+export default function rehypeFailKatexErrors() {
+  return function failOnKatexErrors(tree, file) {
+    const errors = katexErrors(tree);
+    if (errors.length === 0) return;
+
+    const first = errors[0];
+    const source = first.source ? ` for "${first.source}"` : '';
+    const additional =
+      errors.length > 1 ? ` (${errors.length - 1} additional error(s))` : '';
+    const message = `KaTeX rendering failed${source}: ${first.detail}${additional}`;
+
+    if (typeof file?.fail === 'function') {
+      file.fail(message, first.position, 'rehype-katex:parse-error');
+    }
+    throw new Error(message);
+  };
+}