explico 0.11.1 → 0.13.0

package/README.md

@@ -22,7 +22,7 @@ What it gives a course:
   per glyph per page, enforced corpus-wide. Named operators get the same
   treatment one tier softer: a lesson's `\operatorname{Var}` is a warning
   (`operator-explained`) until it carries an entry or the course lists it in
-  `operators.allow`; a shipped baseline (`\exp`, `\int`, trig, …) is exempt.
+  `rules.N8.allow`; a shipped baseline (`\exp`, `\int`, trig, …) is exempt.
 - **Inline citations** — `[@source-id; locator]` → numbered marker + generated
   reference list, resolved against a schema-checked source collection.
 - **Equation identity** — `\label{eq:key}` gives a display equation a stable
@@ -187,8 +187,8 @@ or, without one, the numbers and short captions of the floats inside
 
 ### Lesson exports
 
-A course can opt into a self-contained HTML download and browser-native printing
-for each lesson:
+A course can opt into self-contained HTML downloads of each chapter, each part
+and the whole course, and browser-native printing of every page:
 
 ```ts
 export const courseConfig: CourseConfig = {
@@ -202,18 +202,36 @@ export const courseConfig: CourseConfig = {
 ```
 
 The existing `explicoContentRefresh(courseConfig, manifest)` integration emits
