explico 0.13.1 → 0.14.0

package/dist/compiler/exports/export-chapters.js

@@ -2,7 +2,11 @@ import { readFile } from "node:fs/promises";
 import { extname, join, resolve } from "node:path";
 import { parse } from "parse5";
 import { inferBasePrefix } from "./html-tree.js";
-import { readInlineFragment, readStaticPage } from "./static-tree.js";
+import {
+  readInlineFragment,
+  readStaticDeck,
+  readStaticPage
+} from "./static-tree.js";
 import {
   captureFigures,
   courseChromium,
@@ -17,8 +21,9 @@ function strictMode() {
   const ci = process.env.CI;
   return !!ci && ci !== "false" && ci !== "0" || process.env.EXPLICO_LATEX_STRICT === "1";
 }
-function epochOf(manifest) {
-  const date = manifest.about.knowledge.date;
+function epochOf(manifest, since) {
+  const { releases, date: newest } = manifest.about.knowledge;
+  const date = (since == null ? void 0 : (releases ?? []).find((release) => release.version === since)?.date) ?? newest;
   const parsed = date ? Date.parse(`${date}T00:00:00Z`) : Number.NaN;
   return Number.isFinite(parsed) ? Math.floor(parsed / 1e3) : 0;
 }
@@ -78,6 +83,28 @@ function withLiveClauses(page, captured, base) {
   });
   return { ...page, blocks: update(page.blocks) };
 }
