explico 0.7.0 → 0.8.0

package/src/reference/katex-delimiters.mjs

@@ -0,0 +1,125 @@
+/**
+ * Rule N17's engine half: make `\left`/`\right` grow strictly outward.
+ *
+ * Importing this module for its side effect installs a KaTeX whose
+ * `\delimitershortfall` is `-1pt` instead of the stock `5pt`, so a scalable
+ * delimiter pair is always *strictly* taller than what it wraps and nesting
+ * depth shows up on its own. See `docs/katex-bracket-scaling.md` for the
+ * derivation and `docs/authoring/notation.md#n17` for the authoring rule.
+ *
+ * ## Why this is not a `patches/` file
+ *
+ * `delimiterExtend` is a function-local `const` inside `makeLeftRightDelim`.
+ * Nothing KaTeX exports reaches it — `__defineMacro`, `__defineFunction`,
+ * `__defineSymbol`, `__setFontMetrics` and the settings schema all sit above
+ * the layout engine — so the constant can only be changed in the module's own
+ * source. A `pnpm patch` does that, but a patch is project-local: it cannot
+ * travel inside the published `explico` artifact, so every downstream course
+ * would have to reapply it or silently render flat nests.
+ *
+ * So the engine does it in code instead. It reads KaTeX's own ESM bundle,
+ * rewrites that one constant, imports the result as a module, and moves the
+ * rendering entry points onto the shared `katex` object every consumer in the
+ * process already imported. KaTeX's default export is a plain mutable object
+ * and `rehype-katex` reads `katex.renderToString` at call time, so the swap
+ * reaches lesson-body math without forking the plugin.
+ *
+ * ## Why this is safe to rely on
+ *
+ * The assumptions above (a matching constant, a mutable export, a bundle with
+ * no imports of its own) are all checked here, and `assertDelimiterGrowth()`
+ * renders a known nest afterwards and throws when the sizes do not actually
+ * increase. A course therefore either renders with engine-sized delimiters or
+ * fails its build saying so — it cannot quietly get the stock behaviour.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import katex from 'katex';
+
+/** TeX's `\delimitershortfall`, in points, as KaTeX hard-codes it. */
+const STOCK_SHORTFALL = '5.0';
+/** The negative shortfall that forces strict outward growth. */
+const GROWN_SHORTFALL = '-1.0';
+
+const needle = (points) =>
+  `var delimiterExtend = ${points} / options.fontMetrics().ptPerEm;`;
+
+/** The entry points that build a delimiter and must come from the rewrite. */
+const RENDER_EXPORTS = [
+  'render',
+  'renderToString',
+  '__renderToDomTree',
+  '__renderToHTMLTree',
+];
+
+/**
+ * Exported for the test that pins both failure messages — a KaTeX upgrade that
+ * moves the constant, and a leftover `patches/` file, are the two ways this
+ * stops being able to install itself.
+ */
+export function rewriteBundle(source) {
+  const stock = needle(STOCK_SHORTFALL);
+  if (!source.includes(stock)) {
+    // Either the constant moved or someone already rewrote it. Both mean the
+    // assumption this module rests on no longer holds for this KaTeX build.
+    const alreadyGrown = source.includes(needle(GROWN_SHORTFALL));
+    throw new Error(
+      alreadyGrown
+        ? `explico: katex ${katex.version} already carries the -1pt delimiter ` +
+          'shortfall (a patches/ file?). Remove that patch — the engine ' +
+          'installs it in code (src/reference/katex-delimiters.mjs).'
+        : `explico: cannot install the N17 delimiter sizing into katex ` +
+          `${katex.version}: the \\delimitershortfall constant ` +
+          `(${stock}) is not in its ESM bundle. Re-derive the one-line ` +
+          'change against the new bundle — see docs/katex-bracket-scaling.md.',
+    );
+  }
+  return source.replace(stock, needle(GROWN_SHORTFALL));
+}
+
+async function loadGrownKatex() {
+  const require = createRequire(import.meta.url);
+  const source = readFileSync(require.resolve('katex/dist/katex.mjs'), 'utf8');
+  // The bundle is self-contained, so it can be re-imported from a data URL
+  // with no base to resolve relative specifiers against.
+  const rewritten = rewriteBundle(source);
+  const module = await import(
+    `data:text/javascript;base64,${Buffer.from(rewritten).toString('base64')}`
+  );
+  return module.default;
+}
+
+/**
+ * Render a known nest and confirm the outer pair really is larger than the
+ * inner one. Cheap, and it turns every way this could go wrong — an upstream
+ * refactor, a frozen export, an import that beat us to it — into one loud
+ * failure at the point of installation.
+ */
+export function assertDelimiterGrowth(instance = katex) {
+  const html = instance.renderToString(
+    String.raw`\left[1+\left(\frac{a}{b}\right)\right]`,
+    { displayMode: true, output: 'html' },
+  );
+  const sizes = [...html.matchAll(/delimsizing size(\d)/g)].map((m) =>
+    Number(m[1]),
+  );
+  // Two pairs, so four glyphs: outer, inner, inner, outer.
+  const grew = sizes.length === 4 && sizes[0] > sizes[1];
+  if (!grew) {
+    throw new Error(
+      'explico: the N17 delimiter sizing did not take effect — a nested ' +
+        `\\left…\\right pair rendered as [${sizes.join(', ')}] instead of ` +
+        'growing outward. Something rendered math before ' +
+        "'explico/reference/katex-delimiters.mjs' was imported, or katex " +
+        'changed shape. See docs/katex-bracket-scaling.md.',
+    );
+  }
+}
+
+const grown = await loadGrownKatex();
+for (const name of RENDER_EXPORTS) {
+  if (typeof grown[name] === 'function') katex[name] = grown[name];
+}
+assertDelimiterGrowth();
+
+export default katex;