-`downloads/<lesson-slug>.html` after Astro's static build and adds a download
-control to the top-right header cluster on each lesson. During `astro dev`, the
-first download request runs an isolated static build and streams the resulting
-file; later requests use that result until a watched source file changes. The
-downloaded file contains its CSS,
+`downloads/<docs-slug>.html` for each chapter after Astro's static build, and
+adds a Download button to the top-right header cluster on each page. It opens a
+menu of the scopes that contain the page — "This chapter" on a chapter, "This
+part" on a chapter or its part's page, "Whole course" everywhere — with their
+sizes, read from `downloads/index.json`, which the build writes last. A page
+that is not a chapter (the landing page, a part's page, the glossary) has no
+file of its own: it is in its part's file and the course's. The Print button
+sits beside the menu, and Ctrl+P / Cmd+P run the same print preparation.
+During `astro dev`, the first request for a chapter's file runs an isolated
+static build and streams the resulting file; later requests use that result
+until a watched source file changes. The downloaded file contains its CSS,
 KaTeX fonts, images, client scripts, Astro island components, and renderer; it
 opens directly through `file://` without a server or network access. Search,
 sidebars, pagination, and other site chrome are omitted. Same-page references
-stay local, while links that leave the lesson use `canonicalBaseUrl` and
+stay local, while links that leave the page use `canonicalBaseUrl` and
 cross-lesson hover previews degrade to ordinary links. A retained theme control
 lets an offline reader choose Light, Dark, or Auto; Auto follows changes to the
-viewer’s system color scheme.
+viewer’s system color scheme. Ctrl+P and Cmd+P load the file's labs before the
+print dialog, as on the site.
+
+Each part and the whole course also download as one offline file:
+`downloads/part/<dir>.html` is the part's page and then its chapters, and
+`downloads/course.html` is the landing page, the curriculum map, the figures and
+tables, every part, and the glossary last, each opening with a list of
+contents. They are assembled from the pages the build wrote, so each page keeps
+its own cards, labs and checks. Every id gains the page as a suffix
+(`eq-range--projectiles-projectile-range`), and a reference to another page in
+the same file becomes a link into it, whose hover preview works offline. Each
+page is a section with `content-visibility: auto`, which keeps a long course
+responsive, and starts a new sheet when printed.
 
 The **Print / save as PDF** action calls the browser's native print dialog; it
 does not download or build a `.pdf` file itself. The print layout removes site
@@ -227,12 +245,72 @@ visual result, and keeps linked text clickable with canonical destinations.
 Paper size, margins, browser-added headers/footers, final filename, and the
 choice to save as PDF remain browser and reader settings.
 
-Set `canonicalBaseUrl` to the deployed course root whenever retained lesson
-content links elsewhere in the course. If such a link exists without the base,
-the build fails rather than shipping a dead local link. An unresolved or remote
+Set `canonicalBaseUrl` to the deployed course root whenever retained page
+content links elsewhere in the course. With `standaloneHtml` on that is
+practically always: a chapter links to the glossary and to other chapters. If such a link exists without the base, the build fails rather than
+shipping a dead local link. An unresolved or remote
 stylesheet, script, font, image, iframe, media source, worker, WASM file, or CSS
 URL likewise fails the standalone export audit.
 
+#### Markdown
+
+`markdown: true` writes each chapter, each part and the whole course as
+Markdown after Astro's static build: `downloads/<slug>-markdown.zip`
+(`lesson.md` and its `assets/`), `downloads/part/<dir>-markdown.zip` and
+`downloads/course-markdown.zip` (an `index.md`, one file per chapter, shared
+`assets/`, relative links). It is GitHub's flavour with `$…$` math, so GitHub,
+Obsidian or remark-math with KaTeX shows it as written. Headings, equations and
+floats keep their numbers; each chapter ends with its references, its notation
+and the answers to its checks. A figure the browser draws is a PNG at 2× (it
+needs Playwright with Chromium, as LaTeX does); a `<Diagram>` is a PNG with its
+boxes and arrows listed as text.
+
+#### LaTeX source and PDF
+
+`latex: true` adds two downloads per chapter, both built after Astro's static
+build:
+
+- `downloads/<slug>-latex.zip` — the chapter's LaTeX folder: `main.tex`,
+  explico's book class `explico.cls`, the chapter as readable source, its
+  figures, a `latexmkrc` and a README. Unzip it and run `latexmk`.
+- `downloads/<slug>.pdf` — that same folder compiled: a tagged PDF 2.0
+  (PDF/UA-2) with the chapter's answer key at its end.
+- `downloads/part/<dir>-latex.zip` and `.pdf`, `downloads/course-latex.zip`
+  and `.pdf` — each part and the whole course as a book: title page,
+  contents, lists of figures, tables and diagrams, each part opening with its
+  page's text, its chapters, and notation and abbreviation appendices.
+
+Every document compiles at once, up to one per core.
+
+Numbers are LaTeX's own (`\label`, `\ref`), set up to count the way the website
+does; the build compiles the source unchanged and fails if any number differs
+from the website's. Figures stay vector: a lab is captured from the finished
+site by Chromium, and a `<Diagram>` is drawn as TikZ from its build-time
+layout. `latexPaper` is `letter` (default) or `a4`.
+
+Prose in another script reaches the PDF too. A Greek letter on its own is a
+symbol and is set as math; a Greek word, Cyrillic, Chinese, Japanese, Korean
+and emoji come from fallback fonts under LuaLaTeX, the first the build machine
+has of CMU Serif (TeX Live's `cm-unicode`), Noto Serif or DejaVu Serif for
+Greek and Cyrillic, Noto CJK or Fandol, and Noto Color Emoji. A character no
+font sets stays blank, and the build warns with its name; under pdfLaTeX, which
+has none of these fonts, every such character does.
+
+The build needs TeX Live 2025 or later with `latexmk` and LuaLaTeX
+(`EXPLICO_LATEX_ENGINE=pdflatex` switches to pdfLaTeX), and Playwright with
+Chromium in the course for figures a browser draws. In CI (`CI` set) a missing
+engine or browser fails the build; on a machine without them the build warns
+and still writes the source zips. On GitHub Actions:
+
+```yaml
+- uses: zauguin/install-texlive@v4
+  with:
+    texlive_version: 2026
+    package_file: node_modules/explico/src/compiler/exports/latex/texlive-packages.txt
+- run: pnpm exec playwright install --with-deps chromium
+- run: pnpm build
+```
+
 ```jsonc
 // package.json — the read-side CLI
 "scripts": { "validate:content": "tsx scripts/compile-manifest.ts" }

package/dist/compiler/astro.d.ts

@@ -1,5 +1,5 @@
 import { AstroConfig, AstroIntegration } from 'astro';
-import { C as CourseConfig } from '../course-config-Dsnri9Tk.js';
+import { C as CourseConfig } from '../course-config-rRtME5UV.js';
 import { Manifest } from './manifest.js';
 import '../rules/catalog.js';
 import '../rules/course-rules.js';
@@ -7,6 +7,7 @@ import '../curriculum/validation.js';
 import '../reference/consistency.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';
@@ -17,6 +18,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';
@@ -24,9 +26,14 @@ import '../rules/waivers.js';
 import './knowledge-version.js';
 import './lesson-derivation.js';
 
-/** Match only a configured lesson artifact below Astro's deployment base. */
-declare function matchStandaloneDownload(pathname: string, base: string, lessonSlugs: readonly string[]): string | undefined;
-/** Fail loudly instead of rendering math triggers whose local cards are stale. */
+/** Match only a configured page artifact below Astro's deployment base. */
+declare function matchStandaloneDownload(pathname: string, base: string, pageSlugs: readonly string[]): string | undefined;
+/**
+ * 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.
+ */
 declare function assertLocalNotationParity(lessonId: string, authoredKeys: readonly string[], renderedKeys: readonly string[]): void;
 /** Fail an Astro build if final rendered HTML contains an unusable trigger. */
 declare function assertNotationPayloadHtml(page: string, html: string): void;

package/dist/compiler/astro.js

@@ -8,7 +8,19 @@ import {
   writeManifest
 } from "./manifest.js";
 import { missingNotationPayloadKeys } from "../reference/page-notation.js";
+import { assertFigureSymbolsBound } from "../reference/figure-symbols.js";
+import { undrawnFigurePictures, undrawnFigureWarning } from "../reference/figure-pictures.js";
+import {
+  pageRenderDiagnostics,
+  writeRenderDiagnostics
+} from "./render-diagnostics.js";
 import { writeStandaloneLessonExports } from "./exports/standalone-html.js";
+import { writeCombinedExports } from "./exports/combined-html.js";
+import { writeLatexExports } from "./exports/latex-export.js";
+import { writeMarkdownExports } from "./exports/markdown-export.js";
+import { prepareChapters } from "./exports/export-chapters.js";
+import { writeDownloadIndex } from "./exports/download-index.js";
+import { standaloneFilename, standalonePageSlugs } from "./exports/export-pages.js";
 import remarkAbbreviations from "../reference/remark-abbreviations.mjs";
 import remarkCitation from "../reference/remark-citation.mjs";
 import remarkNotation from "../reference/remark-notation.mjs";
@@ -17,13 +29,13 @@ function normalizedBasePath(base) {
   const segment = base.replace(/^\/+|\/+$/gu, "");
   return segment ? `/${segment}/` : "/";
 }
-function matchStandaloneDownload(pathname, base, lessonSlugs) {
+function matchStandaloneDownload(pathname, base, pageSlugs) {
   const prefix = `${normalizedBasePath(base)}downloads/`;
   if (!pathname.startsWith(prefix) || !pathname.endsWith(".html")) return void 0;
   const slug = pathname.slice(prefix.length, -".html".length);
-  return lessonSlugs.includes(slug) ? slug : void 0;
+  return pageSlugs.includes(slug) ? slug : void 0;
 }
-async function buildDevelopmentDownloads(config, lessonSlugs) {
+async function buildDevelopmentDownloads(config, pageSlugs) {
   const temporaryRoot = await mkdtemp(join(tmpdir(), "explico-standalone-"));
   const outputRoot = join(temporaryRoot, "dist");
   try {
@@ -70,7 +82,7 @@ ${diagnostic.trim()}` : "")
     });
     return new Map(
       await Promise.all(
-        lessonSlugs.map(async (slug) => [
+        pageSlugs.map(async (slug) => [
           slug,
           await readFile(join(outputRoot, "downloads", `${slug}.html`))
         ])
@@ -87,7 +99,7 @@ function assertLocalNotationParity(lessonId, authoredKeys, renderedKeys) {
     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 \u2014 pass courseConfig to loadManifest() and add explicoContentRefresh() to the Astro integrations \u2014 or \`pnpm validate:content\` rejected an entry: fix the errors it reports.`
   );
 }
 function assertNotationPayloadHtml(page, html) {
@@ -131,19 +143,27 @@ function assertRemarkPluginsWired(manifest, markdown) {
 ${missing.map((line) => `  - ${line}`).join("\n")}`
   );
 }
-async function validateGeneratedNotationPayloads(directory) {
+async function validateGeneratedPages(directory, manifest, warn) {
   const root = fileURLToPath(directory);
+  const rendered = [];
   const walk = async (path) => {
     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, source) {
   if (Array.isArray(target) && Array.isArray(source)) {
@@ -240,16 +260,16 @@ function explicoContentRefresh(courseConfig, manifest) {
             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\u2026"
+                developmentDownloads ? `Serving cached standalone page ${slug}.html` : "Building standalone page downloads for local development\u2026"
               );
               developmentDownloads ??= buildDevelopmentDownloads(
                 configuredDevelopment,
-                manifest.lessons.map((lesson) => lesson.slug)
+                standalonePageSlugs(manifest)
               );
               const currentDownloads = developmentDownloads;
               currentDownloads.catch(() => {
@@ -259,7 +279,7 @@ function explicoContentRefresh(courseConfig, manifest) {
               });
               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);
@@ -271,19 +291,32 @@ function explicoContentRefresh(courseConfig, manifest) {
               response.end(request.method === "HEAD" ? void 0 : 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.
+              response.end(`Could not build standalone page download.
 ${message}
 `);
             }
           });
         }
       },
-      "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);
+        const { latex, markdown } = manifest.lessonExports;
+        const prepared = latex || markdown ? await prepareChapters(fileURLToPath(dir), manifest, { logger }) : void 0;
+        await writeLatexExports(dir, manifest, { logger, ...prepared ? { prepared } : {} });
+        await writeMarkdownExports(dir, manifest, { logger, ...prepared ? { prepared } : {} });
+        await writeDownloadIndex(dir);
       }
     }
   };

package/dist/compiler/cli.d.ts

@@ -1,13 +1,15 @@
 import { DiagnosticSeverity } from '../reference/types.js';
 import { EquationLink } from '../reference/gate-math.js';
 import { Manifest, ManifestLesson } from './manifest.js';
+import { RenderDiagnostic } from './render-diagnostics.js';
 import { RulesFilter, RuleInEffect } from '../rules/in-effect.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/gate-retired-keys.js';
 import '../reference/lint-ignore.js';
 import '../reference/equations-validate.js';
 import '../reference/tables-validate.js';
@@ -18,6 +20,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/mixed-content.js';
 import '../reference/gloss.js';
 import '../rules/waivers.js';
@@ -51,6 +54,9 @@ import './lesson-derivation.js';
  *     on any renderability error (unparseable MDX, KaTeX error, unresolved
  *     notation, unknown `[[key]]`, unknown citation), on top of the manifest's
  *     schema / ref / math / equation diagnostics for that lesson.
+ *   - Beside the manifest's diagnostics, every command lists what the last
+ *     `astro build` found on the rendered pages (`render-diagnostics.ts`),
+ *     under the `render:` source.
  */
 
 type ContentCliCode = 'unknown-command' | 'usage' | 'unknown-lesson' | 'unknown-kind' | 'invalid-id' | 'exists' | 'not-a-lesson' | 'no-git';
@@ -87,7 +93,7 @@ interface CliDiagnostic {
  * when their message mentions the lesson; per-file checks (notation, math,
  * equations, consistency) are filtered by `file`.
  */
-declare function lessonDiagnostics(manifest: Manifest, lesson: ManifestLesson): CliDiagnostic[];
+declare function lessonDiagnostics(manifest: Manifest, lesson: ManifestLesson, rendered?: readonly RenderDiagnostic[]): CliDiagnostic[];
 interface RenderResult {
     readonly rendered: boolean;
     readonly diagnostics: readonly CliDiagnostic[];
@@ -117,6 +123,15 @@ interface TokenCounts {
 /** Normalize `foundations/discount-factors` or the dotted id to the dotted id. */
 declare function normalizeLessonId(raw: string): string;
 declare function findLesson(manifest: Manifest, rawId: string): ManifestLesson;
+/**
+ * A lesson file's frontmatter and its body for rendering: the frontmatter is
+ * blanked with spaces, as Astro's MDX plugin does, so line N of the body is
+ * line N of the file and a render error points where the build's would.
+ */
+declare function lessonSource(text: string): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};
 interface DomainFileSignatures {
     readonly file: string;
     readonly signatures: readonly string[];
@@ -137,10 +152,6 @@ interface StatusReport {
         readonly keyedDiagrams: number;
         readonly keyedExamples: number;
     };
-    readonly draftDebt: {
-        readonly lessons: readonly string[];
-        readonly notation: readonly string[];
-    };
     readonly orphans: readonly CliDiagnostic[];
     readonly diagnostics: {
         readonly errors: number;
@@ -148,7 +159,7 @@ interface StatusReport {
         readonly infos: number;
     };
 }
-declare function contentStatus(manifest: Manifest): StatusReport;
+declare function contentStatus(manifest: Manifest, rendered?: readonly RenderDiagnostic[]): StatusReport;
 type DiagnosticThreshold = DiagnosticSeverity;
 interface DiagnosticsReport {
     readonly minimumSeverity: DiagnosticThreshold;
@@ -159,10 +170,13 @@ interface WarningsReport {
     readonly count: number;
     readonly warnings: readonly CliDiagnostic[];
 }
-/** Manifest diagnostics at or above a severity, normalized for tooling. */
-declare function contentDiagnostics(manifest: Manifest, minimumSeverity?: DiagnosticThreshold): DiagnosticsReport;
+/**
+ * Manifest diagnostics at or above a severity, and those the last
+ * `astro build` found on rendered pages, normalized for tooling.
+ */
+declare function contentDiagnostics(manifest: Manifest, minimumSeverity?: DiagnosticThreshold, rendered?: readonly RenderDiagnostic[]): DiagnosticsReport;
 /** Every warning exactly; errors and informational advice are excluded. */
-declare function contentWarnings(manifest: Manifest): WarningsReport;
+declare function contentWarnings(manifest: Manifest, rendered?: readonly RenderDiagnostic[]): WarningsReport;
 interface RulesReport {
     readonly filter: RulesFilter;
     readonly count: number;
@@ -187,7 +201,6 @@ interface ContextReport {
         readonly file: string;
         readonly title: string;
         readonly description: string;
-        readonly status: string;
         readonly teaches: readonly string[];
         readonly requires: readonly string[];
         readonly assumptions: readonly string[];
@@ -271,6 +284,8 @@ interface CheckReport {
 declare function changedLessonIds(): string[];
 declare function contentCheck(manifest: Manifest, options: {
     lesson?: string;
+    /** Several lessons, each checked; `lesson` is the one-lesson form. */
+    lessons?: readonly string[];
     changed?: boolean;
 }): Promise<CheckReport>;
 interface Scaffold {
@@ -286,4 +301,4 @@ interface Scaffold {
 declare function scaffoldLesson(rawId: string): Scaffold;
 declare function scaffoldTerm(rawKey: string): Scaffold;
 
-export { type CheckLessonResult, type CheckReport, type CliDiagnostic, type ContentCliCode, ContentCliError, type ContextReport, type DiagnosticThreshold, type DiagnosticsReport, type DomainFileSignatures, type RenderResult, type RulesReport, type Scaffold, type StatusReport, type TokenCounts, type WarningsReport, changedLessonIds, contentCheck, contentContext, contentDiagnostics, contentRules, contentStatus, contentWarnings, estimateTokens, findLesson, lessonDiagnostics, normalizeLessonId, parseRulesFilter, renderLesson, scaffoldLesson, scaffoldTerm };
+export { type CheckLessonResult, type CheckReport, type CliDiagnostic, type ContentCliCode, ContentCliError, type ContextReport, type DiagnosticThreshold, type DiagnosticsReport, type DomainFileSignatures, type RenderResult, type RulesReport, type Scaffold, type StatusReport, type TokenCounts, type WarningsReport, changedLessonIds, contentCheck, contentContext, contentDiagnostics, contentRules, contentStatus, contentWarnings, estimateTokens, findLesson, lessonDiagnostics, lessonSource, normalizeLessonId, parseRulesFilter, renderLesson, scaffoldLesson, scaffoldTerm };