explico 0.11.1 → 0.13.0

package/dist/reference/math-glyphs.mjs

@@ -185,14 +185,71 @@ function assertPinnedKatex() {
   }
 }
 
+/** The inner environment that takes a top-level LaTeX one's rows inside `$$…$$`. */
+const INNER_ENVIRONMENT = {
+  align: 'aligned',
+  flalign: 'aligned',
+  split: 'aligned',
+  alignat: 'alignedat',
+  gather: 'gathered',
+};
+
+/**
+ * What to write instead of a LaTeX habit KaTeX rejects, or `undefined`.
+ * `replace` is set when KaTeX's own words would mislead: every span is parsed
+ * as inline math, so in a `$$…$$` block KaTeX says a display environment or
+ * `\tag` "can be used only in display mode" — but a block already is the
+ * display, and explico numbers it from its `\label{eq:key}`.
+ */
+function latexHabitAdvice(message, latex) {
+  const NUMBERED = 'a $$…$$ block already is the display, and explico numbers it from its \\label{eq:key}';
+  const display = /\{(\w+)(\*?)\} can be used only in display mode/.exec(message);
+  if (display) {
+    const [, name, star] = display;
+    const inner = INNER_ENVIRONMENT[name];
+    return {
+      replace: true,
+      text: inner
+        ? `\\begin{${name}${star}} is a LaTeX display environment of its own; ${NUMBERED}. Write the rows in \\begin{${inner}}…\\end{${inner}}, one numbered equation per block.`
+        : `\\begin{${name}${star}} is a LaTeX display environment of its own; ${NUMBERED}. Drop \\begin{${name}${star}} and \\end{${name}${star}}.`,
+    };
+  }
+  if (/\\tag works only in display equations/.test(message)) {
+    return {
+      replace: true,
+      text: `\\tag prints a number of its own, but ${NUMBERED}. Drop the \\tag, and refer to the equation with [[eq-key]].`,
+    };
+  }
+  const command = /Undefined control sequence: \\(label|eqref|ref|autoref|cref|cite[a-z]*)\b/.exec(message)?.[1];
+  if (command === 'label') {
+    const label = /\\label\s*\{([^}]*)\}/.exec(latex)?.[1] ?? '';
+    return {
+      text: `An equation's label is \\label{eq:key}, its key lowercase kebab-case, in a $$…$$ block: \\label{${label}} is not one.`,
+    };
+  }
+  if (command !== undefined && command.startsWith('cite')) {
+    return { text: 'Math holds no citation: cite in the prose with [@source-id].' };
+  }
+  if (command !== undefined) {
+    const target = new RegExp(`\\\\${command}\\s*\\{([a-z]+):([^}]*)\\}`).exec(latex);
+    const reference = target ? `[[${target[1]}-${target[2]}]]` : '[[eq-key]]';
+    return { text: `Math holds no reference: write ${reference} in the prose.` };
+  }
+  return undefined;
+}
+
 function parseMath(latex, label) {
   assertPinnedKatex();
   try {
     return katex.__parse(latex, { throwOnError: true, strict: 'error' });
   } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const advice = latexHabitAdvice(message, latex);
     fail(
       'invalid-latex',
-      `KaTeX could not parse ${label}: ${error instanceof Error ? error.message : String(error)}`,
+      advice?.replace
+        ? `KaTeX could not parse ${label}: ${advice.text}`
+        : `KaTeX could not parse ${label}: ${message}${advice ? ` ${advice.text}` : ''}`,
       { label, latex },
     );
   }
