explico 0.2.0 → 0.4.0

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

@@ -0,0 +1,110 @@
+import {
+  KEYED_FLOAT_KEY_PATTERN,
+  parseKeyedFloatRef,
+  scanKeyedJsxFloats
+} from "./keyed-jsx-floats.mjs";
+const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
+function stripCode(text) {
+  return text.replace(/```[\s\S]*?```/g, " ").replace(/~~~[\s\S]*?~~~/g, " ").replace(/`[^`\n]*`/g, " ");
+}
+function bodyFloatRefs(lesson, prefix) {
+  const refs = [];
+  for (const match of stripCode(lesson.body).matchAll(BRACKET_REF)) {
+    const parsed = parseKeyedFloatRef((match[1] ?? "").trim(), { prefix });
+    if (!parsed) continue;
+    refs.push({
+      key: parsed.key,
+      lessonId: lesson.lessonId,
+      ...parsed.lesson ? { targetSlug: parsed.lesson } : {}
+    });
+  }
+  return refs;
+}
+function validateKeyedFloats(lessons, kind) {
+  const { tagName, prefix, noun } = kind;
+  const labels = [];
+  const diagnostics = [];
+  const numbersBySlug = {};
+  for (const lesson of [...lessons].sort(
+    (a, b) => a.lessonId.localeCompare(b.lessonId)
+  )) {
+    const seen = /* @__PURE__ */ new Set();
+    const table = {};
+    for (const raw of scanKeyedJsxFloats(lesson.body, {
+      tagName,
+      numbering: lesson.numbering
+    })) {
+      if (raw.key == null) continue;
+      if (!KEYED_FLOAT_KEY_PATTERN.test(raw.key)) {
+        diagnostics.push({
+          code: `${prefix}-invalid-key`,
+          severity: "error",
+          message: `${lesson.lessonId} has a <${tagName} id="${raw.key}"> whose id is not a valid key \u2014 expected lowercase letters, digits, and hyphens only.`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          key: raw.key
+        });
+        continue;
+      }
+      if (seen.has(raw.key)) {
+        diagnostics.push({
+          code: `${prefix}-duplicate-key`,
+          severity: "error",
+          message: `${lesson.lessonId} has two <${tagName}> elements with id="${raw.key}"; an id is unique per lesson.`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          key: raw.key
+        });
+        continue;
+      }
+      seen.add(raw.key);
+      table[raw.key] = raw.number;
+      labels.push({
+        key: raw.key,
+        number: raw.number,
+        lessonId: lesson.lessonId,
+        slug: lesson.slug,
+        section: raw.section,
+        indexInSection: raw.indexInSection
+      });
+    }
+    numbersBySlug[lesson.slug] = table;
+  }
+  const referenced = /* @__PURE__ */ new Set();
+  for (const lesson of lessons) {
+    const slug = lesson.slug;
+    for (const ref of bodyFloatRefs(lesson, prefix)) {
+      const targetSlug = ref.targetSlug ?? slug;
+      const number = numbersBySlug[targetSlug]?.[ref.key];
+      referenced.add(`${targetSlug}#${ref.key}`);
+      if (number === void 0) {
+        diagnostics.push({
+          code: `${prefix}-ref-resolves`,
+          severity: "error",
+          message: ref.targetSlug ? `${lesson.lessonId} references [[${ref.targetSlug}#${prefix}-${ref.key}]] but that lesson has no <${tagName} id="${ref.key}">` : `${lesson.lessonId} references [[${prefix}-${ref.key}]] but no <${tagName}> on the page carries id="${ref.key}"`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          key: ref.key
+        });
+      }
+    }
+  }
+  for (const label of labels) {
+    if (referenced.has(`${label.slug}#${label.key}`)) continue;
+    diagnostics.push({
+      code: `${prefix}-key-unused`,
+      severity: "warning",
+      message: `${label.lessonId} has a ${noun} id="${label.key}" (${label.number}) but nothing references it with [[${prefix}-${label.key}]]`,
+      file: label.slug,
+      lessonId: label.lessonId,
+      key: label.key
+    });
+  }
+  diagnostics.sort(
+    (a, b) => a.code.localeCompare(b.code) || (a.lessonId ?? "").localeCompare(b.lessonId ?? "") || (a.key ?? "").localeCompare(b.key ?? "") || a.message.localeCompare(b.message)
+  );
+  return { labels, numbersBySlug, diagnostics };
+}
+export {
+  validateKeyedFloats
+};

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

