explico 0.8.0 → 0.11.0

package/dist/reference/math-glyphs.mjs

@@ -46,7 +46,8 @@ const IGNORED_MATH_TOKENS = new Set([
 ]);
 
 // KaTeX font ids mapped back to their LaTeX command, so a single-letter font
-// node can be reconstructed as its source token (`\mathbb{N}`).
+// node can be reconstructed as its source token (`\mathbb{N}`). `\bm{x}`
+// parses as `boldsymbol`, so it is rebuilt as `\boldsymbol{x}`.
 const FONT_COMMANDS = new Map([
   ['mathbb', '\\mathbb'],
   ['mathcal', '\\mathcal'],
@@ -55,8 +56,73 @@ const FONT_COMMANDS = new Map([
   ['mathrm', '\\mathrm'],
   ['mathbf', '\\mathbf'],
   ['mathit', '\\mathit'],
+  ['mathnormal', '\\mathnormal'],
+  ['mathsf', '\\mathsf'],
+  ['mathtt', '\\mathtt'],
+  ['boldsymbol', '\\boldsymbol'],
 ]);
 
+// A font that makes a different symbol: `\mathcal{N}` is not `N`, and
+// `\mathbf{x}` is not `x`, so a letter in one of these never borrows the
+// plain letter's card (rule N4). `\mathit` / `\mathnormal` render the plain
+// italic letter and fall back as before; `\mathrm` is a roman label, skipped
+// whole (rule N10).
+const DISTINCT_FONTS = new Set([
+  'mathbf',
+  'boldsymbol',
+  'mathcal',
+  'mathscr',
+  'mathfrak',
+  'mathbb',
+  'mathsf',
+  'mathtt',
+]);
+
+// Every math-mode accent KaTeX 0.16 parses, over and under (`accent` /
+// `accentUnder` nodes, named by their `label`). Text-mode accents (`\'`, `\^`,
+// …) fail the strict parse, so they never reach the resolver.
+const ACCENT_LABELS = [
+  '\\acute',
+  '\\grave',
+  '\\ddot',
+  '\\tilde',
+  '\\bar',
+  '\\breve',
+  '\\check',
+  '\\hat',
+  '\\vec',
+  '\\dot',
+  '\\mathring',
+  '\\widecheck',
+  '\\widehat',
+  '\\widetilde',
+  '\\overrightarrow',
+  '\\overleftarrow',
+  '\\Overrightarrow',
+  '\\overleftrightarrow',
+  '\\overgroup',
+  '\\overlinesegment',
+  '\\overleftharpoon',
+  '\\overrightharpoon',
+  '\\underleftarrow',
+  '\\underrightarrow',
+  '\\underleftrightarrow',
+  '\\undergroup',
+  '\\underlinesegment',
+  '\\utilde',
+];
+
+/**
+ * Every decoration rule N22 treats as an operator, by canonical name: each
+ * accent (`\hat`, `\widehat`, … — `\widehat` is not `\hat`), `\overline`,
+ * `\underline`, and the superscript marks `'` (any run of primes), `*` (`*`
+ * or `\ast`) and `\dagger`. `^\top`, `^{-1}`, powers, subscripts and fonts
+ * are not decorations.
+ */
+export const DECORATION_NAMES = Object.freeze(
+  new Set([...ACCENT_LABELS, '\\overline', '\\underline', "'", '*', '\\dagger']),
+);
+
 function fontBodyText(value) {
   if (Array.isArray(value)) {
     const parts = value.map(fontBodyText);
@@ -451,6 +517,9 @@ function isIdentifierNode(node) {
   if (node.type !== 'mathord' && node.type !== 'textord') return false;
   if (typeof node.text !== 'string') return false;
   if (/^[0-9.,]+$/u.test(node.text)) return false;
+  // A prime is a mark on the symbol before it (rule N22), never a symbol of
+  // its own — whether typed `'` or spelled `^\prime`.
+  if (node.text === '\\prime') return false;
   return /^(?:\p{L}|\\[A-Za-z]+)$/u.test(node.text);
 }
 
@@ -461,16 +530,198 @@ const sameSpan = (left, right) =>
 const overlaps = (left, right) =>
   left.start < right.end && right.start < left.end;
 
+// --- decorations (rule N22) ---------------------------------------------
+
+/** The nodes of a script or group, with `{…}` groups flattened. */
+function flattenGroup(value) {
+  if (Array.isArray(value)) return value.flatMap(flattenGroup);
+  if (!isNode(value)) return [];
+  if (value.type === 'ordgroup') return flattenGroup(value.body);
+  return [value];
+}
+
+const isPrimeNode = (node) =>
+  node.type === 'textord' && node.text === '\\prime';
+
+/** The mark a superscript is, if any: a run of primes, `*` / `\ast`, or `\dagger`. */
+function scriptMarkName(sup) {
+  const items = flattenGroup(sup);
+  if (items.length === 0) return undefined;
+  if (isPrimeNode(items[0])) return "'";
+  if (items.length !== 1 || items[0].type !== 'atom') return undefined;
+  if (items[0].text === '*' || items[0].text === '\\ast') return '*';
+  if (items[0].text === '\\dagger') return '\\dagger';
+  return undefined;
+}
+
+/**
+ * The decoration a node is, as `{ name, part, command? }` — `part` is the child
+ * key holding what it decorates, `command` the source text before it — or
+ * `undefined` for any other node.
+ */
+function decorationOf(node) {
+  if (!isNode(node)) return undefined;
+  if (node.type === 'accent' || node.type === 'accentUnder') {
+    return DECORATION_NAMES.has(node.label)
+      ? { name: node.label, part: 'base', command: node.label }
+      : undefined;
+  }
+  if (node.type === 'overline' || node.type === 'underline') {
+    const name = `\\${node.type}`;
+    return { name, part: 'body', command: name };
+  }
+  if (node.type === 'supsub' && isNode(node.base)) {
+    const name = scriptMarkName(node.sup);
+    return name === undefined ? undefined : { name, part: 'base' };
+  }
+  return undefined;
+}
+
+function mergeSpans(spans) {
+  const present = spans.filter(Boolean);
+  if (present.length === 0) return undefined;
+  return {
+    start: Math.min(...present.map((span) => span.start)),
+    end: Math.max(...present.map((span) => span.end)),
+  };
+}
+
+// Every source spelling of a KaTeX font id, for widening a font node's span
+// over its command (`\bm{x}` and `\boldsymbol{x}` are one node).
+const FONT_SOURCE_COMMANDS = new Map(
+  [...FONT_COMMANDS].map(([font, command]) => [
+    font,
+    {
+      mathbf: ['\\mathbf', '\\bold'],
+      boldsymbol: ['\\boldsymbol', '\\bm'],
+      mathbb: ['\\mathbb', '\\Bbb'],
+      mathfrak: ['\\mathfrak', '\\frak'],
+    }[font] ?? [command],
+  ]),
+);
+
+/**
+ * Widen the span of an accent's (or `\overline`'s, or a font's) argument over
+ * the command that precedes it and the braces around it. `undefined` when no
+ * command in `commands` is there — a node a macro produced, whose source is
+ * elsewhere.
+ */
+function widenOverCommand(latex, span, commands) {
+  let cursor = span.start;
+  for (;;) {
+    while (cursor > 0 && /\s/.test(latex[cursor - 1])) cursor -= 1;
+    if (latex[cursor - 1] === '{' && !isEscaped(latex, cursor - 1)) {
+      cursor -= 1;
+      continue;
+    }
+    break;
+  }
+  const command = commands.find(
+    (name) => latex.slice(cursor - name.length, cursor) === name,
+  );
+  if (command === undefined) return undefined;
+  const start = cursor - command.length;
+  const argument = skipWhitespace(latex, cursor);
+  const group =
+    latex[argument] === '{' ? readBracedGroup(latex, argument) : undefined;
+  return { start, end: Math.max(span.end, group?.end ?? span.end) };
+}
+
+/** Extend a span over the `'` primes KaTeX leaves without a `loc`. */
+function extendOverPrimes(latex, end) {
+  let cursor = skipWhitespace(latex, end);
+  if (latex[cursor] !== "'") return end;
+  while (latex[cursor] === "'") cursor += 1;
+  return cursor;
+}
+
+/**
+ * A node's full extent in the source. {@link nodeSpan} reads only the `loc`s
+ * KaTeX records, and KaTeX records none on an accent, an `\overline`, a
+ * `supsub` or a `'` prime — so `\hat{\beta}` spans only `\beta`, and `b''`
+ * only `b`. This widens each decoration over its command text or its trailing
+ * primes, so a binding over a decorated form wraps the whole of it.
+ */
+function sourceSpan(value, latex) {
+  if (Array.isArray(value)) {
+    return mergeSpans(value.map((child) => sourceSpan(child, latex)));
+  }
+  if (!isNode(value)) return undefined;
+  const own =
+    value.loc &&
+    Number.isInteger(value.loc.start) &&
+    Number.isInteger(value.loc.end) &&
+    isAuthoredLocation(value.loc, latex)
+      ? { start: value.loc.start, end: value.loc.end }
+      : undefined;
+  let span = mergeSpans([
+    own,
+    ...childValues(value).map((child) => sourceSpan(child, latex)),
+  ]);
+  if (!span) return undefined;
+
+  const commands =
+    value.type === 'font'
+      ? FONT_SOURCE_COMMANDS.get(value.font)
+      : decorationOf(value)?.command;
+  if (commands !== undefined) {
+    span = widenOverCommand(latex, span, [commands].flat()) ?? span;
+  } else if (
+    value.type === 'supsub' &&
+    flattenGroup(value.sup).some((node) => isPrimeNode(node) && !node.loc)
+  ) {
+    span = { start: span.start, end: extendOverPrimes(latex, span.end) };
+  }
+  return {
+    start: span.start,
+    end: trimTrailingWhitespace(latex, span.start, span.end),
+  };
+}
+
+/** A decoration as the resolver records it, or `undefined` if its source text is not found. */
+function decorationRecord(node, latex) {
+  const decoration = decorationOf(node);
+  if (decoration === undefined) return undefined;
+  const span = sourceSpan(node, latex);
+  const partSpan = sourceSpan(node[decoration.part], latex);
+  if (!span || !partSpan) return undefined;
+  // The decoration's own text (`\hat{`, `'`) was not found: nothing to wrap.
+  if (span.start === partSpan.start && span.end === partSpan.end) {
+    return undefined;
+  }
+  const inner = flattenGroup(node[decoration.part]);
+  const single =
+    inner.length === 1 &&
+    (isIdentifierNode(inner[0]) ||
+      (inner[0].type === 'font' && FONT_COMMANDS.has(inner[0].font)));
+  const baseSpan = unwrapEnclosingGroupSpan(latex, partSpan);
+  return {
+    name: decoration.name,
+    start: span.start,
+    end: span.end,
+    part: partSpan,
+    base: single ? latex.slice(baseSpan.start, baseSpan.end).trim() : undefined,
+  };
+}
+
+const ROOT_CONTEXT = Object.freeze({ decorations: [], font: undefined });
+
 /**
  * Walk the parse tree once, collecting: every maximal run of sibling nodes
  * (`containers`, where a canonical form is matched), every identifier atom with
- * its source span, and the spans of every sub/superscript (so a symbol nested
- * in a script can still be marked).
+ * its source span, the spans of every sub/superscript (so a symbol nested in a
+ * script can still be marked), and every decoration (rule N22).
+ *
+ * Each identifier also carries the decorations it sits under (outermost first;
+ * the letter in `\hat{x}'` is under both) and the distinct font it is set in
+ * (`font: 'mathbf'`), if any. No container is recorded inside a distinct
+ * font's body, so the `N` of `\mathcal{N}` can never match an `N` entry.
  */
 function collectSourceStructure(tree, latex) {
   const containers = [];
   const identifiers = [];
   const scriptSpans = [];
+  const decorations = [];
   const seenContainers = new Set();
   const seenIdentifiers = new Set();
 
@@ -485,10 +736,12 @@ function collectSourceStructure(tree, latex) {
     containers.push(usable);
   }
 
-  function visitValue(value, ignored = false) {
+  function visitValue(value, ignored = false, context = ROOT_CONTEXT) {
     if (Array.isArray(value)) {
-      if (!ignored && value.every(isNode)) addContainer(value);
-      for (const child of value) visitValue(child, ignored);
+      if (!ignored && context.font === undefined && value.every(isNode)) {
+        addContainer(value);
+      }
+      for (const child of value) visitValue(child, ignored, context);
       return;
     }
     if (!isNode(value)) return;
@@ -509,6 +762,8 @@ function collectSourceStructure(tree, latex) {
           node: value,
           signature: sequenceSignature([value]),
           ...span,
+          decorations: context.decorations,
+          font: context.font,
         });
       }
     }
@@ -520,32 +775,126 @@ function collectSourceStructure(tree, latex) {
       }
     }
 
-    for (const child of childValues(value)) {
+    const decoration = ignored ? undefined : decorationRecord(value, latex);
+    if (decoration) decorations.push(decoration);
+    const decoratedPart = decoration ? decorationOf(value).part : undefined;
+    const fontContext =
+      value.type === 'font' && DISTINCT_FONTS.has(value.font)
+        ? { ...context, font: value.font }
+        : context;
+
+    for (const key of SOURCE_CHILD_KEYS) {
+      const child = value[key];
+      if (child === undefined || child === null) continue;
+      const childContext =
+        key === decoratedPart
+          ? {
+              ...fontContext,
+              decorations: [...fontContext.decorations, decoration],
+            }
+          : fontContext;
+      const recordContainers = !ignoredBody && childContext.font === undefined;
       if (Array.isArray(child)) {
-        if (!ignoredBody && child.every(isNode)) addContainer(child);
-        for (const nested of child) visitValue(nested, ignoredBody);
+        if (recordContainers && child.every(isNode)) addContainer(child);
+        for (const nested of child) {
+          visitValue(nested, ignoredBody, childContext);
+        }
       } else if (isNode(child)) {
-        if (!ignoredBody) addContainer([child]);
-        visitValue(child, ignoredBody);
+        if (recordContainers) addContainer([child]);
+        visitValue(child, ignoredBody, childContext);
       }
     }
   }
 
   addContainer(tree);
   visitValue(tree);
-  return { containers, identifiers, scriptSpans };
+  return { containers, identifiers, scriptSpans, decorations };
 }
 
 // --- base-glyph signatures ------------------------------------------
 
 function identifierBaseSignature(node) {
   if (isIdentifierNode(node)) return sequenceSignature([node]);
-  if (node?.type === 'supsub' && isIdentifierNode(node.base)) {
+  // `t_k` lends its card to a bare `t`, but `b'` or `\theta^{*}` does not lend
+  // its card to `b` or `\theta`: a mark makes a different quantity (N22).
+  if (
+    node?.type === 'supsub' &&
+    isIdentifierNode(node.base) &&
+    scriptMarkName(node.sup) === undefined
+  ) {
     return sequenceSignature([node.base]);
   }
   return undefined;
 }
 
+/**
+ * The decoration a notation entry is an **operator entry** for: exactly one
+ * decoration over an empty group (`\hat{}`, `\overline{}`, `{}'`, `{}^{*}`,
+ * `{}^{\dagger}`), else `undefined`. Such an entry explains the decoration
+ * wherever it composes (rule N22); it never binds a letter.
+ */
+function decorationOfTree(tree) {
+  if (!Array.isArray(tree) || tree.length !== 1) return undefined;
+  const [node] = tree;
+  const decoration = decorationOf(node);
+  if (decoration === undefined) return undefined;
+  if (node.type === 'supsub' && node.sub) return undefined;
+  const part = node[decoration.part];
+  return isNode(part) && part.type === 'ordgroup' && part.body.length === 0
+    ? decoration.name
+    : undefined;
+}
+
+/**
+ * The operator-entry `latex` for a decoration name — the decoration over an
+ * empty group: `\hat{}`, `\overline{}`, `{}'`, `{}^{*}`, `{}^{\dagger}`. The
+ * inverse of {@link decorationOfEntry}, and how the decoration alone is shown.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function operatorEntryLatex(name) {
+  if (name === "'") return "{}'";
+  if (name === '*') return '{}^{*}';
+  if (name === '\\dagger') return '{}^{\\dagger}';
+  return `${name}{}`;
+}
+
+/**
+ * How a decoration is shown on its own — over a placeholder square, so a
+ * reader sees where it goes: `\hat{\square}`, `\square'`, `\square^{*}`.
+ * A lone `\dot{}` renders as a speck. Display only: the entry's `latex` stays
+ * the empty-group form the resolver keys on.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function operatorDisplayLatex(name) {
+  return operatorEntryLatex(name).replace(/^\{\}/, '\\square').replace(/\{\}$/, '{\\square}');
+}
+
+/**
+ * The decoration a notation entry's `latex` is an operator entry for (see
+ * {@link decorationOfTree}), or `undefined`. `\hat{\beta}` is a whole form,
+ * not an operator entry.
+ *
+ * @param {string} latex
+ * @returns {string | undefined}
+ */
+export function decorationOfEntry(latex) {
+  if (typeof latex !== 'string' || latex.trim() === '') return undefined;
+  try {
+    return decorationOfTree(
+      parseMath(stripNotationMarkers(latex), 'operator entry'),
+    );
+  } catch (error) {
+    if (error instanceof GlyphResolutionError && error.code === 'invalid-latex') {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
 /**
  * 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
@@ -623,7 +972,7 @@ function unwrapEnclosingGroupSpan(latex, span) {
 }
 
 const FONT_WRAPPER_OPEN =
-  /\\(?:mathbb|mathcal|mathfrak|mathscr|mathrm|mathbf|mathit)\{$/;
+  /\\(?:mathbb|mathcal|mathfrak|mathscr|mathrm|mathbf|mathit|mathnormal|mathsf|mathtt|boldsymbol|bm|bold|Bbb|frak)\{$/;
 
 /**
  * KaTeX puts no `loc` on a font node (`\mathbb{E}`, `\mathrm{SST}`, …), so a
@@ -666,7 +1015,7 @@ function isSafeScriptNesting(inner, outer, scriptSpans) {
  * registered. This is deliberately *not* `collectSourceStructure`'s
  * `identifiers` list: that list is built for scanning *page* math, where a
  * `\mathrm{…}` body is correctly treated as opaque (never a bindable atom on
- * its own, [N3](../../docs/authoring/notation.md#n3)) — but reusing it here to
+ * its own, [N10](../../docs/authoring/notation.md#n10)) — but reusing it here to
  * gate the *definition's own* registration wrongly excluded every glyph whose
  * whole declared form is a roman label (`\mathrm{SSR}`, `\mathrm{SST}`, …):
  * such a definition produced zero `identifiers`, so it never entered
@@ -703,6 +1052,7 @@ function buildGlyphIndex(definitions) {
   const bySignature = new Map();
   const byBase = new Map();
   const ambiguousBase = new Set();
+  const operators = new Map();
   let maxNodeLength = 0;
 
   for (const [index, value] of definitions.entries()) {
@@ -739,6 +1089,22 @@ function buildGlyphIndex(definitions) {
     const entry = { key, notation };
     byKey.set(key, entry);
 
+    // An operator entry (`\hat{}`) binds no letter; it explains its
+    // decoration wherever that composes (rule N22).
+    const operator = decorationOfTree(tree);
+    if (operator !== undefined) {
+      const clash = operators.get(operator);
+      if (clash && clash !== key) {
+        fail(
+          'ambiguous-canonical-notation',
+          `Page glyphs "${clash}" and "${key}" are both operator entries for ${operator}.`,
+          { left: clash, right: key },
+        );
+      }
+      operators.set(operator, key);
+      continue;
+    }
+
     const signature = sequenceSignature(tree);
     if (hasBindableGlyph(tree) && tree.length > 0) {
       const clash = bySignature.get(signature);
@@ -763,7 +1129,7 @@ function buildGlyphIndex(definitions) {
     }
   }
 
-  return { byKey, bySignature, byBase, ambiguousBase, maxNodeLength };
+  return { byKey, bySignature, byBase, ambiguousBase, operators, maxNodeLength };
 }
 
 /** Bind whole canonical forms: greedy longest match, left to right, per run. */
@@ -783,7 +1149,9 @@ function matchCanonicalForms(latex, strippedSource, containers, glyphs) {
         const nodes = container.slice(cursor, cursor + length);
         const key = glyphs.bySignature.get(sequenceSignature(nodes));
         if (key === undefined) continue;
-        const rawSpan = sequenceSpan(nodes, strippedSource);
+        // `sourceSpan`, not `sequenceSpan`: a whole-form match on `\hat{\beta}`
+        // or `b'` wraps the decoration too, not just the letter under it.
+        const rawSpan = sourceSpan(nodes, strippedSource);
         if (!rawSpan) continue;
         const span = expandFontWrapperSpan(
           latex,
@@ -837,6 +1205,9 @@ function matchBaseGlyphs(latex, identifiers, canonical, glyphs, scriptSpans) {
 
     const cover = canonical.find((binding) => contains(binding, identifier));
     if (cover && !isSafeScriptNesting(identifier, cover, scriptSpans)) continue;
+    // `\mathbf{x}` is a different symbol from `x` (rule N4): it binds only
+    // through its own entry or an `\explain`, never the plain letter's card.
+    if (identifier.font !== undefined) continue;
 
     const baseSignature = identifier.signature;
     if (glyphs.ambiguousBase.has(baseSignature)) {
@@ -899,26 +1270,61 @@ function injectScopeBindings(latex, bindings) {
   return output;
 }
 
-function unresolvedIdentifiers(latex, identifiers, bindings) {
-  return identifiers
-    .filter((identifier) => {
-      const token = latex.slice(identifier.start, identifier.end);
-      return (
-        !BASE_LIBRARY.has(token) &&
-        !bindings.some((binding) => contains(binding, identifier))
-      );
-    })
-    .map(({ start, end }) => {
+/**
+ * Every identifier no binding covers, plus every decorated form whose
+ * decoration is suspended on this page and that no whole form covers (rule
+ * 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) {
+  const letters = identifiers
+    .filter(
+      (identifier) =>
+        !bindings.some((binding) => contains(binding, identifier)) &&
+        !suspended.some((decoration) => contains(decoration.part, identifier)),
+    )
+    .map(({ start, end, font }) => {
       // 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 });
       return {
         token: latex.slice(wrapped.start, wrapped.end),
+        // A styled base-library letter (`\mathbf{e}`) is not Euler's number.
+        libraryToken: latex.slice(
+          font === undefined ? start : wrapped.start,
+          font === undefined ? end : wrapped.end,
+        ),
         start: wrapped.start,
         end: wrapped.end,
+        ...(font === undefined ? {} : { font }),
       };
     })
-    .sort((left, right) => left.start - right.start || left.end - right.end);
+    .filter(({ libraryToken }) => !BASE_LIBRARY.has(libraryToken))
+    .map(({ libraryToken: _libraryToken, ...item }) => item);
+  const decorated = suspended.map(({ name, start, end }) => ({
+    token: latex.slice(start, end),
+    start,
+    end,
+    suspended: name,
+  }));
+  return [...letters, ...decorated].sort(
+    (left, right) => left.start - right.start || left.end - right.end,
+  );
+}
+
+/**
+ * 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
+ * injected around the decoration never splits `\explain{key}` from its `{…}`.
+ */
+function widenOverExplainPrefix(span, explicitCalls) {
+  let { start } = span;
+  for (;;) {
+    const call = explicitCalls.find((candidate) => candidate.prefixEnd === start);
+    if (!call) break;
+    start = call.callStart;
+  }
+  return { start, end: span.end };
 }
 
 // --- N13: nonlinear functions take a parenthesized argument --------------
@@ -1162,14 +1568,24 @@ function findNestedBareDelimiters(tree) {
  * Resolve and annotate one KaTeX expression against a page's flat glyph table.
  * Source offsets in the result always refer to the original, unmodified LaTeX.
  *
+ * Decorations (rule N22) are reported in `decorations`: `wholeForm` is the key
+ * of the binding that covers the decorated form (`\hat{\beta}` has its own
+ * entry), else `null`; `operator` is the key of the operator entry
+ * (`latex: \hat{}`) whose `\explain` now wraps the decorated form, else
+ * `null`. A decoration named in `options.suspended` never composes: a
+ * decorated form no whole form covers is reported in `unresolved`, marked
+ * `suspended`.
+ *
  * @param {string} latex
  * @param {Array<{key: string, notation: string}>} definitions
+ * @param {{ suspended?: readonly string[] }} [options]
  */
-export function resolveMathGlyphs(latex, definitions) {
+export function resolveMathGlyphs(latex, definitions, options = {}) {
   if (typeof latex !== 'string') {
     fail('invalid-latex-input', 'Math source must be a string.');
   }
 
+  const suspended = new Set(options.suspended ?? []);
   const glyphs = buildGlyphIndex(definitions);
   const explicitCalls = findExplainCalls(latex, glyphs.byKey);
   // The source KaTeX actually parses — `\explain{key}{` prefixes blanked to
@@ -1206,10 +1622,8 @@ export function resolveMathGlyphs(latex, definitions) {
       { violations: nestingViolations },
     );
   }
-  const { containers, identifiers, scriptSpans } = collectSourceStructure(
-    tree,
-    strippedSource,
-  );
+  const { containers, identifiers, scriptSpans, decorations } =
+    collectSourceStructure(tree, strippedSource);
 
   // A canonical container match can be found by seeing through transparent
   // ordgroup/font wrapping into a structural sibling of an explicit
@@ -1237,7 +1651,48 @@ export function resolveMathGlyphs(latex, definitions) {
     scriptSpans,
   );
 
-  const bindings = [...canonical, ...base, ...explicitCalls]
+  // Rule N22: a decoration a whole form covers is part of that symbol. One
+  // that composes is wrapped in its operator entry's `\explain`, around the
+  // letter's own — unless it is suspended on this page, when the decorated
+  // form is unresolved.
+  const letterBindings = [...canonical, ...base, ...explicitCalls];
+  const operatorBindings = [];
+  const suspendedDecorations = [];
+  const decorationResults = decorations.map((decoration) => {
+    const span = widenOverExplainPrefix(decoration, explicitCalls);
+    const wholeForm =
+      covered.find((binding) => contains(binding, span))?.key ?? null;
+    let operator = null;
+    if (wholeForm === null && suspended.has(decoration.name)) {
+      suspendedDecorations.push({ ...decoration, ...span });
+    } else if (wholeForm === null && glyphs.operators.has(decoration.name)) {
+      const straddles = [...letterBindings, ...operatorBindings].some(
+        (binding) =>
+          overlaps(binding, span) &&
+          !contains(span, binding) &&
+          !contains(binding, span),
+      );
+      if (!straddles) {
+        operator = glyphs.operators.get(decoration.name);
+        operatorBindings.push({
+          key: operator,
+          ...span,
+          token: latex.slice(span.start, span.end),
+          level: 'scope',
+          match: 'operator',
+        });
+      }
+    }
+    return {
+      name: decoration.name,
+      ...span,
+      token: latex.slice(span.start, span.end),
+      wholeForm,
+      operator,
+    };
+  });
+
+  const bindings = [...letterBindings, ...operatorBindings]
     .sort(
       (left, right) =>
         left.start - right.start ||
@@ -1279,7 +1734,13 @@ export function resolveMathGlyphs(latex, definitions) {
       match,
       token,
     })),
-    unresolved: unresolvedIdentifiers(latex, identifiers, bindings),
+    unresolved: unresolvedIdentifiers(
+      latex,
+      identifiers,
+      bindings,
+      suspendedDecorations,
+    ),
+    decorations: decorationResults,
   };
 }
 
@@ -1383,18 +1844,92 @@ export function collectOperators(latex) {
   return operators;
 }
 
+// --- decorations -----------------------------------------------------
+
+/**
+ * Blank every `\explain{key}{` / `\slot{key}{` prefix to spaces, keeping the
+ * source's length, so KaTeX parses what the markers wrap and every offset
+ * still points into the original. Unlike `findExplainCalls`, no key is
+ * checked: a scan has no glyph table.
+ */
+function blankMarkerPrefixes(latex) {
+  let source = latex;
+  const calls = [];
+  for (let cursor = 0; cursor < latex.length; cursor++) {
+    const command = MARKER_COMMANDS.find(
+      (name) =>
+        latex.startsWith(name, cursor) &&
+        !isEscaped(latex, cursor) &&
+        !/[A-Za-z@]/.test(latex[cursor + name.length] ?? ''),
+    );
+    if (!command) continue;
+    const keyGroup = readBracedGroup(
+      latex,
+      skipWhitespace(latex, cursor + command.length),
+    );
+    if (!keyGroup) continue;
+    const prefixEnd = skipWhitespace(latex, keyGroup.end);
+    if (latex[prefixEnd] !== '{') continue;
+    source =
+      source.slice(0, cursor) +
+      ' '.repeat(prefixEnd - cursor) +
+      source.slice(prefixEnd);
+    calls.push({ callStart: cursor, prefixEnd });
+    cursor = prefixEnd;
+  }
+  return { source, calls };
+}
+
+/**
+ * Every decoration in one KaTeX expression (rule N22): an accent (`\hat`,
+ * `\widehat`, …), `\overline` / `\underline`, or a superscript mark (`'` for
+ * any run of primes, `*` for `*` / `\ast`, `\dagger`). `name` is the
+ * canonical name in {@link DECORATION_NAMES}; `start`/`end` span the whole
+ * decorated form in `latex`; `base` is the source of what it decorates when
+ * that is one symbol (`\beta`, `b`, `\mathbf{x}`), else `undefined`.
+ *
+ * Pure read, the twin of {@link collectOperators}: `\text{}`, `\mathrm{}` and
+ * operator bodies are skipped, and a span that will not parse returns `[]`
+ * (the math gate owns that error).
+ *
+ * @param {string} latex
+ * @returns {Array<{ name: string, start: number, end: number, base: string | undefined }>}
+ */
+export function collectDecorations(latex) {
+  if (typeof latex !== 'string' || latex.trim() === '') return [];
+
+  const { source, calls } = blankMarkerPrefixes(latex);
+  let tree;
+  try {
+    tree = parseMath(source, 'decoration scan');
+  } catch (error) {
+    if (error instanceof GlyphResolutionError && error.code === 'invalid-latex') {
+      return [];
+    }
+    throw error;
+  }
+
+  return collectSourceStructure(tree, source).decorations.map(
+    ({ name, start, end, base }) => ({
+      name,
+      ...widenOverExplainPrefix({ start, end }, calls),
+      base,
+    }),
+  );
+}
+
 // --- named roman labels ----------------------------------------------
 
 /**
  * Every multi-letter `\mathrm{…}` label in one KaTeX expression (`KE`, `PV`,
  * `opt`) — the upright-label counterpart to {@link collectOperators}. A
- * single-letter body (`\mathrm{d}`, the N7 differential) is not collected:
+ * single-letter body (`\mathrm{d}`, the rule-N2 differential) is not collected:
  * that one is a fixed typographic operator, not a named quantity a reader
  * would need explained.
  *
  * Pure read: nothing here rewrites the source. Used by the
  * `roman-label-explained` consistency check (rule N10); the glyph resolver
- * still skips `\mathrm{…}` bodies whole ([N3](../../docs/authoring/notation.md#n3)).
+ * still skips `\mathrm{…}` bodies whole ([N10](../../docs/authoring/notation.md#n10)).
  *
  * Same `stripNotationMarkers` preprocessing as {@link collectOperators}, and
  * for the same reason: an unstripped `\explain{…}{…}` elsewhere in the span