explico 0.4.0 → 0.6.0

package/src/reference/math-glyphs.mjs

@@ -1,6 +1,7 @@
 import katex from 'katex';
 
 import { BASE_LIBRARY } from './base-library.mjs';
+import { PARENTHESIZED_FUNCTIONS } from './base-operators.mjs';
 
 /**
  * Page-level glyph-map resolver (cleanup plan, D1 decision 2026-09-02).
@@ -181,6 +182,52 @@ function readBracedGroup(value, start) {
   return undefined;
 }
 
+const MARKER_COMMANDS = [EXPLAIN_COMMAND, '\\slot'];
+
+/**
+ * Strip Explico's own `\explain{key}{latex}` / `\slot{key}{latex}` markers
+ * (see `katex-options.mjs`) down to the LaTeX they wrap, recursively. Lesson
+ * math — both a notation card's `formula` and an equation written directly
+ * in prose — carries these markers inline so every symbol is hoverable; a
+ * reader copying the equation out of this system wants the plain math
+ * underneath, not internal notation-key plumbing that means nothing to
+ * KaTeX, MathJax, or LaTeX anywhere else. Shared by `render-notation-math.ts`
+ * (a notation card's copy button) and `remark-notation.mjs` (a numbered
+ * display equation's copy button) — kept here, rather than in either, so
+ * neither module has to import the other.
+ */
+export function stripNotationMarkers(latex) {
+  let result = '';
+  let cursor = 0;
+
+  while (cursor < latex.length) {
+    const command = MARKER_COMMANDS.find(
+      (name) =>
+        latex.startsWith(name, cursor) &&
+        !isEscaped(latex, cursor) &&
+        !/[A-Za-z@]/.test(latex[cursor + name.length] ?? ''),
+    );
+
+    const keyGroup = command
+      ? readBracedGroup(latex, skipWhitespace(latex, cursor + command.length))
+      : undefined;
+    const contentGroup = keyGroup
+      ? readBracedGroup(latex, skipWhitespace(latex, keyGroup.end))
+      : undefined;
+
+    if (contentGroup) {
+      result += stripNotationMarkers(contentGroup.content);
+      cursor = contentGroup.end;
+      continue;
+    }
+
+    result += latex[cursor];
+    cursor += 1;
+  }
+
+  return result;
+}
+
 /**
  * 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
@@ -322,7 +369,24 @@ function sequenceSignature(nodes) {
 
 // --- source spans -----------------------------------------------------
 
-function nodeSpan(node) {
+/**
+ * KaTeX's lexer swallows trailing insignificant whitespace after a
+ * control-word command (`\epsilon`, `\mathrm`, …) into that token's own
+ * `loc.end` — including whitespace this resolver introduces itself when it
+ * blanks an `\explain{key}{` prefix down to spaces (`sourceWithoutExplainPrefixes`).
+ * A symbol's own text never legitimately ends in whitespace, so any span read
+ * off `loc` is trimmed back to its last non-space character before a caller
+ * treats it as the symbol's real boundary — otherwise a bare symbol sitting
+ * right before an `\explain{…}{…}` call gets a span that reaches past itself
+ * and into that call's own command text.
+ */
+function trimTrailingWhitespace(latex, start, end) {
+  let trimmed = end;
+  while (trimmed > start && /\s/.test(latex[trimmed - 1])) trimmed -= 1;
+  return trimmed;
+}
+
+function nodeSpan(node, latex) {
   let start = Number.POSITIVE_INFINITY;
   let end = Number.NEGATIVE_INFINITY;
   const visited = new Set();
@@ -347,13 +411,12 @@ function nodeSpan(node) {
   }
 
   visit(node);
-  return Number.isFinite(start) && Number.isFinite(end)
-    ? { start, end }
-    : undefined;
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return undefined;
+  return { start, end: trimTrailingWhitespace(latex, start, end) };
 }
 
