explico 0.13.1 → 0.14.0

package/src/compiler/decks.ts

@@ -0,0 +1,455 @@
+/**
+ * A course's decks, as the manifest publishes them (`docs/authoring/deck.md`):
+ * each lesson's slide edition read as frames, numbered as the deck page, the
+ * presenter and the PDF number them, with the frames the engine writes
+ * itself — the title frame first, the outcomes frame and the references
+ * frame last — and the deck rules run over them (`decks-validate.ts`).
+ *
+ * Pure: `compileManifest` hands in the files, the notation scope of each
+ * deck's page and the chapter's numbers, and takes back the decks and their
+ * diagnostics.
+ */
+import { createHash } from 'node:crypto';
+
+import type { DeckFile } from './collections';
+import type { NormalizedDeck } from './course-config';
+import { readDeckSource, type DeckFrameSource, type DeckSource } from '../reference/deck-source';
+import {
+  chapterNumberOf,
+  resolvePartRecalls,
+  validateDecks,
+  type ChapterFloats,
+  type DeckRuleSettings,
+  type DeckValidationInput,
+  type PartDeckFacts,
+} from '../reference/decks-validate';
+import { mathSpans, type MathGateDiagnostic, type ScopeEntry } from '../reference/gate-math';
+import { resolveMathGlyphs } from '../reference/math-glyphs.mjs';
+import { citedSourceIds } from './lesson-derivation';
+
+/** One frame of a deck, in the order the deck shows it. */
+export interface ManifestDeckFrame {
+  /** 1-based: the generated title frame is 1. */
+  readonly number: number;
+  /**
+   * What the frame shows, as 12 hex digits of a SHA-256 (v35), as rule C5's
+   * hash names a page's content. A reader's record of the frames they saw
+   * keeps it, so a frame that changed since is told from one they never saw
+   * (`session/deck-memory.ts`). An authored frame hashes its source,
+   * notes included, and the chapter's number for each float it recalls; the
+   * title frame its title, course and authors, not its version, which every
+   * release moves; the outcomes frame its outcomes; the references frame the
+   * sources it cites. Another frame's change leaves it as it is.
+   */
+  readonly id: string;
+  /**
+   * `title` and `outcomes` and `references` are generated; `section` is a
+   * `##` divider; `frame` is a `###` frame.
+   */
+  readonly kind: 'title' | 'section' | 'frame' | 'outcomes' | 'references';
+  /** What the reader sees as its title. */
+  readonly title: string;
+  /** The heading's anchor (a section or a frame). */
+  readonly slug?: string;
+  /** A frame's section, by its anchor. */
+  readonly section?: string;
+  /** How many steps the frame shows in: one more than its `<Pause />` marks. */
+  readonly steps: number;
+  /** `### Title [morph]`: the frame morphs from the frame before it. */
+  readonly morph?: true;
+  /** The chapter floats the frame recalls, as written (`eq-range`, `fig-…`). */
+  readonly recalls?: readonly string[];
+  /** The frame carries speaker notes. */
+  readonly notes?: true;
+  /** The notation keys the frame shows for the first time in the deck — its legend line's first-use list. */
+  readonly symbols?: readonly string[];
+  /**
+   * On a part's deck, the chapter the frame's section covers (v36), by its
+   * lesson slug: on the section's divider and on each of its frames.
+   */
+  readonly chapter?: string;
+}
+
+/** One deck, a lesson's or a part's, as the builder makes it (`ManifestDeck` adds its notation). */
+export interface BuiltDeck {
+  /** The lesson the deck is the slide edition of; a part's deck belongs to none (v36). */
+  readonly lessonId?: string;
+  /**
+   * The deck page's id: `<lessonId>.slides`, the lesson's own id when it has
+   * no chapter, or a part's `<part>.slides`.
+   */
+  readonly pageId: string;
+  /** Its route: `<lesson>/slides`, the lesson's own for a slides-first lesson, or a part's `<part>/slides`. */
+  readonly slug: string;
+  readonly file: string;
+  readonly title: string;
+  readonly description: string;
+  /** The lesson's chapter slug, when the deck stands beside one. */
+  readonly chapter?: string;
+  /** A part's deck (`<part>/index.deck.mdx`, v36): the part's directory, `motion`. */
+  readonly part?: string;
+  /**
+   * Each chapter a part's deck covers, in deck order (v36): its lesson slug,
+   * and the number of the frame its section opens on, the divider — the
+   * chapter's address in the deck, `#slide-N`. Empty on a lesson's deck.
+   */
+  readonly covers: readonly { readonly chapter: string; readonly frame: number }[];
+  /**
+   * A part's deck (v36): the chapter whose float each recall shows, by its
+   * ref (`eq-range` → `projectiles/projectile-range`), which its number
+   * links to. A lesson's deck recalls from its {@link chapter}.
+   */
+  readonly recalledFrom?: Readonly<Record<string, string>>;
+  readonly frames: readonly ManifestDeckFrame[];
+  /** The deck's own labelled equations, numbered (1), (2)… in the deck (rule D8). */
+  readonly equations: readonly { readonly key: string; readonly number: string }[];
+}
+
+/** What the builder needs about each deck's lesson. */
+export interface DeckLessonFacts {
+  readonly title: string;
+  /** Competencies the lesson teaches; the outcomes frame lists their outcomes. */
+  readonly teaches: readonly string[];
+  /** Those outcomes, in order: what the outcomes frame shows. */
+  readonly outcomes?: readonly string[];
+  /** The chapter's numbered floats, by kind, key → number. Absent: no chapter. */
+  readonly chapterFloats?: ChapterFloats;
+}
+
+/** One chapter of a part, as a part's deck draws on it. */
+export interface DeckChapterFacts {
+  /** Its name in the part's directory, what `[chapter: <name>]` writes: `constant-acceleration`. */
+  readonly name: string;
+  /** Its lesson slug: `motion/constant-acceleration`. */
+  readonly slug: string;
+  /** Competencies it teaches; the outcomes frame lists those of every chapter covered. */
+  readonly teaches: readonly string[];
+  /** Their outcomes, in order. */
+  readonly outcomes: readonly string[];
+  /** What it numbers, which a section of the deck may recall. */
+  readonly floats: ChapterFloats;
+}
+
+/** What the builder needs about each part that has a deck. */
+export interface DeckPartFacts {
+  /** The part's label: the title of its deck when the deck sets none. */
+  readonly label: string;
+  /** The part's chapters, in reading order. */
+  readonly chapters: readonly DeckChapterFacts[];
+  /** The part's lessons that are only slides, by name: a section cannot cover one. */
+  readonly slidesFirst: readonly string[];
+}
+
+export interface BuildDecksInput {
+  readonly decks: readonly DeckFile[];
+  readonly settings: NormalizedDeck;
+  readonly rules: DeckRuleSettings;
+  /** The lesson behind each lesson's deck, by lesson id. */
+  readonly lessons: ReadonlyMap<string, DeckLessonFacts>;
+  /** Each part the course configures that has a deck, by its directory. */
+  readonly parts?: ReadonlyMap<string, DeckPartFacts>;
+  /** What every title frame shows under the deck's title: the course's name and its authors. */
+  readonly course?: { readonly name?: string; readonly authors: readonly string[] };
+  /** The glyph table of each deck's page, by page id (`pageScope`). */
+  readonly scopeOf: (pageId: string) => readonly ScopeEntry[];
+  /** Decorations a deck's page suspends (rule N22), by page id. */
+  readonly suspendedOf?: (pageId: string) => readonly string[];
+  /** A `[[key]]` term's label in a heading, as the deck's page reads it. */
+  readonly labelFor?: (pageId: string, key: string) => string | undefined;
+}
+
+const NOTES_BLOCK = /<Notes\s*>[\s\S]*?<\/Notes\s*>/g;
+const TERM = /\[\[\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\]\]/g;
+const EXPLAIN = /\\explain\s*\{([^{}]+)\}/g;
+const EQ_LABEL = /\\label\{eq:([^{}]+)\}/g;
+
+/**
+ * The notation keys a frame shows: its `[[key]]` terms, every bound symbol in
+ * its math, and those of each chapter equation it recalls (`recalled`, by key).
+ */
+function frameKeys(
+  frame: DeckFrameSource,
+  scope: readonly ScopeEntry[],
+  suspended: readonly string[],
+  recalled: ReadonlyMap<string, string> = new Map(),
+): string[] {
+  const text = frame.body.replace(NOTES_BLOCK, (block) => block.replace(/[^\n]/g, ' '));
+  const keys: string[] = [];
+  const add = (key: string) => {
+    if (!keys.includes(key)) keys.push(key);
+  };
+  const known = new Set(scope.map((entry) => entry.key));
+  for (const match of text.matchAll(TERM)) {
+    if (known.has(match[1] ?? '')) add(match[1] ?? '');
+  }
+  const latexes = [
+    ...mathSpans(text).map((span) => span.latex),
+    ...frame.recalls.flatMap((recall) => {
+      const latex = recall.ref?.startsWith('eq-') ? recalled.get(recall.ref.slice(3)) : undefined;
+      return latex === undefined ? [] : [latex];
+    }),
+  ];
+  for (const latex of latexes) {
+    for (const match of latex.matchAll(EXPLAIN)) add((match[1] ?? '').trim());
+    try {
+      const result = resolveMathGlyphs(latex.replace(EQ_LABEL, ''), [...scope], { suspended: [...suspended] }) as {
+        bindings?: readonly { key: string }[];
+      };
+      for (const binding of result.bindings ?? []) add(binding.key);
+    } catch {
+      // A span the resolver rejects is the math gate's finding, not a legend's.
+    }
+  }
+  return keys;
+}
+
+/** The deck's own `\label{eq:…}` keys, in order, outside its notes. */
+function ownEquationKeys(source: DeckSource): string[] {
+  const keys: string[] = [];
+  for (const frame of source.frames) {
+    for (const math of frame.displayMath) {
+      for (const match of math.latex.matchAll(EQ_LABEL)) {
+        const key = (match[1] ?? '').trim();
+        if (key && !keys.includes(key)) keys.push(key);
+      }
+    }
+  }
+  return keys;
+}
+
+/**
+ * A frame's id: 12 hex digits of a SHA-256 over its kind and what it shows,
+ * one string each (`ManifestDeckFrame.id`).
+ */
+export function deckFrameId(kind: ManifestDeckFrame['kind'], shows: readonly string[]): string {
+  return createHash('sha256').update(JSON.stringify([kind, ...shows])).digest('hex').slice(0, 12);
+}
+
+/** An authored frame's source, heading to the next heading; line ends and trailing blanks do not count. */
+function frameSource(body: string, frame: DeckFrameSource): string {
+  return body
+    .slice(frame.index, frame.end)
+    .replace(/\r\n?/gu, '\n')
+    .replace(/[ \t]+$/gmu, '')
+    .trimEnd();
+}
+
+/**
+ * A lesson's deck or a part's, as the deck's frames and generated frames
+ * need it: where a recall is numbered, what the outcomes frame lists, and
+ * the title it falls back on.
+ */
+interface DeckOwner {
+  /** What a frame shows of a float it recalls: its chapter's number and, for an equation, its LaTeX. */
+  readonly recalled: (ref: string) => { readonly number?: string; readonly latex?: string };
+  /** The chapter a frame's section covers, by the frame's place in the source (a part's deck). */
+  readonly frameChapter: (position: number) => string | undefined;
+  readonly teaches: readonly string[];
+  readonly outcomes: readonly string[];
+  /** The title frame's title when the deck file sets none. */
+  readonly fallbackTitle: string;
+  /** What `BuiltDeck` says of whose deck it is. */
+  readonly identity: Pick<BuiltDeck, 'lessonId' | 'chapter' | 'part' | 'covers' | 'recalledFrom'>;
+  readonly validation: Pick<DeckValidationInput, 'hasChapter' | 'inPart' | 'chapter' | 'part'>;
+}
+
+/** What a lesson's deck draws on: its chapter, when it has one. */
+function lessonOwner(deck: Extract<DeckFile, { scope: 'lesson' }>, lesson: DeckLessonFacts | undefined): DeckOwner {
+  const floats = lesson?.chapterFloats;
+  return {
+    recalled: (ref) => {
+      const number = chapterNumberOf(ref, floats);
+      const latex = ref.startsWith('eq-') ? floats?.equations.get(ref.slice(3))?.latex : undefined;
+      return { ...(number === undefined ? {} : { number }), ...(latex === undefined ? {} : { latex }) };
+    },
+    frameChapter: () => undefined,
+    teaches: lesson?.teaches ?? [],
+    outcomes: lesson?.outcomes ?? [],
+    fallbackTitle: lesson?.title ?? deck.lessonId,
+    identity: {
+      lessonId: deck.lessonId,
+      ...(deck.chapterPath === undefined ? {} : { chapter: deck.lessonSlug }),
+      covers: [],
+    },
+    validation: {
+      hasChapter: deck.chapterPath !== undefined,
+      inPart: deck.inPart,
+      ...(floats === undefined ? {} : { chapter: floats }),
+    },
+  };
+}
+
+/**
+ * What a part's deck draws on: the chapters its sections cover. A recall is
+ * the float of the chapter `resolvePartRecalls` finds; the outcomes frame
+ * lists every covered chapter's outcomes, in reading order.
+ */
+function partOwner(
+  deck: Extract<DeckFile, { scope: 'part' }>,
+  part: DeckPartFacts | undefined,
+  source: DeckSource,
+): DeckOwner {
+  const facts: PartDeckFacts = {
+    dir: deck.partDir,
+    chapters: (part?.chapters ?? []).map((chapter) => ({ name: chapter.name, slug: chapter.slug, floats: chapter.floats })),
+    slidesFirst: part?.slidesFirst ?? [],
+  };
+  const recalls = resolvePartRecalls(source, facts);
+  const covered = new Set(recalls.covered.map((chapter) => chapter.name));
+  const inOrder = (part?.chapters ?? []).filter((chapter) => covered.has(chapter.name));
+  const teaches = [...new Set(inOrder.flatMap((chapter) => chapter.teaches))];
+  return {
+    recalled: (ref) => {
+      const floats = recalls.chapterOf.get(ref)?.floats;
+      const number = chapterNumberOf(ref, floats);
+      const latex = ref.startsWith('eq-') ? floats?.equations.get(ref.slice(3))?.latex : undefined;
+      return { ...(number === undefined ? {} : { number }), ...(latex === undefined ? {} : { latex }) };
+    },
+    frameChapter: (position) => recalls.frameChapters[position]?.slug,
+    teaches,
+    outcomes: [...new Set(inOrder.flatMap((chapter) => chapter.outcomes))],
+    fallbackTitle: part?.label ?? deck.partDir,
+    identity: {
+      part: deck.partDir,
+      covers: recalls.covered.map((chapter) => ({ chapter: chapter.slug, frame: chapter.position + 2 })),
+      recalledFrom: Object.fromEntries(
+        [...recalls.chapterOf].sort(([left], [right]) => left.localeCompare(right)).map(([ref, chapter]) => [ref, chapter.slug]),
+      ),
+    },
+    validation: { hasChapter: false, inPart: part !== undefined, part: facts },
+  };
+}
+
+export function buildDecks(input: BuildDecksInput): {
+  decks: BuiltDeck[];
+  diagnostics: MathGateDiagnostic[];
+} {
+  const decks: BuiltDeck[] = [];
+  const validation: DeckValidationInput[] = [];
+  for (const deck of input.decks) {
+    const source = readDeckSource(deck.body, {
+      labelFor: (key) => input.labelFor?.(deck.pageId, key),
+    });
+    const owner =
+      deck.scope === 'part'
+        ? partOwner(deck, input.parts?.get(deck.partDir), source)
+        : lessonOwner(deck, input.lessons.get(deck.lessonId));
+    const scope = input.scopeOf(deck.pageId);
+    const suspended = input.suspendedOf?.(deck.pageId) ?? [];
+    const seen = new Set<string>();
+    // A recalled equation's LaTeX, by its key: the symbols it shows count for the frame's legend.
+    const recalled = new Map(
+      source.frames.flatMap((frame) =>
+        frame.recalls.flatMap((recall): [string, string][] => {
+          if (!recall.ref?.startsWith('eq-')) return [];
+          const latex = owner.recalled(recall.ref).latex;
+          return latex === undefined ? [] : [[recall.ref.slice(3), latex]];
+        }),
+      ),
+    );
+    const newSymbols = source.frames.map((frame) => {
+      const fresh = frameKeys(frame, scope, suspended, recalled).filter((key) => !seen.has(key));
+      for (const key of fresh) seen.add(key);
+      return fresh;
+    });
+    validation.push({
+      file: deck.file,
+      pageId: deck.pageId,
+      body: deck.body,
+      bodyLine: deck.bodyLine,
+      data: deck.data,
+      source,
+      ...owner.validation,
+      newSymbols,
+    });
+
+    const title =
+      typeof deck.data.title === 'string' && deck.data.title.trim() !== ''
+        ? deck.data.title
+        : owner.fallbackTitle;
+    const frames: ManifestDeckFrame[] = [
+      {
+        number: 1,
+        id: deckFrameId('title', [title, input.course?.name ?? '', ...(input.course?.authors ?? [])]),
+        kind: 'title',
+        title,
+        steps: 1,
+      },
+    ];
+    source.frames.forEach((frame, index) => {
+      const symbols = newSymbols[index] ?? [];
+      const recalls = frame.recalls.flatMap((recall) => (recall.ref === undefined ? [] : [recall.ref]));
+      const chapter = owner.frameChapter(index);
+      frames.push({
+        number: frames.length + 1,
+        id: deckFrameId(frame.kind, [
+          frameSource(deck.body, frame),
+          ...recalls.map((ref) => `${ref} ${owner.recalled(ref).number ?? '?'}`),
+        ]),
+        kind: frame.kind,
+        title: frame.title,
+        slug: frame.slug,
+        ...(frame.section === undefined ? {} : { section: frame.section }),
+        steps: frame.pauses.length + 1,
+        ...(frame.morph ? { morph: true as const } : {}),
+        ...(recalls.length === 0 ? {} : { recalls }),
+        ...(frame.notes.length === 0 ? {} : { notes: true as const }),
+        ...(symbols.length === 0 ? {} : { symbols }),
+        ...(chapter === undefined ? {} : { chapter }),
+      });
+    });
+    if (input.settings.outcomesFrame && owner.teaches.length > 0) {
+      frames.push({
+        number: frames.length + 1,
+        id: deckFrameId('outcomes', owner.outcomes),
+        kind: 'outcomes',
+        title: 'What you can now do',
+        steps: 1,
+      });
+    }
+    const cited = [...citedSourceIds(deck.body)].sort();
+    if (cited.length > 0) {
+      frames.push({
+        number: frames.length + 1,
+        id: deckFrameId('references', cited),
+        kind: 'references',
+        title: 'References',
+        steps: 1,
+      });
+    }
+
+    decks.push({
+      ...(owner.identity.lessonId === undefined ? {} : { lessonId: owner.identity.lessonId }),
+      pageId: deck.pageId,
+      slug: deck.route,
+      file: deck.file,
+      title,
+      description: typeof deck.data.description === 'string' ? deck.data.description : '',
+      ...(owner.identity.chapter === undefined ? {} : { chapter: owner.identity.chapter }),
+      ...(owner.identity.part === undefined ? {} : { part: owner.identity.part }),
+      covers: owner.identity.covers,
+      ...(owner.identity.recalledFrom === undefined ? {} : { recalledFrom: owner.identity.recalledFrom }),
+      frames,
+      equations: ownEquationKeys(source).map((key, index) => ({ key, number: String(index + 1) })),
+    });
+  }
+  return {
+    decks: decks.sort((left, right) => left.slug.localeCompare(right.slug)),
+    diagnostics: validateDecks(validation, input.rules),
+  };
+}
+
+/**
+ * Each labelled display equation of a chapter body, by key: its LaTeX (what
+ * rule D8 compares a deck's equation with).
+ */
+export function chapterEquationLatex(body: string): Map<string, string> {
+  const latex = new Map<string, string>();
+  for (const span of mathSpans(body)) {
+    for (const match of span.latex.matchAll(EQ_LABEL)) {
+      const key = (match[1] ?? '').trim();
+      if (key && !latex.has(key)) latex.set(key, span.latex);
+    }
+  }
+  return latex;
+}