@@ -0,0 +1,64 @@
+/** The anchor id for a float, e.g. `{prefix:'tab', key:'foo'}` → `tab-foo`. */
+export function keyedFloatAnchorId({ key, number, prefix }: {
+    key: any;
+    number: any;
+    prefix: any;
+}): string;
+/**
+ * A `[[ … ]]` payload that targets this kind of float: `<prefix>-<key>` on
+ * the current page, or `<lesson-slug>#<prefix>-<key>` across pages.
+ */
+export function parseKeyedFloatRef(raw: any, { prefix }: {
+    prefix: any;
+}): {
+    lesson: string;
+    key: string;
+} | {
+    key: string;
+    lesson?: undefined;
+} | 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, `##`
+ * 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: any, { tagName, numbering }: {
+    tagName: any;
+    numbering: any;
+}): {
+    key: string | null | undefined;
+    number: string;
+    section: number;
+    indexInSection: number;
+}[];
+/**
+ * How many floats of this kind a lesson body holds — the input to the next
+ * lesson's `offset` within the same part.
+ */
+export function countKeyedJsxFloats(markdown: any, { tagName }: {
+    tagName: any;
+}): number;
+/**
+ * The mdast equivalent of `scanKeyedJsxFloats`: walk the tree's *top-level*
+ * children in document order, advancing the section counter on every
+ * 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 `scanKeyedJsxFloats`.
+ */
+export function collectKeyedJsxFloats(tree: any, { tagName, numbering }: {
+    tagName: any;
+    numbering: any;
+}): {
+    key: any;
+    number: string;
+    section: number;
+    indexInSection: number;
+    node: any;
+}[];
+/** Same shape as `EQ_KEY_PATTERN` — the notation-key grammar without dots. */
+export const KEYED_FLOAT_KEY_PATTERN: RegExp;

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

