explico 0.5.0 → 0.6.0

package/src/reference/math-glyphs.mjs

@@ -369,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();
@@ -394,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)),
@@ -428,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
@@ -435,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 = [];
@@ -445,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;
@@ -470,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({
@@ -483,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);
       }
     }
@@ -532,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 };
 }
@@ -553,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,
   };
 }
 
@@ -579,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
@@ -633,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(
@@ -661,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 = [];
 
@@ -677,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,
@@ -1066,10 +1158,13 @@ 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) {
@@ -1097,9 +1192,28 @@ export function resolveMathGlyphs(latex, definitions) {
       { violations: nestingViolations },
     );
   }
-  const { containers, identifiers, scriptSpans } = collectSourceStructure(tree);
+  const { containers, identifiers, scriptSpans } = collectSourceStructure(
+    tree,
+    strippedSource,
+  );
 
-  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,
@@ -1109,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)) {
@@ -1153,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' }>}
  */
@@ -1161,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.
@@ -1245,6 +1382,10 @@ export function collectOperators(latex) {
  * `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 }>}
  */
@@ -1253,7 +1394,7 @@ export function collectRomanLabels(latex) {
 
   let tree;
   try {
-    tree = parseMath(latex, 'roman-label scan');
+    tree = parseMath(stripNotationMarkers(latex), 'roman-label scan');
   } catch (error) {
     if (error instanceof GlyphResolutionError && error.code === 'invalid-latex') {
       return [];

package/src/styles/global.css

@@ -1813,7 +1813,7 @@ body {
   .assessment-actions,
   .assessment-chevron,
   .assessment-feedback.is-idle,
-  .notation-pin,
+  .notation-list-anchor,
   .notation-enhancement-help,
   .lab-controls {
     display: none !important;