explico 0.11.1 → 0.13.0

package/docs/authoring/structure.md

@@ -106,6 +106,13 @@ Part 2  Projectile motion
 
 ## Part pages
 
+A part is listed in `course.settings.json` → `parts` as `{ "dir", "label" }`
+and lives in `content/docs/<dir>/`. A part listed before anything is written
+in it — no chapter and no overview page yet — is left out of the sidebar and
+the numbering, with a `part-empty` warning, so the parts after it keep their
+numbers until it has content. A lesson in a directory no part lists fails
+`validate:content` (`lesson-outside-parts`).
+
 A part is a directory, so `/<part>/` is a URL a reader will eventually type,
 follow, or be handed by a search engine. Without a page it is a 404, and the
 part exists only as a sidebar heading that cannot be linked to.
@@ -154,6 +161,14 @@ missing, holds more than one paragraph, or falls outside the course's
 takes no float numbers, and never appears in `manifest.lessons` or a track. A
 course adds one part at a time; a part without one behaves exactly as before.
 
+**It explains its symbols, and links its floats**
+([S10](structure-rules.md#s10)). A `[[key]]` term, math, a citation, an
+abbreviation and a `[[chapter#tab-key]]` link each open their card on an
+overview page, as on the landing page and any other page outside a part; the
+manifest lists each such page under `pages` with its notation bundle. A
+`<Table>`, `<Figure>`, `<Diagram>`, lab or `\label{eq:…}` stays in its
+chapter, which alone can number it, and the overview links it.
+
 `<PartOverview>` reads the manifest for everything it lists — chapters in
 reading order with their descriptions, the competencies the part teaches, the
 parts it builds on and leads to — so the page cannot fall out of date with the
@@ -301,7 +316,11 @@ punctuation dropped, so `## Two ways to name the same point` is
 `-1`, `-2`. A reference to a heading without a number (deeper than `depth`, or
 with `show: false`) prints the heading's title in quotes instead: a reader
 could not find the number. A reference that names no top-level heading fails
-`pnpm validate:content` (`sec-ref-resolves`) and the build.
+`pnpm validate:content` (`sec-ref-resolves`) and the build. So does a heading
+whose anchor the page already gives something else
+(`heading-anchor-collision`): `## References` on a page that cites a source
+(the References section is generated, at `#references`), or `## Tab totals`
+beside `<Table id="totals">` (`#tab-totals`).
 
 ### Structure from the bottom up
 
@@ -339,6 +358,13 @@ worked-example set (`<CompactExamples>`) is numbered **`‹part›.‹chapter›
 - **Keyed or not, everything counts.** An equation with no `\label{eq:…}` still
   takes a number and a positional anchor (`#eq-2-1-4`); it just cannot be
   referenced by name.
+- **The lesson's flow counts, a callout does not.** An equation or a float
+  in a list item or a `>` quote counts like one at the top level, and so
+  does one in a `<Memo>`, `<ShortNote>` or `<Fold>`. One in a `:::note`
+  aside (or `<Aside>`, or a worked example) is illustrative and takes no
+  number; a `<Table>` or `<Figure>` there fails the build. A display
+  equation is a `$$` block whose fences sit on lines of their own:
+  `$$x$$` inside a sentence, or on one line, is inline math.
 - **The number sits with the caption.** A figure or diagram prints it in the
   caption line below its picture, a table in the caption line above, and a
   display equation beside it. What names each
@@ -432,6 +458,12 @@ that wants them addressed should wrap the table in `<Table id="…">`/
 `<Figure id="…">`, or give the diagram an `id` and move it to the top level (or
 inside `<Memo>`/`<ShortNote>`), or wrap it in `<Figure>`.
 
+A raw table counts only where a `<Table>` would number it: at the top level,
+or in a `<Memo>`, `<ShortNote>` or `<Fold>`. One in a worked example
+(`<CompactExample>`) or another component is illustrative, like an equation
+there, and stays a plain table: a `<Table>` or a `<Figure>` there gets no
+number, and the build fails on it, naming the component it sits in.
+
 ### Knowledge checks
 
 An assessment title is authored once, in `content/assessments/<id>.json`, and
@@ -557,7 +589,9 @@ A block folds in one of two ways, and every default lives in one place, the
 `sections`, `subsections` and `knowledgeChecks` take `{ collapsible,
 defaultOpen }`; the others take `{ defaultOpen }`; `tables` takes
 `{ truncateAfter }` — a table with more rows shows that many, half from each
-end, and a "… N more rows …" line. There is no `disclosure.diagrams`: a
+end, and a "… N more rows …" line, unless that would hide a single row (the
+line is as tall as the row, so the table shows whole). There is no
+`disclosure.diagrams`: a
 diagram does not fold. Every collapsible remembers the reader's own choice,
 per page, over the default (`rememberState={false}` on a memo, a fold, a
 figure's tools or an example set opts that one out). A short note's in-place
@@ -632,3 +666,34 @@ While collapsed, the surrounding sentence remains one paragraph and only the
 point in the reading flow, and exposes a “Show less” control that restores the
 original sentence. Short notes are for a locally optional explanation, not for
 material that needs a number or citations elsewhere; use a memo for that.
+
+## Retired keys
+
+A key the engine has stopped reading fails the build wherever a content file
+still sets it, so a course cannot keep maintaining a field that does nothing.
+Each `retired-key` error names the file and the key's line; deleting the line
+clears it.
+
+| Key | Where it was set | Why it went |
+| --- | --- | --- |
+| `editorialStatus` | pages, notation entries, abbreviations, competencies, assessments, sources, tracks | Lessons are reviewed continuously, so no page ever earns a one-time "reviewed" stamp. The draft / in-review / reviewed labels it put on part pages, notation cards, glossary entries and citations are gone. |
+
+Two of Starlight's own keys do not work in a course, because the manifest,
+not Starlight, decides which chapters a course lists and in what order. A
+lesson's `draft: true` fails the build as `unsupported-key`: Starlight would
+leave the page out of a production build while the sidebar still names it.
+Keep an unfinished lesson outside `content/docs/` until it is ready. A
+chapter's `sidebar.order` warns as `ignored-key`: chapters follow the order of
+the tracks (`content/tracks/*.json`).
+
+## Content schemas
+
+Every content file is checked against its collection's schema — the same
+one `astro build` loads it with (`src/compiler/content-schemas.ts`) — by
+`pnpm validate:content` and `pnpm content check`, so a value the build would
+reject fails there first, at the key's line, as a `content-schema` error:
+a notation `meaning` with `$` or `\`, a source `type` outside `primary`,
+`official-guidance`, `paper`, `book` and `secondary`, or a `studyMinutes`
+range whose low end exceeds its high end. A lesson is checked for the fields
+explico adds (`teaches`, `assumptions`, `studyMinutes`, `notation`);
+Starlight checks its own (`title`, `description`, …) when the site builds.

package/docs/authoring/visualizations.md

@@ -48,8 +48,8 @@ an independent diagram number, a `#dia-<id>` anchor, and references of the form
 equation, table, or figure sequences.
 
 A diagram is named like every float: a long `caption`, shown below the graph
-in the same caption line a figure has (`Diagram 2.1.1`, a chain icon that
-copies the diagram's link, the caption), and an optional `short` caption for
+in the same caption line a figure has (`Diagram 2.1.1`, whose toolbar
+copies the diagram's link, then the caption), and an optional `short` caption for
 the `[[dia-…]]` preview card
 ([components.md § The caption pair](components.md#the-caption-pair)).
 
@@ -63,14 +63,16 @@ or Escape, restores its original width. A diagram never folds by itself: it
 is its graph and then its caption line, in every state. To let a reader fold
 it away, put it in a collapsible section.
 
-By default a laid-out width above `800px` emits a compile-time warning. Treat
-that warning as a prompt to try
-`direction="TB"`, shorter labels, or explicit node sizes before accepting the
-wide layout. Set `warnAboveWidth={false}` only when horizontal overflow is
-intentional, or set a positive pixel value when the course needs a different
-review threshold.
+Each node's box is sized from what it holds: its `text` measured in DejaVu
+Sans, the widest common system font, and its `formula` measured from KaTeX's
+own layout, so neither spills out of the box in any reader's font. A `text`
+wider than about 190px wraps onto more lines and the box grows taller; a
+`formula` never wraps, so a wide one widens its box and the text wraps to it.
+Give a node a `width` to narrow it (its text wraps inside it and the height
+follows) or a `height` to make it taller. A diagram that comes out wider than
+the lesson column is [V8](#v8)'s concern.
 
-_Enforcement._ Review-only, with a compile-time width warning from `Diagram`.
+_Enforcement._ Review-only.
 
 _Exceptions._ A one-off illustrative schematic that is not a graph (a labelled
 photo, a geometric figure) is a [V2](#v2) figure, not a `Diagram`.
@@ -115,16 +117,23 @@ equations.**
 An interactive figure is a React island, hydrated `client:visible` (or
 `client:idle`). It carries:
 
-- **Gate-checked math.** Any equation shown in the figure goes through the
+- **Gate-checked math.** Every symbol the figure shows — an equation, a
+  legend entry, an axis title, a slider label — goes through the
   `labMathScope` / `renderLabMath` / `\slot{}` seam so its symbols are resolved
   against the page's real notation at build time and the island only patches
-  numbers into pre-rendered KaTeX. A wrapper whose template names notation not
-  otherwise present in lesson MDX passes
+  numbers into pre-rendered KaTeX. `renderLabMath(template, scope)` renders a
+  display equation; `renderLabMath(template, scope, { display: false })`
+  renders inline math for a formula that sits in a line, which never scrolls.
+  A lab never calls KaTeX itself: its symbols would open no card. A wrapper
+  whose template names notation not otherwise present in lesson MDX passes
   `{ locals: Astro.locals, context: '<ComponentName> <template>' }` as the third
   `labMathScope` argument; that is the declaration that ships those definitions
   in this page's popup payload. See
   `playground/content/labs/ProjectileRangeExplorer.tsx` +
-  `ProjectileRangeMath.astro`.
+  `ProjectileRangeMath.astro`. Pass the table `labMathScope` returned to
+  `renderLabMath` unchanged: the page's index entries reach the lab through
+  it, so `\mathbf{v}_0` gets its derived card ([N23](notation.md#n23)), and a copy
+  (`[...scope]`) gets neither the cards nor the index check.
 - **Labelled controls.** Every control is a labelled `<input>` — the visible
   label is how any reader knows what a slider sets; where precision
   matters, pair a `range` slider with a `number` field (see `RangeField` in
@@ -136,8 +145,7 @@ An interactive figure is a React island, hydrated `client:visible` (or
   that describes the plot ("the dot marks the landing point") belongs in the
   figure's caption.
 - **Picture, then caption, then tools.** A lab is laid out as a LaTeX figure
-  with its controls after it (docs/plans/figures-and-short-captions.md,
-  decision 3). The plot goes in the `<Figure>`'s default slot — its
+  with its controls after it. The plot goes in the `<Figure>`'s default slot — its
   picture — and the controls in its `tools` slot: an instruction line, the
   sliders and fields, the live equation. The two are separate islands that
   share their values. The tools render after the caption line, in a tray of
@@ -151,20 +159,32 @@ An interactive figure is a React island, hydrated `client:visible` (or
   case shown — "Shown for v₀ = 20 m/s and θ = 30°: range 35.3 m, time of
   flight 2.04 s." The lab writes it with `setFigureState(element, runs)`
   (`explico/components/figure/figure-state.ts`), `element` being any element
-  of its own inside the figure and `runs` plain text, `{ text, italic: true }`
-  or `{ sub }` — never HTML. The clause prints with the caption; a reader
-  of the long caption elsewhere (a preview card, a fold's bar) sees the
-  caption alone.
+  of its own inside the figure and each run a string of plain text or
+  `{ math }`, a symbol rendered at build time with
+  `renderLabMath(template, scope, { display: false })` and handed to the
+  island — never HTML, and never a symbol typed as text, which would open no
+  card. `ProjectileRangePicture.astro` renders the playground's. The clause
+  prints with the caption; a reader of the long caption elsewhere (a
+  preview card, a fold's bar) sees the caption alone.
 - **Which text goes where.** The caption names the figure and says what it
   shows — its subject, its marks and symbols, the case shown — and may state
   the one thing to notice. The argument drawn from the figure is lesson
   text, after the figure. Instructions for the controls belong to the
   controls: the tools' first line, not the caption.
-- **A preview shows the plot.** A same-page `[[fig-…]]` reference to a lab
-  previews a still copy of its plot as drawn; the tools are never copied. A
-  plot not drawn yet — or one on another page, drawn only in the browser —
-  leaves the card to the caption and number, so a lab no longer needs
-  `previewable={false}`.
+- **The build draws the default picture.** The island draws its plot in
+  the browser, after the page loads. So the lab's Astro wrapper draws the
+  same plot at the island's default values at build time and hands it to
+  the island as its children, which the island shows until it has drawn
+  its own. The built page then has the picture before hydration, with
+  JavaScript off, in print and in the standalone HTML export. With
+  Observable Plot that is one options function the island and the wrapper
+  share, and `Plot.plot({ ...options, document })` on a server-side
+  document in the wrapper; see `playground/content/labs/still-plot.ts`,
+  `LaunchAnglePicture.astro` and `LaunchAngleExplorer.tsx`.
+- **A preview shows the plot.** A `[[fig-…]]` reference to a lab previews a
+  still copy of its plot, from this page or another: as drawn once the
+  island has run, else the build's default picture. The tools are never
+  copied, so a lab needs no `previewable={false}`.
 
 The figure itself never hides; a lab that should fold away whole, with the
 prose around it, goes in a `<Fold>` or a collapsible section.
@@ -184,7 +204,22 @@ _How to apply._ Keep the island's job to "patch numbers and redraw". Domain
 math lives in a plain module (`playground/content/domain/motion.ts`), not in the
 component.
 
-_Enforcement._ Review-only.
+_Enforcement._ Partly build-enforced. `pnpm validate:content` follows each
+lesson's relative imports to the course's components and fails one that
+imports `katex` itself (`lab-katex-validate.ts`, `lab-katex-direct`, an
+error), naming the chain of imports that reaches it. `astro build` then reads
+every figure it rendered and fails a symbol KaTeX drew outside a notation
+binding (`figure-symbols.ts`, rule [N4](notation.md#n4)); a course's browser
+test runs the same `unboundFigureSymbols` on a hydrated figure's
+`outerHTML`, which also holds what an island draws only in the browser, as
+the playground's `labs.spec.ts` does. The same build warns about a figure
+whose picture is an island with nothing drawn in the built page
+(`figure-pictures.ts`, `undrawnFigurePictures`, `lab-picture-undrawn`, a
+warning). `renderLabMath` and a `<Diagram>` formula fail `astro build` on
+an index no card explains (rule [N23](notation.md#n23)), as they render.
+`setFigureState` takes no symbol typed as text, so `astro check` fails an
+italic or a `sub` run. That a lab labels its controls and names
+nothing of its own is review-only.
 
 _Exceptions._ None.
 
@@ -348,3 +383,110 @@ _Exceptions._
   are only two.
 - A sketch that draws axes is a chart. If the axes are worth drawing, their
   scale is worth labelling.
+
+---
+
+## V7
+
+**A figure’s picture takes at most `maxPercent` of the screen height.**
+
+The picture is the default slot of a `<Figure>`: the plot, its key and any
+data tables, without the caption line or the tools. On the screens the course
+targets it stays within `maxPercent` (80% unless the course sets
+`rules.V7.maxPercent`) of the viewport height. Then a reader who scrolls to the
+figure sees the whole picture and its caption line at once, with a line of the
+text that points to it.
+
+- **A square or tall plot gets a width, not the column.** A chart drawn with
+  `aspectRatio: 1` (Observable Plot) or a height derived from the container
+  width grows with the column: a square in a 760px column is 760px tall, almost
+  all of a laptop screen. Give such a plot a fixed width (`width: 460`,
+  `aspectRatio: 1`) and centre it, or cap it with
+  `Math.min(containerWidth, 460)`.
+- **Stacked panels share the budget.** Two panels of 300px each are one 600px
+  picture. Shorten both, put them side by side on a wide screen, or keep the
+  secondary one in the tools.
+- **Measure, don't estimate.** Font size, the column width and a lab's
+  hydrated layout all change the height, so judge it from the rendered page.
+
+_Rationale._ A figure is read with its caption and with the sentence that
+sends the reader to it. A picture taller than the screen has to be scrolled
+past to reach its caption, and a control in the tools that redraws it can no
+longer be watched while it is moved.
+
+_How to apply._ In the course’s Playwright suite, open every lesson that has
+a figure, at each viewport the course supports, and expect no findings:
+
+```ts
+import { readFileSync } from 'node:fs';
+import { expect, test } from '@playwright/test';
+import { checkFigureFit, lessonsWithFigures } from 'explico/reference/figure-fit';
+
+const manifest = JSON.parse(readFileSync('build/manifest.json', 'utf8'));
+
+for (const path of lessonsWithFigures(manifest)) {
+  test(`${path} figures fit on one screen (rule V7)`, async ({ page }) => {
+    await page.setViewportSize({ width: 1280, height: 800 });
+    await page.goto(path);
+    const findings = await checkFigureFit(page);
+    expect(findings.map((finding) => finding.message)).toEqual([]);
+  });
+}
+```
+
+Pass `{ maxPercent }` when the course sets `rules.V7.maxPercent`. The check
+opens a figure inside a closed `<Fold>` before it measures, because a reader
+can open it, and waits for each figure’s islands to hydrate and its height to
+settle.
+
+_Enforcement._ Partial. `checkFigureFit` in `src/reference/figure-fit.ts`
+reports `figure-too-tall` for each picture over the budget, on the pages and
+viewports a course’s browser tests open; the build cannot measure a laid-out
+page.
+
+_Exceptions._ A figure whose picture is itself the subject at full size — a
+long table of values, a tall timeline the reader is meant to scroll — may be
+exempted in the test with a stated reason,
+`checkFigureFit(page, { allow: { 'fig-timeline': 'read by scrolling, one row per year' } })`,
+or kept in a `<Fold>` with a
+`<Table>` instead of a figure.
+
+---
+
+## V8
+
+**A diagram is no wider than the lesson column.**
+
+A `<Diagram>` lays out to at most `columnWidth` px (707 unless the course sets
+`rules.V8.columnWidth`): the lesson column at a 1366px-wide window, the most
+common laptop screen (the column is 632px at 1280 and 832px at 1920). Then a
+reader sees the whole graph where the text sends them to it, without scrolling
+it sideways or pressing its widen button ↔.
+
+The engine does the first part itself. A diagram that comes out wider than
+its limit is laid out again with its labels wrapped narrower, down to 120px
+boxes, and only one that still does not fit is reported. Then:
+
+- **Turn a long chain.** A left-to-right chain of five or more nodes rarely
+  fits; `direction="TB"` stacks it.
+- **Shorten a label or a formula.** A node names a step; the explanation goes
+  in the prose or the caption. A formula never wraps, so a long one sets its
+  box's width.
+- **Narrow a node.** A node's `width` makes its text wrap inside it, and its
+  height follows.
+
+_Rationale._ A diagram is a picture of how steps connect. One that scrolls
+shows only some of them at a time, and the reader has to remember the rest.
+
+_How to apply._ Build the course. Each diagram wider than its limit is a
+`dia-too-wide` warning naming the lesson file and the diagram `id`, printed by
+`astro build` (and by `astro dev` as the page renders) and listed by
+`pnpm content warnings` until the next build. A diagram meant to be read by
+scrolling — a long timeline — says `warnAboveWidth={false}`; a number in
+`warnAboveWidth` sets that one diagram's limit instead of the column.
+
+_Enforcement._ Tier-3 warning `dia-too-wide`, for every rendered diagram:
+`Diagram.astro` marks one wider than its limit, `oversizedDiagrams` in
+`src/reference/diagram-fit.ts` finds the mark on each page `astro build`
+writes, and `build/render-diagnostics.json` keeps the findings for
+`content warnings`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Build-time engine for prerequisite-aware, notation-rigorous course content: one validated content model, a semantic notation/citation/equation system with a completeness gate, and a deterministic JSON manifest.",
   "type": "module",
   "license": "UNLICENSED",
@@ -36,13 +36,17 @@
   "dependencies": {
     "@dagrejs/dagre": "3.1.1",
     "esbuild": "0.27.7",
-    "parse5": "7.3.0"
+    "mdast-util-gfm-table": "2.0.0",
+    "mdast-util-math": "3.0.0",
+    "mdast-util-to-markdown": "2.1.2",
+    "parse5": "7.3.0",
+    "remark-directive": "^4.0.0"
   },
   "peerDependencies": {
-    "@astrojs/markdown-remark": "7.2.4",
-    "@astrojs/react": "6.0.4",
-    "@astrojs/starlight": "0.41.9",
-    "astro": "7.2.7",
+    "@astrojs/markdown-remark": "7.3.1",
+    "@astrojs/react": "7.0.0",
+    "@astrojs/starlight": "0.42.4",
+    "astro": "7.3.5",
     "katex": "0.16.47",
     "react": "19.2.8",
     "react-dom": "19.2.8",
@@ -51,7 +55,8 @@
     "remark-mdx": "3.1.1"
   },
   "devDependencies": {
-    "@astrojs/markdown-remark": "7.2.4",
+    "@astrojs/markdown-remark": "7.3.1",
+    "@types/mdast": "4.0.4",
     "@types/node": "24.13.3",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.5",

package/src/compiler/astro.ts

@@ -12,7 +12,20 @@ import {
   writeManifest,
 } from './manifest';
 import { missingNotationPayloadKeys } from '../reference/page-notation';
+import { assertFigureSymbolsBound } from '../reference/figure-symbols';
+import { undrawnFigurePictures, undrawnFigureWarning } from '../reference/figure-pictures';
+import {
+  pageRenderDiagnostics,
+  type RenderDiagnostic,
+  writeRenderDiagnostics,
+} from './render-diagnostics';
 import { writeStandaloneLessonExports } from './exports/standalone-html';
+import { writeCombinedExports } from './exports/combined-html';
+import { writeLatexExports } from './exports/latex-export';
+import { writeMarkdownExports } from './exports/markdown-export';
+import { prepareChapters } from './exports/export-chapters';
+import { writeDownloadIndex } from './exports/download-index';
+import { standaloneFilename, standalonePageSlugs } from './exports/export-pages';
 import remarkAbbreviations from '../reference/remark-abbreviations.mjs';
 import remarkCitation from '../reference/remark-citation.mjs';
 import remarkNotation from '../reference/remark-notation.mjs';
@@ -26,21 +39,21 @@ function normalizedBasePath(base: string): string {
   return segment ? `/${segment}/` : '/';
 }
 
-/** Match only a configured lesson artifact below Astro's deployment base. */
+/** Match only a configured page artifact below Astro's deployment base. */
 export function matchStandaloneDownload(
   pathname: string,
   base: string,
-  lessonSlugs: readonly string[],
+  pageSlugs: readonly string[],
 ): string | undefined {
   const prefix = `${normalizedBasePath(base)}downloads/`;
   if (!pathname.startsWith(prefix) || !pathname.endsWith('.html')) return undefined;
   const slug = pathname.slice(prefix.length, -'.html'.length);
-  return lessonSlugs.includes(slug) ? slug : undefined;
+  return pageSlugs.includes(slug) ? slug : undefined;
 }
 
 async function buildDevelopmentDownloads(
   config: Pick<AstroConfig, 'root'>,
-  lessonSlugs: readonly string[],
+  pageSlugs: readonly string[],
 ): Promise<ReadonlyMap<string, Buffer>> {
   const temporaryRoot = await mkdtemp(join(tmpdir(), 'explico-standalone-'));
   const outputRoot = join(temporaryRoot, 'dist');
@@ -88,7 +101,7 @@ async function buildDevelopmentDownloads(
     });
     return new Map(
       await Promise.all(
-        lessonSlugs.map(async (slug) => [
+        pageSlugs.map(async (slug) => [
           slug,
           await readFile(join(outputRoot, 'downloads', `${slug}.html`)),
         ] as const),
@@ -99,7 +112,12 @@ async function buildDevelopmentDownloads(
   }
 }
 
-/** Fail loudly instead of rendering math triggers whose local cards are stale. */
+/**
+ * Fail loudly instead of rendering math triggers whose local cards are
+ * missing. The manifest bundles every `notation.local` entry with its page,
+ * so the two lists differ only when the manifest is older than the page, or
+ * when `validate:content` rejected an entry.
+ */
 export function assertLocalNotationParity(
   lessonId: string,
   authoredKeys: readonly string[],
@@ -114,10 +132,13 @@ export function assertLocalNotationParity(
     return;
   }
   throw new Error(
-    `Stale Explico manifest for ${lessonId}: lesson notation.local has ` +
-      `[${authored.join(', ')}], but the page notation bundle has ` +
-      `[${rendered.join(', ')}]. Pass courseConfig to loadManifest() and add ` +
-      `explicoContentRefresh() to the Astro integrations.`,
+    `Explico notation mismatch for ${lessonId}: the page's frontmatter ` +
+      `notation.local declares [${authored.join(', ')}], but the manifest's ` +
+      `notation bundle for the page holds [${rendered.join(', ')}]. The ` +
+      `manifest bundles every notation.local entry with its page, so either ` +
+      `it is stale — pass courseConfig to loadManifest() and add ` +
+      `explicoContentRefresh() to the Astro integrations — or ` +
+      `\`pnpm validate:content\` rejected an entry: fix the errors it reports.`,
   );
 }
 
@@ -220,19 +241,35 @@ export function assertRemarkPluginsWired(
   );
 }
 
-async function validateGeneratedNotationPayloads(directory: URL): Promise<void> {
+/**
+ * Check every built page, and return the findings only a rendered page gives
+ * (`render-diagnostics.ts`) for `content warnings`.
+ */
+async function validateGeneratedPages(
+  directory: URL,
+  manifest: Manifest,
+  warn: (message: string) => void,
+): Promise<RenderDiagnostic[]> {
   const root = fileURLToPath(directory);
+  const rendered: RenderDiagnostic[] = [];
   const walk = async (path: string): Promise<void> => {
     for (const entry of await readdir(path, { withFileTypes: true })) {
       const child = join(path, entry.name);
       if (entry.isDirectory()) {
         await walk(child);
       } else if (entry.isFile() && entry.name.endsWith('.html')) {
-        assertNotationPayloadHtml(relative(root, child), await readFile(child, 'utf8'));
+        const html = await readFile(child, 'utf8');
+        const page = relative(root, child);
+        assertNotationPayloadHtml(page, html);
+        assertFigureSymbolsBound(page, html);
+        const undrawn = undrawnFigurePictures(html);
+        if (undrawn.length > 0) warn(undrawnFigureWarning(page, undrawn));
+        rendered.push(...pageRenderDiagnostics(manifest, page, html));
       }
     }
   };
   await walk(root);
+  return rendered;
 }
 
 function replaceInPlace(target: unknown, source: unknown): void {
@@ -370,19 +407,19 @@ export function explicoContentRefresh(
             const slug = matchStandaloneDownload(
               pathname,
               configuredDevelopment.base,
-              manifest.lessons.map((lesson) => lesson.slug),
+              standalonePageSlugs(manifest),
             );
             if (!slug) return next();
 
             try {
               logger.info(
                 developmentDownloads
-                  ? `Serving cached standalone lesson ${slug}.html`
-                  : 'Building standalone lesson downloads for local development…',
+                  ? `Serving cached standalone page ${slug}.html`
+                  : 'Building standalone page downloads for local development…',
               );
               developmentDownloads ??= buildDevelopmentDownloads(
                 configuredDevelopment,
-                manifest.lessons.map((lesson) => lesson.slug),
+                standalonePageSlugs(manifest),
               );
               const currentDownloads = developmentDownloads;
               currentDownloads.catch(() => {
@@ -392,7 +429,7 @@ export function explicoContentRefresh(
               });
               const artifact = (await currentDownloads).get(slug);
               if (!artifact) return next();
-              const filename = `${slug.split('/').at(-1) ?? 'lesson'}.html`;
+              const filename = standaloneFilename(slug);
               response.statusCode = 200;
               response.setHeader('Content-Type', 'text/html; charset=utf-8');
               response.setHeader('Content-Length', artifact.byteLength);
@@ -404,17 +441,31 @@ export function explicoContentRefresh(
               response.end(request.method === 'HEAD' ? undefined : artifact);
             } catch (error) {
               const message = error instanceof Error ? error.message : String(error);
-              logger.error(`Could not build standalone lesson downloads: ${message}`);
+              logger.error(`Could not build standalone page downloads: ${message}`);
               response.statusCode = 500;
               response.setHeader('Content-Type', 'text/plain; charset=utf-8');
-              response.end(`Could not build standalone lesson download.\n${message}\n`);
+              response.end(`Could not build standalone page download.\n${message}\n`);
             }
           });
         }
       },
-      'astro:build:done': async ({ dir }) => {
-        await validateGeneratedNotationPayloads(dir);
+      'astro:build:done': async ({ dir, logger }) => {
+        const rendered = await validateGeneratedPages(dir, manifest, (message) =>
+          logger.warn(message),
+        );
+        for (const diagnostic of writeRenderDiagnostics(rendered)) {
+          logger.warn(`[${diagnostic.code}] ${diagnostic.file}: ${diagnostic.message}`);
+        }
         await writeStandaloneLessonExports(dir, manifest);
+        await writeCombinedExports(dir, manifest);
+        // The print exports share one reading of the chapters and one
+        // capture of their figures.
+        const { latex, markdown } = manifest.lessonExports;
+        const prepared =
+          latex || markdown ? await prepareChapters(fileURLToPath(dir), manifest, { logger }) : undefined;
+        await writeLatexExports(dir, manifest, { logger, ...(prepared ? { prepared } : {}) });
+        await writeMarkdownExports(dir, manifest, { logger, ...(prepared ? { prepared } : {}) });
+        await writeDownloadIndex(dir);
       },
     },
   };