@@ -0,0 +1,191 @@
+/**
+ * Keyed-float identity for a JSX-wrapped table or figure, shared between
+ * `<Table>` and `<Figure>` (Step F-tables-figures).
+ *
+ * This mirrors `equations.mjs`, but the key comes from a plain `id` prop on
+ * the wrapper component rather than a `\label{eq:key}` embedded in shared
+ * LaTeX source — a `<Table>`/`<Figure>` is purpose-built, so there is no
+ * ambiguity an embedded marker would need to resolve. An author writes the
+ * bare key (`id="kinematics-summary"`); the rendered DOM id and the `[[…]]`
+ * reference prefix are computed the same way `\label{eq:key}` becomes
+ * `#eq-key` — `keyedFloatAnchorId` prepends `tab-`/`fig-`.
+ *
+ * Only top-level occurrences count, exactly like `collectDisplayEquations`:
+ * a `<Table>` nested inside a `<CompactExample>` (or any other component) is
+ * illustrative, not part of the lesson's official sequence, so both the
+ * mdast walker and the raw-text scanner only look at the document's direct
+ * top-level blocks.
+ *
+ * `scanKeyedJsxFloats` (raw Markdown, for the manifest builder) and
+ * `collectKeyedJsxFloats` (mdast, for `remark-notation.mjs`) MUST agree —
+ * `tests/notation/keyed-floats.test.ts` checks that, the same contract
+ * `equations.test.ts` holds equations to.
+ */
+
+import {
+  resolveNumbering,
+  stripFencedCode,
+  stripJsxComponents,
+} from './equations.mjs';
+
+/** Same shape as `EQ_KEY_PATTERN` — the notation-key grammar without dots. */
+export const KEYED_FLOAT_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** The visible number for the `index`-th float of one kind under `section`. */
+function floatNumber(section, index) {
+  return section > 0 ? `${section}.${index}` : String(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
+ * advances the `<Figure>` sequence — so `offset` is per kind too.
+ */
+function keyedFloatNumber({
+  prefix,
+  offset = 0,
+  section,
+  indexInSection,
+  indexInLesson,
+}) {
+  return prefix == null
+    ? floatNumber(section, indexInSection)
+    : `${prefix}.${offset + indexInLesson}`;
+}
+
+/** The anchor id for a float, e.g. `{prefix:'tab', key:'foo'}` → `tab-foo`. */
+export function keyedFloatAnchorId({ key, number, prefix }) {
+  return key ? `${prefix}-${key}` : `${prefix}-${String(number).replace(/\./g, '-')}`;
+}
+
+/**
+ * A `[[ … ]]` payload that targets this kind of float: `<prefix>-<key>` on
+ * the current page, or `<lesson-slug>#<prefix>-<key>` across pages.
+ */
+export function parseKeyedFloatRef(raw, { prefix }) {
+  const pattern = new RegExp(
+    `^(?:([a-z0-9]+(?:-[a-z0-9]+)*(?:/[a-z0-9]+(?:-[a-z0-9]+)*)*)#)?${prefix}-([a-z0-9]+(?:-[a-z0-9]+)*)$`,
+  );
+  const match = pattern.exec(String(raw).trim());
+  if (!match) return undefined;
+  return match[1] ? { lesson: match[1], key: match[2] } : { key: match[2] };
+}
+
+/** The `id="…"` attribute value of a JSX opening tag's attribute source. */
+function readIdAttribute(attributesSource) {
+  const match = /\bid\s*=\s*(["'])([^"']*)\1/.exec(attributesSource);
+  return match ? match[2] : 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, `##`
+ * 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);
+  const tokens = [];
+  const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
+  const opening = new RegExp(`<${tagName}\\b([^>]*)>`, 'g');
+  for (const match of text.matchAll(heading)) {
+    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 });
+  }
+  tokens.sort((a, b) => a.index - b.index);
+
+  const labels = [];
+  let section = 0;
+  let indexInSection = 0;
+  let indexInLesson = 0;
+  for (const token of tokens) {
+    if (token.kind === 'section') {
+      section += 1;
+      indexInSection = 0;
+      continue;
+    }
+    indexInSection += 1;
+    indexInLesson += 1;
+    labels.push({
+      key: token.key,
+      number: keyedFloatNumber({
+        prefix,
+        offset,
+        section,
+        indexInSection,
+        indexInLesson,
+      }),
+      section,
+      indexInSection,
+    });
+  }
+  return labels;
+}
+
+/**
+ * How many floats of this kind a lesson body holds — the input to the next
+ * lesson's `offset` within the same part.
+ */
+export function countKeyedJsxFloats(markdown, { tagName }) {
+  return scanKeyedJsxFloats(markdown, { tagName }).length;
+}
+
+/**
+ * The mdast equivalent of `scanKeyedJsxFloats`: walk the tree's *top-level*
+ * children in document order, advancing the section counter on every
+ * 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 `scanKeyedJsxFloats`.
+ */
+export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
+  const { prefix, offset } = resolveNumbering(numbering);
+  const floats = [];
+  let section = 0;
+  let indexInSection = 0;
+  let indexInLesson = 0;
+
+  const children = Array.isArray(tree?.children) ? tree.children : [];
+  for (const node of children) {
+    if (!node || typeof node !== 'object') continue;
+    if (node.type === 'heading' && node.depth === 2) {
+      section += 1;
+      indexInSection = 0;
+      continue;
+    }
+    if (node.type === 'mdxJsxFlowElement' && node.name === tagName) {
+      indexInSection += 1;
+      indexInLesson += 1;
+      const idAttribute = (node.attributes ?? []).find(
+        (attribute) =>
+          attribute?.type === 'mdxJsxAttribute' && attribute.name === 'id',
+      );
+      const key =
+        typeof idAttribute?.value === 'string' ? idAttribute.value : undefined;
+      floats.push({
+        key: key ?? null,
+        number: keyedFloatNumber({
+          prefix,
+          offset,
+          section,
+          indexInSection,
+          indexInLesson,
+        }),
+        section,
+        indexInSection,
+        node,
+      });
+    }
+  }
+  return floats;
+}
+

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