@@ -265,6 +322,8 @@ const MARKER_COMMANDS = [EXPLAIN_COMMAND, '\\slot'];
 export function stripNotationMarkers(latex) {
   let result = '';
   let cursor = 0;
+  // True right after a stripped marker, whose edge the next character meets.
+  let atMarkerEdge = false;
 
   while (cursor < latex.length) {
     const command = MARKER_COMMANDS.find(
@@ -282,18 +341,38 @@ export function stripNotationMarkers(latex) {
       : undefined;
 
     if (contentGroup) {
-      result += stripNotationMarkers(contentGroup.content);
+      result = joinAtMarkerEdge(
+        result,
+        stripNotationMarkers(contentGroup.content),
+      );
       cursor = contentGroup.end;
+      atMarkerEdge = true;
       continue;
     }
 
-    result += latex[cursor];
+    result = atMarkerEdge
+      ? joinAtMarkerEdge(result, latex[cursor])
+      : result + latex[cursor];
+    atMarkerEdge = false;
     cursor += 1;
   }
 
   return result;
 }
 
+/**
+ * Join the two sides of a stripped marker's edge. TeX reads a control word up
+ * to its first non-letter, so `\times` and `m` must not become `\timesm`, nor
+ * `\lambda` and `u` become `\lambdau`. The space is neutral: TeX skips spaces
+ * after a control word in every mode.
+ */
+function joinAtMarkerEdge(before, after) {
+  const word = /\\[A-Za-z]+$/.exec(before);
+  return word && !isEscaped(before, word.index) && /^[A-Za-z]/.test(after)
+    ? `${before} ${after}`
+    : before + after;
+}
+
 /**
  * Every `\explain{key}{latex}` in the source (the escape hatch). Each key must
  * already be in the page glyph table. The returned span points at the wrapped
@@ -385,6 +464,18 @@ function sourceWithoutExplainPrefixes(latex, calls) {
 
 // --- structural signatures --------------------------------------------
 
+/**
+ * The letters of a declared operator's body, spacing dropped, so
+ * `\operatorname{arg\,max}` and `\operatorname{argmax}` sign alike — the
+ * same name rule N8 keys its allow list by.
+ */
+function operatorLetters(value) {
+  if (Array.isArray(value)) return value.map(operatorLetters).join('');
+  if (!isNode(value)) return '';
+  if (value.type === 'mathord' || value.type === 'textord') return value.text ?? '';
+  return operatorLetters(value.body);
+}
+
 function signatureParts(node) {
   if (!isNode(node)) return [];
 
@@ -399,7 +490,15 @@ function signatureParts(node) {
     return [`atom:${node.family ?? ''}:${node.text ?? ''}`];
   if (node.type === 'spacing') return [`space:${node.text ?? ''}`];
   if (node.type === 'op' || node.type === 'operatorname') {
-    return [`operator:${node.name ?? node.type}`];
+    if (typeof node.name === 'string') return [`operator:${node.name}`];
+    // An `\operatorname{…}` (or a `\mathop{…}`) carries its name in `body`,
+    // not `name`. Signed by its node type alone, every declared operator
+    // looked alike: a page's one operator card claimed every other declared
+    // operator on the page, and two operator cards could not share a page.
+    // A body with no letters (`\mathop{\sum}`) falls through to the full
+    // structural signature below.
+    const letters = operatorLetters(node.body);
+    if (letters !== '') return [`operator:${node.type}:${letters}`];
   }
   if (node.type === 'text')
     return [`text:${signatureValue(node.body).join('|')}`];
@@ -722,6 +821,7 @@ function collectSourceStructure(tree, latex) {
   const identifiers = [];
   const scriptSpans = [];
   const decorations = [];
+  const indexed = [];
   const seenContainers = new Set();
   const seenIdentifiers = new Set();
 
@@ -773,6 +873,11 @@ function collectSourceStructure(tree, latex) {
         const span = nodeSpan(script, latex);
         if (span) scriptSpans.push(span);
       }
+      // A symbol with a subscript (rule N23). Not one in a distinct font's
+      // body: `\mathbf{x_1}` is a styled whole, like a container there.
+      if (!ignored && context.font === undefined && indexedForm(value)) {
+        indexed.push(value);
+      }
     }
 
     const decoration = ignored ? undefined : decorationRecord(value, latex);
@@ -808,7 +913,7 @@ function collectSourceStructure(tree, latex) {
 
   addContainer(tree);
   visitValue(tree);
-  return { containers, identifiers, scriptSpans, decorations };
+  return { containers, identifiers, scriptSpans, decorations, indexed };
 }
 
 // --- base-glyph signatures ------------------------------------------
@@ -896,21 +1001,319 @@ export function decorationOfEntry(latex) {
 }
 
 /**
- * The shorter page form a parameterized symbol also permits: the bare base
- * glyph of `t_k` / `r_m` / `j^{(m)}` (one significant node) or the head of a
- * function form `D(0,t)` / `V_0(1_t)` (head followed by `(`).
+ * The bare glyph an entry lends its card to: a plain letter's own, the base of
+ * a superscript form `j^{(m)}`, or the head of a function form `D(0,t)`.
+ *
+ * An index is part of a symbol's name (rule N23), so an entry with a
+ * subscript lends to no bare glyph: `v_0` (a fixed label) is not `v`, and a
+ * family `\alpha_i` gives its card to its own instances (`\alpha_1`, see
+ * {@link resolveIndexedNode}) but never to a bare `\alpha`, which is a
+ * different object. A function form whose head is indexed (`V_0(1_t)`) lends
+ * by that head, as a whole — see {@link indexedFunctionHead}.
  */
 function canonicalBaseSignature(tree) {
+  const head = functionFormHead(tree);
+  if (head === null) return undefined;
+  if (head?.type === 'supsub' && head.sub) return undefined;
+  return identifierBaseSignature(head);
+}
+
+/**
+ * The one significant node of an entry, or the head of a function form
+ * (`D(0,t)`, `V_0(1_t)`: a head followed by `(`); `null` when the entry is
+ * neither.
+ */
+function functionFormHead(tree) {
   const significant = tree.filter(
     (node) => node.type !== 'spacing' && node.type !== 'ordgroup',
   );
-  if (significant.length === 1) return identifierBaseSignature(significant[0]);
-  if (significant.length < 2) return undefined;
+  if (significant.length === 1) return significant[0];
+  if (significant.length < 2) return null;
   const [head, open] = significant;
   if (open.type !== 'atom' || open.family !== 'open' || open.text !== '(') {
-    return undefined;
+    return null;
   }
-  return identifierBaseSignature(head);
+  return head;
+}
+
+/** The indexed head of a function form, `V_0` in `V_0(1_t)`, else `undefined`. */
+function indexedFunctionHead(tree) {
+  const significant = tree.filter(
+    (node) => node.type !== 'spacing' && node.type !== 'ordgroup',
+  );
+  if (significant.length < 2) return undefined;
+  const head = functionFormHead(tree);
+  return head && indexedForm(head) ? head : undefined;
+}
+
+// --- indexed symbols (rule N23) -------------------------------------
+
+/** A top-level comma in a subscript separates two index slots: `x_{i,j}`. */
+const isSlotComma = (node) =>
+  node.type === 'atom' && node.family === 'punct' && node.text === ',';
+
+/** The slots of a subscript, `{…}` groups flattened. */
+function indexSlots(sub) {
+  const slots = [[]];
+  for (const node of flattenGroup(sub)) {
+    if (isSlotComma(node)) slots.push([]);
+    else slots[slots.length - 1].push(node);
+  }
+  return slots;
+}
+
+const isDigitNode = (node) =>
+  (node.type === 'textord' || node.type === 'mathord') &&
+  /^[0-9.]+$/u.test(node.text ?? '');
+
+const isLabelNode = (node) =>
+  node.type === 'text' ||
+  (node.type === 'font' && node.font === ROMAN_LABEL_FONT);
+
+/**
+ * A running index is a lowercase Latin letter: `i`, `k`, `t`. An uppercase
+ * letter in a subscript is a size (`X_N`) or another symbol (`p_X`), and a
+ * Greek one a parameter (`p_\theta`), so neither runs over a set.
+ */
+const RUNNING_INDEX_LETTER = /^[a-z]$/u;
+
+/** True for a letter that is a running index wherever it is a whole slot. */
+export function isRunningIndexLetter(text) {
+  return RUNNING_INDEX_LETTER.test(text);
+}
+
+/**
+ * What one index slot is: `running` (a lowercase letter), `digits`, `named`
+ * (a `\mathrm{…}` / `\text{…}` label, or a subscript the page declares fixed:
+ * an index entry `{}_x`, a letter card with `fixedIndex`), `symbol` (anything
+ * else: `N`, `\theta`, `T_{\mathrm{fwd}}`, `t-1`), or `empty`.
+ */
+function slotKind(slot, fixedSlots) {
+  if (slot.length === 0) return 'empty';
+  if (fixedSlots.has(sequenceSignature(slot))) return 'named';
+  if (slot.every(isDigitNode)) return 'digits';
+  if (slot.length === 1 && isLabelNode(slot[0])) return 'named';
+  if (
+    slot.length === 1 &&
+    slot[0].type === 'mathord' &&
+    RUNNING_INDEX_LETTER.test(slot[0].text ?? '')
+  ) {
+    return 'running';
+  }
+  return 'symbol';
+}
+
+/**
+ * Whether a subscript's base is a symbol an index belongs to: a letter
+ * (`x`, `\theta`), a font-styled symbol (`\mathbf{v}`, `\mathbb{E}`), a roman
+ * label (`\mathrm{RV}`), or a decorated one (`\hat{\beta}`, `b'`). A big
+ * operator (`\sum_{i=1}`), a bracket (`\lVert x\rVert_2`), a number set
+ * (`\mathbb{R}_+`) and a brace (`\underbrace{…}_{…}`) are not.
+ */
+function isSymbolBase(base) {
+  const items = flattenGroup(base);
+  if (items.length !== 1) return false;
+  const [node] = items;
+  if (IGNORED_MATH_TOKENS.has(fontTokenText(node))) return false;
+  if (isIdentifierNode(node)) return true;
+  if (node.type === 'font') return hasBindableGlyph(node) || isLabelNode(node);
+  const decoration = decorationOf(node);
+  return decoration !== undefined && isSymbolBase(node[decoration.part]);
+}
+
+/**
+ * The parts of a symbol with a subscript, or `undefined` for any other node.
+ * `sup` says what rides on top: nothing, a mark (`'`, `*`, `\dagger`: rule
+ * N22) or anything else, a power (`^{2}`, `^{(m)}`).
+ */
+function indexedForm(node) {
+  if (!isNode(node) || node.type !== 'supsub' || !node.sub) return undefined;
+  if (!isSymbolBase(node.base)) return undefined;
+  return {
+    baseSignature: signatureValue(node.base).join('|'),
+    subSignature: signatureValue(node.sub).join('|'),
+    supSignature: node.sup ? signatureValue(node.sup).join('|') : '',
+    sup: !node.sup
+      ? 'none'
+      : scriptMarkName(node.sup) === undefined
+        ? 'power'
+        : 'mark',
+    slots: indexSlots(node.sub),
+  };
+}
+
+/** The signature of a symbol with its subscript and without what rides on top. */
+const coreSignature = (form) =>
+  `supsub(${form.baseSignature})_(${form.subSignature})^()`;
+
+/**
+ * The source span of a symbol and its subscript, without a power or mark
+ * written after them: `v_0` in `v_0^{2}`. When the superscript sits between
+ * them (`v^2_0`, `v'_0`) the two cannot be wrapped apart, so the whole node
+ * is the span.
+ */
+function coreSourceSpan(node, latex) {
+  const whole = sourceSpan(node, latex);
+  if (!node.sup) return whole;
+  const base = sourceSpan(node.base, latex);
+  const sub = sourceSpan(node.sub, latex);
+  if (!whole || !base || !sub) return whole;
+  return /^\s*_\s*$/u.test(latex.slice(base.end, sub.start))
+    ? { start: base.start, end: sub.end }
+    : whole;
+}
+
+/**
+ * Whether an occurrence is an instance of a family: same base, same number of
+ * slots, the same superscript or none on the family, and each slot fits. A
+ * running slot takes anything but a fixed label (`x_1`, `x_{k+1}`, `x_N`; not
+ * `x_{\mathrm{e}}`), a `symbol` slot any symbol (`T_{\mathrm{opt}}` in place
+ * of `T_{\mathrm{fwd}}`), and a fixed slot only itself.
+ */
+function isFamilyInstance(family, form, fixedSlots) {
+  if (family.form.baseSignature !== form.baseSignature) return false;
+  if (family.form.sup !== 'none' && family.form.supSignature !== form.supSignature) {
+    return false;
+  }
+  if (family.form.slots.length !== form.slots.length) return false;
+  return family.form.slots.every((slot, index) => {
+    const kind = family.kinds[index];
+    const filler = form.slots[index];
+    const fillerKind = slotKind(filler, fixedSlots);
+    if (kind === 'running' || kind === 'symbol') {
+      return fillerKind !== 'named' && fillerKind !== 'empty';
+    }
+    return sequenceSignature(slot) === sequenceSignature(filler);
+  });
+}
+
+/**
+ * The key of a derived entry: a base entry composed with an index entry
+ * (`\mathbf{v}_0` from `velocity-vector` and `{}_0`). The build materializes
+ * it from the two (`derived-notation.mjs`); it is never authored, and an
+ * authored key that equals one fails the build.
+ *
+ * @param {string} baseKey
+ * @param {string} indexKey
+ * @returns {string}
+ */
+export function derivedNotationKey(baseKey, indexKey) {
+  return `${baseKey}.sub.${indexKey}`;
+}
+
+/**
+ * The subscript an **index entry** explains — an empty group with a subscript:
+ * `{}_0`, `{}_x`, `{}_{\mathrm{max}}` — as the source after `{}`, else
+ * `undefined`. Such an entry binds no symbol of its own; composed with the
+ * entry of the symbol it indexes, it makes a derived card (rule N23).
+ *
+ * @param {string} latex
+ * @returns {string | undefined}
+ */
+export function indexOfEntry(latex) {
+  if (typeof latex !== 'string' || latex.trim() === '') return undefined;
+  let tree;
+  try {
+    tree = parseMath(stripNotationMarkers(latex), 'index entry');
+  } catch (error) {
+    if (error instanceof GlyphResolutionError && error.code === 'invalid-latex') {
+      return undefined;
+    }
+    throw error;
+  }
+  if (!isIndexEntryTree(tree)) return undefined;
+  const match = /^\s*\{\s*\}\s*(_[\s\S]*)$/u.exec(latex);
+  return match ? match[1].trim() : undefined;
+}
+
+function isIndexEntryTree(tree) {
+  if (!Array.isArray(tree) || tree.length !== 1) return false;
+  const [node] = tree;
+  return (
+    node.type === 'supsub' &&
+    Boolean(node.sub) &&
+    !node.sup &&
+    isNode(node.base) &&
+    node.base.type === 'ordgroup' &&
+    node.base.body.length === 0
+  );
+}
+
+/**
+ * The symbol a base entry gives a derived card: its whole `latex`, or the
+ * glyph it lends to — the head of a function form (`v` of `v(t)`), the base
+ * of a superscript form (`j` of `j^{(m)}`).
+ *
+ * @param {string} notation
+ * @returns {string}
+ */
+export function baseSymbolLatex(notation) {
+  const source = stripNotationMarkers(notation);
+  let tree;
+  try {
+    tree = parseMath(source, 'base symbol');
+  } catch (error) {
+    if (error instanceof GlyphResolutionError) return source.trim();
+    throw error;
+  }
+  let node = functionFormHead(tree);
+  if (!node) return source.trim();
+  if (node.type === 'supsub' && !node.sub && scriptMarkName(node.sup) === undefined) {
+    node = node.base;
+  }
+  const span = sourceSpan(node, source);
+  return span ? source.slice(span.start, span.end) : source.trim();
+}
+
+/**
+ * The symbol of a derived card: the base's symbol with the index entry's
+ * subscript — `\mathbf{v}` and `{}_0` make `\mathbf{v}_0`.
+ *
+ * @param {string} baseNotation
+ * @param {string} indexNotation
+ * @returns {string}
+ */
+export function derivedNotationLatex(baseNotation, indexNotation) {
+  return `${baseSymbolLatex(baseNotation)}${indexOfEntry(indexNotation) ?? ''}`;
+}
+
+/**
+ * How an index entry is shown on its own — over a placeholder square, as an
+ * operator entry is (`\square_0`). Display only.
+ *
+ * @param {string} latex
+ * @returns {string}
+ */
+export function indexDisplayLatex(latex) {
+  return latex.replace(/^\s*\{\s*\}/u, '\\square');
+}
+
+/**
+ * Whether an entry's `latex` has a subscript on a symbol anywhere — what an
+ * `\explain{key}{X_i}` wrap needs from `key` before its card can explain the
+ * index (rule N23, `index-swallowed`).
+ *
+ * @param {string} latex
+ * @returns {boolean}
+ */
+export function entryHasIndex(latex) {
+  if (typeof latex !== 'string' || latex.trim() === '') return false;
+  let tree;
+  try {
+    tree = parseMath(stripNotationMarkers(latex), 'indexed entry');
+  } catch (error) {
+    if (error instanceof GlyphResolutionError && error.code === 'invalid-latex') {
+      return false;
+    }
+    throw error;
+  }
+  const visit = (value) => {
+    if (Array.isArray(value)) return value.some(visit);
+    if (!isNode(value)) return false;
+    if (value.type === 'supsub' && value.sub) return true;
+    return [...SOURCE_CHILD_KEYS].some((key) => visit(value[key]));
+  };
+  return visit(tree);
 }
 
 /**
@@ -1053,6 +1456,21 @@ function buildGlyphIndex(definitions) {
   const byBase = new Map();
   const ambiguousBase = new Set();
   const operators = new Map();
+  // Rule N23: index entries by the subscript they explain, indexed function
+  // heads (`V_0` of `V_0(1_t)`) by their signature, the subscripts the page
+  // declares fixed, and the indexed whole forms that may be families.
+  const indexEntries = new Map();
+  const headForms = new Map();
+  const fixedSlots = new Set();
+  const indexedEntries = [];
+  // What each bare glyph's indexed entries are, for the message of a symbol
+  // that no longer borrows one's card (rule N4).
+  const indexedBases = new Map();
+  const noteIndexedBase = (signature, key) => {
+    const keys = indexedBases.get(signature) ?? [];
+    if (!keys.includes(key)) keys.push(key);
+    indexedBases.set(signature, keys);
+  };
   let maxNodeLength = 0;
 
   for (const [index, value] of definitions.entries()) {
@@ -1105,13 +1523,52 @@ function buildGlyphIndex(definitions) {
       continue;
     }
 
+    // An index entry (`{}_0`) binds no symbol; it explains its subscript
+    // wherever that composes with an explained symbol (rule N23).
+    if (isIndexEntryTree(tree)) {
+      const subscript = signatureValue(tree[0].sub).join('|');
+      const clash = indexEntries.get(subscript);
+      if (clash && clash !== key) {
+        fail(
+          'ambiguous-canonical-notation',
+          `Page glyphs "${clash}" and "${key}" are both index entries for the subscript in "${notation}": an index has one meaning per page (rule N4).`,
+          { left: clash, right: key },
+        );
+      }
+      indexEntries.set(subscript, key);
+      fixedSlots.add(subscript);
+      continue;
+    }
+
+    const fixedIndex = value?.fixedIndex === true;
+    const significant = tree.filter((node) => node.type !== 'spacing');
+    if (significant.length === 1 && indexedForm(significant[0])) {
+      const form = indexedForm(significant[0]);
+      indexedEntries.push({ key, form, fixedIndex });
+      noteIndexedBase(form.baseSignature, key);
+    }
+    if (fixedIndex && significant.length === 1 && isIdentifierNode(significant[0])) {
+      fixedSlots.add(sequenceSignature(significant));
+    }
+    const indexedHead = indexedFunctionHead(tree);
+    if (indexedHead) {
+      noteIndexedBase(indexedForm(indexedHead).baseSignature, key);
+      const head = sequenceSignature([indexedHead]);
+      const clash = headForms.get(head);
+      if (clash && clash !== key) ambiguousBase.add(head);
+      else headForms.set(head, key);
+    }
+
     const signature = sequenceSignature(tree);
     if (hasBindableGlyph(tree) && tree.length > 0) {
       const clash = bySignature.get(signature);
       if (clash && clash !== key) {
         fail(
           'ambiguous-canonical-notation',
-          `Page glyphs "${clash}" and "${key}" have structurally identical LaTeX ("${notation}").`,
+          `Page glyphs "${clash}" and "${key}" have structurally identical LaTeX ("${notation}"), ` +
+            'so a reader hovering it could not tell which is meant: a glyph has one meaning per ' +
+            'page (rule N4), and \\explain does not lift that. Write one of them differently on ' +
+            'this page (another letter, a subscript), or keep one of them off it.',
           { left: clash, right: key },
         );
       }
@@ -1129,18 +1586,163 @@ function buildGlyphIndex(definitions) {
     }
   }
 
-  return { byKey, bySignature, byBase, ambiguousBase, operators, maxNodeLength };
+  // A family is an indexed entry with a running slot (`x_k`, `F_{t,T}`); one
+  // whose every slot is fixed (`v_0`, `T_{\mathrm{opt}}`, or `fixedIndex`)
+  // is a single symbol and lends its card to nothing.
+  const families = new Map();
+  for (const { key, form, fixedIndex } of indexedEntries) {
+    if (fixedIndex) continue;
+    const kinds = form.slots.map((slot) => slotKind(slot, fixedSlots));
+    if (!kinds.includes('running')) continue;
+    const list = families.get(form.baseSignature) ?? [];
+    list.push({ key, form, kinds });
+    families.set(form.baseSignature, list);
+  }
+
+  return {
+    byKey,
+    bySignature,
+    byBase,
+    ambiguousBase,
+    operators,
+    indexEntries,
+    headForms,
+    fixedSlots,
+    families,
+    indexedBases,
+    maxNodeLength,
+  };
+}
+
+/**
+ * The entry that explains a symbol on its own — its whole form, or a bare
+ * glyph's unique card — so that an index entry can compose with it into a
+ * derived card. `undefined` when there is none, or more than one.
+ */
+function baseEntryKey(base, glyphs) {
+  const signature = signatureValue(base).join('|');
+  const whole = glyphs.bySignature.get(signature);
+  if (whole !== undefined) return whole;
+  const items = flattenGroup(base);
+  if (items.length !== 1 || !isIdentifierNode(items[0])) return undefined;
+  if (glyphs.ambiguousBase.has(signature)) return undefined;
+  return glyphs.byBase.get(signature);
+}
+
+/**
+ * Resolve a symbol with a subscript that no whole form matched exactly
+ * (rule N23), taking the first of these that exists:
+ *
+ * 1. the head of a function form (`V_0` of `V_0(1_t)`), or a whole form
+ *    under a power or a mark — `v_0^{2}` is `v_0` squared;
+ * 2. a family whose index has the same shape — `x_1` under `x_k`;
+ * 3. with `derive`, an index entry for its whole subscript and an entry for
+ *    its base: a derived card (`\mathbf{v}_0` from `\mathbf{v}` and `{}_0`).
+ *
+ * Returns `{ key, span, match, derived? }`, or `undefined` to leave the
+ * symbol to its base's card and its index's own.
+ */
+function resolveIndexedNode(node, glyphs, source, derive) {
+  const form = indexedForm(node);
+  if (!form) return undefined;
+  const whole = sourceSpan(node, source);
+  const core = coreSourceSpan(node, source);
+  if (!whole || !core) return undefined;
+
+  const head = sequenceSignature([node]);
+  if (glyphs.headForms.has(head) && !glyphs.ambiguousBase.has(head)) {
+    return { key: glyphs.headForms.get(head), span: whole, match: 'canonical' };
+  }
+  if (form.sup !== 'none') {
+    const signature = coreSignature(form);
+    const key =
+      glyphs.bySignature.get(signature) ??
+      (glyphs.ambiguousBase.has(signature)
+        ? undefined
+        : glyphs.headForms.get(signature));
+    if (key !== undefined) return { key, span: core, match: 'canonical' };
+  }
+
+  const families = (glyphs.families.get(form.baseSignature) ?? []).filter(
+    (family) => isFamilyInstance(family, form, glyphs.fixedSlots),
+  );
+  if (families.length > 1) {
+    const token = source.slice(whole.start, whole.end);
+    fail(
+      'ambiguous-base-fallback',
+      `"${token}" at ${whole.start}:${whole.end} is an instance of more than one page symbol (${families
+        .map((family) => `"${family.key}"`)
+        .join(', ')}); wrap it in \\explain{key}{${token}}.`,
+      { token, start: whole.start, end: whole.end },
+    );
+  }
+  if (families.length === 1) {
+    const [family] = families;
+    return {
+      key: family.key,
+      span: family.form.sup !== 'none' ? whole : core,
+      match: 'family',
+    };
+  }
+
+  if (!derive) return undefined;
+  const indexKey = glyphs.indexEntries.get(form.subSignature);
+  if (indexKey === undefined) return undefined;
+  const baseKey = baseEntryKey(node.base, glyphs);
+  if (baseKey === undefined) return undefined;
+  return {
+    key: derivedNotationKey(baseKey, indexKey),
+    span: core,
+    match: 'derived',
+    derived: { base: baseKey, index: indexKey },
+  };
 }
 
-/** Bind whole canonical forms: greedy longest match, left to right, per run. */
-function matchCanonicalForms(latex, strippedSource, containers, glyphs) {
+/**
+ * Bind whole canonical forms: greedy longest match, left to right, per run.
+ * A symbol with a subscript that no whole form matches exactly is then
+ * resolved as an indexed symbol ({@link resolveIndexedNode}).
+ *
+ * A match inside another one's script still binds — `T_{\mathrm{opt}}` in
+ * `B_{T_{\mathrm{opt}}}` keeps its own card — unless it is a lone letter
+ * (`matchBaseGlyphs` binds those) or the outer match is a derived card, whose
+ * index is explained by the index entry as a whole.
+ */
+function matchCanonicalForms(
+  latex,
+  strippedSource,
+  containers,
+  glyphs,
+  scriptSpans,
+  derive,
+  explicitCalls,
+) {
   const bindings = [];
   const claimed = [];
+  // An author's `\explain` claims what it wraps: a symbol inside one is not
+  // resolved as an indexed symbol, so two families never fail there.
+  const insideExplicit = (node) => {
+    const span = sourceSpan(node, strippedSource);
+    return (
+      span !== undefined && explicitCalls.some((call) => contains(call, span))
+    );
+  };
+
+  const blocked = (span, nodes) =>
+    claimed.some(
+      (existing) =>
+        sameSpan(existing, span) ||
+        (contains(existing, span) &&
+          (existing.match === 'derived' ||
+            (nodes.length === 1 && isIdentifierNode(nodes[0])) ||
+            !isSafeScriptNesting(span, existing, scriptSpans))),
+    );
 
   for (const container of containers) {
     let cursor = 0;
     while (cursor < container.length) {
       let step = 1;
+      let found;
       const maxLength = Math.min(
         glyphs.maxNodeLength,
         container.length - cursor,
@@ -1153,27 +1755,42 @@ function matchCanonicalForms(latex, strippedSource, containers, glyphs) {
         // or `b'` wraps the decoration too, not just the letter under it.
         const rawSpan = sourceSpan(nodes, strippedSource);
         if (!rawSpan) continue;
+        found = { key, nodes, rawSpan, match: 'canonical' };
+        break;
+      }
+      // A group around one node (an `aligned` cell's) shares that node's
+      // container, which is recorded once: look through it.
+      let single = container[cursor];
+      while (single.type === 'ordgroup' && single.body.length === 1) {
+        [single] = single.body;
+      }
+      if (!found && !insideExplicit(single)) {
+        const indexed = resolveIndexedNode(single, glyphs, strippedSource, derive);
+        if (indexed) {
+          found = {
+            ...indexed,
+            nodes: [container[cursor]],
+            rawSpan: indexed.span,
+          };
+        }
+      }
+      if (found) {
         const span = expandFontWrapperSpan(
           latex,
-          unwrapEnclosingGroupSpan(latex, rawSpan),
+          unwrapEnclosingGroupSpan(latex, found.rawSpan),
         );
-        step = length;
-        if (
-          claimed.some(
-            (existing) => sameSpan(existing, span) || contains(existing, span),
-          )
-        ) {
-          break;
+        step = found.nodes.length;
+        if (!blocked(span, found.nodes)) {
+          bindings.push({
+            key: found.key,
+            ...span,
+            token: latex.slice(span.start, span.end),
+            level: 'scope',
+            match: found.match,
+            ...(found.derived ? { derived: found.derived } : {}),
+          });
+          claimed.push({ ...span, match: found.match });
         }
-        bindings.push({
-          key,
-          ...span,
-          token: latex.slice(span.start, span.end),
-          level: 'scope',
-          match: 'canonical',
-        });
-        claimed.push(span);
-        break;
       }
       cursor += step;
     }
@@ -1194,10 +1811,13 @@ function matchBaseGlyphs(latex, identifiers, canonical, glyphs, scriptSpans) {
     // is already accounted for by that call; never re-flag or re-bind it, even
     // when it also sits in a script inside a larger canonical match. (To bind a
     // nested glyph separately, wrap it in its own nested `\explain`.)
+    // A derived card (rule N23) explains its index as a whole, so a letter in
+    // that index (`x` of `v_x` under `{}_x`) gets no card of its own either.
     if (
       canonical.some(
         (binding) =>
-          binding.level === 'explicit' && contains(binding, identifier),
+          (binding.level === 'explicit' || binding.match === 'derived') &&
+          contains(binding, identifier),
       )
     ) {
       continue;
@@ -1276,17 +1896,20 @@ function injectScopeBindings(latex, bindings) {
  * N22). A letter under such a decoration is reported once, as the decorated
  * form (`b''''`, not `b`): that whole form is what needs the entry.
  */
-function unresolvedIdentifiers(latex, identifiers, bindings, suspended) {
+function unresolvedIdentifiers(latex, identifiers, bindings, suspended, indexedBases) {
   const letters = identifiers
     .filter(
       (identifier) =>
         !bindings.some((binding) => contains(binding, identifier)) &&
         !suspended.some((decoration) => contains(decoration.part, identifier)),
     )
-    .map(({ start, end, font }) => {
+    .map(({ start, end, font, signature }) => {
       // Report `\mathbb{E}`, not a bare `E`, so the fix hint points at the
       // whole token the author has to wrap in `\explain`.
       const wrapped = expandFontWrapperSpan(latex, { start, end });
+      // Rule N23: an indexed entry lends its card to no bare glyph, so name
+      // the ones this letter used to borrow from.
+      const lenders = font === undefined ? (indexedBases?.get(signature) ?? []) : [];
       return {
         token: latex.slice(wrapped.start, wrapped.end),
         // A styled base-library letter (`\mathbf{e}`) is not Euler's number.
@@ -1297,6 +1920,7 @@ function unresolvedIdentifiers(latex, identifiers, bindings, suspended) {
         start: wrapped.start,
         end: wrapped.end,
         ...(font === undefined ? {} : { font }),
+        ...(lenders.length === 0 ? {} : { lenders: [...lenders] }),
       };
     })
     .filter(({ libraryToken }) => !BASE_LIBRARY.has(libraryToken))
@@ -1312,6 +1936,151 @@ function unresolvedIdentifiers(latex, identifiers, bindings, suspended) {
   );
 }
 
+/**
+ * How each symbol with a subscript is explained (rule N23), for the check in
+ * `gate-indices.ts`. `how` is one of:
+ *
+ * - `whole-form`, `family`, `derived`: a binding of that kind is exactly the
+ *   symbol; `inside-form`: a larger whole form covers it (`F_k` in `CF_k`);
+ * - `explicit`: an `\explain` around exactly it, whose key's `latex` has an
+ *   index; `swallowed`: the same, but the key's `latex` has none, so its card
+ *   cannot explain the index;
+ * - `inside-wrap`: inside a larger `\explain`, which claims its content;
+ * - `composed`: the base's card plus each slot's own — `explained` only when
+ *   the base has a card and every slot holds a symbol with one (`X_{t-1}`);
+ *   `unexplained` lists the parts that have none, the base first when
+ *   `baseExplained` is false;
+ * - `unresolved`: a letter in it has no card at all, which rule N4 reports.
+ *
+ * `running` lists the running index letters (`i`, `k`, `t`) in its slots that
+ * the page has not declared fixed, with the key of the letter's own card and
+ * of the entry that covers the symbol, for the index-set check.
+ */
+function classifyIndexed(nodes, context) {
+  const { latex, source, bindings, explicitCalls, glyphs, identifiers, unresolved } =
+    context;
+  const tight = (span) => (span ? unwrapEnclosingGroupSpan(latex, span) : span);
+  const size = (span) => span.end - span.start;
+  const cards = bindings.filter((binding) => binding.match !== 'operator');
+  const isUnresolved = (span) => unresolved.some((item) => contains(span, item));
+  const results = [];
+  const seen = new Set();
+
+  for (const node of nodes) {
+    const whole = tight(sourceSpan(node, source));
+    const core = tight(coreSourceSpan(node, source));
+    const base = tight(sourceSpan(node.base, source));
+    const sub = tight(sourceSpan(node.sub, source));
+    if (!whole || !core || !base || !sub) continue;
+    if (seen.has(`${core.start}:${core.end}`)) continue;
+    seen.add(`${core.start}:${core.end}`);
+
+    const slots = indexSlots(node.sub).map((slot) => ({
+      span: tight(sourceSpan(slot, source)),
+      kind: slotKind(slot, glyphs.fixedSlots),
+    }));
+    const exactly = (span) => sameSpan(span, core) || sameSpan(span, whole);
+
+    let how;
+    let key = null;
+    const wrap = explicitCalls
+      .filter((call) => contains(call, core))
+      .sort((left, right) => size(left) - size(right))[0];
+    const cover = cards
+      .filter(
+        (binding) =>
+          binding.level === 'scope' &&
+          binding.match !== 'base' &&
+          contains(binding, core),
+      )
+      .sort((left, right) => size(left) - size(right))[0];
+    if (wrap && !exactly(wrap)) {
+      how = 'inside-wrap';
+    } else if (wrap) {
+      key = wrap.key;
+      how = entryHasIndex(glyphs.byKey.get(wrap.key)?.notation)
+        ? 'explicit'
+        : 'swallowed';
+    } else if (cover) {
+      key = cover.key;
+      how = !exactly(cover)
+        ? 'inside-form'
+        : cover.match === 'canonical'
+          ? 'whole-form'
+          : cover.match;
+    } else if (isUnresolved(whole)) {
+      how = 'unresolved';
+    } else {
+      how = 'composed';
+    }
+
+    const unexplained = [];
+    let baseExplained = true;
+    if (how === 'composed') {
+      // `\hat{\beta}` has a card when `\beta` does; the hat is rule N22's.
+      if (
+        !cards.some(
+          (binding) => contains(binding, base) || contains(base, binding),
+        )
+      ) {
+        baseExplained = false;
+        unexplained.push(latex.slice(base.start, base.end));
+      }
+      for (const slot of slots) {
+        if (slot.kind === 'empty' || !slot.span) continue;
+        const carded = cards.some((binding) => contains(slot.span, binding));
+        if (!carded) unexplained.push(latex.slice(slot.span.start, slot.span.end));
+      }
+    }
+
+    const running = [];
+    // A swallowed index is already an error; its letters wait for the fix.
+    if (!['inside-wrap', 'derived', 'unresolved', 'swallowed'].includes(how)) {
+      for (const slot of slots) {
+        if (slot.kind === 'named' || !slot.span) continue;
+        for (const identifier of identifiers) {
+          if (identifier.font !== undefined) continue;
+          if (identifier.node.type !== 'mathord') continue;
+          if (!RUNNING_INDEX_LETTER.test(identifier.node.text ?? '')) continue;
+          if (!contains(slot.span, identifier)) continue;
+          const own = cards
+            .filter(
+              (binding) =>
+                contains(binding, identifier) && contains(slot.span, binding),
+            )
+            .sort((left, right) => size(left) - size(right))[0];
+          running.push({
+            letter: identifier.node.text,
+            start: identifier.start,
+            end: identifier.end,
+            key: own?.key ?? null,
+            cover: key,
+          });
+        }
+      }
+    }
+
+    // The form as written, markers dropped: `\mathbf{v}_0`, not
+    // `\explain{v}{\mathbf{v}}_0` or the blanked `{\mathbf{v}}_0`.
+    const shown = widenOverExplainPrefix(core, explicitCalls);
+    results.push({
+      token: stripNotationMarkers(latex.slice(shown.start, core.end)).trim(),
+      start: core.start,
+      end: core.end,
+      base: latex.slice(base.start, base.end),
+      index: latex.slice(sub.start, sub.end),
+      how,
+      key,
+      explained:
+        how === 'composed' ? unexplained.length === 0 : how !== 'swallowed',
+      baseExplained,
+      unexplained,
+      running,
+    });
+  }
+  return results.sort((left, right) => left.start - right.start);
+}
+
 /**
  * A decoration over an `\explain{key}{…}` call starts at that call's content
  * group in the blanked source; widen it to the call itself, so a marker
@@ -1576,9 +2345,20 @@ function findNestedBareDelimiters(tree) {
  * decorated form no whole form covers is reported in `unresolved`, marked
  * `suspended`.
  *
+ * A symbol with a subscript (rule N23) takes its exact whole form, else the
+ * family whose index has its shape, else — with `options.derive`, which page
+ * math sets (a lesson body, its assessments, labs and diagrams) — a derived
+ * card from an index entry (`{}_0`) and the base's entry; each such card
+ * wraps the whole indexed symbol. `derived`
+ * lists the derived cards used, as `{ key, base, index }`, for the build to
+ * materialize; `indices` says how each indexed symbol is explained (see
+ * `classifyIndexed`). A definition may carry `fixedIndex: true`: its index
+ * (or, on a letter, the letter as an index) is a fixed label, not a running
+ * one, so it is no family.
+ *
  * @param {string} latex
- * @param {Array<{key: string, notation: string}>} definitions
- * @param {{ suspended?: readonly string[] }} [options]
+ * @param {Array<{key: string, notation: string, fixedIndex?: boolean}>} definitions
+ * @param {{ suspended?: readonly string[], derive?: boolean }} [options]
  */
 export function resolveMathGlyphs(latex, definitions, options = {}) {
   if (typeof latex !== 'string') {
@@ -1586,6 +2366,7 @@ export function resolveMathGlyphs(latex, definitions, options = {}) {
   }
 
   const suspended = new Set(options.suspended ?? []);
+  const derive = options.derive === true;
   const glyphs = buildGlyphIndex(definitions);
   const explicitCalls = findExplainCalls(latex, glyphs.byKey);
   // The source KaTeX actually parses — `\explain{key}{` prefixes blanked to
@@ -1622,7 +2403,7 @@ export function resolveMathGlyphs(latex, definitions, options = {}) {
       { violations: nestingViolations },
     );
   }
-  const { containers, identifiers, scriptSpans, decorations } =
+  const { containers, identifiers, scriptSpans, decorations, indexed } =
     collectSourceStructure(tree, strippedSource);
 
   // A canonical container match can be found by seeing through transparent
@@ -1636,6 +2417,9 @@ export function resolveMathGlyphs(latex, definitions, options = {}) {
     strippedSource,
     containers,
     glyphs,
+    scriptSpans,
+    derive,
+    explicitCalls,
   ).filter(
     (binding) =>
       !explicitCalls.some(
@@ -1660,8 +2444,8 @@ export function resolveMathGlyphs(latex, definitions, options = {}) {
   const suspendedDecorations = [];
   const decorationResults = decorations.map((decoration) => {
     const span = widenOverExplainPrefix(decoration, explicitCalls);
-    const wholeForm =
-      covered.find((binding) => contains(binding, span))?.key ?? null;
+    const cover = covered.find((binding) => contains(binding, span));
+    const wholeForm = cover?.key ?? null;
     let operator = null;
     if (wholeForm === null && suspended.has(decoration.name)) {
       suspendedDecorations.push({ ...decoration, ...span });
@@ -1688,6 +2472,9 @@ export function resolveMathGlyphs(latex, definitions, options = {}) {
       ...span,
       token: latex.slice(span.start, span.end),
       wholeForm,
+      // An author's `\explain` names the whole form; rule N22 checks that
+      // its key's `latex` carries the decoration.
+      wholeFormExplicit: cover?.level === 'explicit',
       operator,
     };
   });
@@ -1726,6 +2513,19 @@ export function resolveMathGlyphs(latex, definitions, options = {}) {
     }
   }
 
+  const unresolved = unresolvedIdentifiers(
+    latex,
+    identifiers,
+    bindings,
+    suspendedDecorations,
+    glyphs.indexedBases,
+  );
+  const derived = new Map();
+  for (const binding of bindings) {
+    if (binding.match !== 'derived' || derived.has(binding.key)) continue;
+    derived.set(binding.key, { key: binding.key, ...binding.derived });
+  }
+
   return {
     latex: injectScopeBindings(latex, bindings),
     bindings: bindings.map(({ key, level, match, token }) => ({
@@ -1734,13 +2534,18 @@ export function resolveMathGlyphs(latex, definitions, options = {}) {
       match,
       token,
     })),
-    unresolved: unresolvedIdentifiers(
+    unresolved,
+    decorations: decorationResults,
+    indices: classifyIndexed(indexed, {
       latex,
-      identifiers,
+      source: strippedSource,
       bindings,
-      suspendedDecorations,
-    ),
-    decorations: decorationResults,
+      explicitCalls,
+      glyphs,
+      identifiers,
+      unresolved,
+    }),
+    derived: [...derived.values()],
   };
 }