-function sequenceSpan(nodes) {
-  const spans = nodes.map(nodeSpan).filter(Boolean);
+function sequenceSpan(nodes, latex) {
+  const spans = nodes.map((node) => nodeSpan(node, latex)).filter(Boolean);
   if (spans.length === 0) return undefined;
   return {
     start: Math.min(...spans.map((span) => span.start)),
@@ -381,6 +444,8 @@ const contains = (outer, inner) =>
   outer.start <= inner.start && inner.end <= outer.end;
 const sameSpan = (left, right) =>
   left.start === right.start && left.end === right.end;
+const overlaps = (left, right) =>
+  left.start < right.end && right.start < left.end;
 
 /**
  * Walk the parse tree once, collecting: every maximal run of sibling nodes
@@ -388,7 +453,7 @@ const sameSpan = (left, right) =>
  * its source span, and the spans of every sub/superscript (so a symbol nested
  * in a script can still be marked).
  */
-function collectSourceStructure(tree) {
+function collectSourceStructure(tree, latex) {
   const containers = [];
   const identifiers = [];
   const scriptSpans = [];
@@ -398,7 +463,7 @@ function collectSourceStructure(tree) {
   function addContainer(nodes) {
     const usable = nodes.filter(isNode);
     if (usable.length === 0) return;
-    const span = sequenceSpan(usable);
+    const span = sequenceSpan(usable, latex);
     if (!span) return;
     const identity = `${span.start}:${span.end}:${usable.length}:${sequenceSignature(usable)}`;
     if (seenContainers.has(identity)) return;
@@ -423,7 +488,7 @@ function collectSourceStructure(tree) {
       IGNORED_MATH_TOKENS.has(fontTokenText(value));
 
     if (!ignored && isIdentifierNode(value)) {
-      const span = nodeSpan(value);
+      const span = nodeSpan(value, latex);
       if (span && !seenIdentifiers.has(`${span.start}:${span.end}`)) {
         seenIdentifiers.add(`${span.start}:${span.end}`);
         identifiers.push({
@@ -436,7 +501,7 @@ function collectSourceStructure(tree) {
 
     if (value.type === 'supsub') {
       for (const script of [value.sub, value.sup]) {
-        const span = nodeSpan(script);
+        const span = nodeSpan(script, latex);
         if (span) scriptSpans.push(span);
       }
     }
@@ -485,19 +550,60 @@ function canonicalBaseSignature(tree) {
   return identifierBaseSignature(head);
 }
 
+/**
+ * When a span sits exactly at the payload of an `\explain{key}{…}` / `\slot{key}{…}`
+ * marker — its whole content, brace to brace — peel the marker off, mirroring
+ * `stripNotationMarkers`. Signature matching sees straight through ordgroup
+ * *and* an already-explicit call (both are transparent wrapping for structural
+ * comparison), so a canonical container match can legitimately resolve to a
+ * span that, in the raw source, is entirely one explicit call; without this,
+ * `unwrapEnclosingGroupSpan` stops at the call's leading `\`, leaving a span
+ * that swallows the whole `\explain{key}{` command text as if it were plain
+ * LaTeX (see `notation.md`'s aligned-block/adjacency traps).
+ */
+function unwrapMarkerSpan(latex, span) {
+  const { start, end } = span;
+  const command = MARKER_COMMANDS.find(
+    (name) =>
+      latex.startsWith(name, start) &&
+      !isEscaped(latex, start) &&
+      !/[A-Za-z@]/.test(latex[start + name.length] ?? ''),
+  );
+  if (!command) return undefined;
+
+  const keyGroup = readBracedGroup(latex, skipWhitespace(latex, start + command.length));
+  const contentGroup = keyGroup
+    ? readBracedGroup(latex, skipWhitespace(latex, keyGroup.end))
+    : undefined;
+  if (!contentGroup || contentGroup.end !== end) return undefined;
+
+  return { start: contentGroup.contentStart, end: contentGroup.contentEnd };
+}
+
 /**
  * KaTeX puts source braces inside an ordgroup node's `loc`, but signatures
- * treat ordgroups as transparent. Peel a fully-enclosing `{…}` off a matched
- * span so `\frac{j}{m}` marks as `\frac{\explain{…}{j}}{…}`, not
- * `\frac\explain{…}{{j}}…`.
+ * treat ordgroups as transparent. Peel a fully-enclosing `{…}` (or an
+ * already-explicit `\explain{key}{…}`/`\slot{key}{…}` marker, {@link
+ * unwrapMarkerSpan}) off a matched span so `\frac{j}{m}` marks as
+ * `\frac{\explain{…}{j}}{…}`, not `\frac\explain{…}{{j}}…`.
  */
 function unwrapEnclosingGroupSpan(latex, span) {
   let { start, end } = span;
-  while (latex[start] === '{') {
-    const group = readBracedGroup(latex, start);
-    if (!group || group.end !== end) break;
-    start = group.contentStart;
-    end = group.contentEnd;
+  for (;;) {
+    if (latex[start] === '{') {
+      const group = readBracedGroup(latex, start);
+      if (group && group.end === end) {
+        start = group.contentStart;
+        end = group.contentEnd;
+        continue;
+      }
+    }
+    const marker = unwrapMarkerSpan(latex, { start, end });
+    if (marker) {
+      ({ start, end } = marker);
+      continue;
+    }
+    break;
   }
   return { start, end };
 }
@@ -506,19 +612,26 @@ const FONT_WRAPPER_OPEN =
   /\\(?:mathbb|mathcal|mathfrak|mathscr|mathrm|mathbf|mathit)\{$/;
 
 /**
- * KaTeX puts no `loc` on a `\mathbb{…}` font node, so a span derived from one
- * begins at the inner letter. When a matched span sits exactly inside a
- * single-letter font command, widen it to wrap the whole `\mathbb{E}` token so
- * the injected `\explain{…}{…}` stays brace-balanced.
+ * KaTeX puts no `loc` on a font node (`\mathbb{E}`, `\mathrm{SST}`, …), so a
+ * span derived from one begins at its inner content, not its own command
+ * text. When a matched span sits exactly inside a font command's braces —
+ * covering that group's entire content, of any length — widen it to wrap the
+ * whole token (`\mathbb{E}`, `\mathrm{SST}`) so the injected `\explain{…}{…}`
+ * stays brace-balanced. (Originally restricted to a single-letter body —
+ * `\mathbb{E}` — which left a multi-letter roman label like `\mathrm{SST}`
+ * wrapped as `\mathrm{\explain{…}{SST}}` instead of the correct
+ * `\explain{…}{\mathrm{SST}}`.)
  */
 function expandFontWrapperSpan(latex, span) {
   const open = latex.slice(0, span.start).match(FONT_WRAPPER_OPEN);
   if (!open) return span;
   const group = readBracedGroup(latex, span.start - 1);
-  if (!group || group.contentEnd - group.contentStart !== 1) return span;
+  if (!group || group.contentStart !== span.start || group.contentEnd !== span.end) {
+    return span;
+  }
   return {
     start: span.start - open[0].length,
-    end: Math.max(span.end, group.end),
+    end: group.end,
   };
 }
 
@@ -532,6 +645,33 @@ function isSafeScriptNesting(inner, outer, scriptSpans) {
 
 // --- glyph table + matching -----------------------------------------
 
+/**
+ * Whether a definition's own canonical LaTeX has content worth indexing for
+ * bare-occurrence matching — as opposed to a degenerate form (bare punctuation
+ * or a relation like `=`) that would over-match unrelated page text if
+ * 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
+ * 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
+ * `bySignature`/`byBase` and could never auto-resolve at a bare occurrence,
+ * regardless of where that occurrence sat on the page. A named operator
+ * (`\operatorname{SE}`) is real content the same way; a bare `=` or `+` is not.
+ */
+function hasBindableGlyph(value) {
+  if (Array.isArray(value)) return value.some(hasBindableGlyph);
+  if (!isNode(value)) return false;
+  if (isIdentifierNode(value)) return true;
+  if (value.type === 'font' && FONT_COMMANDS.has(value.font)) return true;
+  if (value.type === 'op' || value.type === 'operatorname') return true;
+  for (const key of SOURCE_CHILD_KEYS) {
+    if (hasBindableGlyph(value[key])) return true;
+  }
+  return false;
+}
+
 /**
  * Index the page glyph table by structural signature. Because one glyph carries
  * one meaning per page, each signature maps to exactly one key; a genuine
@@ -586,8 +726,7 @@ function buildGlyphIndex(definitions) {
     byKey.set(key, entry);
 
     const signature = sequenceSignature(tree);
-    const hasIdentifier = collectSourceStructure(tree).identifiers.length > 0;
-    if (hasIdentifier && tree.length > 0) {
+    if (hasBindableGlyph(tree) && tree.length > 0) {
       const clash = bySignature.get(signature);
       if (clash && clash !== key) {
         fail(
@@ -614,7 +753,7 @@ function buildGlyphIndex(definitions) {
 }
 
 /** Bind whole canonical forms: greedy longest match, left to right, per run. */
-function matchCanonicalForms(latex, containers, glyphs) {
+function matchCanonicalForms(latex, strippedSource, containers, glyphs) {
   const bindings = [];
   const claimed = [];
 
@@ -630,7 +769,7 @@ function matchCanonicalForms(latex, containers, glyphs) {
         const nodes = container.slice(cursor, cursor + length);
         const key = glyphs.bySignature.get(sequenceSignature(nodes));
         if (key === undefined) continue;
-        const rawSpan = sequenceSpan(nodes);
+        const rawSpan = sequenceSpan(nodes, strippedSource);
         if (!rawSpan) continue;
         const span = expandFontWrapperSpan(
           latex,
@@ -768,6 +907,243 @@ function unresolvedIdentifiers(latex, identifiers, bindings) {
     .sort((left, right) => left.start - right.start || left.end - right.end);
 }
 
+// --- N13: nonlinear functions take a parenthesized argument --------------
+
+// Opening delimiters that visibly bracket a function's argument. A bare `{`
+// (KaTeX `ordgroup`) does not count — it renders no visible mark at all, so
+// `\sin{x}` reads identically to the bare `\sin x` this rule forbids.
+const FUNCTION_ARG_OPENERS = new Set(['(', '[', '\\{']);
+
+// Node types that plausibly start a bare (unparenthesized) argument right
+// after a function name — a letter, a digit, an invisible `{…}` group,
+// another function, an exponent/subscript structure, a fraction, a root, or
+// a styled/labelled run (`\mathrm{…}`, `\color{…}{…}`, …). Anything else
+// (a relation, a binary operator, closing punctuation, or nothing at all) is
+// left alone: the function has no argument in this position to complain
+// about.
+const BARE_ARGUMENT_NODE_TYPES = new Set([
+  'mathord',
+  'textord',
+  'ordgroup',
+  'op',
+  'operatorname',
+  'supsub',
+  'genfrac',
+  'sqrt',
+  'font',
+  'accent',
+  'accentUnder',
+  'overline',
+  'underline',
+  'phantom',
+  'raisebox',
+  'href',
+  'color',
+  'styling',
+  'mclass',
+]);
+
+/** `\,`, `\;`, `\!`, `~`, … — spacing that sits between a function and its
+ * argument without being the argument itself. */
+function isSpacingNode(node) {
+  return isNode(node) && node.type === 'kern';
+}
+
+/** True when `node` is a visible parenthesis/bracket group opening here. */
+function opensFunctionArgument(node) {
+  if (!isNode(node)) return false;
+  if (node.type === 'leftright') return true;
+  return (
+    node.type === 'atom' &&
+    node.family === 'open' &&
+    FUNCTION_ARG_OPENERS.has(node.text)
+  );
+}
+
+/**
+ * The bare command name (`sin`, `log`, …) when `node` is a call to one of
+ * {@link PARENTHESIZED_FUNCTIONS} — either the `op` node itself, or one
+ * wrapped in a `supsub` for `\sin^2 x` / `\log_2 x`.
+ */
+function parenthesizedFunctionName(node) {
+  if (!isNode(node)) return null;
+  if (node.type === 'op' && typeof node.name === 'string') {
+    const name = node.name.replace(/^\\/, '');
+    return PARENTHESIZED_FUNCTIONS.has(name) ? name : null;
+  }
+  if (node.type === 'supsub') return parenthesizedFunctionName(node.base);
+  return null;
+}
+
+/**
+ * Every `\sin x`-shaped violation of N13 in one already-parsed KaTeX tree: a
+ * {@link PARENTHESIZED_FUNCTIONS} name immediately followed, in its own
+ * sibling run, by something that reads as a bare argument rather than a
+ * parenthesized (or bracketed) one. Mirrors `collectOperators`'s tree walk,
+ * but needs sibling context a plain node visitor doesn't carry, so it walks
+ * array bodies explicitly instead of reusing that helper.
+ *
+ * @returns {string[]} one function name per violation, in document order.
+ */
+function findUnparenthesizedFunctionCalls(tree) {
+  const violations = [];
+
+  const visitSiblings = (nodes) => {
+    for (let i = 0; i < nodes.length; i++) {
+      const name = parenthesizedFunctionName(nodes[i]);
+      if (!name) continue;
+      let j = i + 1;
+      while (j < nodes.length && isSpacingNode(nodes[j])) j += 1;
+      const next = j < nodes.length ? nodes[j] : undefined;
+      if (opensFunctionArgument(next)) continue;
+      if (isNode(next) && BARE_ARGUMENT_NODE_TYPES.has(next.type)) {
+        violations.push(name);
+      }
+    }
+  };
+
+  const visit = (value) => {
+    if (Array.isArray(value)) {
+      visitSiblings(value);
+      for (const child of value) visit(child);
+      return;
+    }
+    if (!isNode(value)) return;
+    for (const key of Object.keys(value)) {
+      if (key === 'loc') continue;
+      visit(value[key]);
+    }
+  };
+
+  visit(tree);
+  return violations;
+}
+
+// --- N15: nested visible delimiters need \left/\right sizing -------------
+
+// The four visible delimiter glyphs this rule regulates, keyed by their
+// KaTeX source text. `{`/`}` bare is invisible LaTeX grouping, not a visible
+// mark, so only the escaped, visible `\{`/`\}` counts — the same distinction
+// `FUNCTION_ARG_OPENERS` above already draws.
+const NESTED_DELIM_OPEN = new Map([
+  ['(', 'paren'],
+  ['[', 'bracket'],
+  ['\\{', 'brace'],
+]);
+const NESTED_DELIM_CLOSE = new Map([
+  [')', 'paren'],
+  [']', 'bracket'],
+  ['\\}', 'brace'],
+]);
+// Recognised on either side of a `\left…\right` pair so a mixed pair like
+// `\left.\right|` (an evaluation bar with an invisible left side) still
+// counts as already-sized.
+const NESTED_DELIM_CHARS = new Set(['(', ')', '[', ']', '\\{', '\\}', '|']);
+
+/**
+ * Every N15 violation in one already-parsed KaTeX tree: a bare `(`, `[`,
+ * `\{`, or `|` that either sits inside another of these four delimiters, or
+ * itself contains one, without either side switching to the `\left`/`\right`
+ * auto-sizing form. A `\left…\right` pair is never itself reported — it is
+ * the fix the rule asks for — but a bare delimiter one level inside it still
+ * needs its own `\left`/`\right`, since sizing one level of a nest does not
+ * size the rest.
+ *
+ * Mirrors {@link findUnparenthesizedFunctionCalls}'s tree walk, but needs one
+ * stack carried across the whole recursion (nesting here is "does an
+ * ancestor node in the tree still have an open delimiter", not sibling
+ * adjacency), so it walks the tree itself rather than reusing a sibling-only
+ * visitor.
+ *
+ * `|` has no distinct open/close glyph, so a bare `|` toggles: the first one
+ * at the current depth opens a pipe scope, the next one closes it — matching
+ * how `\lvert x \rvert`-less absolute value is actually written in this
+ * corpus (N9's `\lvert…\rvert` guidance is about *outside*-math prose; a bare
+ * `|` pair is unremarkable inside `$…$` on its own).
+ *
+ * @returns {{ type: string, char: string }[]} one entry per delimiter
+ *   instance that must become `\left`/`\right`, in document order.
+ */
+function findNestedBareDelimiters(tree) {
+  const stack = [];
+  const violations = [];
+
+  const flag = (entry) => {
+    if (entry.reported) return;
+    entry.reported = true;
+    violations.push({ type: entry.type, char: entry.char });
+  };
+
+  const pushOpen = (type, char, bare) => {
+    const entry = { type, char, bare, reported: false };
+    if (stack.length > 0) {
+      const parent = stack[stack.length - 1];
+      // The parent already contains a nested delimiter: if it is bare, it
+      // now needs sizing too, regardless of whether this new one is sized.
+      if (parent.bare) flag(parent);
+      // This one is nested inside another delimiter's span: if it is bare,
+      // it needs sizing, regardless of whether the parent is already sized.
+      if (bare) flag(entry);
+    }
+    stack.push(entry);
+  };
+
+  const visit = (node) => {
+    if (Array.isArray(node)) {
+      for (const child of node) visit(child);
+      return;
+    }
+    if (!isNode(node)) return;
+
+    // A visible delimiter only counts in math mode — the same character
+    // inside `\text{…}` is display text, not a sizing delimiter (it parses
+    // to a plain `textord` in text mode, never reaching this branch).
+    if (node.type === 'atom' && node.mode === 'math') {
+      if (node.family === 'open' && NESTED_DELIM_OPEN.has(node.text)) {
+        pushOpen(NESTED_DELIM_OPEN.get(node.text), node.text, true);
+        return;
+      }
+      if (node.family === 'close' && NESTED_DELIM_CLOSE.has(node.text)) {
+        stack.pop();
+        return;
+      }
+    }
+    if (node.type === 'textord' && node.mode === 'math' && node.text === '|') {
+      const top = stack[stack.length - 1];
+      if (top && top.type === 'pipe') {
+        stack.pop();
+      } else {
+        pushOpen('pipe', '|', true);
+      }
+      return;
+    }
+    if (node.type === 'leftright') {
+      // Already sized. Still an enclosing scope for whatever nests inside it
+      // (a bare delimiter one level in still needs its own sizing), but only
+      // when a tracked glyph is actually on one of its two sides — an
+      // unrelated pair like `\left\langle…\right\rangle` is transparent to
+      // this rule, matching the "with each other" scope of the four glyphs
+      // it names.
+      if (NESTED_DELIM_CHARS.has(node.left) || NESTED_DELIM_CHARS.has(node.right)) {
+        pushOpen('sized', node.left, false);
+        visit(node.body);
+        stack.pop();
+      } else {
+        visit(node.body);
+      }
+      return;
+    }
+
+    for (const key of Object.keys(node)) {
+      if (key === 'loc') continue;
+      visit(node[key]);
+    }
+  };
+
+  visit(tree);
+  return violations;
+}
+
 /**
  * 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.
@@ -782,13 +1158,62 @@ export function resolveMathGlyphs(latex, definitions) {
 
   const glyphs = buildGlyphIndex(definitions);
   const explicitCalls = findExplainCalls(latex, glyphs.byKey);
-  const tree = parseMath(
-    sourceWithoutExplainPrefixes(latex, explicitCalls),
-    'lesson math',
+  // The source KaTeX actually parses — `\explain{key}{` prefixes blanked to
+  // spaces, same length as `latex`. Every `.loc` offset below comes from
+  // parsing *this* string, so it (not `latex`) is what trailing-whitespace
+  // trimming must check: a blanked prefix reads as spaces here but as real
+  // command text in `latex`.
+  const strippedSource = sourceWithoutExplainPrefixes(latex, explicitCalls);
+  const tree = parseMath(strippedSource, 'lesson math');
+
+  const parenViolations = findUnparenthesizedFunctionCalls(tree);
+  if (parenViolations.length > 0) {
+    const names = [...new Set(parenViolations)].map((name) => `\\${name}`).join(', ');
+    fail(
+      'unparenthesized-function',
+      `${names} used without a parenthesized argument in ${JSON.stringify(latex)}. ` +
+        `A nonlinear function always takes a parenthesized argument, even a single ` +
+        `symbol — write \\sin(x), not \\sin x (rule N13).`,
+      { violations: parenViolations },
+    );
+  }
+  const nestingViolations = findNestedBareDelimiters(tree);
+  if (nestingViolations.length > 0) {
+    const shown = [...new Set(nestingViolations.map(({ char }) => char))]
+      .map((char) => `\\left${char}`)
+      .join(', ');
+    fail(
+      'nested-bare-delimiter',
+      `${shown} nested with another (, [, {, or | in ${JSON.stringify(latex)}. ` +
+        `(, [, { and | can be used bare only when not nested — once one of ` +
+        `them is nested inside another, every level of the nest must use the ` +
+        `sizing form (\\left(/\\right), \\left[/\\right], \\left\\{/\\right\\}, ` +
+        `\\left|/\\right|) instead of the bare character (rule N15).`,
+      { violations: nestingViolations },
+    );
+  }
+  const { containers, identifiers, scriptSpans } = collectSourceStructure(
+    tree,
+    strippedSource,
   );
-  const { containers, identifiers, scriptSpans } = collectSourceStructure(tree);
 
-  const canonical = matchCanonicalForms(latex, containers, glyphs);
+  // A canonical container match can be found by seeing through transparent
+  // ordgroup/font wrapping into a structural sibling of an explicit
+  // `\explain{…}{…}` call — if it merely touches that call's span without
+  // being fully nested inside it, the match is spurious (the explicit call
+  // already accounts for that content) and injecting it would double-wrap or
+  // straddle the call's own braces (N-partial-wrap; see `notation.md`).
+  const canonical = matchCanonicalForms(
+    latex,
+    strippedSource,
+    containers,
+    glyphs,
+  ).filter(
+    (binding) =>
+      !explicitCalls.some(
+        (call) => overlaps(binding, call) && !contains(call, binding),
+      ),
+  );
   const covered = [...canonical, ...explicitCalls];
   const base = matchBaseGlyphs(
     latex,
@@ -798,12 +1223,27 @@ export function resolveMathGlyphs(latex, definitions) {
     scriptSpans,
   );
 
-  const bindings = [...canonical, ...base, ...explicitCalls].sort(
-    (left, right) =>
-      left.start - right.start ||
-      right.end - left.end ||
-      (left.level === 'explicit' ? -1 : 1),
-  );
+  const bindings = [...canonical, ...base, ...explicitCalls]
+    .sort(
+      (left, right) =>
+        left.start - right.start ||
+        right.end - left.end ||
+        (left.level === 'explicit' ? -1 : 1),
+    )
+    // An author-written `\explain{key}{…}` that also happens to match its own
+    // canonical or base glyph form resolves twice at the identical span: once
+    // as the explicit call, once as the auto-match. Both carry the same key,
+    // so the ambiguous-span check below (which only objects when the keys
+    // *differ*) lets both through, and `injectScopeBindings` would then wrap
+    // the span in `\explain{key}{…}` a second time, nested around itself.
+    // Keep only the first of a same-span-same-key run; the sort above already
+    // orders the explicit binding ahead of an auto-matched one at that span.
+    .filter(
+      (binding, index, sorted) =>
+        index === 0 ||
+        !sameSpan(sorted[index - 1], binding) ||
+        sorted[index - 1].key !== binding.key,
+    );
 
   for (const [i, left] of bindings.entries()) {
     for (const right of bindings.slice(i + 1)) {
@@ -842,6 +1282,14 @@ export function resolveMathGlyphs(latex, definitions) {
  * Used by the `operator-explained` consistency check (rule N8); the glyph
  * resolver still skips operator bodies whole.
  *
+ * The span handed in is raw lesson source, so it may still carry
+ * `\explain{key}{…}` / `\slot{key}{…}` markers around other symbols in the
+ * same expression — `\explain` is not valid KaTeX, so parsing it unstripped
+ * throws and this function used to swallow that as "no operators here" for
+ * the whole span, silently hiding any `\operatorname{…}` alongside the
+ * marker. `stripNotationMarkers` removes just the marker wrapper first so
+ * the scan sees plain, parseable math.
+ *
  * @param {string} latex
  * @returns {Array<{ name: string, source: 'named' | 'operatorname' }>}
  */
@@ -850,7 +1298,7 @@ export function collectOperators(latex) {
 
   let tree;
   try {
-    tree = parseMath(latex, 'operator scan');
+    tree = parseMath(stripNotationMarkers(latex), 'operator scan');
   } catch (error) {
     // A span that will not parse is the math gate's problem, not this check's.
     // A KaTeX version-pin failure is nobody's to swallow — let it through.
@@ -920,3 +1368,63 @@ export function collectOperators(latex) {
   visit(tree);
   return operators;
 }
+
+// --- 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:
+ * 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)).
+ *
+ * Same `stripNotationMarkers` preprocessing as {@link collectOperators}, and
+ * for the same reason: an unstripped `\explain{…}{…}` elsewhere in the span
+ * fails the raw KaTeX parse and used to silently drop every label in it.
+ *
+ * @param {string} latex
+ * @returns {Array<{ name: string }>}
+ */
+export function collectRomanLabels(latex) {
+  if (typeof latex !== 'string' || latex.trim() === '') return [];
+
+  let tree;
+  try {
+    tree = parseMath(stripNotationMarkers(latex), 'roman-label scan');
+  } catch (error) {
+    if (error instanceof GlyphResolutionError && error.code === 'invalid-latex') {
+      return [];
+    }
+    throw error;
+  }
+
+  const seen = new Set();
+  const labels = [];
+  const visit = (value) => {
+    if (Array.isArray(value)) {
+      for (const child of value) visit(child);
+      return;
+    }
+    if (!isNode(value)) return;
+
+    if (value.type === 'font' && value.font === ROMAN_LABEL_FONT) {
+      const name = fontBodyText(value.body);
+      if (typeof name === 'string' && name.length >= 2 && !seen.has(name)) {
+        seen.add(name);
+        labels.push({ name });
+      }
+    }
+
+    for (const key of Object.keys(value)) {
+      if (key === 'loc') continue;
+      visit(value[key]);
+    }
+  };
+
+  visit(tree);
+  return labels;
+}