explico 0.13.0 → 0.14.0

package/src/compiler/exports/export-chapters.ts

@@ -2,9 +2,16 @@ import { readFile } from 'node:fs/promises';
 import { extname, join, resolve } from 'node:path';
 import { parse } from 'parse5';
 
-import type { Manifest, ManifestLesson } from '../manifest';
+import type { Manifest, ManifestDeck, ManifestLesson } from '../manifest';
 import { inferBasePrefix } from './html-tree';
-import { readInlineFragment, readStaticPage, type Block, type StaticPage } from './static-tree';
+import {
+  readInlineFragment,
+  readStaticDeck,
+  readStaticPage,
+  type Block,
+  type StaticDeck,
+  type StaticPage,
+} from './static-tree';
 import {
   captureFigures,
   courseChromium,
@@ -37,9 +44,15 @@ export function strictMode(): boolean {
   return (!!ci && ci !== 'false' && ci !== '0') || process.env.EXPLICO_LATEX_STRICT === '1';
 }
 
-/** The content date as seconds since 1970: every export's timestamps. */
-export function epochOf(manifest: Pick<Manifest, 'about'>): number {
-  const date = manifest.about.knowledge.date;
+/**
+ * A document's date as seconds since 1970, for its timestamps: the date of
+ * the release its content last changed in (`since`, rule C5), so a document
+ * keeps its date across the releases that did not touch it; the newest
+ * release's date for a change not yet released, and with no `since`.
+ */
+export function epochOf(manifest: Pick<Manifest, 'about'>, since?: string | null): number {
+  const { releases, date: newest } = manifest.about.knowledge;
+  const date = (since == null ? undefined : (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 / 1000) : 0;
 }
@@ -130,14 +143,63 @@ export interface PreparedChapter {
   readonly page: StaticPage;
 }
 
+/** A lesson's deck, read from its page (docs/authoring/deck.md). */
+export interface PreparedDeck {
+  readonly deck: ManifestDeck;
+  /** Its frames, each lab's live caption clause filled in. */
+  readonly page: StaticDeck;
+  /**
+   * Where each of its figures and diagrams was drawn, by anchor: the deck's
+   * own route, or its chapter's for one it recalls (the chapter's capture is
+   * reused).
+   */
+  readonly figureRoutes: ReadonlyMap<string, string>;
+}
+
 export interface PreparedChapters {
   /** The site's base path, `/` or `/course/`. */
   readonly base: string;
   readonly chapters: readonly PreparedChapter[];
+  /** Each lesson's deck. */
+  readonly decks: readonly PreparedDeck[];
   /** What the capture pass drew, by route and anchor. */
   readonly captures: CaptureResults;
 }
 
+/** Read one built deck page into its frames. */
+export async function readBuiltDeck(outputRoot: string, route: string): Promise<{ html: string; page: StaticDeck }> {
+  const html = await readFile(join(outputRoot, route, 'index.html'), 'utf8');
+  return { html, page: readStaticDeck(html, route, route) };
+}
+
+/** Every block a deck's frames show, notes aside. */
+export function deckBlocks(page: StaticDeck): Block[] {
+  return page.frames.flatMap((frame) => frame.segments.flatMap((segment) => segment.blocks));
+}
+
+/** The deck with each figure's live caption clause filled in from where it was drawn. */
+function deckWithLiveClauses(
+  page: StaticDeck,
+  captures: CaptureResults,
+  figureRoutes: ReadonlyMap<string, string>,
+  base: string,
+): StaticDeck {
+  const fill = (blocks: readonly Block[]): Block[] =>
+    blocks.map((block) => {
+      if (block.kind !== 'figure') return block;
+      const route = figureRoutes.get(block.anchor);
+      const live = route === undefined ? undefined : 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) })),
+    })),
+  };
+}
+
 /** Read one built page into its reading tree. */
 export async function readBuiltPage(outputRoot: string, slug: string): Promise<{ html: string; page: StaticPage }> {
   const route = slug.replace(/(?:^|\/)index$/u, '');
@@ -164,20 +226,52 @@ export async function prepareChapters(
   const read: { lesson: ManifestLesson; page: StaticPage }[] = [];
   let base = '/';
   for (const lesson of manifest.lessons) {
+    // A slides-first lesson has no chapter to print: its deck is read below.
+    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 });
   }
 