+async function readBuiltDeck(outputRoot, route) {
+  const html = await readFile(join(outputRoot, route, "index.html"), "utf8");
+  return { html, page: readStaticDeck(html, route, route) };
+}
+function deckBlocks(page) {
+  return page.frames.flatMap((frame) => frame.segments.flatMap((segment) => segment.blocks));
+}
+function deckWithLiveClauses(page, captures, figureRoutes, base) {
+  const fill = (blocks) => blocks.map((block) => {
+    if (block.kind !== "figure") return block;
+    const route = figureRoutes.get(block.anchor);
+    const live = route === void 0 ? void 0 : captures.get(route)?.get(block.anchor)?.liveHtml;
+    return live ? { ...block, live: readInlineFragment(live, page.route, base) } : block;
+  });
+  return {
+    ...page,
+    frames: page.frames.map((frame) => ({
+      ...frame,
+      segments: frame.segments.map((segment) => ({ ...segment, blocks: fill(segment.blocks) }))
+    }))
+  };
+}
 async function readBuiltPage(outputRoot, slug) {
   const route = slug.replace(/(?:^|\/)index$/u, "");
   const html = await readFile(join(outputRoot, route, "index.html"), "utf8");
@@ -90,17 +117,42 @@ async function prepareChapters(outputRoot, manifest, options = {}) {
   const read = [];
   let base = "/";
   for (const lesson of manifest.lessons) {
+    if (lesson.editions && !lesson.editions.includes("chapter")) continue;
     const { html, page } = await readBuiltPage(outputRoot, lesson.slug);
     if (read.length === 0) base = inferBasePrefix(parse(html));
     read.push({ lesson, page });
   }
-  const requests = (latex || markdown ? read : []).map(({ page }) => ({
+  const decksRead = [];
+  const pictured = (blocks) => [...figuresOf(blocks), ...diagramsOf(blocks)].map((float) => float.anchor);
+  for (const deck of manifest.decks ?? []) {
+    const { html, page } = await readBuiltDeck(outputRoot, deck.slug);
+    if (read.length === 0 && decksRead.length === 0) base = inferBasePrefix(parse(html));
+    const routeOf = (anchor) => {
+      const slug = deck.recalledFrom?.[anchor] ?? deck.chapter;
+      const chapter = slug === void 0 ? void 0 : read.find((entry) => entry.lesson.slug === slug);
+      return chapter && pictured(chapter.page.blocks).includes(anchor) ? chapter.page.route : page.route;
+    };
+    const figureRoutes = new Map(pictured(deckBlocks(page)).map((anchor) => [anchor, routeOf(anchor)]));
+    decksRead.push({ deck, page, figureRoutes });
+  }
+  const requests = (latex || markdown ? read : []).map(({ lesson, page }) => ({
     route: page.route,
+    // A figure's PDF carries its chapter's date (rule C5), as the chapter does.
+    epoch: epochOf(manifest, lesson.since),
     anchors: [
       ...figuresOf(page.blocks).filter(needsCapture).map((figure) => figure.anchor),
       ...markdown ? diagramsOf(page.blocks).map((diagram) => diagram.anchor) : []
     ]
   })).filter((request) => request.anchors.length > 0);
+  if (latex || markdown) {
+    for (const { deck, page, figureRoutes } of decksRead) {
+      const anchors = [
+        ...figuresOf(deckBlocks(page)).filter(needsCapture).map((figure) => figure.anchor),
+        ...markdown ? diagramsOf(deckBlocks(page)).map((diagram) => diagram.anchor) : []
+      ].filter((anchor) => figureRoutes.get(anchor) === page.route);
+      if (anchors.length > 0) requests.push({ route: page.route, epoch: epochOf(manifest, deck.since), anchors });
+    }
+  }
   let captures = /* @__PURE__ */ new Map();
   if (requests.length > 0) {
     const chromium = await courseChromium(options.projectRoot ?? process.cwd());
@@ -145,11 +197,17 @@ async function prepareChapters(outputRoot, manifest, options = {}) {
     chapters: read.map(({ lesson, page }) => {
       const captured = captures.get(page.route);
       return { lesson, page: captured ? withLiveClauses(page, captured, base) : page };
-    })
+    }),
+    decks: decksRead.map(({ deck, page, figureRoutes }) => ({
+      deck,
+      page: deckWithLiveClauses(page, captures, figureRoutes, base),
+      figureRoutes
+    }))
   };
 }
 export {
   consoleLogger,
+  deckBlocks,
   diagramsOf,
   epochOf,
   figuresOf,
@@ -158,6 +216,7 @@ export {
   imagesOf,
   needsCapture,
   prepareChapters,
+  readBuiltDeck,
   readBuiltPage,
   strictMode,
   withLiveClauses

package/dist/compiler/exports/export-pages.d.ts

@@ -1,7 +1,7 @@
-import { Manifest } from '../manifest.js';
+import { Manifest, ManifestDeck } from '../manifest.js';
 import '../../curriculum/validation.js';
 import '../../reference/consistency.js';
-import '../../course-config-rRtME5UV.js';
+import '../../course-config-BLtIdkei.js';
 import '../../rules/catalog.js';
 import '../../rules/course-rules.js';
 import '../collections.js';
@@ -23,6 +23,10 @@ import '../../reference/mixed-content.js';
 import '../../reference/gloss.js';
 import '../../rules/waivers.js';
 import '../knowledge-version.js';
+import '../page-versions.js';
+import '../decks.js';
+import '../../reference/decks-validate.js';
+import '../../reference/deck-source.js';
 import '../lesson-derivation.js';
 
 /**
@@ -42,7 +46,30 @@ declare function standaloneFilename(slug: string): string;
  * is in its part's file and the course's (`combined-html.ts`).
  */
 declare function standalonePageSlugs(manifest: Pick<Manifest, 'lessons'>): string[];
+/**
+ * Every page with an HTML download of its own: its route (`slug`) and where
+ * it downloads below `downloads/`, without `.html` (`download`). A chapter
+ * downloads at its slug; a deck at its owner's {@link deckFileStem}, its
+ * Present mode and notes working offline.
+ */
+declare function standaloneDownloads(manifest: Pick<Manifest, 'lessons'> & Partial<Pick<Manifest, 'decks'>>): {
+    readonly slug: string;
+    readonly download: string;
+}[];
+/**
+ * Where a deck downloads below `downloads/`, by its owner's slug — a
+ * lesson's (`projectiles/projectile-range`), or a part's directory
+ * (`motion`): `projectiles/projectile-range-slides` + `.pdf` (the slides),
+ * `-notes.pdf` (each slide with its speaker notes) and `-latex.zip` (their
+ * source); a part's deck `motion-slides` + the same. A slides-first lesson's
+ * deck is named the same way as a chapter's.
+ */
+declare function deckFileStem(ownerSlug: string): string;
+/** Whose a deck is, as its downloads name it: its lesson's slug, or its part's directory. */
+declare function deckOwnerSlug(deck: Pick<ManifestDeck, 'lessonId' | 'part' | 'slug'>, manifest: Pick<Manifest, 'lessons'>): string;
+/** The name a deck's files are saved under: `projectile-range-slides`, a part's `motion-slides`. */
+declare function deckSaveName(ownerSlug: string): string;
 /** The name the course's files are saved under: `Explico Playground — Motion` → `explico-playground-motion`. */
 declare function courseFileStem(manifest: Pick<Manifest, 'about'>): string;
 
-export { courseFileStem, exportPageRoute, exportPageSlugs, standaloneFilename, standalonePageSlugs };
+export { courseFileStem, deckFileStem, deckOwnerSlug, deckSaveName, exportPageRoute, exportPageSlugs, standaloneDownloads, standaloneFilename, standalonePageSlugs };

package/dist/compiler/exports/export-pages.js

@@ -8,15 +8,38 @@ function standaloneFilename(slug) {
   return `${exportPageRoute(slug).split("/").at(-1) || "index"}.html`;
 }
 function standalonePageSlugs(manifest) {
-  return manifest.lessons.map((lesson) => lesson.slug);
+  return manifest.lessons.filter((lesson) => (lesson.editions ?? ["chapter"]).includes("chapter")).map((lesson) => lesson.slug);
+}
+function standaloneDownloads(manifest) {
+  return [
+    ...standalonePageSlugs(manifest).map((slug) => ({ slug, download: slug })),
+    ...(manifest.decks ?? []).map((deck) => ({
+      slug: deck.slug,
+      download: deckFileStem(deckOwnerSlug(deck, manifest))
+    }))
+  ];
+}
+function deckFileStem(ownerSlug) {
+  return `${ownerSlug}-slides`;
+}
+function deckOwnerSlug(deck, manifest) {
+  if (deck.part !== void 0) return deck.part;
+  return manifest.lessons.find((lesson) => lesson.id === deck.lessonId)?.slug ?? deck.slug;
+}
+function deckSaveName(ownerSlug) {
+  return `${ownerSlug.split("/").at(-1) ?? ownerSlug}-slides`;
 }
 function courseFileStem(manifest) {
   return manifest.about.material.name.normalize("NFKD").replace(/[\u0300-\u036f]/gu, "").toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "") || "course";
 }
 export {
   courseFileStem,
+  deckFileStem,
+  deckOwnerSlug,
+  deckSaveName,
   exportPageRoute,
   exportPageSlugs,
+  standaloneDownloads,
   standaloneFilename,
   standalonePageSlugs
 };

package/dist/compiler/exports/latex/beamerthemeexplico.sty

@@ -0,0 +1,124 @@
+%% beamerthemeexplico.sty — the beamer theme of an explico deck.
+%%
+%% explico writes this file next to every deck's LaTeX download
+%% (docs/authoring/deck.md), and builds the deck's PDFs from that same folder:
+%% `main.tex` (the slides) and `handout.tex` (each slide followed by its notes).
+%% Edit it freely in a download.
+%%
+%% A frame ends on its legend line, the symbols it introduces (\ExplicoLegend,
+%% which the deck file sets per frame), above a strip with the section's name
+%% and the frame's number; a thin bar under it is the deck's progress.
+%% Engines: LuaLaTeX (preferred) or pdfLaTeX, TeX Live 2025 or later.
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{beamerthemeexplico}[2026/10/10 explico deck theme]
+\DeclareOptionBeamer{scripts}{\PassOptionsToPackage{scripts}{explico-common}}
+\ProcessOptionsBeamer
+
+%% unicode-math sets the math fonts; beamer must leave them alone.
+\usefonttheme{professionalfonts}
+\RequirePackage{explico-common}
+\RequirePackage{etoolbox}
+
+\setbeamertemplate{navigation symbols}{}
+\setbeamercovered{invisible}
+\setbeamercolor{structure}{fg=explicoaccent}
+\setbeamercolor{title}{fg=explicoaccent}
+\setbeamercolor{frametitle}{fg=explicoaccent,bg=}
+\setbeamerfont{title}{size=\LARGE,series=\bfseries}
+\setbeamerfont{frametitle}{size=\Large,series=\bfseries}
+\setbeamertemplate{frametitle}{%
+  \vskip0.7em
+  {\usebeamerfont{frametitle}\usebeamercolor[fg]{frametitle}\insertframetitle\par}%
+  \vskip0.15em}
+%% A frame that breaks over several (the notation appendix): "Notation", then
+%% "Notation (continued)".
+\setbeamertemplate{frametitle continuation}[from second][(continued)]
+\setbeamercolor{block title}{fg=black,bg=explicoback!60!white}
+\setbeamercolor{block body}{fg=black,bg=explicoback}
+\setbeamercolor{block title alerted}{fg=black,bg=explicoasidecautionback!80!explicoasidecaution}
+\setbeamercolor{block body alerted}{fg=black,bg=explicoasidecautionback}
+\setbeamertemplate{blocks}[rounded]
+\setbeamertemplate{itemize items}[circle]
+\setbeamertemplate{enumerate items}[default]
+\setbeamerfont{caption}{size=\scriptsize}
+
+%% The title frame: the deck's title, its course, its authors and version.
+\setbeamertemplate{title page}{%
+  \vfill
+  {\usebeamerfont{title}\usebeamercolor[fg]{title}\inserttitle\par}%
+  \ifx\insertsubtitle\@empty\else\vskip0.6em{\large\insertsubtitle\par}\fi
+  \vskip1.2em
+  {\small\color{black!65}\insertauthor\par}%
+  \vskip0.3em
+  {\small\color{black!65}\insertdate\par}%
+  \vfill}
+
+%% A section's divider frame: its title over a rule.
+\newcommand{\ExplicoSectionPage}{%
+  \vfill
+  {\usebeamerfont{title}\usebeamercolor[fg]{title}\insertsectionhead\par}%
+  \vskip0.3em{\color{explicoaccent}\rule{0.5\linewidth}{1.5pt}}%
+  \vfill}
+
+%% The deck's own frames (deck.tex sets their count): the progress bar runs
+%% over them, and the notation appendix after them shows none.
+\def\explico@deckframes{\inserttotalframenumber}
+\newcommand{\ExplicoDeckFrames}[1]{\gdef\explico@deckframes{#1}}
+
+%% The legend line: the symbols a frame introduces. The frame's body sets it
+%% on every slide of the frame; the footline prints it and clears it.
+\gdef\explico@legend{}
+\newcommand{\ExplicoLegend}[1]{\gdef\explico@legend{#1}}
+\setbeamertemplate{footline}{%
+  \leavevmode
+  \ifx\explico@legend\@empty\else
+    \hbox to \paperwidth{\hskip1.6em\parbox[b]{\dimexpr\paperwidth-3.2em}{%
+      \raggedright\scriptsize\color{black!70}\explico@legend}}\par\vskip3pt
+  \fi
+  \global\let\explico@legend\@empty
+  \hbox to \paperwidth{\hskip1.6em{\tiny\color{black!55}\insertsectionhead}\hfill
+    {\tiny\color{black!55}\insertframenumber}\hskip1.2em}\par\vskip3pt
+  \ifnum\c@framenumber>\explico@deckframes\relax\else
+    {\color{explicoaccent}\rule{\dimexpr\paperwidth*\c@framenumber/\explico@deckframes\relax}{1.2pt}}%
+  \fi
+}
+
+%% A note page of the handout (handout.tex): the slide's number and title
+%% beside a small copy of the slide, then its speaker notes.
+\setbeamerfont{note page}{size=\small}
+\setbeamertemplate{note page}{%
+  \vskip1em
+  \hbox to \textwidth{%
+    \vtop{\hsize=\dimexpr\textwidth-0.3\paperwidth-1.5em\relax
+      \vskip0pt
+      {\usebeamercolor[fg]{frametitle}\normalsize\bfseries Slide~\insertframenumber\par}%
+      \vskip0.3em
+      {\small\raggedright\insertframetitle\par}}%
+    \hfill
+    \vtop{\vskip0pt\hbox{\setlength{\fboxsep}{0pt}\fcolorbox{black!25}{white}{\insertslideintonotes{0.3}}}}}%
+  \vskip1.2em
+  {\usebeamerfont{note page}\raggedright\insertnote\par}%
+}
+
+%% A figure's, a table's or a diagram's caption on a frame: its number (a
+%% float recalled from the chapter keeps the chapter's), its short caption in
+%% bold, then the long one.
+\newcommand{\ExplicoDeckCaption}[3]{%
+  \par\smallskip{\usebeamerfont{caption}%
+  \if\relax\detokenize{#1}\relax\else{\color{explicoaccent}\textbf{#1}}\enspace\fi
+  \if\relax\detokenize{#2}\relax\else\textbf{#2.}\space\fi#3\par}}
+
+%% A deck's references frame: the list its citations number, as on the
+%% slides. The frame's title names it, so the list has no heading of its own.
+\newenvironment{ExplicoReferences}[1]{%
+  \small
+  \list{\@biblabel{\@arabic\c@enumiv}}{%
+    \settowidth\labelwidth{\@biblabel{#1}}%
+    \leftmargin\labelwidth\advance\leftmargin\labelsep
+    \usecounter{enumiv}\let\p@enumiv\@empty
+    \renewcommand\theenumiv{\@arabic\c@enumiv}}%
+  \sloppy\raggedright
+}{\endlist}
+
+\pdfstringdefDisableCommands{\let\ExplicoGreekWord\@firstofone}
+\endinput

package/dist/compiler/exports/latex/cache.d.ts

@@ -0,0 +1,78 @@
+import { ExportLogger } from '../export-chapters.js';
+import { LatexEngine, CompiledLatex, compileLatex } from './compile.js';
+import { SourceFile } from './document.js';
+import '../../manifest.js';
+import '../../../curriculum/validation.js';
+import '../../../reference/consistency.js';
+import '../../../course-config-BLtIdkei.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';
+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 '../../page-versions.js';
+import '../../decks.js';
+import '../../../reference/decks-validate.js';
+import '../../../reference/deck-source.js';
+import '../../lesson-derivation.js';
+import '../static-tree.js';
+import '../html-tree.js';
+import 'parse5';
+import './capture.js';
+import 'node:http';
+import './serialize.js';
+
+interface CacheContext {
+    readonly engine: LatexEngine['name'];
+    /** `texFingerprint`'s description of the TeX installation. */
+    readonly fingerprint: string;
+    readonly epoch: number;
+    readonly salt: string;
+}
+/** The key of one compile: a hex SHA-256 over its context and its files in path order. */
+declare function cacheKey(files: readonly SourceFile[], context: CacheContext): string;
+interface LatexCache {
+    readonly directory: string;
+    /** The document compiled, or reused from an entry with the same key. */
+    compile(files: readonly SourceFile[], options: {
+        readonly epoch: number;
+        readonly name?: string;
+    }): Promise<{
+        readonly result: CompiledLatex;
+        readonly reused: boolean;
+    }>;
+    /** Delete the entries no build has used for `KEEP_DAYS`; how many went. */
+    prune(now?: Date): Promise<number>;
+}
+declare function openLatexCache(options: {
+    readonly directory: string;
+    readonly engine: LatexEngine;
+    readonly fingerprint: string;
+    readonly salt?: string;
+    readonly logger?: ExportLogger;
+    /** The compile behind a miss; `compileLatex` but in tests. */
+    readonly compile?: typeof compileLatex;
+}): LatexCache;
+/**
+ * The cache `EXPLICO_LATEX_CACHE` names, or `undefined` when it is unset
+ * (today's build: every document compiles) or the directory cannot be made.
+ */
+declare function latexCacheFromEnvironment(engine: LatexEngine, logger: ExportLogger): Promise<LatexCache | undefined>;
+
+export { type CacheContext, type LatexCache, cacheKey, latexCacheFromEnvironment, openLatexCache };

package/dist/compiler/exports/latex/cache.js

@@ -0,0 +1,129 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, readFile, readdir, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { compileLatex, texFingerprint } from "./compile.js";
+const FORMAT = "explico-latex-cache 1";
+const KEEP_DAYS = 7;
+const ENTRY = /^[0-9a-f]{64}$/u;
+function cacheKey(files, context) {
+  const hash = createHash("sha256");
+  for (const line of [FORMAT, context.engine, context.fingerprint, String(context.epoch), context.salt]) {
+    hash.update(`${line.length}:${line}
+`);
+  }
+  for (const file of [...files].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) {
+    const content = typeof file.content === "string" ? Buffer.from(file.content, "utf8") : file.content;
+    hash.update(`${Buffer.byteLength(file.path)}:${file.path}
+${content.byteLength}
+`);
+    hash.update(content);
+  }
+  return hash.digest("hex");
+}
+function encodeEntry(result) {
+  const parts = [result.pdf, Buffer.from(result.aux, "utf8"), Buffer.from(result.log, "utf8")];
+  const payload = Buffer.concat(parts);
+  const header = {
+    pdf: parts[0].byteLength,
+    aux: parts[1].byteLength,
+    log: parts[2].byteLength,
+    sha256: createHash("sha256").update(payload).digest("hex")
+  };
+  return Buffer.concat([Buffer.from(`${FORMAT}
+${JSON.stringify(header)}
+`, "utf8"), payload]);
+}
+function decodeEntry(bytes) {
+  const formatEnd = bytes.indexOf(10);
+  const headerEnd = formatEnd < 0 ? -1 : bytes.indexOf(10, formatEnd + 1);
+  if (headerEnd < 0 || bytes.subarray(0, formatEnd).toString("utf8") !== FORMAT) return void 0;
+  let header;
+  try {
+    header = JSON.parse(bytes.subarray(formatEnd + 1, headerEnd).toString("utf8"));
+  } catch {
+    return void 0;
+  }
+  const { pdf, aux, log, sha256 } = header;
+  if (typeof pdf !== "number" || typeof aux !== "number" || typeof log !== "number") return void 0;
+  const payload = bytes.subarray(headerEnd + 1);
+  if (payload.byteLength !== pdf + aux + log) return void 0;
+  if (createHash("sha256").update(payload).digest("hex") !== sha256) return void 0;
+  return {
+    pdf: Buffer.from(payload.subarray(0, pdf)),
+    aux: payload.subarray(pdf, pdf + aux).toString("utf8"),
+    log: payload.subarray(pdf + aux).toString("utf8")
+  };
+}
+function openLatexCache(options) {
+  const { directory, engine, fingerprint } = options;
+  const compile = options.compile ?? compileLatex;
+  let warned = false;
+  const warnOnce = (message) => {
+    if (warned) return;
+    warned = true;
+    options.logger?.warn(message);
+  };
+  return {
+    directory,
+    async compile(files, compileOptions) {
+      const key = cacheKey(files, { engine: engine.name, fingerprint, epoch: compileOptions.epoch, salt: options.salt ?? "" });
+      const path = join(directory, key);
+      const cached = await readFile(path).then(decodeEntry, () => void 0);
+      if (cached) {
+        const now = /* @__PURE__ */ new Date();
+        await utimes(path, now, now).catch(() => void 0);
+        return { result: cached, reused: true };
+      }
+      const result = await compile(files, engine, compileOptions);
+      const temporary = `${path}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+      try {
+        await writeFile(temporary, encodeEntry(result));
+        await rename(temporary, path);
+      } catch (error) {
+        await rm(temporary, { force: true });
+        warnOnce(
+          `LaTeX export: could not store a compile in ${directory} (${error instanceof Error ? error.message : String(error)}); the build goes on without it.`
+        );
+      }
+      return { result, reused: false };
+    },
+    async prune(now = /* @__PURE__ */ new Date()) {
+      const cutoff = now.getTime() - KEEP_DAYS * 24 * 60 * 60 * 1e3;
+      let removed = 0;
+      for (const name of await readdir(directory).catch(() => [])) {
+        if (!ENTRY.test(name) && !/^[0-9a-f]{64}\.tmp-/u.test(name)) continue;
+        const path = join(directory, name);
+        const modified = await stat(path).then((entry) => entry.mtimeMs, () => void 0);
+        if (modified === void 0 || modified >= cutoff) continue;
+        await rm(path, { force: true });
+        removed += 1;
+      }
+      return removed;
+    }
+  };
+}
+async function latexCacheFromEnvironment(engine, logger) {
+  const setting = process.env.EXPLICO_LATEX_CACHE?.trim();
+  if (!setting) return void 0;
+  const directory = resolve(setting);
+  try {
+    await mkdir(directory, { recursive: true });
+  } catch (error) {
+    logger.warn(
+      `LaTeX export: EXPLICO_LATEX_CACHE names ${directory}, which cannot be made (${error instanceof Error ? error.message : String(error)}); every document compiles.`
+    );
+    return void 0;
+  }
+  return openLatexCache({
+    directory,
+    engine,
+    fingerprint: await texFingerprint(engine),
+    salt: process.env.EXPLICO_LATEX_CACHE_SALT ?? "",
+    logger
+  });
+}
+export {
+  cacheKey,
+  latexCacheFromEnvironment,
+  openLatexCache
+};

package/dist/compiler/exports/latex/capture.d.ts

@@ -1,3 +1,5 @@
+import { Server } from 'node:http';
+
 /**
  * The capture pass: draw each figure a browser has to draw (a hydrated lab, a
  * course component's SVG) and print it as a vector PDF for the LaTeX source.
@@ -24,6 +26,8 @@ interface CaptureRequest {
     readonly route: string;
     /** Anchor ids of the figures and diagrams to capture (`fig-…`, `dia-…`). */
     readonly anchors: readonly string[];
+    /** This page's date for its figure PDFs, over the capture's `epoch`. */
+    readonly epoch?: number;
 }
 interface CapturedFigure {
     /** The figure's picture as a one-page vector PDF. */
@@ -67,6 +71,11 @@ interface PageLike {
 }
 /** Playwright's Chromium from the course's own dependencies, or `undefined`. */
 declare function courseChromium(projectRoot: string): Promise<ChromiumLike | undefined>;
+/** Serve `root` on loopback at `base`; resolves with the origin once listening. */
+declare function serve(root: string, base: string): Promise<{
+    origin: string;
+    server: Server;
+}>;
 /** The size a figure's most common label prints at, as `\footnotesize` in the book's 11 pt. */
 declare const LABEL_PT = 9;
 /** The book's measure, in PostScript points: the most a figure is set at. */
@@ -103,4 +112,4 @@ interface CaptureOptions {
 /** Capture every requested figure, one browser for the whole build. */
 declare function captureFigures(requests: readonly CaptureRequest[], options: CaptureOptions): Promise<CaptureResults>;
 
-export { type CaptureOptions, type CaptureRequest, type CaptureResults, type CapturedFigure, type FigureMeasure, LABEL_PT, captureFigures, courseChromium, figureMeasure, stampPdfDates };
+export { type CaptureOptions, type CaptureRequest, type CaptureResults, type CapturedFigure, type FigureMeasure, LABEL_PT, captureFigures, courseChromium, figureMeasure, serve, stampPdfDates };

package/dist/compiler/exports/latex/capture.js

@@ -408,7 +408,8 @@ async function captureFigures(requests, options) {
             options.measure ?? figureMeasure("letter"),
             options.png ?? false
           );
-          const pdf = options.epoch === void 0 ? printed.pdf : stampPdfDates(printed.pdf, options.epoch);
+          const epoch = request.epoch ?? options.epoch;
+          const pdf = epoch === void 0 ? printed.pdf : stampPdfDates(printed.pdf, epoch);
           figures.set(anchor, { ...printed, pdf, liveHtml: snapshot.live });
         }
         results.set(request.route, figures);
@@ -431,5 +432,6 @@ export {
   captureFigures,
   courseChromium,
   figureMeasure,
+  serve,
   stampPdfDates
 };

package/dist/compiler/exports/latex/compile.d.ts

@@ -2,7 +2,7 @@ import { SourceFile } from './document.js';
 import '../../manifest.js';
 import '../../../curriculum/validation.js';
 import '../../../reference/consistency.js';
-import '../../../course-config-rRtME5UV.js';
+import '../../../course-config-BLtIdkei.js';
 import '../../../rules/catalog.js';
 import '../../../rules/course-rules.js';
 import '../../collections.js';
@@ -24,6 +24,10 @@ import '../../../reference/mixed-content.js';
 import '../../../reference/gloss.js';
 import '../../../rules/waivers.js';
 import '../../knowledge-version.js';
+import '../../page-versions.js';
+import '../../decks.js';
+import '../../../reference/decks-validate.js';
+import '../../../reference/deck-source.js';
 import '../../lesson-derivation.js';
 import '../static-tree.js';
 import '../html-tree.js';
@@ -53,6 +57,13 @@ interface CompiledLatex {
 declare function findLatexEngine(): Promise<LatexEngine | {
     readonly missing: string;
 }>;
+/**
+ * What the compile cache knows of the TeX installation: the engine's and
+ * latexmk's banners and the LaTeX kernel's date and patch level. A TeX Live
+ * release or a kernel update changes it; a package updated with `tlmgr` does
+ * not, which is what `EXPLICO_LATEX_CACHE_SALT` is for.
+ */
+declare function texFingerprint(engine: LatexEngine): Promise<string>;
 /**
  * The characters a compile could not draw, in first-seen order: LuaLaTeX
  * leaves a blank where the font has no glyph and only logs `Missing
@@ -70,4 +81,4 @@ declare function compileLatex(files: readonly SourceFile[], engine: LatexEngine,
     readonly name?: string;
 }): Promise<CompiledLatex>;
 
-export { type CompiledLatex, type LatexEngine, compileLatex, findLatexEngine, missingCharacters };
+export { type CompiledLatex, type LatexEngine, compileLatex, findLatexEngine, missingCharacters, texFingerprint };

package/dist/compiler/exports/latex/compile.js

@@ -42,6 +42,16 @@ async function findLatexEngine() {
   }
   return requested === "lualatex" ? { name: "lualatex", latexmkOption: "-lualatex" } : { name: "pdflatex", latexmkOption: "-pdf" };
 }
+async function texFingerprint(engine) {
+  const firstLine = (output, pattern) => output.split("\n").find((line) => pattern.test(line))?.trim() ?? "";
+  const banner = firstLine((await run(engine.name, ["--version"])).output, /\S/u);
+  const latexmk = firstLine((await run("latexmk", ["-v"])).output, /Version/u);
+  const kernelFile = (await run("kpsewhich", ["latex.ltx"])).output.trim();
+  const kernel = kernelFile ? await readFile(kernelFile, "utf8").catch(() => "") : "";
+  const date = /\\edef\\fmtversion\s*\{([^}]*)\}/u.exec(kernel)?.[1] ?? "";
+  const patch = /\\def\\patch@level\{([^}]*)\}/u.exec(kernel)?.[1] ?? "";
+  return [banner, latexmk, `LaTeX2e ${date} patch level ${patch}`].join("\n");
+}
 function latexErrors(log) {
   const lines = log.split("\n");
   const found = [];
@@ -111,5 +121,6 @@ async function compileLatex(files, engine, options = {}) {
 export {
   compileLatex,
   findLatexEngine,
-  missingCharacters
+  missingCharacters,
+  texFingerprint
 };