explico 0.11.1 → 0.13.0

package/dist/compiler/manifest.js

@@ -40,10 +40,16 @@ import {
 import {
   validateRawFloats
 } from "../reference/raw-floats-validate.js";
+import {
+  validateLabKatexImports
+} from "../reference/lab-katex-validate.js";
 import {
   gateContentMath,
-  pageScope
+  pageScope,
+  scopeEntry
 } from "../reference/gate-math.js";
+import { gateIndices } from "../reference/gate-indices.js";
+import { derivedNotationEntries } from "../reference/derived-entries.js";
 import {
   gateProseNotation,
   gateProseNotationInAssessments
@@ -57,12 +63,18 @@ import { gateCourseRules } from "../reference/gate-course-rules.js";
 import { gateHeadingLength } from "../reference/gate-heading-length.js";
 import { gateHeadingStructure } from "../reference/gate-heading-structure.js";
 import { gatePartPages } from "../reference/gate-part-pages.js";
+import { gateNonChapterPages } from "../reference/gate-non-chapter-pages.js";
+import { findRetiredKeys, findUnsupportedKeys } from "../reference/gate-retired-keys.js";
+import { findMarkupInProps } from "../reference/gate-prop-text.js";
+import { gateMdxExpressions } from "../reference/gate-mdx-expression.js";
+import { CITATION_BRACKET, bracketCitations, withoutLinkCitations } from "../reference/citation-format.mjs";
+import { validateContentSchemas } from "./content-schema.js";
 import {
   scanSectionHeadings,
   scanTitledBlocks
 } from "../reference/sections.mjs";
 import { knowledgeCheckAnchorId } from "../reference/knowledge-checks.mjs";
-import { validateSectionRefs } from "../reference/sections-validate.js";
+import { validateHeadingAnchors, validateSectionRefs } from "../reference/sections-validate.js";
 import {
   splitMixedContent
 } from "../reference/mixed-content.js";
@@ -73,6 +85,7 @@ import { resolveReferenceId } from "../reference/references.js";
 import {
   coursePartsOf,
   normalizeBlockLabels,
+  normalizeCards,
   normalizeLessonExports,
   normalizeDisclosure,
   normalizeNumbering
@@ -93,9 +106,11 @@ import {
 } from "./knowledge-version.js";
 import {
   loadAbbreviationRegistryInput,
+  loadContentRecords,
   loadCurriculumCatalog,
   loadNotationDefinitions,
   loadNotationRegistryInput,
+  loadNonChapterPages,
   loadNotationSpecs,
   loadPartOverviews,
   loadSourceRecords
@@ -106,7 +121,7 @@ import {
   isLessonSlug,
   lessonIdFromSlug
 } from "./lesson-derivation.js";
-const MANIFEST_SCHEMA_VERSION = 24;
+const MANIFEST_SCHEMA_VERSION = 31;
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 const MANIFEST_PATH = join(REPOSITORY_ROOT, "build", "manifest.json");
@@ -119,18 +134,19 @@ function readEnginePackage() {
   }
   return enginePackage;
 }
-const CITE_PATTERN = /\[@([a-z0-9][a-z0-9.-]*)(?:;[ \t\r\n]*([^\]]*))?\]/g;
 function lessonCitations(body) {
   const withoutCode = body.replace(/```[\s\S]*?```/g, "").replace(/`[^`\n]*`/g, "");
   const seen = /* @__PURE__ */ new Set();
   const citations = [];
-  for (const match of withoutCode.matchAll(CITE_PATTERN)) {
-    const id = (match[1] ?? "").trim();
-    const locator = (match[2] ?? "").replace(/\s+/g, " ").trim() || void 0;
-    const dedupeKey = `${id} ${locator ?? ""}`;
-    if (seen.has(dedupeKey)) continue;
-    seen.add(dedupeKey);
-    citations.push(locator === void 0 ? { id } : { id, locator });
+  for (const match of withoutLinkCitations(withoutCode).matchAll(CITATION_BRACKET)) {
+    for (const citation of bracketCitations(match[1] ?? "", match[2])) {
+      const id = citation.id;
+      const locator = citation.locator || void 0;
+      const dedupeKey = `${id} ${locator ?? ""}`;
+      if (seen.has(dedupeKey)) continue;
+      seen.add(dedupeKey);
+      citations.push(locator === void 0 ? { id } : { id, locator });
+    }
   }
   return citations;
 }
@@ -170,17 +186,21 @@ function lessonNotationResolution(lesson, definitionsById, availableDefinitionId
       key: reference.key,
       scope: definition ? definition.kind === "shared" ? "shared" : "local" : "unresolved",
       definitionId: definitionId ?? null,
-      kind: reference.kind,
+      // A page's own references are prose or math; a definition's formula
+      // reference is reported as the definition reference it always was.
+      kind: reference.kind === "formula" ? "definition" : reference.kind,
       line: reference.source.line ?? null,
       column: reference.source.column ?? null
     };
   });
 }
-function lessonNotationBundle(bundle, definitionsById, resolution, cardsByKey) {
+function lessonNotationBundle(bundle, definitionsById, resolution, cardsByKey, derivedUses = []) {
   const definitions = [];
+  const records = [];
   for (const definitionId of bundle?.definitionIds ?? []) {
     const definition = definitionsById.get(definitionId);
     if (!definition) continue;
+    records.push(definition);
     definitions.push({
       id: definition.id,
       key: definition.key,
@@ -188,7 +208,6 @@ function lessonNotationBundle(bundle, definitionsById, resolution, cardsByKey) {
       notation: definition.notation,
       label: definition.label,
       summary: definition.summary,
-      editorialStatus: definition.status,
       seeAlso: [...definition.seeAlso],
       glosses: [...definition.glosses],
       formulaScope: formulaGlyphScope({
@@ -199,13 +218,19 @@ function lessonNotationBundle(bundle, definitionsById, resolution, 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 }
     });
   }
   return {
     bindings: [...bundle?.bindings ?? []].map((binding) => ({ ...binding })),
     definitionIds: [...bundle?.definitionIds ?? []],
     definitions,
+    derived: derivedNotationEntries(
+      derivedUses,
+      new Map(records.map((record) => [record.key, record])),
+      cardsByKey
+    ),
     resolution: [...resolution]
   };
 }
@@ -260,11 +285,19 @@ async function compileManifest(courseConfig) {
     loadNotationRegistryInput(),
     loadAbbreviationRegistryInput()
   ]);
-  const registry = buildNotationRegistry(notationInput);
+  const nonChapterPages = loadNonChapterPages();
+  const withPages = {
+    ...notationInput,
+    lessons: [
+      ...notationInput.lessons,
+      ...nonChapterPages.map((page) => page.notation)
+    ]
+  };
+  const registry = buildNotationRegistry(withPages);
   const cardsByKey = new Map(
     notationInput.sharedDefinitions.map((definition) => [
       definition.key,
-      { key: definition.key, notation: definition.notation }
+      scopeEntry(definition)
     ])
   );
   const definitionsById = new Map(
@@ -275,23 +308,55 @@ async function compileManifest(courseConfig) {
     registry.bundles.map((bundle) => [bundle.lessonId, bundle])
   );
   const assessmentsInput = catalog.assessments;
-  const curriculumIssues = validateCurriculum(catalog);
+  const contentRecords = loadContentRecords();
+  const curriculumIssues = [
+    ...validateCurriculum(catalog),
+    ...validateContentSchemas(contentRecords),
+    ...findRetiredKeys(contentRecords),
+    ...findUnsupportedKeys(contentRecords),
+    ...findMarkupInProps(contentRecords)
+  ];
   const alignmentIssues = validateNotationAlignment(registry, catalog);
   const mathEndAbbreviations = {
     allow: rules.strings("N12", "allow"),
     deny: rules.strings("N12", "deny")
   };
+  const sharedLabels = new Map(
+    notationInput.sharedDefinitions.map((definition) => [definition.key, definition.label])
+  );
+  const localLabelsByLesson = new Map(
+    notationInput.lessons.map((lesson) => [
+      lesson.lessonId,
+      new Map(lesson.localDefinitions.map((definition) => [definition.key, definition.label]))
+    ])
+  );
+  const termLabel = (lessonId, key) => localLabelsByLesson.get(lessonId)?.get(key) ?? sharedLabels.get(key);
+  const indexGate = gateIndices(
+    withPages.lessons,
+    new Map(
+      notationInput.sharedDefinitions.map((definition) => [definition.key, definition])
+    ),
+    {
+      assessments: assessmentsInput,
+      lessonAssessments: catalog.lessons.map((lesson) => ({
+        lessonId: lesson.id,
+        assessmentIds: lesson.assessments
+      }))
+    }
+  );
   const mathIssues = [
+    ...indexGate.diagnostics,
     ...gateContentMath({
-      notationInput,
+      notationInput: withPages,
       assessments: assessmentsInput,
       lessonAssessments: catalog.lessons.map((lesson) => ({
         lessonId: lesson.id,
         assessmentIds: lesson.assessments
       }))
     }),
+    ...gateMdxExpressions(withPages.lessons),
     ...rules.isEnabled("N9") ? [
-      ...gateProseNotation(notationInput.lessons, {
+      ...gateProseNotation(withPages.lessons, {
         allowSpelledUnits: rules.strings("N9", "allow")
       }),
       ...gateProseNotationInAssessments(assessmentsInput, {
@@ -299,16 +364,17 @@ async function compileManifest(courseConfig) {
       })
     ] : [],
     ...rules.isEnabled("N12") ? [
-      ...gateMathPunctuation(notationInput.lessons, mathEndAbbreviations),
+      ...gateMathPunctuation(withPages.lessons, mathEndAbbreviations),
       ...gateMathPunctuationInAssessments(assessmentsInput, mathEndAbbreviations)
     ] : [],
     ...rules.isEnabled("N14") ? gateAbbreviations({
-      notationInput,
+      notationInput: withPages,
       abbreviations: abbreviationsInput,
       courseAbbreviations: rules.settings("N14")
     }) : [],
     ...rules.isEnabled("S1") ? gateHeadingLength(notationInput.lessons, {
-      maxLength: rules.number("S1", "maxLength")
+      maxLength: rules.number("S1", "maxLength"),
+      labelFor: termLabel
     }) : [],
     ...gateHeadingStructure(notationInput.lessons, {
       levels: rules.isEnabled("S6"),
@@ -317,7 +383,9 @@ async function compileManifest(courseConfig) {
     // The course's own rules (`courseRules`): one pass for every enabled `X`
     // rule that carries a `forbid` pattern. A disabled one, and a guide rule
     // with no pattern, do no work here.
-    ...gateCourseRules(notationInput.lessons, rules.course)
+    ...gateCourseRules(withPages.lessons, rules.course),
+    // S10 is locked: a float on a non-chapter page has no number to render.
+    ...gateNonChapterPages(nonChapterPages)
   ];
   const notationLessonById = new Map(
     notationInput.lessons.map((lesson) => [lesson.lessonId, lesson])
@@ -326,22 +394,46 @@ async function compileManifest(courseConfig) {
     assessmentsInput.map((assessment) => [assessment.id, assessment])
   );
   const assessmentContent = [];
+  const assessmentDerived = /* @__PURE__ */ new Map();
   for (const lesson of catalog.lessons) {
     if (lesson.assessments.length === 0) continue;
     const lessonInput = notationLessonById.get(lesson.id);
     if (!lessonInput) continue;
     const scope = pageScope(lessonInput, cardsByKey);
+    const derived = /* @__PURE__ */ new Map();
+    assessmentDerived.set(lesson.id, derived);
+    const page = { derive: true, derived };
     for (const assessmentId of lesson.assessments) {
       const assessment = assessmentInputById.get(assessmentId);
       if (!assessment?.items) continue;
       for (const item of assessment.items) {
         if (!item.id) continue;
+        const numeric = item.type === "numeric" && typeof item.answer?.value === "number" && typeof item.answer.tolerance === "number";
         assessmentContent.push({
           lessonId: lesson.id,
           assessmentId,
           itemId: item.id,
-          promptSegments: splitMixedContent(item.prompt ?? "", scope),
-          explanationSegments: splitMixedContent(item.explanation ?? "", scope)
+          promptSegments: splitMixedContent(item.prompt ?? "", scope, page),
+          explanationSegments: splitMixedContent(item.explanation ?? "", scope, page),
+          type: item.type === "numeric" ? "numeric" : "single-choice",
+          ...item.options ? {
+            options: item.options.flatMap(
+              (option) => option.id ? [
+                {
+                  id: option.id,
+                  label: option.label ?? "",
+                  labelSegments: splitMixedContent(option.label ?? "", scope, page)
+                }
+              ] : []
+            )
+          } : {},
+          ...item.correctOptionId ? { correctOptionId: item.correctOptionId } : {},
+          ...numeric ? {
+            answer: {
+              value: item.answer.value,
+              tolerance: item.answer.tolerance
+            }
+          } : {}
         });
       }
     }
@@ -365,9 +457,31 @@ async function compileManifest(courseConfig) {
   );
   const frontmatterById = lessonFrontmatterById();
   const lessonSlugs = [...notationInput.lessons].map((lesson) => lesson.lessonId.replace(/\./g, "/")).sort();
-  const configuredParts = coursePartsOf(courseConfig);
-  const overviewPages = loadPartOverviews(configuredParts);
+  const listedParts = coursePartsOf(courseConfig);
+  const overviewPages = loadPartOverviews(listedParts);
   const overviewByDir = new Map(overviewPages.map((page) => [page.dir, page]));
+  const hasChapter = (dir) => lessonSlugs.some((slug) => slug.startsWith(`${dir}/`));
+  const configuredParts = listedParts.filter(
+    (part) => hasChapter(part.dir) || overviewByDir.has(part.dir)
+  );
+  for (const part of listedParts) {
+    if (configuredParts.includes(part)) continue;
+    curriculumIssues.push({
+      kind: "part-empty",
+      severity: "warning",
+      message: `course.settings.json \`parts\` lists "${part.dir}" (${JSON.stringify(part.label)}), but content/docs/${part.dir}/ has no chapter and no overview page yet, so the part is left out of the sidebar and the numbering until it has one.`
+    });
+  }
+  const partDirs = new Set(listedParts.map((part) => part.dir));
+  for (const lesson of notationInput.lessons) {
+    const dir = lesson.lessonId.split(".")[0] ?? "";
+    if (partDirs.has(dir)) continue;
+    curriculumIssues.push({
+      kind: "lesson-outside-parts",
+      message: `${lesson.source.file} is in content/docs/${dir}/, which no part in course.settings.json \`parts\` lists, so it has no part, no chapter number and no place in the sidebar. Add { "dir": "${dir}", "label": "\u2026" } to \`parts\`, or move the lesson into a part's directory.`,
+      file: lesson.source.file
+    });
+  }
   if (rules.isEnabled("S2")) {
     mathIssues.push(
       ...gatePartPages(
@@ -381,7 +495,7 @@ async function compileManifest(courseConfig) {
   }
   const waiverDiagnostics = [];
   const waiverRules = { courseRules: rules.course };
-  const waivers = notationInput.lessons.flatMap((lesson) => {
+  const waivers = withPages.lessons.flatMap((lesson) => {
     const collected = collectWaivers(lesson, waiverRules);
     waiverDiagnostics.push(...collected.diagnostics);
     return collected.waivers;
@@ -408,10 +522,10 @@ async function compileManifest(courseConfig) {
   const placementByLessonId = /* @__PURE__ */ new Map();
   const chapterScoped = numberingSettings.floats === "chapter";
   let partCursor = 0;
-  for (const group of sidebar) {
+  for (const group of sidebar.slice(0, configuredParts.length)) {
+    partCursor += 1;
     const lessonIds = group.items.filter((item) => typeof item === "string").map(lessonIdFromSlug);
     if (lessonIds.length === 0) continue;
-    partCursor += 1;
     const used = {
       equations: 0,
       tables: 0,
@@ -452,7 +566,8 @@ async function compileManifest(courseConfig) {
         lesson.lessonId,
         scanSectionHeadings(lesson.body, {
           ...placement ? { prefix: `${placement.part}.${placement.chapter}` } : {},
-          depth: numberingSettings.sections.depth
+          depth: numberingSettings.sections.depth,
+          labelFor: (key) => termLabel(lesson.lessonId, key)
         })
       ];
     })
@@ -467,7 +582,8 @@ async function compileManifest(courseConfig) {
         headingSlugs: (headingsByLessonId.get(lesson.lessonId) ?? []).map(
           (heading) => heading.slug
         )
-      }))
+      })),
+      nonChapterPages.map((page) => page.slug)
     )
   );
   const manifestParts = configuredParts.map((part, index) => {
@@ -569,6 +685,45 @@ async function compileManifest(courseConfig) {
       })
     ])
   );