+  // Each deck's frames. A figure or diagram it recalls is its chapter's, drawn
+  // there: a lesson's deck recalls from its chapter, a part's from the
+  // chapter each recall names (`recalledFrom`).
+  const decksRead: { deck: ManifestDeck; page: StaticDeck; figureRoutes: Map<string, string> }[] = [];
+  const pictured = (blocks: readonly Block[]) => [...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: string) => {
+      const slug = deck.recalledFrom?.[anchor] ?? deck.chapter;
+      const chapter = slug === undefined ? undefined : 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: CaptureRequest[] = (latex || markdown ? read : [])
-    .map(({ page }) => ({
+    .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);
+  // A deck's own figures (and, for Markdown, its own diagrams), drawn on its page.
+  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);
+      // A figure's PDF carries its deck's date (rule C5).
+      if (anchors.length > 0) requests.push({ route: page.route, epoch: epochOf(manifest, deck.since), anchors });
+    }
+  }
   let captures: CaptureResults = new Map();
   if (requests.length > 0) {
     const chromium = await courseChromium(options.projectRoot ?? process.cwd());
@@ -229,5 +323,10 @@ export async function prepareChapters(
       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,
+    })),
   };
 }

package/src/compiler/exports/export-pages.ts

@@ -1,4 +1,4 @@
-import type { Manifest } from '../manifest';
+import type { Manifest, ManifestDeck } from '../manifest';
 
 /**
  * Every page a reader can print or download, by docs slug: each chapter
@@ -28,7 +28,51 @@ export function standaloneFilename(slug: string): string {
  * is in its part's file and the course's (`combined-html.ts`).
  */
 export function standalonePageSlugs(manifest: Pick<Manifest, 'lessons'>): string[] {
-  return manifest.lessons.map((lesson) => lesson.slug);
+  return manifest.lessons.filter((lesson) => (lesson.editions ?? ['chapter']).includes('chapter')).map((lesson) => lesson.slug);
+}
+
+/**
+ * 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.
+ */
+export function standaloneDownloads(
+  manifest: Pick<Manifest, 'lessons'> & Partial<Pick<Manifest, 'decks'>>,
+): { readonly slug: string; readonly download: string }[] {
+  return [
+    ...standalonePageSlugs(manifest).map((slug) => ({ slug, download: slug })),
+    ...(manifest.decks ?? []).map((deck) => ({
+      slug: deck.slug,
+      download: deckFileStem(deckOwnerSlug(deck, manifest)),
+    })),
+  ];
+}
+
+/**
+ * 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.
+ */
+export function deckFileStem(ownerSlug: string): string {
+  return `${ownerSlug}-slides`;
+}
+
+/** Whose a deck is, as its downloads name it: its lesson's slug, or its part's directory. */
+export function deckOwnerSlug(
+  deck: Pick<ManifestDeck, 'lessonId' | 'part' | 'slug'>,
+  manifest: Pick<Manifest, 'lessons'>,
+): string {
+  if (deck.part !== undefined) return deck.part;
+  return manifest.lessons.find((lesson) => lesson.id === deck.lessonId)?.slug ?? deck.slug;
+}
+
+/** The name a deck's files are saved under: `projectile-range-slides`, a part's `motion-slides`. */
+export function deckSaveName(ownerSlug: string): string {
+  return `${ownerSlug.split('/').at(-1) ?? ownerSlug}-slides`;
 }
 
 /** The name the course's files are saved under: `Explico Playground — Motion` → `explico-playground-motion`. */

package/src/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/src/compiler/exports/latex/cache.ts

