explico 0.7.0 → 0.11.0

package/dist/reference/katex-delimiters.mjs

@@ -0,0 +1,138 @@
+/**
+ * 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 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() {
+  // Imported here, not at the top: should a browser graph ever reach this
+  // module (a lab island once did, through `render-lab-math.ts`; islands now
+  // import `lab-math-slot.ts`), Vite's `node:fs` stub throws on first access —
+  // which, for a static named import, is module evaluation itself, so the
+  // island would never hydrate.
+  const { readFileSync } = await import('node:fs');
+  const { createRequire } = await import('node:module');
+  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. The URL is built at
+  // run time on purpose, so Vite has nothing to analyze here.
+  const rewritten = rewriteBundle(source);
+  const module = await import(
+    /* @vite-ignore */
+    `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.',
+    );
+  }
+}
+
+// Build and server rendering only. In a browser there is no KaTeX bundle on
+// disk to rewrite. No client graph should include this module (lab math is
+// rendered on the server); if one does, a client-side render falls back to
+// stock sizing rather than breaking the island.
+if (typeof window === 'undefined') {
+  const grown = await loadGrownKatex();
+  for (const name of RENDER_EXPORTS) {
+    if (typeof grown[name] === 'function') katex[name] = grown[name];
+  }
+  assertDelimiterGrowth();
+}
+
+export default katex;

package/dist/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/dist/reference/keyed-float-validate.d.ts

@@ -8,11 +8,18 @@
  * - `<prefix>-ref-resolves` (error): every `[[<prefix>-key]]` /
  *   `[[slug#<prefix>-key]]` points at the matching keyed float with that `id`.
  * - `<prefix>-key-unused` (info): a keyed float is never referenced.
+ * - `<prefix>-removed-prop` (error): the tag sets a prop that no longer
+ *   exists. Mostly a name prop (`<Figure title>`, `<Diagram label>`) — every
+ *   float is named by the one caption pair, `caption` (long) and `short`
+ *   (optional), and a removed prop would otherwise render nothing and escape
+ *   rule S1 — and a diagram's compaction props (`defaultOpen`,
+ *   `rememberState`), since a diagram no longer folds by itself.
  *
- * `tables-validate.ts`, `figures-validate.ts`, and `diagrams-validate.ts` are
- * thin wrappers over this so callers import a kind-specific validator with
- * narrow diagnostic-code types, while `equations-validate.ts` stays untouched
- * — equations predate this and keep their own dedicated path.
+ * `tables-validate.ts`, `figures-validate.ts`, `diagrams-validate.ts` and
+ * `examples-validate.ts` (`<CompactExamples>`, which adds its required-prop
+ * check) are thin wrappers over this so callers import a kind-specific
+ * validator with narrow diagnostic-code types, while `equations-validate.ts`
+ * stays untouched — equations predate this and keep their own dedicated path.
  */
 interface KeyedFloatKind {
     /** The MDX component tag, e.g. `Table` or `Figure`. */
@@ -21,10 +28,19 @@ interface KeyedFloatKind {
     readonly prefix: string;
     /** Lowercase noun used in diagnostic messages, e.g. `table` or `figure`. */
     readonly noun: string;
+    /**
+     * Name props this kind no longer takes, each with the fix its diagnostic
+     * gives, e.g. `{ title: 'use \`caption\` …' }`. Omitted: none.
+     */
+    readonly removedProps?: Readonly<Record<string, string>>;
 }
 interface KeyedFloatLabelRecord {
     readonly key: string;
     readonly number: string;
+    /** The float's literal `short` caption, when it has one. */
+    readonly short?: string;
+    /** The float's literal `caption`; absent when it is an expression. */
+    readonly caption?: string;
     readonly lessonId: string;
     readonly slug: string;
     readonly section: number;
@@ -57,14 +73,15 @@ interface KeyedFloatLessonInput {
     readonly file: string;
     readonly body: string;
     /**
-     * `{ prefix, offset }` — the part's 1-based ordinal among the sidebar groups,
-     * and how many floats of this kind earlier lessons of that part already used.
-     * When set, floats are numbered `‹part›.‹offset + n›`; when omitted, the
-     * legacy `##`-section scheme. Each kind counts on its own, so the caller
-     * passes a different `offset` for `<Table>` than for `<Figure>`.
+     * `{ prefix, offset }` — the lesson's float-number prefix (`‹part›.‹chapter›`,
+     * or `‹part›` under `numbering.floats: "part"`) and how many floats of this
+     * kind precede the lesson in that scope. When set, floats are numbered
+     * `‹prefix›.‹offset + n›`; when omitted, the legacy `##`-section scheme.
+     * Each kind counts on its own, so the caller passes a different `offset`
+     * for `<Table>` than for `<Figure>`.
      */
     readonly numbering?: {
-        readonly prefix: number;
+        readonly prefix: number | string;
         readonly offset: number;
     };
 }

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

@@ -21,7 +21,7 @@ function bodyFloatRefs(lesson, prefix) {
   return refs;
 }
 function validateKeyedFloats(lessons, kind) {
-  const { tagName, prefix, noun } = kind;
+  const { tagName, prefix, noun, removedProps = {} } = kind;
   const labels = [];
   const diagnostics = [];
   const numbersBySlug = {};
@@ -34,6 +34,18 @@ function validateKeyedFloats(lessons, kind) {
       tagName,
       numbering: lesson.numbering
     })) {
+      for (const prop of raw.props) {
+        const fix = removedProps[prop];
+        if (fix === void 0) continue;
+        diagnostics.push({
+          code: `${prefix}-removed-prop`,
+          severity: "error",
+          message: `${lesson.lessonId} has a <${tagName} ${prop}="\u2026">${raw.key ? ` (id="${raw.key}")` : ""}, but <${tagName}> has no \`${prop}\` prop: ${fix}`,
+          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({
@@ -62,6 +74,8 @@ function validateKeyedFloats(lessons, kind) {
       labels.push({
         key: raw.key,
         number: raw.number,
+        ...raw.short ? { short: raw.short } : {},
+        ...raw.caption ? { caption: raw.caption } : {},
         lessonId: lesson.lessonId,
         slug: lesson.slug,
         section: raw.section,

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

@@ -19,10 +19,13 @@ export function parseKeyedFloatRef(raw: any, { prefix }: {
 } | undefined;
 /**
  * The raw-text equivalent of `collectKeyedJsxFloats`, mirroring
- * `scanEquationLabels`: every top-level `<TagName …>` in appearance order.
- * With `numbering` (`{ prefix, offset }` — the part's ordinal and the count of
- * this kind of float in earlier lessons of that part) the number is
- * `‹part›.‹offset + n›`, `n` sequential over the whole lesson; without it, `##`
+ * `scanEquationLabels`: every top-level `<TagName …>` in appearance order,
+ * with its literal `short` / `caption` (the caption pair every float takes;
+ * `null` when absent or an expression) and `props`, the names of every prop
+ * the tag sets, for `keyed-float-validate.ts`'s removed-prop check.
+ * With `numbering` (`{ prefix, offset }` — the lesson's float-number prefix
+ * and the count of this kind of float before it in that scope) the number is
+ * `‹prefix›.‹offset + n›`, `n` sequential over the whole lesson; without it, `##`
  * headings advance a section counter. Other JSX components' bodies are blanked
  * first so a `<Table>` nested inside e.g. `<CompactExample>` (and any `##`-like
  * text inside an unrelated component) is never counted.
@@ -33,6 +36,9 @@ export function scanKeyedJsxFloats(markdown: any, { tagName, numbering }: {
 }): {
     key: string | null | undefined;
     number: string;
+    short: string | null | undefined;
+    caption: string | null | undefined;
+    props: any[] | undefined;
     section: number;
     indexInSection: number;
 }[];
@@ -45,7 +51,7 @@ export function countKeyedJsxFloats(markdown: any, { tagName }: {
 }): number;
 /**
  * The mdast equivalent of `scanKeyedJsxFloats`: walk the tree's top-level
- * children (and through `<Memo>` bodies) in document order, advancing the
+ * children (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

@@ -11,8 +11,9 @@
  * `#eq-key` — `keyedFloatAnchorId` prepends `tab-`/`fig-`/`dia-`.
  *
  * Only top-level occurrences count, exactly like `collectDisplayEquations`,
- * except that `<Memo>` is transparent: a float in a memo remains a side-note
- * in the lesson's reading order. A keyed float nested inside a
+ * except that the `TRANSPARENT_COMPONENTS` (`<Memo>`, `<ShortNote>`,
+ * `<Fold>`) are see-through: a float in a memo or a fold stays in the
+ * lesson's reading order. A keyed float nested inside a
  * `<CompactExample>` (or any other component) is illustrative, not part of the
  * official sequence.
  *
@@ -26,6 +27,7 @@ import {
   resolveNumbering,
   stripFencedCode,
   stripJsxComponents,
+  TRANSPARENT_COMPONENTS,
 } from './equations.mjs';
 
 /** Same shape as `EQ_KEY_PATTERN` — the notation-key grammar without dots. */
@@ -37,10 +39,11 @@ function floatNumber(section, index) {
 }
 
 /**
- * The visible number for one float. With a `prefix` (the part's ordinal) the
- * scheme is `‹part›.‹offset + indexInLesson›` and `##` headings are ignored;
- * without it, the legacy `##`-section scheme. Mirrors `displayEquationNumber`
- * in `equations.mjs`. Each kind of float counts on its own — a `<Table>` never
+ * The visible number for one float. With a `prefix` (`‹part›.‹chapter›`, or
+ * the part alone under `numbering.floats: "part"`) the scheme is
+ * `‹prefix›.‹offset + indexInLesson›` and `##` headings are ignored; without
+ * it, the legacy `##`-section scheme. Mirrors `displayEquationNumber` in
+ * `equations.mjs`. Each kind of float counts on its own — a `<Table>` never
  * advances the `<Figure>` or `<Diagram>` sequence — so `offset` is per kind too.
  */
 function keyedFloatNumber({
@@ -79,22 +82,60 @@ function readIdAttribute(attributesSource) {
   return match ? match[2] : undefined;
 }
 
+/**
+ * A literal string attribute (`name="…"` / `name='…'`) of a JSX opening tag's
+ * attribute source, trimmed; `null` when absent, empty, or an expression.
+ */
+function readStringAttribute(attributesSource, name) {
+  const match = new RegExp(
+    String.raw`(?:^|\s)${name}\s*=\s*(?:"([^"]*)"|'([^']*)')`,
+  ).exec(attributesSource);
+  const value = (match?.[1] ?? match?.[2])?.trim();
+  return value ? value : null;
+}
+
+/** Every prop name a JSX opening tag's attribute source sets (`name=`). */
+function attributeNames(attributesSource) {
+  const bare = attributesSource.replace(
+    /"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}/g,
+    ' ',
+  );
+  return [...bare.matchAll(/(?:^|\s)([A-Za-z_][\w:.-]*)\s*=/g)].map(
+    (match) => match[1],
+  );
+}
+
+/** A literal string value of an mdast JSX attribute, trimmed, else `null`. */
+function mdxStringAttribute(node, name) {
+  const attribute = (node.attributes ?? []).find(
+    (candidate) =>
+      candidate?.type === 'mdxJsxAttribute' && candidate.name === name,
+  );
+  const value =
+    typeof attribute?.value === 'string' ? attribute.value.trim() : '';
+  return value ? value : null;
+}
+
 /**
  * The raw-text equivalent of `collectKeyedJsxFloats`, mirroring
- * `scanEquationLabels`: every top-level `<TagName …>` in appearance order.
- * With `numbering` (`{ prefix, offset }` — the part's ordinal and the count of
- * this kind of float in earlier lessons of that part) the number is
- * `‹part›.‹offset + n›`, `n` sequential over the whole lesson; without it, `##`
+ * `scanEquationLabels`: every top-level `<TagName …>` in appearance order,
+ * with its literal `short` / `caption` (the caption pair every float takes;
+ * `null` when absent or an expression) and `props`, the names of every prop
+ * the tag sets, for `keyed-float-validate.ts`'s removed-prop check.
+ * With `numbering` (`{ prefix, offset }` — the lesson's float-number prefix
+ * and the count of this kind of float before it in that scope) the number is
+ * `‹prefix›.‹offset + n›`, `n` sequential over the whole lesson; without it, `##`
  * headings advance a section counter. Other JSX components' bodies are blanked
  * first so a `<Table>` nested inside e.g. `<CompactExample>` (and any `##`-like
  * text inside an unrelated component) is never counted.
  */
 export function scanKeyedJsxFloats(markdown, { tagName, numbering }) {
   const { prefix, offset } = resolveNumbering(numbering);
-  const text = stripJsxComponents(stripFencedCode(markdown), tagName, [
-    'Memo',
-    'ShortNote',
-  ]);
+  const text = stripJsxComponents(
+    stripFencedCode(markdown),
+    tagName,
+    TRANSPARENT_COMPONENTS,
+  );
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
   const opening = new RegExp(`<${tagName}\\b([^>]*)>`, 'g');
@@ -102,8 +143,16 @@ export function scanKeyedJsxFloats(markdown, { tagName, numbering }) {
     tokens.push({ kind: 'section', index: match.index });
   }
   for (const match of text.matchAll(opening)) {
-    const key = readIdAttribute(match[1] ?? '');
-    tokens.push({ kind: 'float', index: match.index, key: key ?? null });
+    const attributes = match[1] ?? '';
+    const key = readIdAttribute(attributes);
+    tokens.push({
+      kind: 'float',
+      index: match.index,
+      key: key ?? null,
+      short: readStringAttribute(attributes, 'short'),
+      caption: readStringAttribute(attributes, 'caption'),
+      props: attributeNames(attributes),
+    });
   }
   tokens.sort((a, b) => a.index - b.index);
 
@@ -128,6 +177,9 @@ export function scanKeyedJsxFloats(markdown, { tagName, numbering }) {
         indexInSection,
         indexInLesson,
       }),
+      short: token.short,
+      caption: token.caption,
+      props: token.props,
       section,
       indexInSection,
     });
@@ -145,7 +197,7 @@ export function countKeyedJsxFloats(markdown, { tagName }) {
 
 /**
  * The mdast equivalent of `scanKeyedJsxFloats`: walk the tree's top-level
- * children (and through `<Memo>` bodies) in document order, advancing the
+ * children (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
@@ -171,6 +223,8 @@ export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
         typeof idAttribute?.value === 'string' ? idAttribute.value : undefined;
       floats.push({
         key: key ?? null,
+        short: mdxStringAttribute(node, 'short'),
+        caption: mdxStringAttribute(node, 'caption'),
         number: keyedFloatNumber({
           prefix,
           offset,
@@ -186,8 +240,7 @@ export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
     }
     if (
       node.type === 'mdxJsxFlowElement' &&
-      node.name !== 'Memo' &&
-      node.name !== 'ShortNote'
+      !TRANSPARENT_COMPONENTS.includes(node.name)
     ) {
       return;
     }
@@ -207,7 +260,7 @@ export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
       collectFromDetail(node);
     } else if (
       node.type === 'mdxJsxFlowElement' &&
-      (node.name === 'Memo' || node.name === 'ShortNote')
+      TRANSPARENT_COMPONENTS.includes(node.name)
     ) {
       collectFromDetail(node);
     }

package/dist/reference/knowledge-checks-validate.d.ts

@@ -6,7 +6,7 @@ interface KnowledgeCheckLessonInput {
     readonly body: string;
     readonly assessmentIds: readonly string[];
     readonly numbering?: {
-        readonly prefix: number;
+        readonly prefix: number | string;
         readonly offset: number;
     };
 }

package/dist/reference/knowledge-checks.d.mts

@@ -10,7 +10,9 @@ export function parseKnowledgeCheckRef(raw: any): {
 export function knowledgeCheckAnchorId(key: any): string;
 /**
  * Number an ordered assessment-id list. With manifest placement, the number
- * is `part.offset + index`; without it, the list remains usefully page-local.
+ * is `‹prefix›.‹offset + index›` — `prefix` is `‹part›.‹chapter›`, or the part
+ * alone under `numbering.floats: "part"`; without it, the list remains
+ * usefully page-local.
  */
 export function collectKnowledgeChecks(assessmentIds: any, numbering: any): any;
 /**

package/dist/reference/knowledge-checks.mjs

@@ -28,12 +28,17 @@ export function knowledgeCheckAnchorId(key) {
 
 /**
  * Number an ordered assessment-id list. With manifest placement, the number
- * is `part.offset + index`; without it, the list remains usefully page-local.
+ * is `‹prefix›.‹offset + index›` — `prefix` is `‹part›.‹chapter›`, or the part
+ * alone under `numbering.floats: "part"`; without it, the list remains
+ * usefully page-local.
  */
 export function collectKnowledgeChecks(assessmentIds, numbering) {
-  const prefix = Number.isInteger(numbering?.prefix) && numbering.prefix > 0
-    ? numbering.prefix
-    : undefined;
+  const rawPrefix = numbering?.prefix;
+  const prefix =
+    (Number.isInteger(rawPrefix) && rawPrefix > 0) ||
+    (typeof rawPrefix === 'string' && /^\d+(?:\.\d+)*$/.test(rawPrefix))
+      ? rawPrefix
+      : undefined;
   const offset = Number.isInteger(numbering?.offset) && numbering.offset >= 0
     ? numbering.offset
     : 0;

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

@@ -1,4 +1,5 @@
 import { LabMathScopeDefinition } from './render-lab-math.js';
+import './lab-math-slot.js';
 
 interface LessonNotationFrontmatter {
     readonly local?: ReadonlyArray<{

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

@@ -0,0 +1,34 @@
+/**
+ * The half of lab math an interactive island needs in the browser: the shape
+ * of a compiled template and its slot placeholder. It imports nothing, so an
+ * island that uses it stays clear of the KaTeX build chain behind
+ * `render-lab-math.ts`, which is server-only (`katex-delimiters.mjs` reads
+ * KaTeX's bundle from disk).
+ */
+interface RenderedLabMath {
+    /** KaTeX HTML+MathML with `data-notation-key` and `data-lab-slot` spans. */
+    readonly html: string;
+    /** Slot names, in template order, the island must supply at runtime. */
+    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 `render-lab-math.ts` 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;
+
+export { type RenderedLabMath, slotPlaceholder };

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

@@ -0,0 +1,6 @@
+function slotPlaceholder(name) {
+  return `\u27E6${name}\u27E7`;
+}
+export {
+  slotPlaceholder
+};