explico 0.11.1 → 0.13.0

package/dist/reference/katex-measure.js

@@ -0,0 +1,223 @@
+import katex, {} from "katex";
+import fontMetricsData from "katex/src/fontMetricsData.js";
+import { createNotationKatexOptions } from "./katex-options.mjs";
+const SIZE_MULTIPLIERS = [0.5, 0.6, 0.7, 0.8, 0.9, 1, 1.2, 1.44, 1.728, 2.074, 2.488];
+const CLASS_PADDING = {
+  "x-arrow-pad": [0.5, 0.5],
+  "cd-arrow-pad": [0.27778, 0.55556],
+  boxpad: [0.3, 0.3],
+  "cancel-pad": [0.2, 0.2],
+  anglpad: [0.03889, 0.03889]
+};
+const CLASS_MARGIN = {
+  "cancel-lap": [-0.2, -0.2],
+  angl: [0, 0.03889]
+};
+const CLASS_BORDER = {
+  fbox: [0.04, 0.04],
+  fcolorbox: [0.04, 0.04],
+  angl: [0, 0.049]
+};
+const ZERO_WIDTH = /* @__PURE__ */ new Set(["llap", "rlap", "clap", "pstrut", "vlist-s"]);
+function has(node, name) {
+  return node.classes?.includes(name) ?? false;
+}
+function em(value) {
+  if (!value) return 0;
+  const match = /^(-?\d*\.?\d+)em$/.exec(value.trim());
+  return match ? Number(match[1]) : 0;
+}
+function sizing(node) {
+  if (!has(node, "sizing") && !has(node, "fontsize-ensurer")) return 1;
+  let from = 0;
+  let to = 0;
+  for (const name of node.classes ?? []) {
+    const reset = /^reset-size(\d+)$/.exec(name);
+    if (reset) from = Number(reset[1]);
+    const size = /^size(\d+)$/.exec(name);
+    if (size) to = Number(size[1]);
+  }
+  const fromMultiplier = SIZE_MULTIPLIERS[from - 1];
+  const toMultiplier = SIZE_MULTIPLIERS[to - 1];
+  return fromMultiplier && toMultiplier ? toMultiplier / fromMultiplier : 1;
+}
+function pairOf(table, node) {
+  let total = 0;
+  for (const name of node.classes ?? []) {
+    const pair = table[name];
+    if (pair) total += pair[0] + pair[1];
+  }
+  return total;
+}
+const ROOT_FONT = { family: "Main", bold: false, italic: false };
+const FONT_CLASSES = {
+  textbf: { bold: true },
+  textit: { italic: true },
+  textrm: { family: "Main" },
+  texttt: { family: "Typewriter" },
+  mathnormal: { family: "Math", italic: true },
+  mathit: { family: "Main", italic: true },
+  mathrm: { italic: false },
+  mathbf: { family: "Main", bold: true },
+  boldsymbol: { family: "Math", bold: true, italic: true },
+  amsrm: { family: "AMS" },
+  mathbb: { family: "AMS" },
+  textbb: { family: "AMS" },
+  mathcal: { family: "Caligraphic" },
+  mathfrak: { family: "Fraktur" },
+  textfrak: { family: "Fraktur" },
+  mathboldfrak: { family: "Fraktur", bold: true },
+  textboldfrak: { family: "Fraktur", bold: true },
+  mathtt: { family: "Typewriter" },
+  mathscr: { family: "Script" },
+  textscr: { family: "Script" },
+  mathsf: { family: "SansSerif" },
+  textsf: { family: "SansSerif" },
+  mathboldsf: { family: "SansSerif", bold: true },
+  textboldsf: { family: "SansSerif", bold: true },
+  mathsfit: { family: "SansSerif", italic: true },
+  mathitsf: { family: "SansSerif", italic: true },
+  textitsf: { family: "SansSerif", italic: true },
+  mainrm: { family: "Main", italic: false }
+};
+function fontOf(node, inherited) {
+  let font = inherited;
+  for (const name of node.classes ?? []) {
+    const rule = FONT_CLASSES[name];
+    if (rule) font = { ...font, ...rule };
+  }
+  if (has(node, "delimsizing")) {
+    for (const size of [1, 2, 3, 4]) {
+      if (has(node, `size${size}`)) font = { ...font, family: `Size${size}` };
+    }
+  }
+  if (has(node, "op-symbol")) {
+    if (has(node, "small-op")) font = { ...font, family: "Size1" };
+    if (has(node, "large-op")) font = { ...font, family: "Size2" };
+  }
+  return font;
+}
+const METRICS = fontMetricsData;
+function metricsFor(font) {
+  const variants = [
+    font.bold && font.italic ? "BoldItalic" : font.bold ? "Bold" : font.italic ? "Italic" : "Regular",
+    font.bold ? "Bold" : void 0,
+    font.italic ? "Italic" : void 0,
+    "Regular"
+  ];
+  for (const variant of variants) {
+    const table = variant && METRICS[`${font.family}-${variant}`];
+    if (table) return table;
+  }
+  return METRICS["Main-Regular"] ?? {};
+}
+const WIDE_GLYPHS = /* @__PURE__ */ new Map([
+  [8748, 0.85],
+  // ∬ \iint
+  [8749, 1.22],
+  // ∭ \iiint
+  [8751, 0.85],
+  // ∯ \oiint
+  [8752, 1.22],
+  // ∰ \oiiint
+  [10764, 1.6]
+  // ⨌ \iiiint
+]);
+function glyphWidth(table, char) {
+  if (char === "\u200B") return 0;
+  const metrics = table[String(char.codePointAt(0))] ?? table["77"];
+  return metrics?.[4] ?? 1;
+}
+function glyphAdvances(node, font) {
+  const [first, ...rest] = [...node.text ?? ""];
+  if (first === void 0) return [];
+  const table = metricsFor(font);
+  const wide = (char) => WIDE_GLYPHS.get(char.codePointAt(0) ?? 0);
+  const firstWidth = wide(first) ?? (node.width && node.width > 0 ? node.width : glyphWidth(table, first));
+  return [firstWidth, ...rest.map((char) => wide(char) ?? glyphWidth(table, char))];
+}
+function glyphPx(advanceEm, fontPx) {
+  return Math.max(Math.round(advanceEm * Math.round(fontPx)), advanceEm * fontPx);
+}
+function advance(node, inherited, context, parent) {
+  const frame = {
+    scale: inherited.scale * sizing(node),
+    font: fontOf(node, inherited.font)
+  };
+  const scale = frame.scale * context.fontPx;
+  const style = node.style ?? {};
+  if (typeof node.text === "string") {
+    const marginRight = style.marginRight !== void 0 ? em(style.marginRight) : Math.max(0, node.italic ?? 0);
+    const glyphs = glyphAdvances(node, frame.font).reduce(
+      (sum, width) => sum + glyphPx(width, scale),
+      0
+    );
+    return glyphs + (marginRight + em(style.marginLeft)) * scale;
+  }
+  if (!node.classes) return 0;
+  const margins = (em(style.marginLeft) + em(style.marginRight) + pairOf(CLASS_MARGIN, node) + rootMargin(node, parent)) * scale;
+  if (node.classes.some((name) => ZERO_WIDTH.has(name))) return margins;
+  if (has(node, "accent-body") && !has(node, "accent-full")) return margins;
+  let content;
+  if (has(node, "nulldelimiter")) {
+    content = 0.12 * scale;
+  } else if (em(style.width) > 0) {
+    content = em(style.width) * scale;
+  } else if (has(node, "vlist-t")) {
+    content = tableWidth(node, frame, context);
+  } else if (has(node, "vlist")) {
+    content = Math.max(
+      0,
+      ...(node.children ?? []).map((row) => advance(row, frame, context, node))
+    );
+  } else {
+    content = (node.children ?? []).reduce(
+      (sum, child) => sum + advance(child, frame, context, node),
+      0
+    );
+  }
+  content = Math.max(content, em(style.minWidth) * scale);
+  if (has(node, "vertical-separator")) content = Math.max(content, 1);
+  const padding = (em(style.paddingLeft) + pairOf(CLASS_PADDING, node)) * scale;
+  const border = (em(style.borderRightWidth) + pairOf(CLASS_BORDER, node)) * scale;
+  return content + padding + border + margins;
+}
+function rootMargin(node, parent) {
+  return has(node, "root") && parent !== void 0 && has(parent, "sqrt") ? 0.2777777778 - 0.5555555556 : 0;
+}
+function tableWidth(node, frame, context) {
+  const columns = [];
+  for (const row of node.children ?? []) {
+    let column = 0;
+    for (const cell of row.children ?? []) {
+      if (has(cell, "vlist-s")) continue;
+      columns[column] = Math.max(columns[column] ?? 0, advance(cell, frame, context, row));
+      column += 1;
+    }
+  }
+  return columns.reduce((sum, width) => sum + width, 0);
+}
+function collectBases(node, out) {
+  if (has(node, "base")) {
+    out.push(node);
+    return out;
+  }
+  for (const child of node.children ?? []) collectBases(child, out);
+  return out;
+}
+function measureFormula(latex, fontPx) {
+  const { __renderToHTMLTree } = katex;
+  const tree = __renderToHTMLTree(latex, {
+    ...createNotationKatexOptions(),
+    displayMode: false
+  });
+  const bases = collectBases(tree, []);
+  return {
+    width: advance(tree, { scale: 1, font: ROOT_FONT }, { fontPx }),
+    height: Math.max(0, ...bases.map((base) => base.height ?? 0)) * fontPx,
+    depth: Math.max(0, ...bases.map((base) => base.depth ?? 0)) * fontPx
+  };
+}
+export {
+  measureFormula
+};

