explico 0.12.0 → 0.13.0

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`.
@@ -128,7 +130,10 @@ An interactive figure is a React island, hydrated `client:visible` (or
   `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
@@ -166,11 +171,20 @@ An interactive figure is a React island, hydrated `client:visible` (or
   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.
@@ -198,9 +212,14 @@ 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. `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.
+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.
 
@@ -364,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.12.0",
+  "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

@@ -13,7 +13,19 @@ import {
 } 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';
@@ -27,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');
@@ -89,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),
@@ -229,8 +241,17 @@ 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);
@@ -238,12 +259,17 @@ async function validateGeneratedNotationPayloads(directory: URL): Promise<void>
         await walk(child);
       } else if (entry.isFile() && entry.name.endsWith('.html')) {
         const html = await readFile(child, 'utf8');
-        assertNotationPayloadHtml(relative(root, child), html);
-        assertFigureSymbolsBound(relative(root, child), html);
+        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 {
@@ -381,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(() => {
@@ -403,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);
@@ -415,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);
       },
     },
   };