explico 0.5.0 → 0.7.0

package/dist/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/dist/reference/references.js

@@ -28,7 +28,8 @@ function compareDiagnostics(left, right) {
   return severityRank(left.severity) - severityRank(right.severity) || left.code.localeCompare(right.code) || (left.lessonId ?? "").localeCompare(right.lessonId ?? "") || (left.key ?? "").localeCompare(right.key ?? "") || (left.definitionId ?? "").localeCompare(right.definitionId ?? "") || compareSourceSpans(left.source, right.source) || left.message.localeCompare(right.message);
 }
 function severityRank(severity) {
-  return severity === "error" ? 0 : 1;
+  if (severity === "error") return 0;
+  return severity === "warning" ? 1 : 2;
 }
 export {
   NOTATION_KEY_PATTERN,

package/dist/reference/registry.js

@@ -144,7 +144,7 @@ function buildNotationRegistry(rawInput) {
     if (!reachableDefinitions.has(candidate.id)) {
       diagnostics.push({
         code: "unused-definition",
-        severity: "warning",
+        severity: "info",
         message: `${candidate.id} is not reachable from any lesson reference`,
         key: candidate.input.key,
         lessonId: candidate.kind === "local" ? candidate.lesson.lessonId : void 0,

package/dist/reference/rehype-base-links.d.mts

@@ -0,0 +1,23 @@
+/**
+ * Prefixes root-relative `<a href="/...">` links in rendered lesson content
+ * with the course's Astro `base` path.
+ *
+ * A course deployed under a subpath (any GitHub Pages *project* site, e.g.
+ * `base: '/my-course'`) gets that prefix applied automatically to Starlight's
+ * own generated navigation — sidebar, pagination, breadcrumbs — because those
+ * are rendered by Starlight's own `.astro` components, which call its
+ * internal `pathWithBase()` helper. They are **not** applied to anything
+ * produced by the Markdown/MDX → rehype pipeline: a lesson's own prose links
+ * (`[text](/other-lesson/)`), `remark-notation.mjs`'s equation cross-
+ * references, and `remark-citation.mjs`'s citation links are all root-
+ * relative absolute paths written or generated without the base in mind, so
+ * without this plugin every one of them 404s on a subpath deployment. A
+ * lesson's Starlight frontmatter (e.g. `hero.actions[].link`) is untouched
+ * either way — that YAML never enters this pipeline — so write those as
+ * paths relative to the current page instead.
+ *
+ * A no-op when the course has no base (`base` omitted or `'/'`, e.g. local
+ * dev or a GitHub *user/org* Pages site), so a course can wire this in
+ * unconditionally and it only does anything on the deployments that need it.
+ */
+export default function rehypeBaseLinks(base: any): (tree: any) => void;

package/dist/reference/rehype-base-links.mjs

@@ -0,0 +1,40 @@
+/**
+ * Prefixes root-relative `<a href="/...">` links in rendered lesson content
+ * with the course's Astro `base` path.
+ *
+ * A course deployed under a subpath (any GitHub Pages *project* site, e.g.
+ * `base: '/my-course'`) gets that prefix applied automatically to Starlight's
+ * own generated navigation — sidebar, pagination, breadcrumbs — because those
+ * are rendered by Starlight's own `.astro` components, which call its
+ * internal `pathWithBase()` helper. They are **not** applied to anything
+ * produced by the Markdown/MDX → rehype pipeline: a lesson's own prose links
+ * (`[text](/other-lesson/)`), `remark-notation.mjs`'s equation cross-
+ * references, and `remark-citation.mjs`'s citation links are all root-
+ * relative absolute paths written or generated without the base in mind, so
+ * without this plugin every one of them 404s on a subpath deployment. A
+ * lesson's Starlight frontmatter (e.g. `hero.actions[].link`) is untouched
+ * either way — that YAML never enters this pipeline — so write those as
+ * paths relative to the current page instead.
+ *
+ * A no-op when the course has no base (`base` omitted or `'/'`, e.g. local
+ * dev or a GitHub *user/org* Pages site), so a course can wire this in
+ * unconditionally and it only does anything on the deployments that need it.
+ */
+export default function rehypeBaseLinks(base) {
+  const prefix = base && base !== '/' ? base.replace(/\/+$/, '') : '';
+
+  return function transform(tree) {
+    if (!prefix) return;
+    visit(tree);
+  };
+
+  function visit(node) {
+    if (node.type === 'element' && node.tagName === 'a') {
+      const href = node.properties?.href;
+      if (typeof href === 'string' && href.startsWith('/') && !href.startsWith('//')) {
+        node.properties.href = prefix + href;
+      }
+    }
+    if (Array.isArray(node.children)) node.children.forEach(visit);
+  }
+}

package/dist/reference/remark-abbreviations.mjs

@@ -5,12 +5,15 @@
  * requires every abbreviation-shaped word in prose to either be universal or
  * carry a `content/abbreviations/*.md` entry, so the literal written form
  * (`abbr`, or one of its `aliases`) is itself the trigger. This plugin scans
- * ordinary prose for that literal text and wraps the **first** occurrence per
- * document in a real link (`/glossary/#abbr-<key>`, so it still navigates
- * with no JS) carrying the `data-abbr-key` an island script reads to render a
- * hover/click card, exactly the way `remarkCitation` wraps `[@id]` markers.
- * Later occurrences of the same term on the same page stay plain text, so a
- * common short word isn't turned into a link everywhere it appears.
+ * ordinary prose for that literal text and wraps **every** occurrence in a
+ * real link (`/glossary/#abbr-<key>`, so it still navigates with no JS)
+ * carrying the `data-abbr-key` an island script reads to render a hover/click
+ * card, exactly the way `remarkCitation` wraps `[@id]` markers. A reader who
+ * deep-links into a mid-page heading — the sidebar TOC, a heading anchor, an
+ * external link — sees the same hoverable cue no matter which occurrence they
+ * land on first, rather than only the earliest one in document order.
+ * `AbbreviationLayer.astro` already resolves every marker independently by
+ * `data-abbr-key`, so wrapping every occurrence needs no island-side change.
  *
  * Matches only ever come from the known table by construction, so unlike
  * citation's `[@id]` there is no "unknown id" failure path here.
@@ -118,10 +121,6 @@ export default function remarkAbbreviations(options = {}) {
     const { regex, keyByMatch } = buildMatcher(suppliedAbbreviations);
     if (!regex) return;
 
-    // Fresh per file, same lifetime as citation's own `pairs` Map: only the
-    // first occurrence of a given key on this page gets wrapped.
-    const usedKeys = new Set();
-
     const replaceText = (value) => {
       regex.lastIndex = 0;
       const output = [];
@@ -131,13 +130,12 @@ export default function remarkAbbreviations(options = {}) {
 
       while ((match = regex.exec(value))) {
         const key = keyByMatch.get(match[0]);
-        if (!key || usedKeys.has(key)) continue;
+        if (!key) continue;
 
         if (match.index > cursor) {
           output.push({ type: 'text', value: value.slice(cursor, match.index) });
         }
         output.push(termNode(key, match[0], base));
-        usedKeys.add(key);
         changed = true;
         cursor = match.index + match[0].length;
       }

package/dist/reference/remark-citation.d.mts

@@ -1,6 +1,10 @@
 /**
- * @param {{ sources?: Map<string, object> | readonly object[] | (() => Map<string, object> | readonly object[]) }} [options]
+ * @param {{
+ *   sources?: Map<string, object> | readonly object[] | (() => Map<string, object> | readonly object[]),
+ *   defaultOpen?: boolean,
+ * }} [options]
  */
 export default function remarkCitation(options?: {
     sources?: Map<string, object> | readonly object[] | (() => Map<string, object> | readonly object[]);
+    defaultOpen?: boolean;
 }): (tree: any, file: any) => void;

package/dist/reference/render-lab-math.d.ts

@@ -9,7 +9,24 @@ interface RenderedLabMath {
     readonly slots: readonly string[];
     /** Notation keys the template resolved to, for diagnostics. */
     readonly keys: readonly string[];
+    /**
+     * Plain, copyable LaTeX — every explained glyph resolved to its bare
+     * symbol, every `\slot{name}{…}` replaced by `slotPlaceholder(name)` — so
+     * the island can substitute each slot's *current* live value in and keep
+     * `[data-notation-formula]`'s `data-latex` accurate as the reader drags a
+     * control, the same "click the equation to copy it" gesture a static
+     * lesson or glossary equation gets (`NotationLayer.astro`).
+     */
+    readonly plainLatexTemplate: string;
 }
+/**
+ * A slot's placeholder inside `plainLatexTemplate` — distinct from the
+ * numeric sentinel `sentinelFor` below uses internally (that one only has to
+ * survive a single notation-binding pass at build time; this one is the
+ * stable, name-keyed token an island substitutes with a live value at
+ * runtime, so it's exported for that purpose).
+ */
+declare function slotPlaceholder(name: string): string;
 /**
  * Compile a developer-authored lab math template the same way lesson `$$`
  * math is compiled: every identifier must resolve to a notation key in the
@@ -18,4 +35,4 @@ interface RenderedLabMath {
  */
 declare function renderLabMath(template: string, scope: readonly LabMathScopeDefinition[]): RenderedLabMath;
 
-export { type LabMathScopeDefinition, type RenderedLabMath, renderLabMath };
+export { type LabMathScopeDefinition, type RenderedLabMath, renderLabMath, slotPlaceholder };

package/dist/reference/render-lab-math.js

@@ -1,6 +1,9 @@
 import katex from "katex";
-import { resolveMathGlyphs } from "./math-glyphs.mjs";
+import { resolveMathGlyphs, stripNotationMarkers } from "./math-glyphs.mjs";
 import { createNotationKatexOptions } from "./katex-options.mjs";
+function slotPlaceholder(name) {
+  return `\u27E6${name}\u27E7`;
+}
 const SLOT_PATTERN = /\\slot\{([a-z][a-z0-9]*)\}\{((?:[^{}]|\{[^{}]*\})*)\}/g;
 const sentinelFor = (index) => `909909${index}.909909`;
 function renderLabMath(template, scope) {
@@ -30,6 +33,7 @@ function renderLabMath(template, scope) {
     );
   }
   let bound = result.latex;
+  let copyBound = result.latex;
   slots.forEach(({ name, fallback }, index) => {
     const sentinel = sentinelFor(index);
     if (!bound.includes(sentinel)) {
@@ -42,6 +46,7 @@ function renderLabMath(template, scope) {
       sentinel,
       `\\htmlData{lab-slot=${name}}{${fallback}}`
     );
+    copyBound = copyBound.replace(sentinel, slotPlaceholder(name));
   });
   const html = katex.renderToString(
     bound,
@@ -50,9 +55,11 @@ function renderLabMath(template, scope) {
   return {
     html,
     slots: slots.map(({ name }) => name),
-    keys: [...new Set(result.bindings.map(({ key }) => key))]
+    keys: [...new Set(result.bindings.map(({ key }) => key))],
+    plainLatexTemplate: stripNotationMarkers(copyBound)
   };
 }
 export {
-  renderLabMath
+  renderLabMath,
+  slotPlaceholder
 };

package/dist/reference/tables-validate.d.ts

@@ -5,7 +5,7 @@ import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } fr
 type TableDiagnosticCode = 'tab-invalid-key' | 'tab-duplicate-key' | 'tab-ref-resolves' | 'tab-key-unused';
 interface TableDiagnostic {
     readonly code: TableDiagnosticCode;
-    readonly severity: 'error' | 'warning';
+    readonly severity: 'error' | 'warning' | 'info';
     readonly message: string;
     readonly file?: string;
     readonly lessonId?: string;

package/dist/reference/types.d.ts

@@ -100,7 +100,7 @@ interface AbbreviationDefinitionInput {
     readonly source: SourceSpan;
 }
 type NotationDiagnosticCode = 'invalid-key' | 'duplicate-page' | 'duplicate-definition' | 'conflicting-definition' | 'undefined-reference' | 'reference-cycle' | 'unused-definition' | 'alignment-unknown-competency' | 'alignment-unknown-lesson' | 'alignment-introduction' | 'alignment-unavailable' | 'alignment-review-state' | 'gloss-collides-with-card';
-type DiagnosticSeverity = 'error' | 'warning';
+type DiagnosticSeverity = 'error' | 'warning' | 'info';
 interface NotationDiagnostic {
     readonly code: NotationDiagnosticCode;
     readonly severity: DiagnosticSeverity;