explico 0.3.0 → 0.5.0

package/dist/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
@@ -768,6 +815,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.
@@ -786,6 +1070,33 @@ export function resolveMathGlyphs(latex, definitions) {
     sourceWithoutExplainPrefixes(latex, explicitCalls),
     '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);
 
   const canonical = matchCanonicalForms(latex, containers, glyphs);
@@ -920,3 +1231,59 @@ 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)).
+ *
+ * @param {string} latex
+ * @returns {Array<{ name: string }>}
+ */
+export function collectRomanLabels(latex) {
+  if (typeof latex !== 'string' || latex.trim() === '') return [];
+
+  let tree;
+  try {
+    tree = parseMath(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;
+}

package/dist/reference/mdx-attributes.d.mts

@@ -0,0 +1,13 @@
+/**
+ * Replace computed string attributes on an MDX JSX node without disturbing
+ * author-owned props. Remark adapters use this when the build, rather than the
+ * author, owns values such as a visible number or DOM anchor.
+ *
+ * @param {object} node
+ * @param {Record<string, string>} values
+ */
+export function injectMdxStringAttributes(node: object, values: Record<string, string>): void;
+/** Return every ordinary MDX JSX attribute with `name`. */
+export function mdxAttributesNamed(node: any, name: any): any;
+/** Remove an internal adapter-owned attribute from an MDX JSX node. */
+export function removeMdxAttribute(node: any, name: any): void;

package/dist/reference/mdx-attributes.mjs

@@ -0,0 +1,38 @@
+/**
+ * Replace computed string attributes on an MDX JSX node without disturbing
+ * author-owned props. Remark adapters use this when the build, rather than the
+ * author, owns values such as a visible number or DOM anchor.
+ *
+ * @param {object} node
+ * @param {Record<string, string>} values
+ */
+export function injectMdxStringAttributes(node, values) {
+  const names = new Set(Object.keys(values));
+  node.attributes = (node.attributes ?? []).filter(
+    (attribute) =>
+      !(
+        attribute?.type === 'mdxJsxAttribute' &&
+        typeof attribute.name === 'string' &&
+        names.has(attribute.name)
+      ),
+  );
+  for (const [name, value] of Object.entries(values)) {
+    node.attributes.push({ type: 'mdxJsxAttribute', name, value });
+  }
+}
+
+/** Return every ordinary MDX JSX attribute with `name`. */
+export function mdxAttributesNamed(node, name) {
+  return (node?.attributes ?? []).filter(
+    (attribute) =>
+      attribute?.type === 'mdxJsxAttribute' && attribute.name === name,
+  );
+}
+
+/** Remove an internal adapter-owned attribute from an MDX JSX node. */
+export function removeMdxAttribute(node, name) {
+  node.attributes = (node.attributes ?? []).filter(
+    (attribute) =>
+      !(attribute?.type === 'mdxJsxAttribute' && attribute.name === name),
+  );
+}

package/dist/reference/mixed-content.d.ts

@@ -0,0 +1,17 @@
+import { ScopeEntry } from './gate-math.js';
+import './types.js';
+
+type ContentSegment = {
+    readonly type: 'text';
+    readonly value: string;
+} | {
+    readonly type: 'math';
+    readonly latex: string;
+};
+/**
+ * Split `text` into ordered segments, resolving each math span's glyphs
+ * against `scope`. Never throws.
+ */
+declare function splitMixedContent(text: string, scope: readonly ScopeEntry[]): ContentSegment[];
+
+export { type ContentSegment, splitMixedContent };

package/dist/reference/mixed-content.js

@@ -0,0 +1,29 @@
+import { resolveMathGlyphs } from "./math-glyphs.mjs";
+const MATH_SPAN = /\$\$([\s\S]+?)\$\$|(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/g;
+function splitMixedContent(text, scope) {
+  const segments = [];
+  let cursor = 0;
+  const pattern = new RegExp(MATH_SPAN);
+  let match;
+  while (match = pattern.exec(text)) {
+    if (match.index > cursor) {
+      segments.push({ type: "text", value: text.slice(cursor, match.index) });
+    }
+    const raw = match[1] ?? match[2] ?? "";
+    let latex = raw;
+    try {
+      latex = resolveMathGlyphs(raw, [...scope]).latex;
+    } catch {
+      latex = raw;
+    }
+    segments.push({ type: "math", latex });
+    cursor = match.index + match[0].length;
+  }
+  if (cursor < text.length) {
+    segments.push({ type: "text", value: text.slice(cursor) });
+  }
+  return segments;
+}
+export {
+  splitMixedContent
+};

package/dist/reference/page-notation.d.ts

@@ -0,0 +1,52 @@
+import { Manifest, ManifestLessonNotation } from '../compiler/manifest.js';
+import '../curriculum/validation.js';
+import './consistency.js';
+import '../compiler/course-config.js';
+import '../compiler/collections.js';
+import './types.js';
+import './lint-ignore.js';
+import './equations-validate.js';
+import './tables-validate.js';
+import './keyed-float-validate.js';
+import './figures-validate.js';
+import './diagrams-validate.js';
+import './knowledge-checks-validate.js';
+import './raw-floats-validate.js';
+import './gate-math.js';
+import './mixed-content.js';
+import './gloss.js';
+import '../compiler/knowledge-version.js';
+import '../compiler/lesson-derivation.js';
+
+interface PageNotationDependency {
+    readonly key: string;
+    readonly context: string;
+}
+/**
+ * Record notation keys emitted by a nested server component for this request.
+ * The request-local collector is deliberately keyed by `Astro.locals`: static
+ * builds render pages concurrently, so a process-global set would leak symbols
+ * between lessons and defeat page-local notation scope.
+ */
+declare function registerPageNotationDependencies(locals: object, keys: Iterable<string>, context: string): void;
+declare function pageNotationDependencies(locals: object): PageNotationDependency[];
+/** Starlight's route id as exposed to nested Astro components. */
+declare function routeIdFromLocals(locals: object): string | undefined;
+/** Collect the notation keys that survived into a sanitized KaTeX tree. */
+declare function notationKeysInMathNodes(nodes: readonly {
+    readonly type: string;
+    readonly properties?: Readonly<Record<string, string>>;
+    readonly children?: readonly unknown[];
+}[]): string[];
+/**
+ * Extend one compiled lesson bundle with only the definitions requested by
+ * components rendered on that page (plus those definitions' normal closure).
+ */
+declare function notationDefinitionsForRenderedPage(manifest: Manifest, lessonId: string, dependencies: readonly PageNotationDependency[]): ManifestLessonNotation[];
+/**
+ * Structural backstop over final HTML: every trigger must have a source entry
+ * from which the popup enhancer can populate a card.
+ */
+declare function missingNotationPayloadKeys(html: string): string[];
+
+export { type PageNotationDependency, missingNotationPayloadKeys, notationDefinitionsForRenderedPage, notationKeysInMathNodes, pageNotationDependencies, registerPageNotationDependencies, routeIdFromLocals };