@@ -0,0 +1,183 @@
+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 type { ExportLogger } from '../export-chapters';
+import { compileLatex, texFingerprint, type CompiledLatex, type LatexEngine } from './compile';
+import type { SourceFile } from './document';
+
+/**
+ * A cache of compiled documents (`EXPLICO_LATEX_CACHE=<directory>`), so a
+ * build compiles only the documents whose source changed. A document's key
+ * is a SHA-256 over everything its compile reads: the cache's format, the
+ * engine and a fingerprint of the TeX installation, the epoch the PDF is
+ * dated with, `EXPLICO_LATEX_CACHE_SALT`, and every file of its folder
+ * (path, length and bytes). A shared notation card, a renumbered chapter, a
+ * new `explico.cls` or a figure all change some file, so the key needs no
+ * dependency graph and cannot miss one.
+ *
+ * An entry keeps what `compileLatex` returns, the PDF, the `.aux` and the
+ * log, so a reused document is checked like a compiled one: its numbers
+ * against the website's, its log for characters no font set. An entry is
+ * written under a temporary name and renamed, a failed compile stores
+ * nothing, and an entry that does not read back whole is a miss. A hit
+ * touches its entry; entries no build has used for `KEEP_DAYS` are deleted.
+ */
+
+const FORMAT = 'explico-latex-cache 1';
+const KEEP_DAYS = 7;
+const ENTRY = /^[0-9a-f]{64}$/u;
+
+export 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. */
+export function cacheKey(files: readonly SourceFile[], context: CacheContext): string {
+  const hash = createHash('sha256');
+  for (const line of [FORMAT, context.engine, context.fingerprint, String(context.epoch), context.salt]) {
+    hash.update(`${line.length}:${line}\n`);
+  }
+  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}\n${content.byteLength}\n`);
+    hash.update(content);
+  }
+  return hash.digest('hex');
+}
+
+/** One file per entry: a format line, the parts' lengths and digest as JSON, then the parts. */
+function encodeEntry(result: CompiledLatex): Buffer {
+  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}\n${JSON.stringify(header)}\n`, 'utf8'), payload]);
+}
+
+/** The compile an entry holds, or `undefined` when it is not whole. */
+function decodeEntry(bytes: Buffer): CompiledLatex | undefined {
+  const formatEnd = bytes.indexOf(0x0a);
+  const headerEnd = formatEnd < 0 ? -1 : bytes.indexOf(0x0a, formatEnd + 1);
+  if (headerEnd < 0 || bytes.subarray(0, formatEnd).toString('utf8') !== FORMAT) return undefined;
+  let header: { pdf?: unknown; aux?: unknown; log?: unknown; sha256?: unknown };
+  try {
+    header = JSON.parse(bytes.subarray(formatEnd + 1, headerEnd).toString('utf8'));
+  } catch {
+    return undefined;
+  }
+  const { pdf, aux, log, sha256 } = header;
+  if (typeof pdf !== 'number' || typeof aux !== 'number' || typeof log !== 'number') return undefined;
+  const payload = bytes.subarray(headerEnd + 1);
+  if (payload.byteLength !== pdf + aux + log) return undefined;
+  if (createHash('sha256').update(payload).digest('hex') !== sha256) return undefined;
+  return {
+    pdf: Buffer.from(payload.subarray(0, pdf)),
+    aux: payload.subarray(pdf, pdf + aux).toString('utf8'),
+    log: payload.subarray(pdf + aux).toString('utf8'),
+  };
+}
+
+export 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>;
+}
+
+export 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 {
+  const { directory, engine, fingerprint } = options;
+  const compile = options.compile ?? compileLatex;
+  let warned = false;
+  const warnOnce = (message: string) => {
+    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, () => undefined);
+      if (cached) {
+        const now = new Date();
+        await utimes(path, now, now).catch(() => undefined);
+        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 = new Date()) {
+      const cutoff = now.getTime() - KEEP_DAYS * 24 * 60 * 60 * 1000;
+      let removed = 0;
+      for (const name of await readdir(directory).catch(() => [] as string[])) {
+        // An entry, or what an interrupted write left behind.
+        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, () => undefined);
+        if (modified === undefined || modified >= cutoff) continue;
+        await rm(path, { force: true });
+        removed += 1;
+      }
+      return removed;
+    },
+  };
+}
+
+/**
+ * The cache `EXPLICO_LATEX_CACHE` names, or `undefined` when it is unset
+ * (today's build: every document compiles) or the directory cannot be made.
+ */
+export async function latexCacheFromEnvironment(engine: LatexEngine, logger: ExportLogger): Promise<LatexCache | undefined> {
+  const setting = process.env.EXPLICO_LATEX_CACHE?.trim();
+  if (!setting) return undefined;
+  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 undefined;
+  }
+  return openLatexCache({
+    directory,
+    engine,
+    fingerprint: await texFingerprint(engine),
+    salt: process.env.EXPLICO_LATEX_CACHE_SALT ?? '',
+    logger,
+  });
+}

package/src/compiler/exports/latex/capture.ts

@@ -32,6 +32,8 @@ export 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;
 }
 
 export interface CapturedFigure {
@@ -140,7 +142,7 @@ async function existingFile(path: string): Promise<string | undefined> {
 }
 
 /** Serve `root` on loopback at `base`; resolves with the origin once listening. */
-async function serve(root: string, base: string): Promise<{ origin: string; server: Server }> {
+export async function serve(root: string, base: string): Promise<{ origin: string; server: Server }> {
   const rootPath = resolve(root);
   const server = createServer((request, response) => {
     void (async () => {
@@ -629,7 +631,8 @@ export async function captureFigures(
             options.measure ?? figureMeasure('letter'),
             options.png ?? false,
           );
-          const pdf = options.epoch === undefined ? printed.pdf : stampPdfDates(printed.pdf, options.epoch);
+          const epoch = request.epoch ?? options.epoch;
+          const pdf = epoch === undefined ? printed.pdf : stampPdfDates(printed.pdf, epoch);
           figures.set(anchor, { ...printed, pdf, liveHtml: snapshot.live });
         }
         results.set(request.route, figures);

package/src/compiler/exports/latex/compile.ts

@@ -79,6 +79,24 @@ export async function findLatexEngine(): Promise<LatexEngine | { readonly missin
     : { name: 'pdflatex', latexmkOption: '-pdf' };
 }
 
+/**
+ * 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.
+ */
+export async function texFingerprint(engine: LatexEngine): Promise<string> {
+  const firstLine = (output: string, pattern: RegExp) =>
+    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');
+}
+
 /**
  * The last LaTeX errors of a log, with their file and line. A Lua error
  * (`[\directlua]:1: …`, `….lua:12: …`) carries no TeX file and line.