@@ -18,6 +18,24 @@ export function resolveMathGlyphs(latex: string, definitions: Array<{
     }[];
     unresolved: any;
 };
+/**
+ * Every named operator in one KaTeX expression: a built-in `op` node
+ * (`\exp`, `\int`, `\sum`, …) or an author-declared `\operatorname{…}` /
+ * `\mathop{…}` (`Var`, `Cov`, …). The `name` is the KaTeX command without its
+ * backslash for a built-in, and the verbatim body for a declared one — the
+ * form `BASE_OPERATORS` and `course.config.ts` `operators` are keyed by.
+ *
+ * Pure read: unlike `resolveMathGlyphs`, nothing here rewrites the source.
+ * Used by the `operator-explained` consistency check (rule N8); the glyph
+ * resolver still skips operator bodies whole.
+ *
+ * @param {string} latex
+ * @returns {Array<{ name: string, source: 'named' | 'operatorname' }>}
+ */
+export function collectOperators(latex: string): Array<{
+    name: string;
+    source: "named" | "operatorname";
+}>;
 /**
  * Page-level glyph-map resolver (cleanup plan, D1 decision 2026-09-02).
  *

package/dist/reference/math-glyphs.mjs

@@ -828,3 +828,95 @@ export function resolveMathGlyphs(latex, definitions) {
     unresolved: unresolvedIdentifiers(latex, identifiers, bindings),
   };
 }
+
+// --- named operators ------------------------------------------------
+
+/**
+ * Every named operator in one KaTeX expression: a built-in `op` node
+ * (`\exp`, `\int`, `\sum`, …) or an author-declared `\operatorname{…}` /
+ * `\mathop{…}` (`Var`, `Cov`, …). The `name` is the KaTeX command without its
+ * backslash for a built-in, and the verbatim body for a declared one — the
+ * form `BASE_OPERATORS` and `course.config.ts` `operators` are keyed by.
+ *
+ * Pure read: unlike `resolveMathGlyphs`, nothing here rewrites the source.
+ * Used by the `operator-explained` consistency check (rule N8); the glyph
+ * resolver still skips operator bodies whole.
+ *
+ * @param {string} latex
+ * @returns {Array<{ name: string, source: 'named' | 'operatorname' }>}
+ */
+export function collectOperators(latex) {
+  if (typeof latex !== 'string' || latex.trim() === '') return [];
+
+  let tree;
+  try {
+    tree = parseMath(latex, 'operator scan');
+  } catch (error) {
+    // A span that will not parse is the math gate's problem, not this check's.
+    // A KaTeX version-pin failure is nobody's to swallow — let it through.
+    if (error instanceof GlyphResolutionError && error.code === 'invalid-latex') {
+      return [];
+    }
+    throw error;
+  }
+
+  const seen = new Set();
+  const operators = [];
+  const add = (name, source) => {
+    const trimmed = typeof name === 'string' ? name.trim() : '';
+    if (trimmed === '') return;
+    const identity = `${source}:${trimmed}`;
+    if (seen.has(identity)) return;
+    seen.add(identity);
+    operators.push({ name: trimmed, source });
+  };
+
+  // The declared-operator name is its letters with any internal spacing
+  // dropped, so `\operatorname{arg\,max}` keys as `argmax` — `fontBodyText`
+  // alone bails on the `\,`.
+  const declaredName = (body) => {
+    const direct = fontBodyText(body);
+    if (typeof direct === 'string') return direct;
+    const letters = [];
+    const gather = (value) => {
+      if (Array.isArray(value)) {
+        value.forEach(gather);
+        return;
+      }
+      if (!isNode(value)) return;
+      if (value.type === 'mathord' || value.type === 'textord') {
+        letters.push(value.text ?? '');
+      }
+      if (value.type === 'ordgroup') gather(value.body);
+    };
+    gather(body);
+    return letters.join('');
+  };
+
+  const visit = (value) => {
+    if (Array.isArray(value)) {
+      for (const child of value) visit(child);
+      return;
+    }
+    if (!isNode(value)) return;
+
+    if (value.type === 'operatorname') {
+      add(declaredName(value.body), 'operatorname');
+    } else if (value.type === 'op') {
+      if (typeof value.name === 'string' && value.name.length > 0) {
+        add(value.name.replace(/^\\/, ''), 'named');
+      } else if (value.body !== undefined) {
+        // `\mathop{Foo}` — a hand-rolled operator with no command name.
+        add(declaredName(value.body), 'operatorname');
+      }
+    }
+
+    for (const key of Object.keys(value)) {
+      if (key === 'loc') continue;
+      visit(value[key]);
+    }
+  };
+
+  visit(tree);
+  return operators;
+}