package/src/compiler/exports/deck-fit.ts

@@ -0,0 +1,127 @@
+/**
+ * Rule D2's rendered half: every frame of every deck fits its canvas.
+ *
+ * Only a browser knows how tall a frame's content is — its fonts, its math,
+ * its hydrated labs — so after Astro has built the site this opens each deck
+ * page in the course's Chromium, lets its controller lay the frames out at the
+ * canvas size (`components/deck/deck-controller.ts`), and reports each frame
+ * whose content runs past its canvas: `frame-overflow`, an error, which fails
+ * the build. The canvas has the same size on every screen, so one measure
+ * holds for every reader. Without a browser it warns and checks nothing;
+ * in CI (`CI`, `EXPLICO_LATEX_STRICT=1`) a missing browser fails the build.
+ */
+import { parse } from 'parse5';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { inferBasePrefix } from './html-tree';
+import { courseChromium, serve } from './latex/capture';
+import { strictMode, type ExportLogger } from './export-chapters';
+import type { Manifest } from '../manifest';
+
+export interface FrameFitFinding {
+  readonly code: 'frame-overflow';
+  readonly severity: 'error';
+  /** The deck file. */
+  readonly file: string;
+  readonly frame: number;
+  readonly title: string;
+  /** How far past the canvas the content runs, in canvas pixels. */
+  readonly overflow: number;
+  readonly message: string;
+}
+
+/** The measure the page runs: each frame whose content is taller or wider than its box. */
+function measureFrames(): { frame: number; title: string; overflow: number }[] {
+  const found: { frame: number; title: string; overflow: number }[] = [];
+  for (const frame of document.querySelectorAll<HTMLElement>('.deck .deck-frame')) {
+    const body = frame.querySelector<HTMLElement>('.deck-frame__body');
+    const canvas = frame.querySelector<HTMLElement>('.deck-canvas');
+    const over = Math.max(
+      body ? body.scrollHeight - body.clientHeight : 0,
+      body ? body.scrollWidth - body.clientWidth : 0,
+      canvas ? canvas.scrollHeight - canvas.clientHeight : 0,
+    );
+    if (over > 1) {
+      found.push({
+        frame: Number(frame.dataset.frame),
+        title: frame.querySelector('.deck-frame__title, .deck-title__title')?.textContent?.trim() ?? '',
+        overflow: Math.round(over),
+      });
+    }
+  }
+  return found;
+}
+
+export async function checkFrameFit(
+  outputRoot: string,
+  manifest: Pick<Manifest, 'decks'>,
+  options: { readonly logger: ExportLogger; readonly projectRoot?: string; readonly timeoutMs?: number },
+): Promise<FrameFitFinding[]> {
+  const decks = manifest.decks ?? [];
+  if (decks.length === 0) return [];
+  const chromium = await courseChromium(options.projectRoot ?? process.cwd());
+  if (!chromium) {
+    const message =
+      'frame-overflow (rule D2): no Chromium from Playwright in this course, so no frame was measured. ' +
+      'Install it (`pnpm exec playwright install chromium`) to check that every frame fits its canvas.';
+    if (strictMode()) throw new Error(message);
+    options.logger.warn(message);
+    return [];
+  }
+  const firstPage = await readFile(join(outputRoot, decks[0]!.slug, 'index.html'), 'utf8');
+  const base = inferBasePrefix(parse(firstPage));
+  const { origin, server } = await serve(outputRoot, base);
+  const findings: FrameFitFinding[] = [];
+  let browser: Awaited<ReturnType<typeof chromium.launch>> | undefined;
+  try {
+    browser = await chromium.launch();
+    for (const deck of decks) {
+      const context = await browser.newContext({
+        viewport: { width: 1280, height: 900 },
+        colorScheme: 'light',
+        reducedMotion: 'reduce',
+        locale: 'en-US',
+      });
+      try {
+        const page = await context.newPage();
+        await page.goto(`${origin}${base}${deck.slug}/`, { waitUntil: 'load' });
+        // Until the controller has laid the frames out and the fonts are in;
+        // then each frame comes into view once, for its labs to hydrate.
+        await page.evaluate(async (timeout: number) => {
+          const start = performance.now();
+          while (!(document.querySelector('.deck[data-deck-ready]') && document.fonts.status === 'loaded')) {
+            if (performance.now() - start > timeout) break;
+            await new Promise((done) => setTimeout(done, 50));
+          }
+          for (const frame of document.querySelectorAll<HTMLElement>('.deck .deck-frame')) {
+            frame.scrollIntoView({ block: 'center' });
+            await new Promise((done) => requestAnimationFrame(() => setTimeout(done, 30)));
+          }
+          await new Promise((done) => setTimeout(done, 400));
+          // The controller fits each figure to its frame, as a reader's page does.
+          (window as Window & { explicoDeckOverflow?: () => number[] }).explicoDeckOverflow?.();
+        }, options.timeoutMs ?? 30_000);
+        for (const { frame, title, overflow } of (await page.evaluate(measureFrames)) as ReturnType<typeof measureFrames>) {
+          findings.push({
+            code: 'frame-overflow',
+            severity: 'error',
+            file: deck.file,
+            frame,
+            title,
+            overflow,
+            message:
+              `${deck.file}: slide ${frame}${title ? ` “${title}”` : ''} does not fit its canvas — its content runs ` +
+              `${overflow}px past it (rule D2). Split the frame in two, move its argument into <Notes>, or recall less.`,
+          });
+        }
+      } finally {
+        await context.close();
+      }
+    }
+  } finally {
+    await browser?.close();
+    await new Promise<void>((done) => server.close(() => done()));
+  }
+  return findings;
+}