explico 0.12.0 → 0.13.1

package/src/reference/figure-fit.ts

@@ -0,0 +1,139 @@
+/**
+ * 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`. */
+export const FIGURE_FIT_MAX_PERCENT = 80;
+
+/** One `<Figure>` as measured on a rendered page. */
+export 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;
+}
+
+export 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.
+ */
+export function figureFitFindings(
+  measured: readonly FigureMeasurement[],
+  screenHeight: number,
+  maxPercent: number = FIGURE_FIT_MAX_PERCENT,
+): FigureFitFinding[] {
+  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.`,
+    }));
+}
+
+/** The part of a Playwright `Page` the check uses. */
+export 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.
+ */
+export async 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[]> {
+  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,
+  );
+}
+
+/**
+ * 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`).
+ */
+export function lessonsWithFigures(manifest: {
+  readonly lessons: readonly { readonly slug: string; readonly figures: readonly unknown[] }[];
+}): string[] {
+  return manifest.lessons.filter((lesson) => lesson.figures.length > 0).map((lesson) => `/${lesson.slug}/`);
+}
+
+/**
+ * Runs in the browser, so it must not close over anything in this module.
+ */
+async function measureFigures(): Promise<FigureMeasurement[]> {
+  const nextFrame = () => new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+  const out: FigureMeasurement[] = [];
+  for (const figure of document.querySelectorAll<HTMLElement>('figure.keyed-figure')) {
+    for (let fold = figure.parentElement?.closest('details'); fold; fold = fold.parentElement?.closest('details')) {
+      fold.open = true;
+    }
+    const body = figure.querySelector<HTMLElement>(':scope > .keyed-figure__body');
+    if (!body) continue;
+    figure.scrollIntoView({ block: 'start' });
+    // An island keeps its `ssr` attribute until it has hydrated.
+    const deadline = performance.now() + 5000;
+    while (body.querySelector('astro-island[ssr]') && performance.now() < deadline) await nextFrame();
+    // Then wait for the height to hold still for a few frames: a chart may
+    // size itself from its container after it mounts.
+    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;
+}

package/src/reference/figure-pictures.ts

@@ -0,0 +1,96 @@
+/**
+ * Every figure has its picture in the built page (rule V3). A lab draws its
+ * plot in the browser, after the page loads, so without a copy drawn at
+ * build time the page holds an empty box until then: a reference card made
+ * from the page (from another page, or before the figure scrolls into view)
+ * has only the caption, and so do print without JavaScript and the
+ * standalone HTML export. A lab draws its default picture at build time and
+ * hands it to its island as children (`still-plot.ts` in the playground).
+ *
+ * `undrawnFigurePictures` reads rendered HTML: a `figure.keyed-figure` whose
+ * picture (`.keyed-figure__body`) holds an `<astro-island>` but nothing drawn
+ * (`svg`, `img`, `picture`, `canvas`, `video` or `table`) is reported.
+ * `compiler/astro.ts` runs it on every built page and warns; it is a
+ * warning, not an error, since the figure still works once hydrated.
+ */
+
+import { parse, type DefaultTreeAdapterMap } from 'parse5';
+
+type HtmlNode = DefaultTreeAdapterMap['node'];
+type HtmlElement = DefaultTreeAdapterMap['element'];
+
+/** The diagnostic a built page with an undrawn picture gets. */
+export interface UndrawnFigurePicture {
+  readonly code: 'lab-picture-undrawn';
+  /** The figure's anchor id, e.g. `fig-launch-angle-explorer`. */
+  readonly figure: string;
+}
+
+const DRAWN = new Set(['svg', 'img', 'picture', 'canvas', 'video', 'table']);
+
+function isElement(node: HtmlNode): node is HtmlElement {
+  return 'tagName' in node;
+}
+
+function attribute(node: HtmlElement, name: string): string | undefined {
+  return node.attrs.find((attr) => attr.name === name)?.value;
+}
+
+function hasClass(node: HtmlElement, name: string): boolean {
+  return (attribute(node, 'class') ?? '').split(/\s+/u).includes(name);
+}
+
+/** Element children only; a `<template>`'s content is never drawn, so it is skipped. */
+function childrenOf(node: HtmlNode): readonly HtmlNode[] {
+  if (isElement(node) && node.tagName === 'template') return [];
+  return 'childNodes' in node ? node.childNodes : [];
+}
+
+function find(node: HtmlNode, test: (el: HtmlElement) => boolean): HtmlElement | undefined {
+  for (const child of childrenOf(node)) {
+    if (!isElement(child)) continue;
+    if (test(child)) return child;
+    const inner = find(child, test);
+    if (inner) return inner;
+  }
+  return undefined;
+}
+
+/** The figures in `html` whose picture is an island with nothing drawn. */
+export function undrawnFigurePictures(html: string): UndrawnFigurePicture[] {
+  // Most pages have no lab; they need no parse.
+  if (!html.includes('keyed-figure') || !html.includes('astro-island')) return [];
+  const found: UndrawnFigurePicture[] = [];
+  const visit = (node: HtmlNode) => {
+    for (const child of childrenOf(node)) {
+      if (!isElement(child)) continue;
+      if (child.tagName === 'figure' && hasClass(child, 'keyed-figure')) {
+        const body = find(child, (el) => hasClass(el, 'keyed-figure__body'));
+        if (
+          body &&
+          find(body, (el) => el.tagName === 'astro-island') &&
+          !find(body, (el) => DRAWN.has(el.tagName))
+        ) {
+          found.push({ code: 'lab-picture-undrawn', figure: attribute(child, 'id') ?? '' });
+        }
+      }
+      visit(child);
+    }
+  };
+  visit(parse(html));
+  return found;
+}
+
+/** The build's warning for one page, naming each figure and what to do. */
+export function undrawnFigureWarning(
+  page: string,
+  figures: readonly UndrawnFigurePicture[],
+): string {
+  return (
+    `lab-picture-undrawn (rule V3): on rendered page "${page}", ` +
+    figures.map(({ figure }) => `#${figure}`).join(', ') +
+    ' draw nothing until the browser runs the island, so a preview card, ' +
+    'print without JavaScript and the HTML export show no picture. Draw the ' +
+    'default picture at build time and pass it to the island as its children.'
+  );
+}

package/src/reference/figures-validate.ts

@@ -12,7 +12,8 @@ export type FigureDiagnosticCode =
   | 'fig-duplicate-key'
   | 'fig-ref-resolves'
   | 'fig-key-unused'
-  | 'fig-removed-prop';
+  | 'fig-removed-prop'
+  | 'fig-unread-prop';
 
 export interface FigureDiagnostic {
   readonly code: FigureDiagnosticCode;

package/src/reference/gate-abbreviations.ts

@@ -58,7 +58,7 @@ function findAbbreviationLikeTokens(text: string): AbbreviationMatch[] {
 
 const FIX =
   'Add it to an abbreviations-table entry (content/abbreviations/*.md), ' +
-  'allowlist it in abbreviations.allow in course.config.ts if it is common, ' +
+  'allowlist it in rules.N14.allow in the course config (course.config.ts, or the course.settings.json it reads) if it is common, ' +
   'non-technical usage, or — if it names a math quantity — introduce it as ' +
   '\\mathrm{…} (or \\operatorname{…}) bound to a notation entry the reader ' +
   'can hover. See docs/authoring/notation.md#n14.';

package/src/reference/gate-course-rules.ts

@@ -4,9 +4,10 @@
  *
  * One loop over every enabled course rule's `forbid` patterns, matched against
  * the same "is this really prose" surface rule N9 uses — `proseOnly` blanks
- * code fences, inline code, `$…$` / `$$…$$`, `[[key]]` references, `import`
- * lines, JSX tags and MDX comments to spaces, so offsets still point at the
- * source. A match becomes a `MathGateDiagnostic` with the rule's own ID as its
+ * code fences, inline code, `$…$` / `$$…$$`, `[[key]]` references, link
+ * addresses, `import` lines, JSX tags and MDX comments to spaces, so offsets
+ * still point at the source — plus the text of each visible prop (`caption`,
+ * `short`, `title`, `label`) as a paragraph of its own. A match becomes a `MathGateDiagnostic` with the rule's own ID as its
  * code and a lesson `file` + `line`, which is what lets `{/* explico-allow X1:
  * reason *\/}` waive one place.
  *
@@ -17,6 +18,7 @@
  */
 import type { MathGateDiagnostic } from './gate-math';
 import { lessonLine, proseOnly } from './gate-prose-notation';
+import { propStrings } from './gate-prop-text';
 import type { NotationLessonInput } from './types';
 import type { CourseRule, CourseRulePattern } from '../rules/course-rules';
 
@@ -69,14 +71,27 @@ function headings(text: string): Unit[] {
   return units;
 }
 
-function unitsFor(scope: CourseRulePattern['scope'], prose: string): Unit[] {
+/** The props whose text a reader sees: a float's or a memo's captions, a short note's title, a fold's bar. */
+const VISIBLE_PROPS = new Set(['caption', 'short', 'title', 'label']);
+
+/**
+ * Each visible prop's text, as a unit of its own: a caption is prose a reader
+ * sees, and a prop holds plain text (invariant `prop-text`).
+ */
+function visibleProps(body: string): Unit[] {
+  return propStrings(body)
+    .filter((prop) => VISIBLE_PROPS.has(prop.name) && prop.value.trim() !== '')
+    .map((prop) => ({ text: prop.value, index: prop.offset }));
+}
+
+function unitsFor(scope: CourseRulePattern['scope'], prose: string, body: string): Unit[] {
   switch (scope) {
     case 'prose':
-      return [{ text: prose, index: 0 }];
+      return [{ text: prose, index: 0 }, ...visibleProps(body)];
     case 'heading':
       return headings(prose);
     case 'paragraph':
-      return paragraphs(prose);
+      return [...paragraphs(prose), ...visibleProps(body)];
   }
 }
 
@@ -111,7 +126,7 @@ export function gateCourseRules(
     const cache = new Map<CourseRulePattern['scope'], Unit[]>();
     for (const rule of active) {
       for (const pattern of rule.forbid) {
-        if (!cache.has(pattern.scope)) cache.set(pattern.scope, unitsFor(pattern.scope, prose));
+        if (!cache.has(pattern.scope)) cache.set(pattern.scope, unitsFor(pattern.scope, prose, lesson.body));
         for (const unit of cache.get(pattern.scope)!) {
           for (const [index, token] of matches(pattern, unit)) {
             diagnostics.push({

package/src/reference/gate-heading-length.ts

@@ -21,6 +21,7 @@
  */
 import { EQ_CAPTION_PATTERN, stripFencedCode } from './equations.mjs';
 import { stripHeadingMarker } from './rehype-heading-anchors.mjs';
+import { headingDisplayText } from './sections.mjs';
 import type { MathGateDiagnostic } from './gate-math';
 import { lessonLine } from './gate-prose-notation';
 import type { NotationLessonInput } from './types';
@@ -67,14 +68,20 @@ function overLimitMessage(kind: string, text: string, limit: number): string {
   );
 }
 
-function headingFindings(text: string, limit: number): Finding[] {
+function headingFindings(
+  text: string,
+  limit: number,
+  labelFor?: (key: string) => string | undefined,
+): Finding[] {
   const out: Finding[] = [];
   const re = new RegExp(HEADING_LINE.source, HEADING_LINE.flags);
   let match: RegExpExecArray | null;
   while ((match = re.exec(text))) {
     const level = match[1]?.length ?? 1;
-    // What the reader sees: `[collapsed]`, `[card]` and the like never render.
-    const title = stripHeadingMarker(match[2] ?? '').trim();
+    // What the reader sees: `[collapsed]`, `[card]` and the like never
+    // render, a formula reads as its glyphs (`\explain{k}{R}` is `R`) and a
+    // `[[key]]` term as its label.
+    const title = headingDisplayText(stripHeadingMarker(match[2] ?? ''), { labelFor });
     if (title.length > limit) {
       out.push({
         index: match.index,
@@ -123,9 +130,13 @@ function equationCaptionFindings(text: string, limit: number): Finding[] {
 }
 
 /** Every S1 finding in one lesson body, in source order. */
-function findingsIn(text: string, limit: number): Finding[] {
+function findingsIn(
+  text: string,
+  limit: number,
+  labelFor?: (key: string) => string | undefined,
+): Finding[] {
   return [
-    ...headingFindings(text, limit),
+    ...headingFindings(text, limit, labelFor),
     ...floatTitleFindings(text, limit),
     ...equationCaptionFindings(text, limit),
   ].sort((a, b) => a.index - b.index);
@@ -138,14 +149,21 @@ function findingsIn(text: string, limit: number): Finding[] {
  */
 export function gateHeadingLength(
   lessons: readonly NotationLessonInput[],
-  options: { readonly maxLength?: number } = {},
+  options: {
+    readonly maxLength?: number;
+    /** A `[[key]]` term's label on a lesson's page, as a heading shows it. */
+    readonly labelFor?: (lessonId: string, key: string) => string | undefined;
+  } = {},
 ): MathGateDiagnostic[] {
   const diagnostics: MathGateDiagnostic[] = [];
   const limit = options.maxLength ?? HEADING_LENGTH_LIMIT;
 
   for (const lesson of lessons) {
     const text = stripFencedCode(lesson.body);
-    for (const finding of findingsIn(text, limit)) {
+    const labelFor = options.labelFor
+      ? (key: string) => options.labelFor?.(lesson.lessonId, key)
+      : undefined;
+    for (const finding of findingsIn(text, limit, labelFor)) {
       diagnostics.push({
         context: 'structure',
         code: 'title-length',

package/src/reference/gate-heading-structure.ts

@@ -83,7 +83,7 @@ function blocksOf(body: string): Block[] {
 }
 
 interface Finding {
-  readonly code: 'heading-skip' | 'heading-adjacent';
+  readonly code: 'heading-skip' | 'heading-adjacent' | 'heading-nested';
   readonly index: number;
   readonly token: string;
   readonly message: string;
@@ -129,6 +129,44 @@ function skipFindings(blocks: readonly Block[]): Finding[] {
   return out;
 }
 
+/** The components that title themselves below an `<h2>`: a memo (an `<h6>` bar) and a short note (inline). */
+const HOSTS = ['Memo', 'ShortNote'] as const;
+
+/**
+ * Rule S6: a component that draws an `<h2>` never sits inside a memo or a
+ * short note. Its heading would land under the host's own, the order would
+ * jump, and "On this page" would never list it.
+ */
+function nestedFindings(body: string): Finding[] {
+  const blank = (match: string) => match.replace(/[^\n]/g, ' ');
+  const text = body.replace(/```[\s\S]*?```/g, blank).replace(/\{\/\*[\s\S]*?\*\/\}/g, blank);
+  const out: Finding[] = [];
+  for (const host of HOSTS) {
+    const opening = new RegExp(`<${host}\\b(?:[^>"']|"[^"]*"|'[^']*')*(?<!/)>`, 'g');
+    for (const open of text.matchAll(opening)) {
+      const start = (open.index ?? 0) + open[0].length;
+      const end = text.indexOf(`</${host}>`, start);
+      if (end === -1) continue;
+      for (const inner of text.slice(start, end).matchAll(/<(AssessmentSet|CompactExamples)\b/g)) {
+        const name = inner[1]!;
+        const what = name === 'CompactExamples' ? 'set of worked examples' : 'knowledge check';
+        out.push({
+          code: 'heading-nested',
+          index: start + (inner.index ?? 0),
+          token: `<${name}>`,
+          message:
+            `\`<${name}>\` sits inside a \`<${host}>\`, ${TITLED_COMPONENTS[name]!.what}, ` +
+            `${host === 'Memo' ? 'under the memo’s own `<h6>`' : 'in the middle of the note'}: ` +
+            'the heading order jumps, and "On this page" never lists it (rule S6). A ' +
+            `${what} is a section of the lesson: put it at the top level, after the ` +
+            `${host === 'Memo' ? 'memo' : 'paragraph'}.`,
+        });
+      }
+    }
+  }
+  return out;
+}
+
 /** Rule S7: a heading is followed by body content before the next heading. */
 function adjacentFindings(blocks: readonly Block[], lesson: NotationLessonInput): Finding[] {
   const out: Finding[] = [];
@@ -174,6 +212,7 @@ export function gateHeadingStructure(
     const blocks = blocksOf(lesson.body);
     const findings = [
       ...(levels ? skipFindings(blocks) : []),
+      ...(levels ? nestedFindings(lesson.body) : []),
       ...(adjacency ? adjacentFindings(blocks, lesson) : []),
     ].sort((a, b) => a.index - b.index);
     for (const finding of findings) {