package/dist/reference/remark-notation.d.mts

@@ -1,18 +1,79 @@
+/**
+ * The numbering inputs a lesson page needs, read off one manifest.
+ *
+ * Every number on a page comes from two places that MUST agree: the page's own
+ * counters (`numbering`) and the manifest tables a cross-page `[[slug#eq-key]]`
+ * is resolved against (`equations` / `tables` / `figures`). Deriving all four
+ * from the same manifest in one step is what stops a course config from
+ * supplying one without the other — the omission that produced page-local
+ * `(2.2)` and cross-page `(4.5)` for the same equation.
+ *
+ * `numbering` maps a lesson slug to `{ part, equations, tables, figures }`:
+ * the part's ordinal (the number before the dot) and, per kind of float, how
+ * many of them the earlier lessons of that part already used.
+ */
+export function numberingFromManifest(manifest: any): {
+    equations?: undefined;
+    tables?: undefined;
+    figures?: undefined;
+    numbering?: undefined;
+} | {
+    equations: any;
+    tables: any;
+    figures: any;
+    numbering: {
+        [k: string]: any;
+    };
+};
 /**
  * @param {{
  *   definitions?: Map<string, object> | readonly object[] | Record<string, object> | (() => Map<string, object> | readonly object[] | Record<string, object>),
  *   resolve?: (key: string, context: object) => object | undefined,
  *   unknown?: 'error' | 'warn' | 'ignore',
  *   base?: string,
+ *   manifest?: object,
  *   equations?: Record<string, Record<string, string>>,
+ *   tables?: Record<string, Record<string, string>>,
+ *   figures?: Record<string, Record<string, string>>,
+ *   numbering?: Record<string, { part: number, equations: number, tables: number, figures: number }>,
+ *   chapters?: Record<string, number>,
  * }} [options]
+ *
+ * `manifest` is the preferred wiring: pass the compiled manifest and the four
+ * numbering inputs below are read off it together, so they cannot drift apart.
+ * They stay available individually for hand-built trees, and an explicitly
+ * supplied one still wins over the manifest.
+ *
+ * `numbering` maps a lesson slug to its **part** (the number before the dot)
+ * and, per kind of float, how many the earlier lessons of that part already
+ * used. Every display equation / `<Table>` / `<Figure>` on the page is then
+ * numbered `‹part›.‹offset + n›`, with `##` and `###` headings ignored; with no
+ * entry the legacy `##`-section scheme applies. It must agree with
+ * `manifest.lessons[]`, which is what feeds `equations`/`tables`/`figures`
+ * above — supplying the tables without `numbering` numbers the same equation
+ * twice, and `assertManifestNumberParity` turns that into a build error rather
+ * than a page whose references disagree with their targets.
+ *
+ * `chapters` is the superseded per-lesson form (slug → the lesson's course
+ * ordinal, no running offset). Still read when `numbering` has no entry, so a
+ * config written against the old option keeps building.
  */
 export default function remarkNotation(options?: {
     definitions?: Map<string, object> | readonly object[] | Record<string, object> | (() => Map<string, object> | readonly object[] | Record<string, object>);
     resolve?: (key: string, context: object) => object | undefined;
     unknown?: "error" | "warn" | "ignore";
     base?: string;
+    manifest?: object;
     equations?: Record<string, Record<string, string>>;
+    tables?: Record<string, Record<string, string>>;
+    figures?: Record<string, Record<string, string>>;
+    numbering?: Record<string, {
+        part: number;
+        equations: number;
+        tables: number;
+        figures: number;
+    }>;
+    chapters?: Record<string, number>;
 }): (tree: any, file: any) => void;
 /**
  * Remark adapter for semantic notation references.