explico 0.13.1 → 0.15.0

package/src/reference/deck-remark.mjs

@@ -0,0 +1,600 @@
+/**
+ * The remark half of a deck page (`<lesson>.deck.mdx`, docs/authoring/deck.md).
+ * `remark-notation.mjs` calls it on a deck: before its own pass, to expand
+ * each `<Recall ref>` into the chapter's float, stamp the frame headings with
+ * the manifest's anchors and numbers, and open the deck on its title frame;
+ * after it, to write each frame's legend line and close the deck on its
+ * outcomes frame. The rehype half (`rehype-deck.mjs`) wraps the frames.
+ *
+ * A deck is a page of its own lesson: its math binds in the chapter's scope
+ * (the chapter's `notation.local`), its numbers are the chapter's for what it
+ * recalls and its own (1), (2) for the equations it labels, and its figures,
+ * tables and diagrams are otherwise unnumbered (rule D8).
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parseFrontmatter } from '@astrojs/markdown-remark';
+import { EQ_CAPTION_PATTERN, EQ_LABEL_PATTERN, equationCaption } from './equations.mjs';
+import { injectMdxStringAttributes } from './mdx-attributes.mjs';
+
+const DECK_DOC_PATH = /[\\/]content[\\/]docs[\\/](.+?)\.deck\.(?:md|mdx)$/;
+const PART_DECK_SLUG = /^([^/]+)\/index$/;
+
+/**
+ * The deck a docs file is, or `undefined`. A lesson's: `{ scope: 'lesson',
+ * lessonSlug, lessonId, path, chapterPath }`, the chapter being the lesson's
+ * `.mdx` (or `.md`) beside it. A part's (`<part>/index.deck.mdx`): `{ scope:
+ * 'part', partDir, pageId, path }`, its page id `<part>.slides`.
+ */
+export function deckOfFile(file) {
+  for (const value of [file?.path, file?.history?.[0], file?.data?.file]) {
+    if (typeof value !== 'string') continue;
+    const match = DECK_DOC_PATH.exec(value);
+    if (!match) continue;
+    const slug = match[1].replace(/\\/g, '/');
+    const part = PART_DECK_SLUG.exec(slug);
+    if (part) return { scope: 'part', path: value, partDir: part[1], pageId: `${part[1]}.slides` };
+    const stem = value.replace(/\.deck\.(?:md|mdx)$/, '');
+    const chapterPath = ['.mdx', '.md'].map((extension) => `${stem}${extension}`).find((path) => existsSync(path));
+    return {
+      scope: 'lesson',
+      path: value,
+      lessonSlug: slug,
+      lessonId: slug.replace(/\//g, '.'),
+      ...(chapterPath === undefined ? {} : { chapterPath }),
+    };
+  }
+  return undefined;
+}
+
+/**
+ * The chapter file of a lesson of a part's deck's part (`motion/range` →
+ * `…/motion/range.mdx`, or `.md`), beside the deck, if there is one.
+ */
+export function partChapterPath(deck, lessonSlug) {
+  const name = String(lessonSlug).split('/').at(-1) ?? '';
+  return ['.mdx', '.md'].map((extension) => join(dirname(deck.path), `${name}${extension}`)).find((path) => existsSync(path));
+}
+
+/**
+ * The chapter files whose scope a deck's symbols bind in, in order: a
+ * lesson's deck its chapter (none for a slides-first lesson); a part's deck
+ * every chapter of its part, in reading order (`manifest.parts[].lessons`).
+ */
+export function deckScopeChapters(deck, manifest) {
+  if (deck.scope !== 'part') return deck.chapterPath ? [deck.chapterPath] : [];
+  const lessons = new Map((manifest?.lessons ?? []).map((lesson) => [lesson.id, lesson]));
+  const part = (manifest?.parts ?? []).find((entry) => entry.dir === deck.partDir);
+  return (part?.lessons ?? []).flatMap((id) => {
+    const lesson = lessons.get(id);
+    if (!lesson || !(lesson.editions ?? ['chapter']).includes('chapter')) return [];
+    const path = partChapterPath(deck, lesson.slug);
+    return path ? [path] : [];
+  });
+}
+
+const chapterCache = new Map();
+
+/** A chapter file's frontmatter and body, read once per change of the file. */
+export function readChapter(chapterPath) {
+  const mtime = statSync(chapterPath).mtimeMs;
+  const cached = chapterCache.get(chapterPath);
+  if (cached && cached.mtime === mtime) return cached;
+  const raw = readFileSync(chapterPath, 'utf8');
+  const parsed = parseFrontmatter(raw);
+  const entry = {
+    mtime,
+    data: parsed.frontmatter ?? {},
+    body: parsed.content.replace(/^\n/, ''),
+  };
+  chapterCache.set(chapterPath, entry);
+  return entry;
+}
+
+/**
+ * The manifest's deck for a deck file (`deckOfFile`) — a lesson's or a
+ * part's — or, given a lesson id, for that lesson, if there is one.
+ */
+export function manifestDeckOf(manifest, owner) {
+  const decks = manifest?.decks ?? [];
+  if (typeof owner === 'string') return decks.find((deck) => deck.lessonId === owner);
+  return owner?.scope === 'part'
+    ? decks.find((deck) => deck.part === owner.partDir)
+    : decks.find((deck) => deck.lessonId === owner?.lessonId);
+}
+
+// --- tree helpers -------------------------------------------------------
+
+function el(hName, hProperties, children = []) {
+  return { type: 'paragraph', data: { hName, hProperties }, children };
+}
+
+function text(value) {
+  return { type: 'text', value };
+}
+
+function stringAttribute(node, name) {
+  const attribute = (node?.attributes ?? []).find(
+    (candidate) => candidate?.type === 'mdxJsxAttribute' && candidate.name === name,
+  );
+  return typeof attribute?.value === 'string' ? attribute.value : undefined;
+}
+
+function stripPositions(node) {
+  if (!node || typeof node !== 'object') return node;
+  delete node.position;
+  if (Array.isArray(node.children)) node.children.forEach(stripPositions);
+  if (Array.isArray(node.attributes)) node.attributes.forEach(stripPositions);
+  return node;
+}
+
+/** Visit every node with its parent and index; `skip` returning true keeps out of a subtree. */
+function walk(node, visit, parent, index) {
+  if (!node || typeof node !== 'object') return;
+  if (visit(node, parent, index) === false) return;
+  if (!Array.isArray(node.children)) return;
+  for (let position = 0; position < node.children.length; position += 1) {
+    walk(node.children[position], visit, node, position);
+  }
+}
+
+function labelKeyOf(latex) {
+  EQ_LABEL_PATTERN.lastIndex = 0;
+  const match = EQ_LABEL_PATTERN.exec(String(latex ?? ''));
+  EQ_LABEL_PATTERN.lastIndex = 0;
+  return match ? match[1] : undefined;
+}
+
+/** The identifiers a JSX subtree uses as components: `Figure`, `RangeLab`, `Plot` of `Plot.Line`. */
+function componentNames(node) {
+  const names = new Set();
+  walk(node, (child) => {
+    if ((child.type === 'mdxJsxFlowElement' || child.type === 'mdxJsxTextElement') && typeof child.name === 'string') {
+      const root = child.name.split('.')[0];
+      if (/^[A-Z]/.test(root)) names.add(root);
+    }
+  });
+  return names;
+}
+
+/** Each local name an ESM node of `tree` binds: `{ name → { source, imported } }`. */
+function importedNames(tree) {
+  const names = new Map();
+  for (const node of tree.children ?? []) {
+    if (node?.type !== 'mdxjsEsm') continue;
+    for (const statement of node.data?.estree?.body ?? []) {
+      if (statement.type !== 'ImportDeclaration') continue;
+      const source = statement.source?.value;
+      for (const specifier of statement.specifiers ?? []) {
+        const local = specifier.local?.name;
+        if (!local) continue;
+        names.set(local, {
+          source,
+          imported:
+            specifier.type === 'ImportDefaultSpecifier'
+              ? 'default'
+              : specifier.type === 'ImportNamespaceSpecifier'
+                ? '*'
+                : (specifier.imported?.name ?? specifier.imported?.value ?? local),
+        });
+      }
+    }
+  }
+  return names;
+}
+
+function importStatement(local, { source, imported }) {
+  const from = JSON.stringify(source);
+  if (imported === 'default') return `import ${local} from ${from};`;
+  if (imported === '*') return `import * as ${local} from ${from};`;
+  return imported === local ? `import { ${local} } from ${from};` : `import { ${imported} as ${local} } from ${from};`;
+}
+
+// --- recall -------------------------------------------------------------
+
+const RECALL_REF = /^(eq|fig|tab|dia)-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+const FLOAT_TAG = { fig: 'Figure', tab: 'Table', dia: 'Diagram' };
+const NUMBER_TABLE = { eq: 'equations', fig: 'figures', tab: 'tables', dia: 'diagrams' };
+
+/**
+ * Replace each `<Recall ref="eq-…" />` (or `fig-`, `tab-`, `dia-`) with the
+ * chapter's own float, parsed from the chapter with this page's parser.
+ * A recalled equation's math node and a recalled float's element carry
+ * `data.explicoRecall = { prefix, key, number, href }`; the imports a
+ * recalled float's components need are added to the deck's own.
+ */
+/**
+ * What MDX's compile does to a tree before any course plugin sees it: a
+ * paragraph holding only JSX (and white space) becomes that JSX, as flow.
+ * An inline SVG's `<text x="…">0</text>` line parses as such a paragraph;
+ * kept, it would put a `<p>` inside the `<svg>`. `processor.parse` stops
+ * short of that step, so a chapter read for a recall takes it here
+ * (`remark-mark-and-unravel` in `@mdx-js/mdx`).
+ */
+export function unravelJsxParagraphs(tree) {
+  const visit = (node) => {
+    if (!Array.isArray(node.children)) return;
+    for (let index = 0; index < node.children.length; index += 1) {
+      const child = node.children[index];
+      if (child.type === 'paragraph') {
+        const jsx = child.children.filter((inner) => inner.type === 'mdxJsxTextElement' || inner.type === 'mdxTextExpression');
+        const onlyJsx = child.children.every(
+          (inner) => jsx.includes(inner) || (inner.type === 'text' && inner.value.trim() === ''),
+        );
+        if (jsx.length > 0 && onlyJsx) {
+          const flow = jsx.map((inner) => ({
+            ...inner,
+            type: inner.type === 'mdxJsxTextElement' ? 'mdxJsxFlowElement' : 'mdxFlowExpression',
+          }));
+          node.children.splice(index, 1, ...flow);
+          index += flow.length - 1;
+          for (const element of flow) visit(element);
+          continue;
+        }
+      }
+      visit(child);
+    }
+  };
+  visit(tree);
+  return tree;
+}
+
+export function expandRecalls(tree, { processor, deck, deckEntry, manifest, base, fail }) {
+  const recalls = [];
+  walk(tree, (node, parent, index) => {
+    if (node.type === 'mdxJsxFlowElement' && node.name === 'Recall' && parent) {
+      recalls.push({ node, parent, index });
+      return false;
+    }
+    return true;
+  });
+  if (recalls.length === 0) return;
+  if (deck.scope !== 'part' && !deck.chapterPath) {
+    fail(
+      `<Recall> on a deck with no chapter: a slides-first lesson has nothing to recall. Show the float itself (rule D8).`,
+      recalls[0].node,
+    );
+  }
+  if (typeof processor?.parse !== 'function') {
+    fail('<Recall> needs remark-notation to run inside a unified processor (its parser reads the chapter).', recalls[0].node);
+  }
+  // Each chapter a recall reads, parsed once: a lesson's deck reads its
+  // chapter, a part's the chapter the manifest found for each recall.
+  const chapters = new Map();
+  const chapterOf = (lessonSlug) => {
+    if (!chapters.has(lessonSlug)) {
+      const path = deck.scope === 'part' ? partChapterPath(deck, lessonSlug) : deck.chapterPath;
+      const chapterTree = path ? unravelJsxParagraphs(processor.parse(readChapter(path).body)) : undefined;
+      chapters.set(lessonSlug, chapterTree && { tree: chapterTree, imports: importedNames(chapterTree) });
+    }
+    return chapters.get(lessonSlug);
+  };
+  const deckImports = importedNames(tree);
+  const needed = new Map();
+  const baseUrl = String(base ?? '').replace(/\/$/, '');
+
+  // Walk from the last recall back, so an earlier one's index stays right.
+  for (const { node, parent, index } of [...recalls].reverse()) {
+    const ref = stringAttribute(node, 'ref');
+    const match = ref === undefined ? null : RECALL_REF.exec(ref);
+    if (!match) {
+      fail(`<Recall ref="${ref ?? ''}">: a recall names \`eq-\`, \`fig-\`, \`tab-\` or \`dia-\` and a key of the chapter.`, node);
+    }
+    const [, prefix, key] = match;
+    const lessonSlug = deck.scope === 'part' ? deckEntry?.recalledFrom?.[ref] : deck.lessonSlug;
+    if (lessonSlug === undefined) {
+      fail(
+        `<Recall ref="${ref}">: no chapter this part's deck covers numbers it (\`recall-unresolved\`). Recompile the manifest if you just added it.`,
+        node,
+      );
+    }
+    const chapter = chapterOf(lessonSlug);
+    const number = manifest?.[NUMBER_TABLE[prefix]]?.numbersBySlug?.[lessonSlug]?.[key];
+    let found;
+    walk(chapter?.tree, (candidate) => {
+      if (found) return false;
+      if (prefix === 'eq' && candidate.type === 'math' && labelKeyOf(candidate.value) === key) found = candidate;
+      else if (
+        prefix !== 'eq' &&
+        candidate.type === 'mdxJsxFlowElement' &&
+        candidate.name === FLOAT_TAG[prefix] &&
+        stringAttribute(candidate, 'id') === key
+      ) {
+        found = candidate;
+      }
+      return !found;
+    });
+    if (!found || number === undefined) {
+      fail(
+        `<Recall ref="${ref}">: the chapter ${lessonSlug} numbers no ${prefix === 'eq' ? `equation labelled eq:${key}` : `<${FLOAT_TAG[prefix]} id="${key}">`}. Recompile the manifest if you just added it.`,
+        node,
+      );
+    }
+    const recalled = stripPositions(structuredClone(found));
+    recalled.data = {
+      ...recalled.data,
+      explicoRecall: { prefix, key, number, href: `${baseUrl}/${lessonSlug}/#${prefix}-${key}` },
+    };
+    if (prefix === 'eq') {
+      // Its own label is the chapter's; the deck shows it with the chapter's number.
+      recalled.value = String(recalled.value ?? '').replace(EQ_LABEL_PATTERN, '');
+    } else {
+      for (const name of componentNames(recalled)) {
+        if (deckImports.has(name)) continue;
+        const binding = chapter.imports.get(name);
+        if (!binding) {
+          fail(`<Recall ref="${ref}">: the chapter's <${name}> is not an import the deck can repeat.`, node);
+        }
+        const earlier = needed.get(name);
+        if (earlier && (earlier.source !== binding.source || earlier.imported !== binding.imported)) {
+          fail(
+            `<Recall ref="${ref}">: ${lessonSlug} imports <${name}> from ${binding.source}, and a chapter recalled ` +
+              `before it from ${earlier.source}. One page imports a name once: rename the import in one chapter.`,
+            node,
+          );
+        }
+        needed.set(name, binding);
+      }
+    }
+    parent.children.splice(index, 1, recalled);
+  }
+
+  if (needed.size > 0) {
+    const source = [...needed].map(([name, binding]) => importStatement(name, binding)).join('\n');
+    const esm = processor.parse(`${source}\n`).children.filter((child) => child.type === 'mdxjsEsm');
+    const lastImport = tree.children.reduce((last, child, position) => (child.type === 'mdxjsEsm' ? position : last), -1);
+    tree.children.splice(lastImport + 1, 0, ...esm.map(stripPositions));
+  }
+}
+
+// --- numbering ------------------------------------------------------------
+
+const TRANSPARENT = new Set(['Memo', 'ShortNote', 'Fold']);
+
+/**
+ * The deck page's equations and floats, in its reading order, and what each
+ * shows: a recalled one the chapter's number, a labelled equation of the
+ * deck its own (1), (2) in label order (`manifest.decks[].equations`), and
+ * the deck's own floats no number.
+ */
+export function collectDeckFloats(tree, deckEntry) {
+  const ownNumbers = new Map((deckEntry?.equations ?? []).map((equation) => [equation.key, equation.number]));
+  const equations = new Map();
+  const floats = new Map();
+  // The deck's own floats of each kind, counted for an unkeyed one's anchor.
+  const positions = { fig: 0, tab: 0, dia: 0 };
+  const visit = (node) => {
+    if (!node || typeof node !== 'object') return;
+    if (node.type === 'math') {
+      const recall = node.data?.explicoRecall;
+      if (recall) {
+        equations.set(node, { key: recall.key, number: recall.number, short: equationCaption(node.value), href: recall.href });
+        return;
+      }
+      const key = labelKeyOf(node.value);
+      if (key !== undefined) {
+        equations.set(node, { key, number: ownNumbers.get(key) ?? '?', short: equationCaption(node.value) });
+      }
+      return;
+    }
+    if (node.type === 'mdxJsxFlowElement') {
+      const prefix = Object.entries(FLOAT_TAG).find(([, tag]) => tag === node.name)?.[0];
+      if (prefix) {
+        const recall = node.data?.explicoRecall;
+        if (recall) {
+          floats.set(node, { prefix, key: recall.key, number: recall.number, href: recall.href });
+        } else {
+          positions[prefix] += 1;
+          floats.set(node, { prefix, key: stringAttribute(node, 'id'), position: positions[prefix] });
+        }
+        return;
+      }
+      if (!TRANSPARENT.has(node.name) && node.name !== 'Notes') return;
+    }
+    if (Array.isArray(node.children)) node.children.forEach(visit);
+  };
+  visit(tree);
+  return { equations, floats };
+}
+
+// --- frames ---------------------------------------------------------------
+
+/**
+ * Give the deck's `##` and `###` headings the anchors and frame numbers the
+ * manifest decided, in order; a different count fails the build (a stale
+ * manifest), as a chapter's headings do.
+ */
+export function stampDeckHeadings(tree, deckEntry, fail) {
+  const headed = (deckEntry?.frames ?? []).filter((frame) => frame.kind === 'section' || frame.kind === 'frame');
+  const nodes = (tree.children ?? []).filter((node) => node?.type === 'heading' && (node.depth === 2 || node.depth === 3));
+  if (nodes.length !== headed.length) {
+    fail(
+      `Stale Explico manifest for the deck ${deckEntry?.slug ?? ''}: this page has ${nodes.length} section and frame headings, ` +
+        `the manifest lists ${headed.length}. Recompile the manifest from the current content.`,
+    );
+  }
+  nodes.forEach((node, index) => {
+    const frame = headed[index];
+    node.data = node.data ?? {};
+    node.data.hProperties = {
+      ...node.data.hProperties,
+      id: frame.slug,
+      'data-deck-frame': String(frame.number),
+      'data-deck-kind': frame.kind,
+      'data-deck-steps': String(frame.steps),
+      ...(frame.morph ? { 'data-deck-morph': '' } : {}),
+    };
+  });
+}
+
+/**
+ * On a part's deck, give each `<AssessmentSet>` the lesson whose checks it
+ * asks (`lesson`, the component's prop): the chapter its frame's section
+ * covers (`frames[].chapter`). A frame in no such section asks none, which
+ * the manifest reports as `deck-check-no-chapter`.
+ */
+export function markDeckChecks(tree, deckEntry, fail) {
+  const headed = (deckEntry?.frames ?? []).filter((frame) => frame.kind === 'section' || frame.kind === 'frame');
+  let position = -1;
+  for (const node of tree.children ?? []) {
+    if (node?.type === 'heading' && (node.depth === 2 || node.depth === 3)) {
+      position += 1;
+      continue;
+    }
+    const chapter = headed[position]?.chapter;
+    walk(node, (child) => {
+      if (child.type !== 'mdxJsxFlowElement' || child.name !== 'AssessmentSet') return true;
+      if (!chapter) {
+        fail(
+          "<AssessmentSet> on a part's deck, in a section that names no chapter (`deck-check-no-chapter`): " +
+            'move it into a `## Title [chapter: <name>]` section, whose chapter it asks.',
+          child,
+        );
+      }
+      injectMdxStringAttributes(child, { lesson: chapter.replace(/\//g, '.') });
+      return false;
+    });
+  }
+}
+
+/**
+ * The generated title frame: the deck's title, its course, its authors and
+ * the version its content is at (rules D10 and C5), in the words of a
+ * chapter's PDF (`versionPhrase` in compiler/page-versions.ts).
+ */
+export function titleFrameNode(manifest, deckEntry) {
+  const about = manifest?.about ?? {};
+  const authors = (about.authors ?? []).map((author) => author.name).filter(Boolean);
+  const course = about.material?.name;
+  const current = about.knowledge?.version;
+  const since = deckEntry && 'since' in deckEntry ? deckEntry.since : current;
+  const version = current
+    ? since === null
+      ? `with changes after version ${current}, not yet released`
+      : `unchanged since version ${since}`
+    : undefined;
+  return el(
+    'section',
+    { className: ['deck-frame', 'deck-frame--title'], 'data-deck-frame': '1', 'data-deck-kind': 'title' },
+    [
+      el('p', { className: ['deck-title__title'] }, [text(deckEntry?.title ?? '')]),
+      ...(course ? [el('p', { className: ['deck-title__course'] }, [text(course)])] : []),
+      ...(authors.length > 0 ? [el('p', { className: ['deck-title__authors'] }, [text(authors.join(', '))])] : []),
+      ...(version ? [el('p', { className: ['deck-title__version'] }, [text(`Content ${version}`)])] : []),
+    ],
+  );
+}
+
+/**
+ * The competencies a deck's outcomes frame lists: its lesson's, or on a
+ * part's deck every covered chapter's, in reading order, each once.
+ */
+export function deckTeaches(manifest, deckEntry) {
+  const lessons = new Map((manifest?.lessons ?? []).map((lesson) => [lesson.id, lesson]));
+  if (deckEntry?.part === undefined) return lessons.get(deckEntry?.lessonId)?.teaches ?? [];
+  const covered = new Set((deckEntry.covers ?? []).map((cover) => cover.chapter));
+  const part = (manifest?.parts ?? []).find((entry) => entry.dir === deckEntry.part);
+  const chapters = (part?.lessons ?? []).filter((id) => covered.has(id.replace(/\./g, '/')));
+  return [...new Set(chapters.flatMap((id) => lessons.get(id)?.teaches ?? []))];
+}
+
+/** The generated outcomes frame: what the lesson's competencies say a student can now do. */
+export function outcomesFrameNode(manifest, deckEntry, lesson) {
+  const frame = (deckEntry?.frames ?? []).find((entry) => entry.kind === 'outcomes');
+  if (!frame) return undefined;
+  const byId = new Map((manifest?.competencies ?? []).map((competency) => [competency.id, competency]));
+  const outcomes = (lesson?.teaches ?? []).map((id) => byId.get(id)?.outcome).filter(Boolean);
+  return el(
+    'section',
+    {
+      className: ['deck-frame', 'deck-frame--outcomes'],
+      'data-deck-frame': String(frame.number),
+      'data-deck-kind': 'outcomes',
+    },
+    [
+      el('p', { className: ['deck-frame__title'], role: 'heading', 'aria-level': '3' }, [text(frame.title)]),
+      {
+        type: 'list',
+        ordered: false,
+        spread: false,
+        children: outcomes.map((outcome) => ({
+          type: 'listItem',
+          spread: false,
+          children: [{ type: 'paragraph', children: [text(outcome)] }],
+        })),
+      },
+    ],
+  );
+}
+
+const EXPLAIN_KEY = /\\explain\s*\{([^{}]+)\}/g;
+
+/** The notation keys a subtree shows, in order: bound math symbols and `[[key]]` terms, not its notes. */
+function keysIn(nodes) {
+  const keys = [];
+  const add = (key) => {
+    if (key && !keys.includes(key)) keys.push(key);
+  };
+  for (const root of nodes) {
+    walk(root, (node) => {
+      if (node.type === 'mdxJsxFlowElement' && node.name === 'Notes') return false;
+      if ((node.type === 'math' || node.type === 'inlineMath') && typeof node.value === 'string') {
+        for (const match of node.value.matchAll(EXPLAIN_KEY)) add(match[1].trim());
+      }
+      const key = node.data?.hProperties?.['data-notation-key'];
+      if (typeof key === 'string') add(key);
+      return true;
+    });
+  }
+  return keys;
+}
+
+/**
+ * After notation ran: give each `###` frame its legend line — the symbols it
+ * shows for the first time in the deck (`first-use`), or all it shows
+ * (`every-frame`) — as math the page's KaTeX pass renders, each symbol bound
+ * to its card. `resolved` is the page's resolved notation (`key → entry`).
+ */
+export function insertLegends(tree, { resolved, mode }) {
+  if (mode === 'off') return;
+  const children = tree.children ?? [];
+  const starts = [];
+  children.forEach((node, index) => {
+    if (node?.type === 'heading' && (node.depth === 2 || node.depth === 3)) starts.push(index);
+  });
+  const seen = new Set();
+  const inserts = [];
+  starts.forEach((start, position) => {
+    const node = children[start];
+    const end = starts[position + 1] ?? children.length;
+    const keys = keysIn(children.slice(start + 1, end));
+    if (node.depth !== 3) {
+      for (const key of keys) seen.add(key);
+      return;
+    }
+    const shown = (mode === 'every-frame' ? keys : keys.filter((key) => !seen.has(key))).filter((key) => resolved[key]);
+    for (const key of keys) seen.add(key);
+    if (shown.length === 0) return;
+    inserts.push({
+      at: end,
+      node: el(
+        'div',
+        { className: ['deck-legend'], 'data-deck-legend': '' },
+        shown.flatMap((key) => {
+          const entry = resolved[key];
+          const latex = String(entry.notation ?? entry.latex ?? key);
+          return [
+            el('span', { className: ['deck-legend__item'] }, [
+              { type: 'inlineMath', value: `\\explain{${key}}{${latex}}`, data: { hName: 'code', hProperties: { className: ['language-math', 'math-inline'] }, hChildren: [{ type: 'text', value: `\\explain{${key}}{${latex}}` }] } },
+              text(' '),
+              el('span', { className: ['deck-legend__label'] }, [text(String(entry.label ?? key))]),
+            ]),
+          ];
+        }),
+      ),
+    });
+  });
+  for (const { at, node } of inserts.reverse()) children.splice(at, 0, node);
+}
+
+export const DECK_CAPTION_PATTERN = EQ_CAPTION_PATTERN;