package/src/reference/katex-options.mjs

@@ -1,3 +1,7 @@
+// Side-effect import: installs rule N17's delimiter sizing onto the shared
+// `katex` module before anything renders. A course wires this file into its
+// `astro.config.mjs`, so `rehype-katex` inherits it without a patch.
+import './katex-delimiters.mjs';
 import { NOTATION_KEY_PATTERN } from './remark-notation.mjs';
 
 export const EXPLAIN_MACRO = String.raw`\htmlData{notation-key=#1}{#2}`;

package/src/reference/math-glyphs.mjs

@@ -1,4 +1,4 @@
-import katex from 'katex';
+import katex from './katex-delimiters.mjs';
 
 import { BASE_LIBRARY } from './base-library.mjs';
 import { PARENTHESIZED_FUNCTIONS } from './base-operators.mjs';
@@ -386,6 +386,19 @@ function trimTrailingWhitespace(latex, start, end) {
   return trimmed;
 }
 
+/**
+ * KaTeX gives a node it produced by expanding a macro a `loc` from the lexer
+ * over the *macro body*, not over the source being scanned: `\vdots` expands
+ * to `{\varvdots\rule{0pt}{15pt}}`, and its `\varvdots` atom arrives with
+ * `loc.start = 1`, `loc.end = 10` — offsets into that 27-character body.
+ * Those numbers are valid indices into any longer source, so they read as a
+ * real span pointing at unrelated text. Every `loc` therefore has to prove it
+ * belongs to the string this pass parsed before its offsets are believed.
+ */
+function isAuthoredLocation(loc, latex) {
+  return loc?.lexer?.input === latex;
+}
+
 function nodeSpan(node, latex) {
   let start = Number.POSITIVE_INFINITY;
   let end = Number.NEGATIVE_INFINITY;
@@ -397,7 +410,8 @@ function nodeSpan(node, latex) {
     if (
       value.loc &&
       Number.isInteger(value.loc.start) &&
-      Number.isInteger(value.loc.end)
+      Number.isInteger(value.loc.end) &&
+      isAuthoredLocation(value.loc, latex)
     ) {
       start = Math.min(start, value.loc.start);
       end = Math.max(end, value.loc.end);

package/src/reference/render-lab-math.ts

@@ -1,4 +1,4 @@
-import katex from 'katex';
+import katex from './katex-delimiters.mjs';
 import { resolveMathGlyphs, stripNotationMarkers } from './math-glyphs.mjs';
 import { createNotationKatexOptions } from './katex-options.mjs';
 

package/src/reference/types.ts

@@ -88,6 +88,13 @@ export interface NotationLessonInput {
   readonly references: readonly NotationReferenceInput[];
   /** Original lesson body, retained for lossless loader adapters. */
   readonly body: string;
+  /**
+   * 1-based line in `source.file` where `body` starts. Gates scan the body, so
+   * every finding's index is body-relative; this is what turns one into a real
+   * location in the file. Optional so a hand-built input (a test, an adapter)
+   * stays valid — it then behaves as 1, the pre-0.7.1 behavior.
+   */
+  readonly bodyLine?: number;
   readonly source: SourceSpan;
 }