+  const engineAnchorsFor = (lessonId, body) => {
+    const slug = lessonId.replace(/\./g, "/");
+    const anchors = /* @__PURE__ */ new Map();
+    const keyed = (floats, prefix, owner) => {
+      for (const float of floats) anchors.set(`${prefix}-${float.key}`, owner(float.key));
+    };
+    keyed(equationsBySlug.get(slug) ?? [], "eq", (key) => `the equation labelled eq:${key}`);
+    keyed(tablesBySlug.get(slug) ?? [], "tab", (key) => `<Table id="${key}">`);
+    keyed(figuresBySlug.get(slug) ?? [], "fig", (key) => `<Figure id="${key}">`);
+    keyed(diagramsBySlug.get(slug) ?? [], "dia", (key) => `<Diagram id="${key}">`);
+    keyed(examplesBySlug.get(slug) ?? [], "ex", (key) => `<CompactExamples id="${key}">`);
+    for (const check of checksBySlug.get(slug) ?? []) {
+      anchors.set(knowledgeCheckAnchorId(check.key), `the knowledge check ${check.key}`);
+    }
+    for (const [name, prefix] of [
+      ["Memo", "memo"],
+      ["ShortNote", "short-note"]
+    ]) {
+      const tag = new RegExp(`<${name}\\b[^>]*?\\bid=["']([^"']+)["']`, "g");
+      for (const match of body.matchAll(tag)) {
+        anchors.set(`${prefix}-${match[1]}`, `<${name} id="${match[1]}">`);
+      }
+    }
+    if (deriveSources(body).length > 0) {
+      anchors.set("references", "the References section generated from the page\u2019s citations");
+    }
+    return anchors;
+  };
+  mathIssues.push(
+    ...validateHeadingAnchors(
+      notationInput.lessons.map((lesson) => ({
+        file: lesson.source.file,
+        body: lesson.body,
+        ...lesson.bodyLine === void 0 ? {} : { bodyLine: lesson.bodyLine },
+        headings: headingsByLessonId.get(lesson.lessonId) ?? [],
+        anchors: engineAnchorsFor(lesson.lessonId, lesson.body)
+      }))
+    )
+  );
   const titledBlocksFor = (lessonId) => {
     const slug = lessonId.replace(/\./g, "/");
     const body = bodyByLessonId.get(lessonId) ?? "";
@@ -593,6 +748,14 @@ async function compileManifest(courseConfig) {
       }
     );
   };