package/dist/reference/keyed-float-validate.js

@@ -46,6 +46,18 @@ function validateKeyedFloats(lessons, kind) {
           ...raw.key ? { key: raw.key } : {}
         });
       }
+      for (const prop of ["short", "caption"]) {
+        if (!raw.props.includes(prop) || raw[prop] != null) continue;
+        const places = prefix === "ex" ? `its [[${prefix}-\u2026]] card and a copied link` : `its [[${prefix}-\u2026]] card, a copied link, a folded section's line and the "Figures and tables" page`;
+        diagnostics.push({
+          code: `${prefix}-unread-prop`,
+          severity: "warning",
+          message: `${lesson.lessonId} has a <${tagName} ${prop}={\u2026}>${raw.key ? ` (id="${raw.key}")` : ""}, but the manifest reads only a quoted \`${prop}\`, so ${places} name this ${noun} without it. Write ${prop}="\u2026", with typographic quotes (\u2018\u2019 \u201C\u201D) inside.`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          ...raw.key ? { key: raw.key } : {}
+        });
+      }
       if (raw.key == null) continue;
       if (!KEYED_FLOAT_KEY_PATTERN.test(raw.key)) {
         diagnostics.push({

package/dist/reference/keyed-jsx-floats.d.mts

@@ -50,8 +50,8 @@ export function countKeyedJsxFloats(markdown: any, { tagName }: {
     tagName: any;
 }): number;
 /**
- * The mdast equivalent of `scanKeyedJsxFloats`: walk the tree's top-level
- * children (and through the `TRANSPARENT_COMPONENTS`' bodies) in document order, advancing the
+ * The mdast equivalent of `scanKeyedJsxFloats`: walk the lesson's flow (and
+ * through the `TRANSPARENT_COMPONENTS`' bodies) in document order, advancing the
  * section counter on every top-level depth-2 heading and emitting a record for
  * every `mdxJsxFlowElement` named `tagName` — keyed or not, exactly like
  * `collectDisplayEquations`. `numbering` is threaded the same way as in

package/dist/reference/keyed-jsx-floats.mjs

@@ -25,6 +25,7 @@
 
 import {
   resolveNumbering,
+  stripContainerDirectives,
   stripFencedCode,
   stripJsxComponents,
   TRANSPARENT_COMPONENTS,
@@ -131,10 +132,9 @@ function mdxStringAttribute(node, name) {
  */
 export function scanKeyedJsxFloats(markdown, { tagName, numbering }) {
   const { prefix, offset } = resolveNumbering(numbering);
-  const text = stripJsxComponents(
-    stripFencedCode(markdown),
-    tagName,
-    TRANSPARENT_COMPONENTS,
+  // A `:::note` aside is a callout, like `<Aside>`: nothing in it numbers.
+  const text = stripContainerDirectives(
+    stripJsxComponents(stripFencedCode(markdown), tagName, TRANSPARENT_COMPONENTS),
   );
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
@@ -196,8 +196,8 @@ export function countKeyedJsxFloats(markdown, { tagName }) {
 }
 
 /**
- * The mdast equivalent of `scanKeyedJsxFloats`: walk the tree's top-level
- * children (and through the `TRANSPARENT_COMPONENTS`' bodies) in document order, advancing the
+ * The mdast equivalent of `scanKeyedJsxFloats`: walk the lesson's flow (and
+ * through the `TRANSPARENT_COMPONENTS`' bodies) in document order, advancing the
  * section counter on every top-level depth-2 heading and emitting a record for
  * every `mdxJsxFlowElement` named `tagName` — keyed or not, exactly like
  * `collectDisplayEquations`. `numbering` is threaded the same way as in
@@ -210,8 +210,12 @@ export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
   let indexInSection = 0;
   let indexInLesson = 0;
 
+  // The lesson's flow — top-level blocks, list items, blockquotes — and the
+  // `TRANSPARENT_COMPONENTS`' bodies; never another component's body or a
+  // `:::note` aside. `scanKeyedJsxFloats` reads the same set from the text.
   const collectFromDetail = (node) => {
     if (!node || typeof node !== 'object') return;
+    if (node.type === 'containerDirective') return;
     if (node.type === 'mdxJsxFlowElement' && node.name === tagName) {
       indexInSection += 1;
       indexInLesson += 1;
@@ -256,14 +260,7 @@ export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
       indexInSection = 0;
       continue;
     }
-    if (node.type === 'mdxJsxFlowElement' && node.name === tagName) {
-      collectFromDetail(node);
-    } else if (
-      node.type === 'mdxJsxFlowElement' &&
-      TRANSPARENT_COMPONENTS.includes(node.name)
-    ) {
-      collectFromDetail(node);
-    }
+    collectFromDetail(node);
   }
   return floats;
 }

package/dist/reference/lab-katex-validate.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Rule V3's seam, checked in the source: a component a lesson renders draws
+ * its math through `renderLabMath`, which binds every symbol to the page's
+ * notation, never by calling KaTeX itself — a legend helper around
+ * `katex.renderToString` binds none, so its symbols open no card.
+ *
+ * Starting at each lesson's own imports, this follows every relative import
+ * — the course's visuals, wherever they live — and reports each file that
+ * imports `katex` as `lab-katex-direct`, with the chain of imports that
+ * reaches it. A package import (`explico/…`, `react`) is not followed:
+ * explico's own KaTeX use is the seam. A type-only import and the KaTeX
+ * stylesheet draw nothing and are not reported.
+ *
+ * `figure-symbols.ts` checks the same promise on the rendered page, which
+ * also catches math a lab draws some other way.
+ */
+interface LabKatexDiagnostic {
+    readonly code: 'lab-katex-direct';
+    readonly severity: 'error';
+    readonly message: string;
+    /** The file that imports `katex`, repository-relative. */
+    readonly file: string;
+    /** The first lesson (by id) whose imports reach it. */
+    readonly lessonId: string;
+}
+interface LabKatexLessonInput {
+    readonly lessonId: string;
+    /** Repository-relative path of the lesson file. */
+    readonly file: string;
+    readonly body: string;
+}
+/**
+ * Every module a source file imports at run time, in order: static, re-exported,
+ * dynamic and `require`d. A type-only import is left out.
+ */
+declare function importSpecifiers(source: string): string[];
+/**
+ * Each course file that a lesson's imports reach and that imports `katex`.
+ * `root` is the repository root the lesson paths are relative to.
+ */
+declare function validateLabKatexImports(lessons: readonly LabKatexLessonInput[], root?: string): LabKatexDiagnostic[];
+
+export { type LabKatexDiagnostic, type LabKatexLessonInput, importSpecifiers, validateLabKatexImports };

package/dist/reference/lab-katex-validate.js

@@ -0,0 +1,96 @@
+import { readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { stripFencedCode } from "./equations.mjs";
+const EXTENSIONS = [".astro", ".tsx", ".ts", ".jsx", ".js", ".mjs", ".mts", ".cjs"];
+const SOURCE_FILE = /\.(?:astro|tsx|ts|jsx|js|mjs|mts|cjs|mdx)$/u;
+const IMPORT_PATTERNS = [
+  // import x from 'y' · import { x } from 'y' · import 'y' · import type … from 'y'
+  /\bimport\s+(type\s+)?(?:[\w*{}\s,$]+?\s+from\s+)?(['"])([^'"\n]+)\2/gu,
+  // export { x } from 'y' · export * from 'y' · export type { x } from 'y'
+  /\bexport\s+(type\s+)?(?:\*(?:\s+as\s+[\w$]+)?|\{[^}]*\})\s+from\s+(['"])([^'"\n]+)\2/gu,
+  // import('y') · require('y')
+  /\b(?:import|require)\s*\(\s*()(['"])([^'"\n]+)\2\s*\)/gu
+];
+function importSpecifiers(source) {
+  const found = [];
+  for (const pattern of IMPORT_PATTERNS) {
+    for (const match of source.matchAll(pattern)) {
+      if (match[1]) continue;
+      found.push({ index: match.index ?? 0, specifier: match[3] });
+    }
+  }
+  return found.sort((a, b) => a.index - b.index).map(({ specifier }) => specifier);
+}
+function isKatexModule(specifier) {
+  if (specifier !== "katex" && !specifier.startsWith("katex/")) return false;
+  return !/\.(?:css|woff2?|ttf)$/u.test(specifier);
+}
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+function resolveRelative(fromFile, specifier) {
+  const base = join(dirname(fromFile), specifier);
+  const candidates = [
+    base,
+    // `./chart.js` written for `./chart.ts`, the TypeScript ESM convention.
+    .../\.[cm]?js$/u.test(base) ? [".ts", ".tsx", ".mts", ".cts"].map((ext) => base.replace(/\.[cm]?js$/u, ext)) : [],
+    ...EXTENSIONS.map((ext) => `${base}${ext}`),
+    ...EXTENSIONS.map((ext) => join(base, `index${ext}`))
+  ];
+  return candidates.find(isFile);
+}
+function validateLabKatexImports(lessons, root = process.cwd()) {
+  const read = (path) => {
+    try {
+      return readFileSync(path, "utf8");
+    } catch {
+      return void 0;
+    }
+  };
+  const repoPath = (path) => relative(root, path).split(sep).join("/");
+  const diagnostics = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Set();
+  for (const lesson of [...lessons].sort((a, b) => a.lessonId.localeCompare(b.lessonId))) {
+    const lessonPath = join(root, lesson.file);
+    const queue = [
+      { path: lessonPath, source: stripFencedCode(lesson.body), chain: [lesson.file] }
+    ];
+    while (queue.length > 0) {
+      const { path, source, chain } = queue.shift();
+      for (const specifier of importSpecifiers(source)) {
+        if (isKatexModule(specifier)) {
+          const file = repoPath(path);
+          if (!diagnostics.has(file)) {
+            diagnostics.set(file, {
+              code: "lab-katex-direct",
+              severity: "error",
+              file,
+              lessonId: lesson.lessonId,
+              message: `${file} imports '${specifier}' and draws math whose symbols open no notation card (reached by ${chain.join(" \u2192 ")}). Render a lab's math with renderLabMath(template, scope) \u2014 { display: false } for a legend entry, an axis title or a label \u2014 so every symbol is bound to the page's notation (rule V3).`
+            });
+          }
+          continue;
+        }
+        if (!specifier.startsWith(".")) continue;
+        const target = resolveRelative(path, specifier);
+        if (!target || !SOURCE_FILE.test(target) || target.includes(`${sep}node_modules${sep}`)) {
+          continue;
+        }
+        if (seen.has(target)) continue;
+        seen.add(target);
+        const text = read(target);
+        if (text === void 0) continue;
+        queue.push({ path: target, source: text, chain: [...chain, repoPath(target)] });
+      }
+    }
+  }
+  return [...diagnostics.values()].sort((a, b) => a.file.localeCompare(b.file));
+}
+export {
+  importSpecifiers,
+  validateLabKatexImports
+};

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

@@ -5,6 +5,7 @@ interface LessonNotationFrontmatter {
     readonly local?: ReadonlyArray<{
         readonly key: string;
         readonly latex: string;
+        readonly fixedIndex?: boolean;
     }>;
 }
 /**

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

@@ -1,5 +1,6 @@
 import { loadManifest } from "../compiler/manifest.js";
 import {
+  bindScopeToPage,
   registerPageNotationDependencies,
   routeIdFromLocals
 } from "./page-notation.js";
@@ -9,7 +10,8 @@ async function labMathScope(notation, body = "", component) {
   const local = notation?.local ?? [];
   const scope = local.map((definition) => ({
     key: definition.key,
-    notation: definition.latex
+    notation: definition.latex,
+    ...definition.fixedIndex === true ? { fixedIndex: true } : {}
   }));
   const referenced = /* @__PURE__ */ new Set();
   const explicitlyExplained = /* @__PURE__ */ new Set();
@@ -32,7 +34,11 @@ async function labMathScope(notation, body = "", component) {
     }
     const shared = sharedByKey.get(key);
     if (shared) {
-      scope.push({ key: shared.key, notation: shared.notation });
+      scope.push({
+        key: shared.key,
+        notation: shared.notation,
+        ...shared.fixedIndex ? { fixedIndex: true } : {}
+      });
       resolvedKeys.add(key);
       continue;
     }
@@ -48,6 +54,11 @@ async function labMathScope(notation, body = "", component) {
       resolvedKeys,
       component.context
     );
+    bindScopeToPage(scope, {
+      locals: component.locals,
+      context: component.context,
+      checkIndices: !manifest.rules.disabled.includes("N23")
+    });
   }
   return scope;
 }

package/dist/reference/lint-ignore.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 const IGNORE_PATH = join(process.cwd(), "lint-ignore.yml");
-const LINE = /^-\s*([a-z0-9-]+)(?::([^\s—-][^—-]*?))?\s*(?:—|--|\s-\s)\s*(.+?)\s*$/;
+const LINE = /^-\s*([a-z0-9-]+)(?::([^\s—][^—]*?))?\s*(?:—|--|\s-\s)\s*(.+?)\s*$/;
 function parseLintIgnore(text) {
   const entries = [];
   for (const rawLine of text.split("\n")) {

package/dist/reference/math-glyphs.d.mts

@@ -39,6 +39,64 @@ export function operatorDisplayLatex(name: string): string;
  * @returns {string | undefined}
  */
 export function decorationOfEntry(latex: string): string | undefined;
+/** True for a letter that is a running index wherever it is a whole slot. */
+export function isRunningIndexLetter(text: any): boolean;
+/**
+ * The key of a derived entry: a base entry composed with an index entry
+ * (`\mathbf{v}_0` from `velocity-vector` and `{}_0`). The build materializes
+ * it from the two (`derived-notation.mjs`); it is never authored, and an
+ * authored key that equals one fails the build.
+ *
+ * @param {string} baseKey
+ * @param {string} indexKey
+ * @returns {string}
+ */
+export function derivedNotationKey(baseKey: string, indexKey: string): string;
+/**
+ * The subscript an **index entry** explains — an empty group with a subscript:
+ * `{}_0`, `{}_x`, `{}_{\mathrm{max}}` — as the source after `{}`, else
+ * `undefined`. Such an entry binds no symbol of its own; composed with the
+ * entry of the symbol it indexes, it makes a derived card (rule N23).
+ *
+ * @param {string} latex
+ * @returns {string | undefined}
+ */
+export function indexOfEntry(latex: string): string | undefined;
+/**
+ * The symbol a base entry gives a derived card: its whole `latex`, or the
+ * glyph it lends to — the head of a function form (`v` of `v(t)`), the base
+ * of a superscript form (`j` of `j^{(m)}`).
+ *
+ * @param {string} notation
+ * @returns {string}
+ */
+export function baseSymbolLatex(notation: string): string;
+/**
+ * The symbol of a derived card: the base's symbol with the index entry's
+ * subscript — `\mathbf{v}` and `{}_0` make `\mathbf{v}_0`.
+ *
+ * @param {string} baseNotation
+ * @param {string} indexNotation
+ * @returns {string}
+ */
+export function derivedNotationLatex(baseNotation: string, indexNotation: string): string;
+/**
+ * How an index entry is shown on its own — over a placeholder square, as an
+ * operator entry is (`\square_0`). Display only.
+ *
+ * @param {string} latex
+ * @returns {string}
+ */
+export function indexDisplayLatex(latex: string): string;
+/**
+ * Whether an entry's `latex` has a subscript on a symbol anywhere — what an
+ * `\explain{key}{X_i}` wrap needs from `key` before its card can explain the
+ * index (rule N23, `index-swallowed`).
+ *
+ * @param {string} latex
+ * @returns {boolean}
+ */
+export function entryHasIndex(latex: string): boolean;
 /**
  * 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.
@@ -51,15 +109,28 @@ export function decorationOfEntry(latex: string): string | undefined;
  * decorated form no whole form covers is reported in `unresolved`, marked
  * `suspended`.
  *
+ * A symbol with a subscript (rule N23) takes its exact whole form, else the
+ * family whose index has its shape, else — with `options.derive`, which page
+ * math sets (a lesson body, its assessments, labs and diagrams) — a derived
+ * card from an index entry (`{}_0`) and the base's entry; each such card
+ * wraps the whole indexed symbol. `derived`
+ * lists the derived cards used, as `{ key, base, index }`, for the build to
+ * materialize; `indices` says how each indexed symbol is explained (see
+ * `classifyIndexed`). A definition may carry `fixedIndex: true`: its index
+ * (or, on a letter, the letter as an index) is a fixed label, not a running
+ * one, so it is no family.
+ *
  * @param {string} latex
- * @param {Array<{key: string, notation: string}>} definitions
- * @param {{ suspended?: readonly string[] }} [options]
+ * @param {Array<{key: string, notation: string, fixedIndex?: boolean}>} definitions
+ * @param {{ suspended?: readonly string[], derive?: boolean }} [options]
  */
 export function resolveMathGlyphs(latex: string, definitions: Array<{
     key: string;
     notation: string;
+    fixedIndex?: boolean;
 }>, options?: {
     suspended?: readonly string[];
+    derive?: boolean;
 }): {
     latex: string;
     bindings: {
@@ -72,11 +143,32 @@ export function resolveMathGlyphs(latex: string, definitions: Array<{
     decorations: {
         token: string;
         wholeForm: any;
+        wholeFormExplicit: boolean;
         operator: any;
         start: any;
         end: any;
         name: any;
     }[];
+    indices: {
+        token: string;
+        start: any;
+        end: any;
+        base: any;
+        index: any;
+        how: any;
+        key: any;
+        explained: boolean;
+        baseExplained: boolean;
+        unexplained: any[];
+        running: {
+            letter: any;
+            start: any;
+            end: any;
+            key: any;
+            cover: any;
+        }[];
+    }[];
+    derived: any[];
 };
 /**
  * Every named operator in one KaTeX expression: a built-in `op` node