explico 0.11.1 → 0.13.0

package/dist/reference/diagram-layout.d.ts

@@ -45,19 +45,68 @@ interface DiagramLayout {
  * would otherwise create a phantom zero-size node).
  */
 declare function layoutDiagram(nodes: readonly DiagramNodeInput[], edges: readonly DiagramEdgeInput[], options?: DiagramLayoutOptions): DiagramLayout;
-interface BoxSizeEstimate {
+/** A node's text font size, in px. */
+declare const NODE_FONT_PX = 13.6;
+/**
+ * A node's formula font size, in px: KaTeX's own `.katex { font-size: 1.21em }`
+ * of the node's text. `katex.css` is unlayered, so no rule in the component's
+ * `@layer` can shrink it, and at that size KaTeX_Main's x-height matches the
+ * label's.
+ */
+declare const FORMULA_FONT_PX: number;
+/** What a node holds, measured: its label, and its formula's box in px. */
+interface NodeBoxContent {
+    readonly text?: string;
+    /** `measureFormula(latex, FORMULA_FONT_PX)`. */
+    readonly formula?: {
+        readonly width: number;
+        readonly height: number;
+        readonly depth: number;
+    };
+}
+interface NodeBoxOptions {
+    /** The author's width: the label wraps inside it and the height follows. */
+    readonly width?: number;
+    /** The author's height. */
+    readonly height?: number;
+    /** The widest box a label is wrapped to fit before it takes a second line. */
+    readonly maxWidth?: number;
+}
+interface NodeBox {
     readonly width: number;
     readonly height: number;
+    /** The label as it is wrapped in DejaVu Sans. */
+    readonly lines: readonly string[];
 }
 /**
- * Estimate a diagram node's box from its label text (or raw, pre-resolution
- * LaTeX for a formula node). Deliberately generous: it is meant to avoid
- * clipping, not to match a real render pixel-for-pixel. Pass an explicit
- * `width`/`height` on the node to override for a label this estimate gets
- * badly wrong.
+ * Size a node's box from its measured content: as wide as its widest line of
+ * text or its formula, whichever is wider, plus the inset, and as tall as its
+ * lines of text, the gap and its formula's line. A label wider than `maxWidth`
+ * wraps; a formula never does, so a wide formula widens the box instead and the
+ * label wraps to it. An author's `width` or `height` makes the box larger,
+ * never too small for its formula or its lines.
  */
-declare function estimateBoxSize(content: string, kind: 'text' | 'formula', options?: {
-    readonly maxWidth?: number;
-}): BoxSizeEstimate;
+declare function nodeBoxSize(content: NodeBoxContent, options?: NodeBoxOptions): NodeBox;
+/** One node to fit: what it holds, and the author's size if any. */
+interface FitNodeInput {
+    readonly id: string;
+    readonly content: NodeBoxContent;
+    readonly width?: number;
+    readonly height?: number;
+}
+interface FitOptions extends DiagramLayoutOptions {
+    /** The widest the diagram should lay out (rule V8's column); omit to skip fitting. */
+    readonly fitWidth?: number;
+}
+/**
+ * Size every node from its content and lay the diagram out. When `fitWidth`
+ * is set and the diagram comes out wider, wrap the labels of the nodes without
+ * an author's `width` narrower, step by step, until it fits; a diagram that
+ * still does not fit keeps its narrowest layout, and the caller warns.
+ */
+declare function fitDiagramLayout(nodes: readonly FitNodeInput[], edges: readonly DiagramEdgeInput[], options?: FitOptions): {
+    readonly layout: DiagramLayout;
+    readonly boxes: ReadonlyMap<string, NodeBox>;
+};
 
-export { type BoxSizeEstimate, type DiagramEdgeInput, type DiagramLayout, type DiagramLayoutOptions, type DiagramNodeInput, type LaidOutEdge, type LaidOutNode, type Point, estimateBoxSize, layoutDiagram };
+export { type DiagramEdgeInput, type DiagramLayout, type DiagramLayoutOptions, type DiagramNodeInput, FORMULA_FONT_PX, type FitNodeInput, type FitOptions, type LaidOutEdge, type LaidOutNode, NODE_FONT_PX, type NodeBox, type NodeBoxContent, type NodeBoxOptions, type Point, fitDiagramLayout, layoutDiagram, nodeBoxSize };

package/dist/reference/diagram-layout.js

@@ -1,4 +1,5 @@
 import dagre from "@dagrejs/dagre";
+import { textWidth, wrapText } from "./text-measure.js";
 function layoutDiagram(nodes, edges, options = {}) {
   const ids = /* @__PURE__ */ new Set();
   for (const node of nodes) {
@@ -19,6 +20,11 @@ function layoutDiagram(nodes, edges, options = {}) {
     if (!ids.has(edge.to)) {
       throw new Error(`Diagram edge references unknown node "${edge.to}".`);
     }
+    if (edge.from === edge.to) {
+      throw new Error(
+        `Diagram edge from "${edge.from}" to itself: a diagram draws no loop on one node. Name the repetition in the label ("Repeat until it converges"), or draw the step it returns to as its own node.`
+      );
+    }
   }
   const graph = new dagre.graphlib.Graph();
   graph.setGraph({
@@ -91,32 +97,87 @@ function layoutDiagram(nodes, edges, options = {}) {
     height: maxY - minY + padding * 2
   };
 }
-const DEFAULT_MAX_WIDTH = 220;
+const NODE_FONT_PX = 13.6;
+const FORMULA_FONT_PX = NODE_FONT_PX * 1.21;
+const LINE_PX = 17;
+const CSS_PADDING_X = 8;
+const INSET_X = 16;
+const INSET_Y = 14;
+const GAP_PX = 2.4;
+const FORMULA_ASCENT_PX = 14;
+const FORMULA_DESCENT_PX = 5.5;
 const MIN_WIDTH = 90;
-const PADDING_X = 20;
-const PADDING_Y = 16;
-const LINE_HEIGHT = 22;
-const CHAR_WIDTH = {
-  text: 7.2,
-  formula: 11
-};
-function formulaVisibleLength(latex) {
-  const collapsed = latex.replace(/\\[a-zA-Z]+/g, "x").replace(/[{}$]/g, "").trim();
-  return Math.max(1, collapsed.length);
+const DEFAULT_MAX_WIDTH = 220;
+function balancedLines(text, maxWidth) {
+  const greedy = wrapText(text, maxWidth, NODE_FONT_PX);
+  if (greedy.length <= 1) return greedy;
+  let low = 1;
+  let high = Math.ceil(maxWidth);
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2);
+    if (wrapText(text, middle, NODE_FONT_PX).length <= greedy.length) high = middle;
+    else low = middle + 1;
+  }
+  return wrapText(text, high, NODE_FONT_PX);
+}
+function nodeBoxSize(content, options = {}) {
+  const text = content.text?.trim() ?? "";
+  const formula = content.formula;
+  const formulaWidth = formula?.width ?? 0;
+  let width;
+  let lines;
+  if (options.width !== void 0) {
+    width = Math.max(options.width, Math.ceil(formulaWidth + 2 * CSS_PADDING_X));
+    lines = text ? wrapText(text, width - 2 * CSS_PADDING_X, NODE_FONT_PX) : [];
+  } else {
+    const maxContent = Math.max(
+      (options.maxWidth ?? DEFAULT_MAX_WIDTH) - 2 * INSET_X,
+      formulaWidth
+    );
+    lines = text ? balancedLines(text, maxContent) : [];
+    const contentWidth = Math.max(
+      formulaWidth,
+      ...lines.map((line) => textWidth(line, NODE_FONT_PX))
+    );
+    width = Math.max(MIN_WIDTH, Math.ceil(contentWidth + 2 * INSET_X));
+  }
+  const formulaHeight = formula ? Math.max(FORMULA_ASCENT_PX, formula.height) + Math.max(FORMULA_DESCENT_PX, formula.depth) : 0;
+  const gap = lines.length > 0 && formula ? GAP_PX : 0;
+  const contentHeight = Math.ceil(lines.length * LINE_PX + gap + formulaHeight + 2 * INSET_Y);
+  const height = Math.max(options.height ?? 0, contentHeight);
+  return { width, height, lines };
+}
+const FIT_MAX_WIDTHS = [DEFAULT_MAX_WIDTH, 200, 180, 160, 140, 120];
+function fitDiagramLayout(nodes, edges, options = {}) {
+  let result;
+  for (const maxWidth of FIT_MAX_WIDTHS) {
+    const boxes = new Map(
+      nodes.map((node) => [
+        node.id,
+        nodeBoxSize(node.content, {
+          maxWidth,
+          ...node.width !== void 0 ? { width: node.width } : {},
+          ...node.height !== void 0 ? { height: node.height } : {}
+        })
+      ])
+    );
+    const layout = layoutDiagram(
+      nodes.map((node) => ({ id: node.id, ...sizeOf(boxes.get(node.id)) })),
+      edges,
+      options
+    );
+    result = { layout, boxes };
+    if (options.fitWidth === void 0 || layout.width <= options.fitWidth) break;
+  }
+  return result;
 }
-function estimateBoxSize(content, kind, options = {}) {
-  const maxWidth = options.maxWidth ?? DEFAULT_MAX_WIDTH;
-  const visibleLength = kind === "formula" ? formulaVisibleLength(content) : content.trim().length || 1;
-  const charWidth = CHAR_WIDTH[kind];
-  const naturalWidth = visibleLength * charWidth + PADDING_X * 2;
-  const width = Math.min(maxWidth, Math.max(MIN_WIDTH, naturalWidth));
-  const usableWidth = width - PADDING_X * 2;
-  const charsPerLine = Math.max(1, Math.floor(usableWidth / charWidth));
-  const lines = Math.max(1, Math.ceil(visibleLength / charsPerLine));
-  const height = lines * LINE_HEIGHT + PADDING_Y * 2;
-  return { width: Math.round(width), height: Math.round(height) };
+function sizeOf(box) {
+  return { width: box.width, height: box.height };
 }
 export {
-  estimateBoxSize,
-  layoutDiagram
+  FORMULA_FONT_PX,
+  NODE_FONT_PX,
+  fitDiagramLayout,
+  layoutDiagram,
+  nodeBoxSize
 };

package/dist/reference/diagrams-validate.d.ts

@@ -2,7 +2,7 @@ import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } fr
 
 /** `validateKeyedFloats` for `<Diagram>` — see `keyed-float-validate.ts`. */
 
-type DiagramDiagnosticCode = 'dia-invalid-key' | 'dia-duplicate-key' | 'dia-ref-resolves' | 'dia-key-unused' | 'dia-removed-prop';
+type DiagramDiagnosticCode = 'dia-invalid-key' | 'dia-duplicate-key' | 'dia-ref-resolves' | 'dia-key-unused' | 'dia-removed-prop' | 'dia-unread-prop';
 interface DiagramDiagnostic {
     readonly code: DiagramDiagnosticCode;
     readonly severity: 'error' | 'warning' | 'info';

package/dist/reference/equations-validate.d.ts

@@ -25,7 +25,7 @@ interface EquationRefRecord {
     /** Target lesson slug for a cross-page reference; `undefined` = same page. */
     readonly targetSlug?: string;
 }
-type EquationDiagnosticCode = 'eq-duplicate-key' | 'eq-ref-resolves' | 'eq-key-unused';
+type EquationDiagnosticCode = 'eq-duplicate-key' | 'eq-ref-resolves' | 'eq-key-unused' | 'eq-label-repeated' | 'eq-latex-ref';
 interface EquationDiagnostic {
     readonly code: EquationDiagnosticCode;
     readonly severity: 'error' | 'warning' | 'info';

package/dist/reference/equations-validate.js

@@ -1,4 +1,5 @@
-import { parseEquationRef, scanEquationLabels } from "./equations.mjs";
+import { parseEquationRef, repeatedEquationLabels, scanEquationLabels } from "./equations.mjs";
+import { proseOnly } from "./gate-prose-notation.js";
 const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
 function stripCode(text) {
   return text.replace(/```[\s\S]*?```/g, " ").replace(/~~~[\s\S]*?~~~/g, " ").replace(/`[^`\n]*`/g, " ");
@@ -16,6 +17,7 @@ function bodyEquationRefs(lesson) {
   }
   return refs;
 }
+const LATEX_REFERENCE = /\\(eqref|ref|autoref|cref|Cref)\s*\{([^{}\n]*)\}/g;
 function validateEquations(lessons) {
   const labels = [];
   const diagnostics = [];
@@ -50,6 +52,29 @@ function validateEquations(lessons) {
       });
     }
     numbersBySlug[lesson.slug] = table;
+    for (const match of proseOnly(lesson.body).matchAll(LATEX_REFERENCE)) {
+      const [, command, target = ""] = match;
+      const [prefix, key] = target.includes(":") ? target.split(":", 2) : ["eq", target];
+      diagnostics.push({
+        code: "eq-latex-ref",
+        severity: "error",
+        message: `${lesson.lessonId} writes \\${command}{${target}}, LaTeX's reference: MDX reads its {\u2026} as JavaScript, and the page fails to build. Write [[${prefix}-${key}]].`,
+        file: lesson.file,
+        lessonId: lesson.lessonId,
+        key: key ?? target
+      });
+    }
+    for (const keys of repeatedEquationLabels(lesson.body)) {
+      const [first, ...rest] = keys;
+      diagnostics.push({
+        code: "eq-label-repeated",
+        severity: "error",
+        message: `${lesson.lessonId} puts ${keys.map((key) => `\\label{eq:${key}}`).join(" and ")} in one display block, which is one numbered equation: eq:${first} names it, and ${rest.map((key) => `[[eq-${key}]]`).join(", ")} would point at nothing. Split the block into one $$\u2026$$ block per equation you refer to.`,
+        file: lesson.file,
+        lessonId: lesson.lessonId,
+        key: rest[0]
+      });
+    }
   }
   const referenced = /* @__PURE__ */ new Set();
   for (const lesson of lessons) {

package/dist/reference/equations.d.mts

@@ -74,6 +74,27 @@ export function stripFencedCode(markdown: any): string;
  * a transparent body do not change the surrounding page's section counter.
  */
 export function stripJsxComponents(markdown: any, keep: any, transparent?: any[]): string;
+/**
+ * Blank the body of every `:::name … :::` container directive — a Starlight
+ * aside (`:::note`, `:::tip`, …) — keeping newlines, the text-scan twin of a
+ * tree walk that never enters a `containerDirective`. An aside is a callout,
+ * like `<Aside>`: what it holds is illustrative and numbers nothing. A fence
+ * of more colons closes only on as many; one left open runs to the end.
+ */
+export function stripContainerDirectives(markdown: any): string;
+/**
+ * Every `$$` display block in a Markdown text the way remark-math reads one:
+ * an opening fence of two or more `$` that starts a line — inside a list item
+ * or a blockquote too — with nothing but a `$`-free meta after it, up to a
+ * closing fence of at least as many `$` on a line of its own (or the end of
+ * the text). `$$x$$` inside a paragraph, or on one line, is inline math and
+ * is not a display block. Each block is `{ index, body }`: the offset of its
+ * opening line and the text between the fences.
+ */
+export function displayMathBlocks(markdown: any): {
+    index: number;
+    body: string;
+}[];
 /**
  * Every display equation in a Markdown body, keyed or not, in appearance order
  * with its assigned number and its `\caption{}` short caption (`short`, or
@@ -94,6 +115,12 @@ export function scanDisplayEquations(markdown: any, numbering: any): {
     section: number;
     indexInSection: number;
 }[];
+/**
+ * The keys of each display block that carries more than one `\label{eq:…}`,
+ * in order. A block is one numbered equation: its first label names it, and
+ * a later one would name nothing.
+ */
+export function repeatedEquationLabels(markdown: any): string[][];
 /** The keyed subset of `scanDisplayEquations` — the manifest builder's view. */
 export function scanEquationLabels(markdown: any, numbering: any): {
     key: string | null | undefined;

package/dist/reference/equations.mjs

@@ -204,6 +204,87 @@ export function stripJsxComponents(markdown, keep, transparent = []) {
  */
 export const TRANSPARENT_COMPONENTS = Object.freeze(['Memo', 'ShortNote', 'Fold']);
 
+/**
+ * Blank the body of every `:::name … :::` container directive — a Starlight
+ * aside (`:::note`, `:::tip`, …) — keeping newlines, the text-scan twin of a
+ * tree walk that never enters a `containerDirective`. An aside is a callout,
+ * like `<Aside>`: what it holds is illustrative and numbers nothing. A fence
+ * of more colons closes only on as many; one left open runs to the end.
+ */
+export function stripContainerDirectives(markdown) {
+  const lines = String(markdown).split('\n');
+  let fence = 0;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index] ?? '';
+    if (fence === 0) {
+      const open = /^[ \t]{0,3}(:{3,})[A-Za-z]/.exec(line);
+      if (!open) continue;
+      fence = open[1].length;
+      lines[index] = line.replace(/[^\n]/g, ' ');
+      continue;
+    }
+    const close = /^[ \t]{0,3}(:{3,})[ \t]*$/.exec(line);
+    if (close && close[1].length >= fence) fence = 0;
+    lines[index] = line.replace(/[^\n]/g, ' ');
+  }
+  return lines.join('\n');
+}
+
+/** A line with its blockquote markers, list marker and indentation removed. */
+function containerContent(line) {
+  let rest = String(line);
+  for (;;) {
+    const next = rest
+      .replace(/^[ \t]*>[ \t]?/, '')
+      .replace(/^[ \t]*(?:[-*+]|\d{1,9}[.)])[ \t]+/, '');
+    if (next === rest) return rest.replace(/^[ \t]+/, '');
+    rest = next;
+  }
+}
+
+/**
+ * Every `$$` display block in a Markdown text the way remark-math reads one:
+ * an opening fence of two or more `$` that starts a line — inside a list item
+ * or a blockquote too — with nothing but a `$`-free meta after it, up to a
+ * closing fence of at least as many `$` on a line of its own (or the end of
+ * the text). `$$x$$` inside a paragraph, or on one line, is inline math and
+ * is not a display block. Each block is `{ index, body }`: the offset of its
+ * opening line and the text between the fences.
+ */
+export function displayMathBlocks(markdown) {
+  const text = String(markdown);
+  const lines = text.split('\n');
+  const starts = [];
+  let offset = 0;
+  for (const line of lines) {
+    starts.push(offset);
+    offset += line.length + 1;
+  }
+  const blocks = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const open = /^(\${2,})[ \t]*[^$]*$/.exec(containerContent(lines[index]));
+    if (!open) continue;
+    const size = open[1].length;
+    let end = lines.length;
+    for (let next = index + 1; next < lines.length; next += 1) {
+      const close = /^(\${2,})[ \t]*$/.exec(containerContent(lines[next]));
+      if (close && close[1].length >= size) {
+        end = next;
+        break;
+      }
+    }
+    blocks.push({
+      index: starts[index],
+      body: lines
+        .slice(index + 1, end)
+        .map((line) => containerContent(line))
+        .join('\n'),
+    });
+    index = end;
+  }
+  return blocks;
+}
+
 /**
  * Every display equation in a Markdown body, keyed or not, in appearance order
  * with its assigned number and its `\caption{}` short caption (`short`, or
@@ -219,25 +300,20 @@ export const TRANSPARENT_COMPONENTS = Object.freeze(['Memo', 'ShortNote', 'Fold'
  */
 export function scanDisplayEquations(markdown, numbering) {
   const { prefix, offset } = resolveNumbering(numbering);
-  const text = stripJsxComponents(
-    stripFencedCode(markdown),
-    undefined,
-    TRANSPARENT_COMPONENTS,
-  );
+  const text = equationText(markdown);
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
-  const display = /\$\$([\s\S]+?)\$\$/g;
   for (const match of text.matchAll(heading)) {
     tokens.push({ kind: 'section', index: match.index });
   }
-  for (const match of text.matchAll(display)) {
+  for (const block of displayMathBlocks(text)) {
     EQ_LABEL_PATTERN.lastIndex = 0;
-    const label = EQ_LABEL_PATTERN.exec(match[1]);
+    const label = EQ_LABEL_PATTERN.exec(block.body);
     tokens.push({
       kind: 'equation',
-      index: match.index,
+      index: block.index,
       key: label ? label[1] : null,
-      short: equationCaption(match[1]),
+      short: equationCaption(block.body),
     });
   }
   tokens.sort((a, b) => a.index - b.index);
@@ -271,6 +347,31 @@ export function scanDisplayEquations(markdown, numbering) {
   return labels;
 }
 
+/**
+ * A lesson body as the equation scans read it: no fenced code, no component
+ * but the transparent ones, no `:::` directive body.
+ */
+function equationText(markdown) {
+  return stripContainerDirectives(
+    stripJsxComponents(stripFencedCode(markdown), undefined, TRANSPARENT_COMPONENTS),
+  );
+}
+
+/**
+ * The keys of each display block that carries more than one `\label{eq:…}`,
+ * in order. A block is one numbered equation: its first label names it, and
+ * a later one would name nothing.
+ */
+export function repeatedEquationLabels(markdown) {
+  return displayMathBlocks(equationText(markdown))
+    // A copy: `matchAll` starts at the shared pattern's `lastIndex`, which
+    // `scanDisplayEquations`' `exec` leaves past the label it found.
+    .map((block) =>
+      [...block.body.matchAll(new RegExp(EQ_LABEL_PATTERN.source, 'g'))].map((match) => match[1]),
+    )
+    .filter((keys) => keys.length > 1);
+}
+
 /** The keyed subset of `scanDisplayEquations` — the manifest builder's view. */
 export function scanEquationLabels(markdown, numbering) {
   return scanDisplayEquations(markdown, numbering).filter(
@@ -301,13 +402,16 @@ export function collectDisplayEquations(tree, numbering) {
   let indexInSection = 0;
   let indexInLesson = 0;
 
-  // Top-level blocks plus the bodies of the `TRANSPARENT_COMPONENTS`: other
-  // MDX components (a `<CompactExample>` worked example, an `<Aside>`) remain
-  // illustrative and outside the lesson's official equation sequence. The
-  // transparent ones occupy an exact point in the reading order, even while
-  // visually collapsed.
+  // The lesson's flow — top-level blocks, list items, blockquotes — plus the
+  // bodies of the `TRANSPARENT_COMPONENTS`: other MDX components (a
+  // `<CompactExample>` worked example, an `<Aside>`) and `:::note`-style
+  // asides remain illustrative and outside the lesson's official equation
+  // sequence. The transparent ones occupy an exact point in the reading
+  // order, even while visually collapsed. `scanDisplayEquations` reads the
+  // same set from the text.
   const collectFromDetail = (node) => {
     if (!node || typeof node !== 'object') return;
+    if (node.type === 'containerDirective') return;
     if (node.type === 'math') {
       indexInSection += 1;
       indexInLesson += 1;
@@ -347,13 +451,7 @@ export function collectDisplayEquations(tree, numbering) {
       indexInSection = 0;
       continue;
     }
-    if (node.type === 'math') collectFromDetail(node);
-    else if (
-      node.type === 'mdxJsxFlowElement' &&
-      TRANSPARENT_COMPONENTS.includes(node.name)
-    ) {
-      collectFromDetail(node);
-    }
+    collectFromDetail(node);
   }
   return equations;
 }

package/dist/reference/examples-validate.d.ts

@@ -12,7 +12,7 @@ import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } fr
  * no default title to fall back on.
  */
 
-type ExampleDiagnosticCode = 'ex-invalid-key' | 'ex-duplicate-key' | 'ex-ref-resolves' | 'ex-key-unused' | 'ex-removed-prop' | 'ex-missing-prop';
+type ExampleDiagnosticCode = 'ex-invalid-key' | 'ex-duplicate-key' | 'ex-ref-resolves' | 'ex-key-unused' | 'ex-removed-prop' | 'ex-unread-prop' | 'ex-missing-prop';
 interface ExampleDiagnostic {
     readonly code: ExampleDiagnosticCode;
     readonly severity: 'error' | 'warning' | 'info';

package/dist/reference/figure-fit.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Rule V7 — a figure's picture fits on one screen.
+ *
+ * A picture's height is only known once the browser has laid the page out and
+ * hydrated its islands, so this check runs in a course's Playwright suite, not
+ * in the build: open each lesson that has a figure, call
+ * {@link checkFigureFit}, and expect no findings. The pure half,
+ * {@link figureFitFindings}, turns measured heights into findings and is what
+ * the unit tests pin.
+ */
+/** The share of the screen height a picture may take unless the course sets `rules.V7.maxPercent`. */
+declare const FIGURE_FIT_MAX_PERCENT = 80;
+/** One `<Figure>` as measured on a rendered page. */
+interface FigureMeasurement {
+    /** The figure's anchor, `fig-<key>`. */
+    readonly anchor: string;
+    /** Its number, `2.1.3`. */
+    readonly number: string;
+    /** Height of the picture — the figure's default slot — in CSS pixels. */
+    readonly height: number;
+}
+interface FigureFitFinding {
+    readonly code: 'figure-too-tall';
+    readonly severity: 'warning';
+    readonly rule: 'V7';
+    readonly anchor: string;
+    readonly number: string;
+    readonly height: number;
+    /** The tallest picture the budget allows at this screen height, in CSS pixels. */
+    readonly limit: number;
+    readonly message: string;
+}
+/**
+ * The pictures taller than `maxPercent` of a `screenHeight`-pixel screen.
+ * A picture of height zero is skipped: nothing was drawn to judge.
+ */
+declare function figureFitFindings(measured: readonly FigureMeasurement[], screenHeight: number, maxPercent?: number): FigureFitFinding[];
+/** The part of a Playwright `Page` the check uses. */
+interface FigureFitPage {
+    evaluate<R>(pageFunction: () => R | Promise<R>): Promise<R>;
+    viewportSize(): {
+        readonly width: number;
+        readonly height: number;
+    } | null;
+}
+/**
+ * Measure every `<Figure>` on the open page and report the pictures that break
+ * rule V7 at the page's current viewport. A figure inside a closed `<Fold>` or
+ * `<details>` is opened first, since a reader can open it; each figure is
+ * scrolled into view and waits for its islands to hydrate and its height to
+ * settle before it is measured.
+ */
+declare function checkFigureFit(page: FigureFitPage, options?: {
+    readonly maxPercent?: number;
+    /** Figures exempt from the budget, by anchor (`fig-<key>`), each with the reason it may be taller. */
+    readonly allow?: Readonly<Record<string, string>>;
+}): Promise<FigureFitFinding[]>;
+/**
+ * The lesson paths whose manifest entry has at least one figure — the pages a
+ * course's V7 test opens. Pass the manifest the build wrote
+ * (`build/manifest.json`).
+ */
+declare function lessonsWithFigures(manifest: {
+    readonly lessons: readonly {
+        readonly slug: string;
+        readonly figures: readonly unknown[];
+    }[];
+}): string[];
+
+export { FIGURE_FIT_MAX_PERCENT, type FigureFitFinding, type FigureFitPage, type FigureMeasurement, checkFigureFit, figureFitFindings, lessonsWithFigures };

package/dist/reference/figure-fit.js

@@ -0,0 +1,60 @@
+const FIGURE_FIT_MAX_PERCENT = 80;
+function figureFitFindings(measured, screenHeight, maxPercent = FIGURE_FIT_MAX_PERCENT) {
+  const limit = Math.floor(screenHeight * maxPercent / 100);
+  return measured.filter((figure) => figure.height > limit).map((figure) => ({
+    code: "figure-too-tall",
+    severity: "warning",
+    rule: "V7",
+    anchor: figure.anchor,
+    number: figure.number,
+    height: figure.height,
+    limit,
+    message: `Figure ${figure.number} (#${figure.anchor}): its picture is ${figure.height}px tall, ${Math.round(figure.height / screenHeight * 100)}% of a ${screenHeight}px screen; rule V7 allows ${maxPercent}% (${limit}px). Give a square or tall plot a fixed width instead of the full column, or split stacked panels.`
+  }));
+}
+async function checkFigureFit(page, options = {}) {
+  const viewport = page.viewportSize();
+  if (!viewport) throw new Error("checkFigureFit needs a page with a fixed viewport size.");
+  const measured = await page.evaluate(measureFigures);
+  const allow = options.allow ?? {};
+  for (const [anchor, reason] of Object.entries(allow)) {
+    if (!reason.trim()) throw new Error(`checkFigureFit: the exemption for #${anchor} needs a reason.`);
+  }
+  return figureFitFindings(
+    measured.filter((figure) => !(figure.anchor in allow)),
+    viewport.height,
+    options.maxPercent
+  );
+}
+function lessonsWithFigures(manifest) {
+  return manifest.lessons.filter((lesson) => lesson.figures.length > 0).map((lesson) => `/${lesson.slug}/`);
+}
+async function measureFigures() {
+  const nextFrame = () => new Promise((resolve) => requestAnimationFrame(() => resolve()));
+  const out = [];
+  for (const figure of document.querySelectorAll("figure.keyed-figure")) {
+    for (let fold = figure.parentElement?.closest("details"); fold; fold = fold.parentElement?.closest("details")) {
+      fold.open = true;
+    }
+    const body = figure.querySelector(":scope > .keyed-figure__body");
+    if (!body) continue;
+    figure.scrollIntoView({ block: "start" });
+    const deadline = performance.now() + 5e3;
+    while (body.querySelector("astro-island[ssr]") && performance.now() < deadline) await nextFrame();
+    let height = -1;
+    for (let still = 0, frames = 0; still < 5 && frames < 120; frames++) {
+      await nextFrame();
+      const now = body.getBoundingClientRect().height;
+      still = Math.abs(now - height) < 0.5 ? still + 1 : 0;
+      height = now;
+    }
+    out.push({ anchor: figure.id, number: figure.dataset.figNumber ?? "", height: Math.round(height) });
+  }
+  return out;
+}
+export {
+  FIGURE_FIT_MAX_PERCENT,
+  checkFigureFit,
+  figureFitFindings,
+  lessonsWithFigures
+};