+  const labKatexDiagnostics = validateLabKatexImports(
+    notationInput.lessons.map((lesson) => ({
+      lessonId: lesson.lessonId,
+      file: lesson.source.file,
+      body: lesson.body
+    })),
+    REPOSITORY_ROOT
+  );
   const rawFloatDiagnostics = validateRawFloats(
     notationInput.lessons.map((lesson) => ({
       lessonId: lesson.lessonId,
@@ -633,7 +796,6 @@ async function compileManifest(courseConfig) {
       title: frontmatter.title,
       description: frontmatter.description,
       ...frontmatter.studyMinutes === void 0 ? {} : { studyMinutes: frontmatter.studyMinutes },
-      status: meta.status,
       teaches: [...teaches],
       requires: [...meta.requires],
       assumptions: [...meta.assumptions],
@@ -660,18 +822,36 @@ async function compileManifest(courseConfig) {
           definitionsById,
           availableDefinitionIds
         ),
-        cardsByKey
+        cardsByKey,
+        [
+          ...indexGate.derivedByLesson.get(id) ?? [],
+          ...assessmentDerived.get(id)?.values() ?? []
+        ]
       )
     });
   }
   lessons.sort((a, b) => a.id.localeCompare(b.id));
+  const pages = nonChapterPages.map((page) => ({
+    id: page.id,
+    slug: page.slug,
+    file: page.file,
+    notation: lessonNotationBundle(
+      bundlesByLesson.get(page.id),
+      definitionsById,
+      lessonNotationResolution(
+        page.notation,
+        definitionsById,
+        availableDefinitionIds
+      ),
+      cardsByKey,
+      indexGate.derivedByLesson.get(page.id)
+    )
+  })).sort((a, b) => a.id.localeCompare(b.id));
   const consistencyIssues = runConsistencyChecks({
     registry,
-    notationInput,
+    notationInput: withPages,
     specs: loadNotationSpecs(),
-    catalog,
     lintIgnore: loadLintIgnore(),
-    conventions: courseConfig.conventions,
     operators: rules.settings("N8"),
     romanLabels: rules.settings("N10"),
     accents: rules.settings("N22")
@@ -726,6 +906,7 @@ async function compileManifest(courseConfig) {
     disclosure: normalizeDisclosure(courseConfig),
     numbering: numberingSettings,
     blockLabels,
+    cards: normalizeCards(courseConfig),
     about,
     notation: {
       definitions: registry.definitions,
@@ -741,6 +922,7 @@ async function compileManifest(courseConfig) {
     sidebar,
     parts: manifestParts,
     lessons,
+    pages,
     prereqEdges,
     equations: {
       labels: equationValidation.labels,
@@ -776,7 +958,7 @@ async function compileManifest(courseConfig) {
       consistency: dropDisabled(consistencyIssues, off),
       equations: dropDisabled(equationValidation.diagnostics, off),
       tables: dropDisabled(tableValidation.diagnostics, off),
-      figures: dropDisabled(figureValidation.diagnostics, off),
+      figures: dropDisabled([...figureValidation.diagnostics, ...labKatexDiagnostics], off),
       diagrams: dropDisabled(diagramValidation.diagnostics, off),
       checks: dropDisabled(checkValidation.diagnostics, off),
       examples: dropDisabled(exampleValidation.diagnostics, off),

package/dist/compiler/render-diagnostics.d.ts

@@ -0,0 +1,65 @@
+import { DiagnosticSeverity } from '../reference/types.js';
+import { Manifest } from './manifest.js';
+import '../curriculum/validation.js';
+import '../reference/consistency.js';
+import '../course-config-rRtME5UV.js';
+import '../rules/catalog.js';
+import '../rules/course-rules.js';
+import './collections.js';
+import '../reference/gate-retired-keys.js';
+import '../reference/lint-ignore.js';
+import '../reference/equations-validate.js';
+import '../reference/tables-validate.js';
+import '../reference/keyed-float-validate.js';
+import '../reference/figures-validate.js';
+import '../reference/diagrams-validate.js';
+import '../reference/examples-validate.js';
+import '../reference/folds-validate.js';
+import '../reference/knowledge-checks-validate.js';
+import '../reference/raw-floats-validate.js';
+import '../reference/lab-katex-validate.js';
+import '../reference/gate-math.js';
+import '../reference/mixed-content.js';
+import '../reference/gloss.js';
+import '../rules/waivers.js';
+import './knowledge-version.js';
+import './lesson-derivation.js';
+
+/**
+ * Diagnostics only a rendered page can give, kept from one `astro build` for
+ * `content warnings`.
+ *
+ * Most checks read the content tree, so the manifest carries them and every
+ * `content` command recomputes them. A few need the page as Astro renders it:
+ * a diagram drawn by a wrapper component lays out to a width only its render
+ * knows (rule V8, `reference/diagram-fit.ts`). `compiler/astro.ts` reports
+ * those as the build finishes and writes them to
+ * `build/render-diagnostics.json`, replacing the previous build's; the
+ * `content` CLI lists them beside the manifest's under the `render:` source.
+ * They are as current as the last build: run `pnpm build` (or `astro build`)
+ * after changing a diagram to refresh them.
+ */
+
+declare const RENDER_DIAGNOSTICS_PATH: string;
+interface RenderDiagnostic {
+    readonly code: string;
+    readonly severity: DiagnosticSeverity;
+    readonly message: string;
+    /** The lesson's source file, e.g. `content/docs/motion/range.mdx`; else the built page. */
+    readonly file: string;
+    readonly lessonId?: string;
+    /** The float the finding is about, e.g. a diagram's `id`. */
+    readonly key?: string;
+}
+/**
+ * The render diagnostics of one built page. A diagram that appears on more
+ * than one page (a lesson and its standalone export) is reported once per
+ * lesson by {@link writeRenderDiagnostics}.
+ */
+declare function pageRenderDiagnostics(manifest: Pick<Manifest, 'lessons'>, page: string, html: string): RenderDiagnostic[];
+/** Replace the last build's render diagnostics with these, deduplicated and sorted. */
+declare function writeRenderDiagnostics(diagnostics: readonly RenderDiagnostic[], path?: string): readonly RenderDiagnostic[];
+/** What the last build reported; `[]` before the first build. */
+declare function readRenderDiagnostics(path?: string): readonly RenderDiagnostic[];
+
+export { RENDER_DIAGNOSTICS_PATH, type RenderDiagnostic, pageRenderDiagnostics, readRenderDiagnostics, writeRenderDiagnostics };

package/dist/compiler/render-diagnostics.js

@@ -0,0 +1,56 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+  diagramTooWideMessage,
+  oversizedDiagrams
+} from "../reference/diagram-fit.js";
+const RENDER_DIAGNOSTICS_PATH = join(
+  process.cwd(),
+  "build",
+  "render-diagnostics.json"
+);
+function slugOfPage(page) {
+  return page.split(/[\\/]/u).join("/").replace(/(^|\/)index\.html$/u, "").replace(/\.html$/u, "");
+}
+function pageRenderDiagnostics(manifest, page, html) {
+  const oversized = oversizedDiagrams(html);
+  if (oversized.length === 0) return [];
+  const slug = slugOfPage(page);
+  const lesson = manifest.lessons.find((candidate) => candidate.slug === slug);
+  return oversized.map((diagram) => ({
+    code: diagram.code,
+    severity: "warning",
+    message: diagramTooWideMessage(diagram.key, diagram.width, diagram.limit),
+    file: lesson?.file ?? page,
+    ...lesson ? { lessonId: lesson.id } : {},
+    key: diagram.key
+  }));
+}
+function writeRenderDiagnostics(diagnostics, path = RENDER_DIAGNOSTICS_PATH) {
+  const unique = /* @__PURE__ */ new Map();
+  for (const diagnostic of diagnostics) {
+    unique.set(`${diagnostic.file}\0${diagnostic.code}\0${diagnostic.key ?? diagnostic.message}`, diagnostic);
+  }
+  const sorted = [...unique.values()].sort(
+    (a, b) => a.file.localeCompare(b.file) || a.code.localeCompare(b.code) || (a.key ?? "").localeCompare(b.key ?? "")
+  );
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify({ diagnostics: sorted }, null, 2)}
+`);
+  return sorted;
+}
+function readRenderDiagnostics(path = RENDER_DIAGNOSTICS_PATH) {
+  if (!existsSync(path)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return Array.isArray(parsed.diagnostics) ? parsed.diagnostics : [];
+  } catch {
+    return [];
+  }
+}
+export {
+  RENDER_DIAGNOSTICS_PATH,
+  pageRenderDiagnostics,
+  readRenderDiagnostics,
+  writeRenderDiagnostics
+};

package/dist/compiler/resolution-report.d.ts

@@ -1,11 +1,12 @@
 import { Manifest } from './manifest.js';
 import '../curriculum/validation.js';
 import '../reference/consistency.js';
-import '../course-config-Dsnri9Tk.js';
+import '../course-config-rRtME5UV.js';
 import '../rules/catalog.js';
 import '../rules/course-rules.js';
 import './collections.js';
 import '../reference/types.js';
+import '../reference/gate-retired-keys.js';
 import '../reference/lint-ignore.js';
 import '../reference/equations-validate.js';
 import '../reference/tables-validate.js';
@@ -16,6 +17,7 @@ import '../reference/examples-validate.js';
 import '../reference/folds-validate.js';
 import '../reference/knowledge-checks-validate.js';
 import '../reference/raw-floats-validate.js';
+import '../reference/lab-katex-validate.js';
 import '../reference/gate-math.js';
 import '../reference/mixed-content.js';
 import '../reference/gloss.js';