explico 0.12.0 → 0.13.0

package/dist/reference/gate-prop-text.js

@@ -0,0 +1,106 @@
+const blank = (text) => text.replace(/[^\n]/g, " ");
+function blankNonJsx(text) {
+  return text.replace(/^---\r?\n[\s\S]*?\r?\n---(?=\r?\n|$)/, blank).replace(/\{\/\*[\s\S]*?\*\/\}/g, blank).replace(/```[\s\S]*?```/g, blank).replace(/(^|[^`])`[^`\n]*`/g, (match, lead) => lead + blank(match.slice(lead.length)));
+}
+function readTag(text, start) {
+  let quote;
+  let depth = 0;
+  let props = "";
+  for (let index = start; index < text.length; index += 1) {
+    const char = text[index];
+    const kept = depth === 0 || char === "\n" ? char : " ";
+    if (quote !== void 0) {
+      if (char === quote) quote = void 0;
+      props += kept;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`" && depth > 0) {
+      quote = char;
+    } else if (char === "{") {
+      depth += 1;
+    } else if (char === "}") {
+      depth = Math.max(0, depth - 1);
+      props += " ";
+      continue;
+    } else if (char === ">" && depth === 0) {
+      return { end: index + 1, props: props + char };
+    }
+    props += depth === 0 || char === "\n" ? char : " ";
+  }
+  return void 0;
+}
+function propStrings(text) {
+  const searchable = blankNonJsx(text);
+  const found = [];
+  const opening = /<([A-Za-z][\w.:-]*)/g;
+  let match;
+  while (match = opening.exec(searchable)) {
+    const tag = readTag(searchable, match.index);
+    if (tag === void 0) break;
+    for (const prop of tag.props.matchAll(/([A-Za-z_][\w:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
+      const value = prop[2] ?? prop[3] ?? "";
+      const valueAt = match.index + (prop.index ?? 0) + prop[0].length - value.length - 1;
+      found.push({ tag: match[1], name: prop[1], value: text.slice(valueAt, valueAt + value.length), offset: valueAt });
+    }
+    opening.lastIndex = tag.end;
+  }
+  return found;
+}
+function blankPropStrings(text) {
+  let out = text;
+  for (const { value, offset } of propStrings(text)) {
+    out = out.slice(0, offset) + blank(value) + out.slice(offset + value.length);
+  }
+  return out;
+}
+const INLINE_MATH = /(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/;
+const REFERENCE = /\[\[[^\]\n]*\]\]/;
+const CITATION = /\[@[^\]\n]*\]/;
+function markupIn(value) {
+  const math = INLINE_MATH.exec(value);
+  if (math) {
+    return {
+      found: `math (\`${math[0]}\`)`,
+      advice: 'Write the symbol in Unicode or words ("v\u2080", "the launch speed"); the prose next to it typesets the symbol.'
+    };
+  }
+  const reference = REFERENCE.exec(value);
+  if (reference) {
+    return {
+      found: `a reference (\`${reference[0]}\`)`,
+      advice: "Name the target in words, and reference it from the prose next to the component."
+    };
+  }
+  const citation = CITATION.exec(value);
+  if (citation) {
+    return {
+      found: `a citation (\`${citation[0]}\`)`,
+      advice: "Cite the source in the prose next to the component."
+    };
+  }
+  return void 0;
+}
+function findMarkupInProps(records) {
+  const issues = [];
+  for (const { file, text } of records) {
+    const path = file.replace(/\\/g, "/");
+    if (!path.startsWith("content/docs/") || !path.endsWith(".mdx")) continue;
+    for (const prop of propStrings(text)) {
+      const markup = markupIn(prop.value);
+      if (markup === void 0) continue;
+      const line = text.slice(0, prop.offset).split("\n").length;
+      issues.push({
+        kind: "markup-in-prop",
+        message: `${file}:${line}: <${prop.tag}> \`${prop.name}\` holds ${markup.found}, but a prop is plain text: it would print as typed. ${markup.advice}`,
+        file,
+        line
+      });
+    }
+  }
+  return issues;
+}
+export {
+  blankPropStrings,
+  findMarkupInProps,
+  propStrings
+};

package/dist/reference/gate-prose-notation.d.ts

@@ -34,10 +34,12 @@ interface AssessmentLike {
 /**
  * `keepMath` leaves `$…$` / `$$…$$` in place (everything else still blanked,
  * offsets unchanged) — for a check that needs to see what a math span sits
- * next to, such as `$x = 3$ meters`.
+ * next to, such as `$x = 3$ meters`. `keepReferences` leaves `[[…]]` in
+ * place, for the check that a reference is well formed.
  */
 declare function proseOnly(body: string, options?: {
     readonly keepMath?: boolean;
+    readonly keepReferences?: boolean;
 }): string;
 /** Exported for the same reason as {@link proseOnly}. */
 declare function lineOf(text: string, index: number): number;

package/dist/reference/gate-prose-notation.js

@@ -6,12 +6,14 @@ const INLINE_MATH = /(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/g;
 const IMPORT_LINE = /^[ \t]*import\b[^\n]*$/gm;
 const KEY_REFERENCE = /\[\[[^\]\n]*\]\]/g;
 const JSX_TAG = /<\/?[A-Za-z][^<>]*>/g;
+const LINK_DESTINATION = /\]\((?:[^()\n]|\([^()\n]*\))*\)/g;
+const LINK_DEFINITION = /^[ \t]{0,3}\[[^\]\n]+\]:[ \t]*\S[^\n]*$/gm;
 const MDX_COMMENT = /\{\/\*[\s\S]*?\*\/\}/g;
 function proseOnly(body, options = {}) {
   const blank = (match) => match.replace(/[^\n]/g, " ");
   const code = body.replace(MDX_COMMENT, blank).replace(CODE_FENCE, blank).replace(INLINE_CODE, (match, lead) => lead + blank(match.slice(lead.length)));
   const math = options.keepMath ? code : code.replace(DISPLAY_MATH, blank).replace(INLINE_MATH, blank);
-  return math.replace(IMPORT_LINE, blank).replace(KEY_REFERENCE, blank).replace(JSX_TAG, blank);
+  return math.replace(IMPORT_LINE, blank).replace(KEY_REFERENCE, (match) => options.keepReferences ? match : blank(match)).replace(LINK_DESTINATION, (match) => `]${blank(match.slice(1))}`).replace(LINK_DEFINITION, blank).replace(JSX_TAG, blank);
 }
 function lineOf(text, index) {
   return text.slice(0, index).split("\n").length;
@@ -43,7 +45,7 @@ const SLASH_IDIOMS = /* @__PURE__ */ new Set([
   "a/b"
 ]);
 const SLASH_TOKENS = /\b([A-Za-z]{1,6})\/([A-Za-z]{1,6})\b/g;
-const FAKE_SCRIPT = /[A-Za-z0-9][_^][A-Za-z0-9{]/g;
+const FAKE_SCRIPT = /[A-Za-z0-9]+[_^](?:\{[^{}\n]{0,24}\}?|[A-Za-z0-9]+)/g;
 const PROSE_NOTATION_CODE = "prose-notation";
 function findAll(text, pattern, toFinding) {
   const out = [];

package/dist/reference/gate-retired-keys.d.ts

@@ -0,0 +1,35 @@
+import { CurriculumIssue } from '../curriculum/validation.js';
+
+/**
+ * The retired-key gate (invariant `retired-keys`). A content file that still
+ * sets a key the engine no longer reads fails the build, once per key and
+ * file, so a course stops maintaining a field that does nothing. The finding
+ * points at the key's line, and deleting that line clears it. See
+ * docs/authoring/structure.md#retired-keys.
+ */
+
+/** One content file as `loadContentRecords` (`compiler/collections.ts`) reads it. */
+interface ContentRecord {
+    /** Repository-relative path, e.g. `content/sources/hull.json`. */
+    readonly file: string;
+    /** Top-level fields: a page's frontmatter, or a JSON record's object. */
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly text: string;
+}
+/** Each retired key, with what an author does about it. Keys are plain identifiers. */
+declare const RETIRED_KEYS: Readonly<Record<string, string>>;
+/** One `retired-key` issue per retired key a record sets, in record order. */
+declare function findRetiredKeys(records: readonly ContentRecord[]): CurriculumIssue[];
+/** The 1-based line a `key:` (YAML) or `"key":` (JSON) first starts on. */
+declare function keyLine(text: string, key: string): number | undefined;
+/**
+ * Starlight frontmatter a lesson may set but explico cannot honour: the
+ * manifest, not Starlight, decides which pages a course lists and in what
+ * order (invariant `retired-keys`). `draft: true` is an error — Starlight
+ * drops the page from a production build while the sidebar still names it, so
+ * the build fails — and `sidebar.order` a warning, since chapters follow the
+ * tracks and the key does nothing.
+ */
+declare function findUnsupportedKeys(records: readonly ContentRecord[]): CurriculumIssue[];
+
+export { type ContentRecord, RETIRED_KEYS, findRetiredKeys, findUnsupportedKeys, keyLine };

package/dist/reference/gate-retired-keys.js

@@ -0,0 +1,58 @@
+const RETIRED_KEYS = {
+  editorialStatus: "explico no longer tracks a draft / in-review / reviewed status, because lessons are reviewed continuously. Delete the line."
+};
+function findRetiredKeys(records) {
+  const issues = [];
+  for (const { file, data, text } of records) {
+    for (const [key, advice] of Object.entries(RETIRED_KEYS)) {
+      if (!(key in data)) continue;
+      const line = keyLine(text, key);
+      const at = line === void 0 ? file : `${file}:${line}`;
+      issues.push({
+        kind: "retired-key",
+        message: `${at}: \`${key}\` is retired. ${advice}`,
+        file,
+        ...line === void 0 ? {} : { line }
+      });
+    }
+  }
+  return issues;
+}
+function keyLine(text, key) {
+  const match = new RegExp(`^[ \\t]*(?:"${key}"|${key})[ \\t]*:`, "m").exec(text);
+  return match === null ? void 0 : text.slice(0, match.index).split("\n").length;
+}
+function findUnsupportedKeys(records) {
+  const issues = [];
+  for (const { file, data, text } of records) {
+    if (!file.replace(/\\/g, "/").startsWith("content/docs/")) continue;
+    if (data.draft === true) {
+      const line = keyLine(text, "draft");
+      issues.push({
+        kind: "unsupported-key",
+        message: `${line === void 0 ? file : `${file}:${line}`}: \`draft: true\` is not supported in a course: Starlight leaves a draft out of a production build, but explico still lists and numbers it, so the build fails ("The slug \u2026 specified in the Starlight sidebar config does not exist"). Keep an unfinished lesson outside content/docs/ until it is ready.`,
+        file,
+        ...line === void 0 ? {} : { line }
+      });
+    }
+    const sidebar = data.sidebar;
+    const chapter = /^content\/docs\/[^/]+\/(?!index\.mdx?$)[^/]+\.mdx?$/.test(file.replace(/\\/g, "/"));
+    if (chapter && sidebar !== null && typeof sidebar === "object" && "order" in sidebar) {
+      const line = keyLine(text, "order");
+      issues.push({
+        kind: "ignored-key",
+        severity: "warning",
+        message: `${line === void 0 ? file : `${file}:${line}`}: \`sidebar.order\` does nothing in a course: chapters follow the order of the tracks (content/tracks/*.json), then their slugs. Order them there and delete the line.`,
+        file,
+        ...line === void 0 ? {} : { line }
+      });
+    }
+  }
+  return issues;
+}
+export {
+  RETIRED_KEYS,
+  findRetiredKeys,
+  findUnsupportedKeys,
+  keyLine
+};

package/dist/reference/gloss.d.ts

@@ -41,6 +41,8 @@ interface ResolvedGloss {
 interface GlyphScopeEntry {
     readonly key: string;
     readonly notation: string;
+    /** Rule N23: the entry's index is a fixed label, so it is no family. */
+    readonly fixedIndex?: true;
 }
 /**
  * The key segment derived from a gloss name: lower-cased, runs of anything

package/dist/reference/katex-measure.d.ts

@@ -0,0 +1,17 @@
+/** A formula's box at one font size, in px. */
+interface FormulaMetrics {
+    /** Advance width. */
+    readonly width: number;
+    /** Height above the baseline. */
+    readonly height: number;
+    /** Depth below the baseline. */
+    readonly depth: number;
+}
+/**
+ * Measure `latex` as the notation KaTeX renders it — the same macros
+ * (`\explain`, `\slot`), trust boundary and delimiter sizing as lesson math —
+ * at a font size of `fontPx`. Throws on LaTeX KaTeX cannot render.
+ */
+declare function measureFormula(latex: string, fontPx: number): FormulaMetrics;
+
+export { type FormulaMetrics, measureFormula };

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-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;
 }