explico 0.13.0 → 0.14.0

package/src/reference/decks-validate.ts

@@ -0,0 +1,604 @@
+/**
+ * The deck rules (`docs/authoring/deck.md`): the `D` area and the `decks`
+ * invariant, over each deck read as frames (`deck-source.ts`). One pass per
+ * deck; the manifest runs it and drops the codes of a rule the course turned
+ * off, as for every gate.
+ *
+ * What it cannot see is the rendered fit of a frame (rule D2's
+ * `frame-overflow`), which the build measures in a browser after Astro has
+ * built the deck.
+ */
+import type { MathGateDiagnostic } from './gate-math';
+import { lessonLine } from './gate-prose-notation';
+import { frameAt, type DeckFrameSource, type DeckPause, type DeckSource } from './deck-source';
+
+/**
+ * What a chapter numbers, by kind: each key with its number, and an
+ * equation's LaTeX (for rule D8's retyped check). What a deck may recall.
+ */
+export interface ChapterFloats {
+  readonly equations: ReadonlyMap<string, { readonly number: string; readonly latex?: string }>;
+  readonly figures: ReadonlyMap<string, string>;
+  readonly tables: ReadonlyMap<string, string>;
+  readonly diagrams: ReadonlyMap<string, string>;
+}
+
+/** A part, as its deck's rules see it (`<part>/index.deck.mdx`). */
+export interface PartDeckFacts {
+  /** The part's directory: `motion`. */
+  readonly dir: string;
+  /**
+   * The part's chapters in reading order: each by its name in the part's
+   * directory (what `[chapter: <name>]` writes), with its lesson slug and
+   * what it numbers.
+   */
+  readonly chapters: readonly {
+    readonly name: string;
+    readonly slug: string;
+    readonly floats: ChapterFloats;
+  }[];
+  /** The part's lessons that are only slides, by name: they have no chapter to cover. */
+  readonly slidesFirst?: readonly string[];
+}
+
+/** One deck, as the manifest hands it to the rules. */
+export interface DeckValidationInput {
+  /** Repository-relative path of the deck file. */
+  readonly file: string;
+  /** The deck's page id (`motion.range.slides`, the lesson's own, or a part's `motion.slides`). */
+  readonly pageId: string;
+  /** True when the lesson has a chapter beside the deck. */
+  readonly hasChapter: boolean;
+  /** True when the deck sits in a part's directory, as a lesson does. */
+  readonly inPart: boolean;
+  readonly body: string;
+  /** 1-based file line the body starts on. */
+  readonly bodyLine: number;
+  /** The deck file's frontmatter. */
+  readonly data: Readonly<Record<string, unknown>>;
+  readonly source: DeckSource;
+  /** What the deck may recall from its chapter, by kind. */
+  readonly chapter?: ChapterFloats;
+  /** A part's deck: its part, whose chapters its sections may cover. */
+  readonly part?: PartDeckFacts;
+  /** Per frame of {@link source}, the notation keys it shows for the first time in the deck. */
+  readonly newSymbols?: readonly (readonly string[])[];
+}
+
+/** One chapter a part deck's section covers. */
+export interface CoveredChapter {
+  readonly name: string;
+  readonly slug: string;
+  readonly floats: ChapterFloats;
+  /** The section's place in {@link DeckSource.frames}: its divider. */
+  readonly position: number;
+}
+
+/** What a part's deck recalls, and from where (`resolvePartRecalls`). */
+export interface PartRecalls {
+  /** The chapters its sections cover, in deck order, each once. */
+  readonly covered: readonly CoveredChapter[];
+  /** Each frame's chapter, by its place in {@link DeckSource.frames}: its section's, when that names one of the part. */
+  readonly frameChapters: readonly (CoveredChapter | undefined)[];
+  /** The chapter each recalled float is the chapter's own, by its ref (`eq-range`). */
+  readonly chapterOf: ReadonlyMap<string, CoveredChapter>;
+  /** Why a recall names nothing, by its offset in the deck body. */
+  readonly problems: ReadonlyMap<number, string>;
+}
+
+const RECALL_TABLE = { eq: 'equations', fig: 'figures', tab: 'tables', dia: 'diagrams' } as const;
+
+/** The number a chapter gives the float `ref` names (`eq-range`, `fig-…`), if it numbers one. */
+export function chapterNumberOf(ref: string, floats: ChapterFloats | undefined): string | undefined {
+  const match = RECALL_REF.exec(ref);
+  if (!match || floats === undefined) return undefined;
+  const [, kind, key] = match;
+  if (kind === 'eq') return floats.equations.get(key ?? '')?.number;
+  return floats[RECALL_TABLE[kind as 'fig' | 'tab' | 'dia']].get(key ?? '');
+}
+
+/**
+ * The chapters a part deck's sections cover: each a `## Title [chapter:
+ * <name>]` whose name is one of `chapters`, in deck order and once (a
+ * repeat is the same chapter), with the place of its divider in
+ * `source.frames`; and each frame's chapter, its section's. The divider's
+ * frame number is that place plus 2, after the title frame.
+ */
+export function coveredSections(
+  source: DeckSource,
+  chapters: ReadonlySet<string>,
+): {
+  readonly covered: readonly { readonly name: string; readonly position: number }[];
+  readonly frameChapters: readonly (string | undefined)[];
+} {
+  const covered: { name: string; position: number }[] = [];
+  const frameChapters: (string | undefined)[] = [];
+  let current: string | undefined;
+  source.frames.forEach((frame, position) => {
+    if (frame.kind === 'section') {
+      current = frame.chapter !== undefined && chapters.has(frame.chapter) ? frame.chapter : undefined;
+      if (current !== undefined && !covered.some((entry) => entry.name === current)) {
+        covered.push({ name: current, position });
+      }
+    }
+    frameChapters.push(current);
+  });
+  return { covered, frameChapters };
+}
+
+/**
+ * Where each recall of a part's deck comes from. A section that names a
+ * chapter covers it; a recall is the float of the chapter its section
+ * covers when that chapter numbers it, and otherwise of the one other
+ * covered chapter that does. Two that do, with neither the section's own,
+ * or a ref one frame recalls from one chapter and another from a second,
+ * name no float of their own: a deck page holds one float per anchor.
+ */
+export function resolvePartRecalls(source: DeckSource, part: PartDeckFacts): PartRecalls {
+  const byName = new Map(part.chapters.map((chapter) => [chapter.name, chapter]));
+  const sections = coveredSections(source, new Set(byName.keys()));
+  const covered: CoveredChapter[] = sections.covered.map(({ name, position }) => ({ ...byName.get(name)!, position }));
+  const frameChapters = sections.frameChapters.map((name) =>
+    name === undefined ? undefined : covered.find((chapter) => chapter.name === name),
+  );
+
+  const chapterOf = new Map<string, CoveredChapter>();
+  const problems = new Map<number, string>();
+  source.frames.forEach((frame, position) => {
+    const own = frameChapters[position];
+    for (const recall of frame.recalls) {
+      if (recall.ref === undefined || !RECALL_REF.test(recall.ref)) continue;
+      const ref = recall.ref;
+      const numbering = covered.filter((chapter) => chapterNumberOf(ref, chapter.floats) !== undefined);
+      const from =
+        own !== undefined && numbering.includes(own) ? own : numbering.length === 1 ? numbering[0] : undefined;
+      const earlier = chapterOf.get(ref);
+      if (from === undefined) {
+        problems.set(
+          recall.index,
+          numbering.length === 0
+            ? covered.length === 0
+              ? `recalls \`${ref}\`, but no section of this deck names a chapter to recall from (\`## Title [chapter: <name>]\`)`
+              : `recalls \`${ref}\`, which no chapter this deck covers numbers (${covered.map((chapter) => chapter.slug).join(', ')})`
+            : `recalls \`${ref}\`, which ${numbering.map((chapter) => chapter.slug).join(' and ')} each number: ` +
+              `recall it in the section that names the chapter you mean`,
+        );
+      } else if (earlier !== undefined && earlier !== from) {
+        problems.set(
+          recall.index,
+          `recalls \`${ref}\` from ${from.slug}, where an earlier frame recalls it from ${earlier.slug}: ` +
+            'a deck shows one float under one anchor',
+        );
+      } else {
+        chapterOf.set(ref, from);
+      }
+    }
+  });
+  return { covered, frameChapters, chapterOf, problems };
+}
+
+export interface DeckRuleSettings {
+  /** D2 */
+  readonly maxWords: number;
+  readonly maxBullets: number;
+  /** D5 */
+  readonly maxTitleLength: number;
+  /** D6 */
+  readonly maxSteps: number;
+  /** D9 */
+  readonly maxNewSymbols: number;
+}
+
+export const DECK_RULE_DEFAULTS: DeckRuleSettings = {
+  maxWords: 70,
+  maxBullets: 7,
+  maxTitleLength: 50,
+  maxSteps: 4,
+  maxNewSymbols: 4,
+};
+
+/** Frontmatter a lesson's chapter holds for the lesson; a deck beside it does not set it. */
+const LESSON_FIELDS = ['teaches', 'assumptions', 'studyMinutes', 'notation'] as const;
+const RECALL_REF = /^(eq|fig|tab|dia)-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+const NOTATION_KEY = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+
+/**
+ * A display equation's LaTeX as rule D8 compares it: no `\label` or
+ * `\caption`, each `\explain{key}{body}` as its body, no spacing commands, no
+ * `\left` / `\right`, no whitespace.
+ */
+export function comparableLatex(latex: string): string {
+  let text = String(latex)
+    .replace(/\\label\{[^{}]*\}/g, '')
+    .replace(/\\caption\{(?:[^{}]|\{[^{}]*\})*\}/g, '');
+  // `\explain{key}{body}` → `body`, innermost first, until none is left.
+  for (let guard = 0; guard < 20 && /\\explain\s*\{/.test(text); guard += 1) {
+    text = text.replace(/\\explain\s*\{[^{}]*\}\s*\{((?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*)\}/g, '$1');
+  }
+  return text
+    .replace(/\\(?:left|right|big|Big|bigg|Bigg)(?![A-Za-z])/g, '')
+    .replace(/\\(?:,|;|:|!|quad|qquad)(?![A-Za-z])/g, '')
+    .replace(/\s+/g, '');
+}
+
+function frameName(frame: DeckFrameSource): string {
+  return `${frame.kind === 'section' ? '##' : '###'} ${JSON.stringify(frame.title)}`;
+}
+
+export function validateDecks(
+  decks: readonly DeckValidationInput[],
+  settings: DeckRuleSettings = DECK_RULE_DEFAULTS,
+): MathGateDiagnostic[] {
+  const diagnostics: MathGateDiagnostic[] = [];
+  for (const deck of decks) {
+    const lineAt = (index: number) => lessonLine({ body: deck.body, bodyLine: deck.bodyLine }, index);
+    const push = (finding: Finding) => {
+      const { index, ...rest } = finding;
+      diagnostics.push({
+        context: 'structure',
+        file: deck.file,
+        ...(index === undefined ? {} : { line: lineAt(index) }),
+        ...rest,
+      });
+    };
+
+    const { source, part } = deck;
+    if (!deck.inPart) {
+      push({
+        code: 'deck-outside-part',
+        severity: 'error',
+        message:
+          part !== undefined
+            ? `${deck.file} is the deck of content/docs/${part.dir}/, which no part in course.settings.json \`parts\` lists. ` +
+              `A part's deck sits in a part's directory: add { "dir": "${part.dir}", "label": "…" } to \`parts\`, or move it.`
+            : `${deck.file} is a deck outside a part's directory. A deck is the slide edition of a lesson: ` +
+              "put it beside the lesson, `content/docs/<part>/<lesson>.deck.mdx`, or make it a part's, `content/docs/<part>/index.deck.mdx`.",
+      });
+    }
+    if (deck.hasChapter || part !== undefined) {
+      const set = LESSON_FIELDS.filter((field) => deck.data[field] !== undefined);
+      if (set.length > 0) {
+        push({
+          code: 'deck-frontmatter',
+          severity: 'error',
+          message:
+            part !== undefined
+              ? `${deck.file} sets ${set.map((field) => `\`${field}\``).join(', ')}. A part's deck is no lesson: it sets only ` +
+                "`title` and `description`, and shows its chapters' symbols and outcomes."
+              : `${deck.file} sets ${set.map((field) => `\`${field}\``).join(', ')}, which the lesson's chapter holds. ` +
+                'A deck beside its chapter sets only `title` and `description`; move the rest into the chapter.',
+        });
+      }
+    }
+
+    // A part's deck: each `## Title [chapter: <name>]` names one chapter of
+    // the part. A chapter may run over several sections in a row, each
+    // naming it, the first one's divider its address in the deck; never two
+    // runs. Elsewhere the marker means nothing.
+    const partRecalls = part === undefined ? undefined : resolvePartRecalls(source, part);
+    const named = new Set<string>();
+    // The chapter the section before named: a run goes on while it is the same.
+    let previous: string | undefined;
+    for (const frame of source.frames) {
+      if (frame.kind !== 'section') continue;
+      const before = previous;
+      previous = frame.chapter;
+      if (frame.chapter === undefined) continue;
+      const chapter = frame.chapter;
+      if (part === undefined) {
+        push({
+          code: 'deck-chapter-outside-part',
+          severity: 'error',
+          message:
+            `${frameName(frame)} names the chapter \`${chapter}\`, but this is a lesson's deck, which covers its own lesson. ` +
+            "Only a part's deck (`content/docs/<part>/index.deck.mdx`) names the chapter a section covers; drop the `[chapter: …]` marker.",
+          index: frame.index,
+          token: chapter,
+        });
+      } else if (!part.chapters.some((entry) => entry.name === chapter)) {
+        push({
+          code: 'deck-chapter-unknown',
+          severity: 'error',
+          message: (part.slidesFirst ?? []).includes(chapter)
+            ? `${frameName(frame)} names \`${chapter}\`, a lesson of ${part.dir} taught as slides only: it has no chapter to cover. ` +
+              'Drop the marker, or name a chapter of the part.'
+            : `${frameName(frame)} names \`${chapter}\`, which is no chapter of ${part.dir}. ` +
+              (part.chapters.length > 0
+                ? `Its chapters are ${part.chapters.map((entry) => `\`${entry.name}\``).join(', ')}: name one by its file's name.`
+                : 'The part has no chapter: drop the marker.'),
+          index: frame.index,
+          token: chapter,
+        });
+      } else if (named.has(chapter) && before !== chapter) {
+        push({
+          code: 'deck-chapter-repeated',
+          severity: 'error',
+          message:
+            `${frameName(frame)} names \`${chapter}\`, which an earlier section of the deck covers already, with a section of ` +
+            "another chapter or of the deck's own between them. A chapter's sections follow one another, the first one's divider " +
+            "the chapter's address in the deck: move this section up to the others.",
+          index: frame.index,
+          token: chapter,
+        });
+      } else {
+        named.add(chapter);
+      }
+    }
+    if (part !== undefined && [...part.chapters.map((entry) => entry.name), ...(part.slidesFirst ?? [])].includes('slides')) {
+      push({
+        code: 'deck-route-taken',
+        severity: 'error',
+        message:
+          `${deck.file} is served at /${part.dir}/slides/, which is the address of the lesson content/docs/${part.dir}/slides. ` +
+          "Rename the lesson's file, or the part keeps no deck of its own.",
+      });
+    }
+    for (const marker of source.misplacedMarkers) {
+      push({
+        code: 'deck-marker-misplaced',
+        severity: 'error',
+        message:
+          marker.marker === 'chapter'
+            ? `### ${JSON.stringify(marker.title)} carries \`[chapter: …]\`, which a section's \`##\` heading carries: ` +
+              'it names the chapter the whole section covers. Move it to the section.'
+            : `## ${JSON.stringify(marker.title)} carries \`[morph]\`, which a frame's \`###\` heading carries: ` +
+              'a section divider shows its title alone and has nothing to morph from. Drop it, or move it to the frame.',
+        index: marker.index,
+        token: marker.title,
+      });
+    }
+
+    const frames = source.frames.filter((frame) => frame.kind === 'frame');
+    if (frames.length === 0) {
+      push({
+        code: 'deck-empty',
+        severity: 'error',
+        message: `${deck.file} has no frame. A frame is a \`###\` heading and what follows it (rule D1).`,
+      });
+    }
+    for (const heading of source.deepHeadings) {
+      push({
+        code: 'frame-depth',
+        severity: 'error',
+        message:
+          `A ${'#'.repeat(heading.level)} heading ${JSON.stringify(heading.text)} in a deck (rule D1): ` +
+          '`##` opens a section and `###` is a frame; nothing else is a heading here. Make it a frame, or bold text in the frame.',
+        index: heading.index,
+        token: heading.text,
+      });
+    }
+    for (const loose of source.loose) {
+      const section = loose.where === 'section' ? frameAt(source, loose.index) : undefined;
+      push({
+        code: 'deck-loose-content',
+        severity: 'error',
+        message:
+          loose.where === 'before'
+            ? "Content before the deck's first heading belongs to no frame (rule D1). Put it in a `###` frame; the title frame is generated."
+            : `Content under ${section ? frameName(section) : 'a section heading'} before its first \`###\` frame (rule D1): ` +
+              'a section is a divider that shows only its title. Put the content in a `###` frame.',
+        index: loose.index,
+      });
+    }
+
+    for (const [position, frame] of source.frames.entries()) {
+      if (frame.title.length > settings.maxTitleLength) {
+        push({
+          code: 'frame-title-length',
+          severity: 'error',
+          message:
+            `${frameName(frame)} is ${frame.title.length} characters, over the ${settings.maxTitleLength}-character ` +
+            'limit (rule D5, `rules.D5.maxLength`): a frame title stays on one line. Shorten it and move the rest into the frame.',
+          index: frame.index,
+          token: frame.title,
+        });
+      }
+      if (frame.kind !== 'frame') continue;
+      checkFrame(frame, position);
+    }
+
+    function checkFrame(frame: DeckFrameSource, position: number): void {
+      if (frame.words > settings.maxWords || frame.bullets > settings.maxBullets) {
+        const over = [
+          frame.words > settings.maxWords ? `${frame.words} words (most ${settings.maxWords})` : '',
+          frame.bullets > settings.maxBullets ? `${frame.bullets} list items (most ${settings.maxBullets})` : '',
+        ].filter(Boolean);
+        push({
+          code: 'frame-dense',
+          severity: 'warning',
+          message:
+            `${frameName(frame)} shows ${over.join(' and ')} (rule D2): it will not fit its canvas. ` +
+            'Split it into two frames, or move the argument into its `<Notes>`.',
+          index: frame.index,
+          token: frame.title,
+        });
+      }
+      if ((frame.words > 0 || frame.bullets > 0) && frame.notes.length === 0) {
+        push({
+          code: 'frame-notes-missing',
+          severity: 'warning',
+          message:
+            `${frameName(frame)} has text but no \`<Notes>\` (rule D4): write what the speaker says — the reasoning, ` +
+            'the transition, the question to ask — in `<Notes>…</Notes>` on the frame.',
+          index: frame.index,
+          token: frame.title,
+        });
+      }
+      const steps = frame.pauses.length + 1;
+      if (steps > settings.maxSteps) {
+        push({
+          code: 'frame-steps',
+          severity: 'warning',
+          message:
+            `${frameName(frame)} shows in ${steps} steps, more than ${settings.maxSteps} (rule D6, \`rules.D6.maxSteps\`). ` +
+            'Make the later steps a frame of their own.',
+          index: frame.index,
+          token: frame.title,
+        });
+      }
+
+      const pictures =
+        frame.floats.filter((float) => float.name === 'Figure' || float.name === 'Table' || float.name === 'Diagram').length +
+        frame.recalls.filter((recall) => recall.ref !== undefined && !recall.ref.startsWith('eq-')).length;
+      if (pictures > 1) {
+        push({
+          code: 'frame-floats',
+          severity: 'warning',
+          message:
+            `${frameName(frame)} holds ${pictures} figures, tables or diagrams (rule D7): one per frame, at the canvas width. ` +
+            'Give the second its own frame.',
+          index: frame.index,
+          token: frame.title,
+        });
+      }
+
+      const drivesSomething =
+        frame.floats.some((float) => float.name === 'Figure') ||
+        frame.recalls.some((recall) => recall.ref?.startsWith('fig-') === true);
+      for (const pause of frame.pauses) {
+        const problems = pauseProblems(pause, drivesSomething);
+        if (problems.length > 0) {
+          push({
+            code: 'pause-invalid',
+            severity: 'error',
+            message: `<Pause> on ${frameName(frame)}: ${problems.join('; ')}. See docs/authoring/deck.md, "Steps and animation".`,
+            index: pause.index,
+          });
+        }
+      }
+
+      for (const recall of frame.recalls) {
+        const problem =
+          partRecalls === undefined
+            ? recallProblem(recall.ref, deck)
+            : (recallFormProblem(recall.ref) ?? partRecalls.problems.get(recall.index));
+        if (problem !== undefined) {
+          push({
+            code: 'recall-unresolved',
+            severity: 'error',
+            message:
+              `<Recall> on ${frameName(frame)} ${problem}. A recall names a labelled equation (\`eq-<key>\`) or a ` +
+              (partRecalls === undefined
+                ? "keyed `<Figure>`, `<Table>` or `<Diagram>` of the deck's own chapter."
+                : 'keyed `<Figure>`, `<Table>` or `<Diagram>` of a chapter a section of the deck covers.'),
+            index: recall.index,
+            ...(recall.ref === undefined ? {} : { token: recall.ref }),
+          });
+        }
+      }
+
+      // A question frame on a part's deck asks its section's chapter's checks.
+      if (
+        part !== undefined &&
+        frame.chapter === undefined &&
+        frame.floats.some((float) => float.name === 'AssessmentSet')
+      ) {
+        push({
+          code: 'deck-check-no-chapter',
+          severity: 'error',
+          message:
+            `${frameName(frame)} holds <AssessmentSet>, but its section names no chapter. On a part's deck a question ` +
+            "frame asks the checks of the chapter its section covers: move it into a `## Title [chapter: <name>]` section.",
+          index: frame.floats.find((float) => float.name === 'AssessmentSet')?.index ?? frame.index,
+          token: frame.title,
+        });
+      }
+
+      // Rule D8: on a part's deck, the equations of the chapters it covers.
+      const chapterEquations = (
+        partRecalls === undefined
+          ? [...(deck.chapter?.equations ?? new Map<string, { number: string; latex?: string }>())]
+          : partRecalls.covered.flatMap((chapter) => [...chapter.floats.equations])
+      ).filter(([, equation]) => equation.latex !== undefined);
+      if (chapterEquations.length > 0) {
+        for (const math of frame.displayMath) {
+          const mine = comparableLatex(math.latex);
+          if (mine === '') continue;
+          const same = chapterEquations.find(([, equation]) => comparableLatex(equation.latex ?? '') === mine);
+          if (same) {
+            push({
+              code: 'frame-retyped',
+              severity: 'warning',
+              message:
+                `${frameName(frame)} retypes the chapter's equation (${same[1].number}) (rule D8). ` +
+                `Write <Recall ref="eq-${same[0]}" /> instead: it shows the chapter's number and links to it.`,
+              index: math.index,
+              token: `eq-${same[0]}`,
+            });
+          }
+        }
+      }
+
+      const fresh = deck.newSymbols?.[position] ?? [];
+      if (fresh.length > settings.maxNewSymbols) {
+        push({
+          code: 'frame-new-symbols',
+          severity: 'info',
+          message:
+            `${frameName(frame)} introduces ${fresh.length} symbols the deck has not shown before ` +
+            `(${fresh.join(', ')}), more than ${settings.maxNewSymbols} (rule D9). Introduce some on an earlier frame.`,
+          index: frame.index,
+          token: frame.title,
+        });
+      }
+    }
+  }
+  return diagnostics;
+}
+
+interface Finding {
+  readonly code: string;
+  readonly severity: 'error' | 'warning' | 'info';
+  readonly message: string;
+  /** Offset in the deck body; the finding's line is worked out from it. */
+  readonly index?: number;
+  readonly token?: string;
+}
+
+/** What is wrong with a `<Pause>`'s props, if anything. */
+function pauseProblems(pause: DeckPause, drivesSomething: boolean): string[] {
+  const problems: string[] = [];
+  if (pause.unknown.length > 0) {
+    problems.push(`takes no ${pause.unknown.map((name) => `\`${name}\``).join(', ')}`);
+  }
+  const drives =
+    pause.control !== undefined || pause.to !== undefined || pause.from !== undefined || pause.seconds !== undefined;
+  if (drives && pause.highlight !== undefined) {
+    problems.push('either drives a figure (`control`, `to`) or lights a symbol (`highlight`), not both');
+  }
+  if (drives && (pause.control === undefined || pause.control.trim() === '' || pause.to === undefined)) {
+    problems.push('drives a figure with both `control` (the label of the lab’s control) and `to`');
+  }
+  for (const name of ['from', 'to', 'seconds'] as const) {
+    const value = pause[name];
+    if (value !== undefined && !Number.isFinite(Number(value))) {
+      problems.push(`\`${name}="${value}"\` is not a number`);
+    }
+  }
+  if (pause.seconds !== undefined && Number(pause.seconds) <= 0) {
+    problems.push('`seconds` is more than zero');
+  }
+  if (pause.control !== undefined && !drivesSomething) {
+    problems.push('drives a lab control, but the frame has no `<Figure>` or recalled figure to drive');
+  }
+  if (pause.highlight !== undefined && !NOTATION_KEY.test(pause.highlight)) {
+    problems.push(`\`highlight="${pause.highlight}"\` is not a notation key`);
+  }
+  return problems;
+}
+
+/** What is wrong with a `<Recall ref>` as written, whatever it names, or `undefined`. */
+function recallFormProblem(ref: string | undefined): string | undefined {
+  if (ref === undefined) return 'has no `ref`';
+  return RECALL_REF.test(ref) ? undefined : `\`ref="${ref}"\` is not \`eq-\`, \`fig-\`, \`tab-\` or \`dia-\` and a key`;
+}
+
+/** Why a `<Recall ref>` on a lesson's deck names nothing, or `undefined` when it resolves. */
+function recallProblem(ref: string | undefined, deck: DeckValidationInput): string | undefined {
+  const form = recallFormProblem(ref);
+  if (form !== undefined || ref === undefined) return form;
+  if (!deck.hasChapter || deck.chapter === undefined) {
+    return `recalls \`${ref}\`, but this lesson has no chapter to recall from`;
+  }
+  return chapterNumberOf(ref, deck.chapter) === undefined ? `recalls \`${ref}\`, which the chapter does not number` : undefined;
+}

package/src/reference/diagram-layout.ts

@@ -199,7 +199,9 @@ export function layoutDiagram(
 //
 // The constants mirror `Diagram.astro`'s `.diagram-node-content`, set in px
 // so a reader's font size cannot outgrow a box: `font-size: 13.6px`,
-// `line-height: 1.25`, `padding: 3.2px 8px`, `gap: 2.4px`.
+// `line-height: 1.25`, `padding: 3.2px 8px`, `gap: 2.4px`. The page's text-size
+// menu shrinks the finished drawing as a whole (`.diagram-frame` in
+// `Diagram.astro`), so these stay the build-time numbers at every size.
 
 /** A node's text font size, in px. */
 export const NODE_FONT_PX = 13.6;