explico 0.2.0 → 0.3.0

package/dist/reference/diagram-layout.d.ts

@@ -0,0 +1,63 @@
+interface DiagramNodeInput {
+    readonly id: string;
+    readonly width: number;
+    readonly height: number;
+}
+interface DiagramEdgeInput {
+    readonly from: string;
+    readonly to: string;
+}
+interface DiagramLayoutOptions {
+    /** Top-to-bottom (default) or left-to-right. */
+    readonly direction?: 'TB' | 'LR';
+    readonly nodeSeparation?: number;
+    readonly rankSeparation?: number;
+    /** Uniform padding added around the computed bounding box. */
+    readonly padding?: number;
+}
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+interface LaidOutNode {
+    readonly id: string;
+    /** Top-left corner, not the center dagre itself works in. */
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+interface LaidOutEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly points: readonly Point[];
+}
+interface DiagramLayout {
+    readonly nodes: readonly LaidOutNode[];
+    readonly edges: readonly LaidOutEdge[];
+    /** The SVG canvas size a caller should use as the `viewBox`. */
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Lay out a small directed graph. Node ids must be unique; an edge naming an
+ * undeclared node fails loudly rather than silently dropping it (dagre itself
+ * would otherwise create a phantom zero-size node).
+ */
+declare function layoutDiagram(nodes: readonly DiagramNodeInput[], edges: readonly DiagramEdgeInput[], options?: DiagramLayoutOptions): DiagramLayout;
+interface BoxSizeEstimate {
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Estimate a diagram node's box from its label text (or raw, pre-resolution
+ * LaTeX for a formula node). Deliberately generous: it is meant to avoid
+ * clipping, not to match a real render pixel-for-pixel. Pass an explicit
+ * `width`/`height` on the node to override for a label this estimate gets
+ * badly wrong.
+ */
+declare function estimateBoxSize(content: string, kind: 'text' | 'formula', options?: {
+    readonly maxWidth?: number;
+}): BoxSizeEstimate;
+
+export { type BoxSizeEstimate, type DiagramEdgeInput, type DiagramLayout, type DiagramLayoutOptions, type DiagramNodeInput, type LaidOutEdge, type LaidOutNode, type Point, estimateBoxSize, layoutDiagram };

package/dist/reference/diagram-layout.js

@@ -0,0 +1,122 @@
+import dagre from "@dagrejs/dagre";
+function layoutDiagram(nodes, edges, options = {}) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const node of nodes) {
+    if (ids.has(node.id)) {
+      throw new Error(`Diagram declares node "${node.id}" more than once.`);
+    }
+    if (!(node.width > 0) || !(node.height > 0)) {
+      throw new Error(
+        `Diagram node "${node.id}" must have a positive width and height.`
+      );
+    }
+    ids.add(node.id);
+  }
+  for (const edge of edges) {
+    if (!ids.has(edge.from)) {
+      throw new Error(`Diagram edge references unknown node "${edge.from}".`);
+    }
+    if (!ids.has(edge.to)) {
+      throw new Error(`Diagram edge references unknown node "${edge.to}".`);
+    }
+  }
+  const graph = new dagre.graphlib.Graph();
+  graph.setGraph({
+    rankdir: options.direction ?? "TB",
+    nodesep: options.nodeSeparation ?? 24,
+    ranksep: options.rankSeparation ?? 48,
+    marginx: 0,
+    marginy: 0
+  });
+  graph.setDefaultEdgeLabel(() => ({}));
+  for (const node of nodes) {
+    graph.setNode(node.id, { width: node.width, height: node.height });
+  }
+  for (const edge of edges) {
+    graph.setEdge(edge.from, edge.to);
+  }
+  dagre.layout(graph);
+  const centeredNodes = nodes.map((node) => {
+    const label = graph.node(node.id);
+    const cx = label.x ?? 0;
+    const cy = label.y ?? 0;
+    return {
+      id: node.id,
+      x: cx - node.width / 2,
+      y: cy - node.height / 2,
+      width: node.width,
+      height: node.height
+    };
+  });
+  const rawEdges = edges.map((edge) => {
+    const label = graph.edge(edge.from, edge.to) ?? {};
+    return {
+      from: edge.from,
+      to: edge.to,
+      points: (label.points ?? []).map((point) => ({
+        x: point.x,
+        y: point.y
+      }))
+    };
+  });
+  const padding = options.padding ?? 12;
+  const xs = [
+    ...centeredNodes.flatMap((node) => [node.x, node.x + node.width]),
+    ...rawEdges.flatMap((edge) => edge.points.map((point) => point.x))
+  ];
+  const ys = [
+    ...centeredNodes.flatMap((node) => [node.y, node.y + node.height]),
+    ...rawEdges.flatMap((edge) => edge.points.map((point) => point.y))
+  ];
+  const minX = xs.length > 0 ? Math.min(...xs) : 0;
+  const minY = ys.length > 0 ? Math.min(...ys) : 0;
+  const maxX = xs.length > 0 ? Math.max(...xs) : 0;
+  const maxY = ys.length > 0 ? Math.max(...ys) : 0;
+  const shiftX = padding - minX;
+  const shiftY = padding - minY;
+  return {
+    nodes: centeredNodes.map((node) => ({
+      ...node,
+      x: node.x + shiftX,
+      y: node.y + shiftY
+    })),
+    edges: rawEdges.map((edge) => ({
+      ...edge,
+      points: edge.points.map((point) => ({
+        x: point.x + shiftX,
+        y: point.y + shiftY
+      }))
+    })),
+    width: maxX - minX + padding * 2,
+    height: maxY - minY + padding * 2
+  };
+}
+const DEFAULT_MAX_WIDTH = 220;
+const MIN_WIDTH = 90;
+const PADDING_X = 20;
+const PADDING_Y = 16;
+const LINE_HEIGHT = 22;
+const CHAR_WIDTH = {
+  text: 7.2,
+  formula: 11
+};
+function formulaVisibleLength(latex) {
+  const collapsed = latex.replace(/\\[a-zA-Z]+/g, "x").replace(/[{}$]/g, "").trim();
+  return Math.max(1, collapsed.length);
+}
+function estimateBoxSize(content, kind, options = {}) {
+  const maxWidth = options.maxWidth ?? DEFAULT_MAX_WIDTH;
+  const visibleLength = kind === "formula" ? formulaVisibleLength(content) : content.trim().length || 1;
+  const charWidth = CHAR_WIDTH[kind];
+  const naturalWidth = visibleLength * charWidth + PADDING_X * 2;
+  const width = Math.min(maxWidth, Math.max(MIN_WIDTH, naturalWidth));
+  const usableWidth = width - PADDING_X * 2;
+  const charsPerLine = Math.max(1, Math.floor(usableWidth / charWidth));
+  const lines = Math.max(1, Math.ceil(visibleLength / charsPerLine));
+  const height = lines * LINE_HEIGHT + PADDING_Y * 2;
+  return { width: Math.round(width), height: Math.round(height) };
+}
+export {
+  estimateBoxSize,
+  layoutDiagram
+};

package/dist/reference/equations-validate.d.ts

@@ -44,6 +44,11 @@ interface EquationLessonInput {
     readonly slug: string;
     readonly file: string;
     readonly body: string;
+    /**
+     * The lesson's 1-based ordinal in the course. When set, equations are
+     * numbered `‹chapter›.‹n›`; when omitted, the legacy `##`-section scheme.
+     */
+    readonly chapter?: number;
 }
 declare function validateEquations(lessons: readonly EquationLessonInput[]): EquationValidation;
 

package/dist/reference/equations-validate.js

@@ -25,7 +25,7 @@ function validateEquations(lessons) {
   )) {
     const seen = /* @__PURE__ */ new Set();
     const table = {};
-    for (const raw of scanEquationLabels(lesson.body)) {
+    for (const raw of scanEquationLabels(lesson.body, lesson.chapter)) {
       if (seen.has(raw.key)) {
         diagnostics.push({
           code: "eq-duplicate-key",

package/dist/reference/equations.d.mts

@@ -8,19 +8,45 @@ export function parseEquationRef(raw: any): {
 } | undefined;
 /** Remove every `\label{eq:…}` (and the whitespace it leaves) from a math source. */
 export function stripEquationLabels(latex: any): string;
+/**
+ * The visible number for one display equation. With `chapter` (the lesson's
+ * course ordinal) the scheme is `‹chapter›.‹indexInLesson›` and `##` headings
+ * are ignored; without it, the legacy `##`-section scheme.
+ */
+export function displayEquationNumber({ chapter, section, indexInSection, indexInLesson, }: {
+    chapter: any;
+    section: any;
+    indexInSection: any;
+    indexInLesson: any;
+}): string;
 /** The positional anchor id for an unkeyed equation, e.g. `2.4` → `eq-2-4`. */
 export function equationAnchorId({ key, number }: {
     key: any;
     number: any;
 }): string;
+export function stripFencedCode(markdown: any): string;
+/**
+ * Blank the body of every block-level MDX component (`<Capitalised …> … </…>`)
+ * so a `$$…$$` used to illustrate a worked example inside `<CompactExample>`
+ * (or an `<Aside>`, etc.) is not counted as a lesson-body equation. The
+ * outermost match wins, so nested components are blanked in one pass;
+ * newlines are kept so line/section structure is unchanged.
+ *
+ * `keep`, when given, leaves a component of that name untouched instead of
+ * blanking it — `keyed-jsx-floats.mjs` uses this to blank every *other*
+ * component while still finding `<Table>`/`<Figure>` tags at the top level.
+ */
+export function stripJsxComponents(markdown: any, keep: any): string;
 /**
  * Every keyed display equation in a Markdown body, in appearance order, with
- * its assigned number. `$$…$$` blocks only; `##` headings between them advance
- * the section counter. Every display block advances the in-section index, so a
- * keyed equation's number reflects its position among *all* display equations,
- * not only the keyed ones.
+ * its assigned number. `$$…$$` blocks only. With `chapter` (the lesson's
+ * course ordinal) the number is `‹chapter›.‹n›`, `n` sequential over every
+ * display block in the lesson; without it, `##` headings advance a section
+ * counter and the number is `‹section›.‹indexInSection›`. Either way every
+ * display block advances the index, so a keyed equation's number reflects its
+ * position among *all* display equations, not only the keyed ones.
  */
-export function scanEquationLabels(markdown: any): {
+export function scanEquationLabels(markdown: any, chapter: any): {
     key: string;
     number: string;
     section: number;
@@ -30,9 +56,10 @@ export function scanEquationLabels(markdown: any): {
  * The mdast equivalent of `scanEquationLabels` for *every* display equation:
  * walk the tree in document order, advancing the section counter on every
  * depth-2 heading and emitting a record for every `math` node. `key` is the
- * `\label{eq:…}` payload when present, else `null`.
+ * `\label{eq:…}` payload when present, else `null`. `chapter` is threaded the
+ * same way as in `scanEquationLabels`.
  */
-export function collectDisplayEquations(tree: any): {
+export function collectDisplayEquations(tree: any, chapter: any): {
     key: string | null;
     number: string;
     section: number;
@@ -43,7 +70,7 @@ export function collectDisplayEquations(tree: any): {
  * The keyed subset of `collectDisplayEquations` — the tree-walk counterpart of
  * `scanEquationLabels`. Numbers reflect position among all display equations.
  */
-export function collectEquationLabels(tree: any): {
+export function collectEquationLabels(tree: any, chapter: any): {
     key: string | null;
     number: string;
     section: number;
@@ -53,9 +80,13 @@ export function collectEquationLabels(tree: any): {
 /**
  * Equation identity (Step D7, extended F3) — shared, framework-free helpers.
  *
- * Every display equation (`$$…$$`) in a lesson is numbered and given an
- * `id`, from appearance order scoped to the enclosing `##` section (`(2.4)` =
- * fourth display equation under the second section). An author additionally
+ * Every display equation (`$$…$$`) in a lesson is numbered and given an `id`
+ * from appearance order. When the caller supplies a `chapter` (the lesson's
+ * ordinal position in the course), the number is `‹chapter›.‹n›` — `n` counts
+ * every display equation in the lesson and `##` headings do not affect it
+ * (`(2.4)` = fourth display equation of the second lesson). With no `chapter`
+ * the number falls back to the `##`-section scheme `‹section›.‹indexInSection›`
+ * (used by hand-built test trees and non-lesson pages). An author additionally
  * marks an equation with a trailing `\label{eq:<key>}` inside its `$$…$$`
  * block (inside math, so the `:` is safe and the form matches amsmath) when
  * they want a *stable* anchor that survives edits and cross-page references:

package/dist/reference/equations.mjs

@@ -1,9 +1,13 @@
 /**
  * Equation identity (Step D7, extended F3) — shared, framework-free helpers.
  *
- * Every display equation (`$$…$$`) in a lesson is numbered and given an
- * `id`, from appearance order scoped to the enclosing `##` section (`(2.4)` =
- * fourth display equation under the second section). An author additionally
+ * Every display equation (`$$…$$`) in a lesson is numbered and given an `id`
+ * from appearance order. When the caller supplies a `chapter` (the lesson's
+ * ordinal position in the course), the number is `‹chapter›.‹n›` — `n` counts
+ * every display equation in the lesson and `##` headings do not affect it
+ * (`(2.4)` = fourth display equation of the second lesson). With no `chapter`
+ * the number falls back to the `##`-section scheme `‹section›.‹indexInSection›`
+ * (used by hand-built test trees and non-lesson pages). An author additionally
  * marks an equation with a trailing `\label{eq:<key>}` inside its `$$…$$`
  * block (inside math, so the `:` is safe and the form matches amsmath) when
  * they want a *stable* anchor that survives edits and cross-page references:
@@ -58,12 +62,28 @@ function equationNumber(section, index) {
   return section > 0 ? `${section}.${index}` : String(index);
 }
 
+/**
+ * The visible number for one display equation. With `chapter` (the lesson's
+ * course ordinal) the scheme is `‹chapter›.‹indexInLesson›` and `##` headings
+ * are ignored; without it, the legacy `##`-section scheme.
+ */
+export function displayEquationNumber({
+  chapter,
+  section,
+  indexInSection,
+  indexInLesson,
+}) {
+  return chapter == null
+    ? equationNumber(section, indexInSection)
+    : `${chapter}.${indexInLesson}`;
+}
+
 /** The positional anchor id for an unkeyed equation, e.g. `2.4` → `eq-2-4`. */
 export function equationAnchorId({ key, number }) {
   return key ? `eq-${key}` : `eq-${String(number).replace(/\./g, '-')}`;
 }
 
-function stripFencedCode(markdown) {
+export function stripFencedCode(markdown) {
   return String(markdown)
     .replace(/```[\s\S]*?```/g, (block) => block.replace(/[^\n]/g, ' '))
     .replace(/~~~[\s\S]*?~~~/g, (block) => block.replace(/[^\n]/g, ' '))
@@ -76,22 +96,28 @@ function stripFencedCode(markdown) {
  * (or an `<Aside>`, etc.) is not counted as a lesson-body equation. The
  * outermost match wins, so nested components are blanked in one pass;
  * newlines are kept so line/section structure is unchanged.
+ *
+ * `keep`, when given, leaves a component of that name untouched instead of
+ * blanking it — `keyed-jsx-floats.mjs` uses this to blank every *other*
+ * component while still finding `<Table>`/`<Figure>` tags at the top level.
  */
-function stripJsxComponents(markdown) {
+export function stripJsxComponents(markdown, keep) {
   return String(markdown).replace(
     /<([A-Z][A-Za-z0-9]*)(?:\s[^>]*)?>[\s\S]*?<\/\1>/g,
-    (block) => block.replace(/[^\n]/g, ' '),
+    (block, name) => (name === keep ? block : block.replace(/[^\n]/g, ' ')),
   );
 }
 
 /**
  * Every keyed display equation in a Markdown body, in appearance order, with
- * its assigned number. `$$…$$` blocks only; `##` headings between them advance
- * the section counter. Every display block advances the in-section index, so a
- * keyed equation's number reflects its position among *all* display equations,
- * not only the keyed ones.
+ * its assigned number. `$$…$$` blocks only. With `chapter` (the lesson's
+ * course ordinal) the number is `‹chapter›.‹n›`, `n` sequential over every
+ * display block in the lesson; without it, `##` headings advance a section
+ * counter and the number is `‹section›.‹indexInSection›`. Either way every
+ * display block advances the index, so a keyed equation's number reflects its
+ * position among *all* display equations, not only the keyed ones.
  */
-export function scanEquationLabels(markdown) {
+export function scanEquationLabels(markdown, chapter) {
   const text = stripJsxComponents(stripFencedCode(markdown));
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
@@ -113,6 +139,7 @@ export function scanEquationLabels(markdown) {
   const labels = [];
   let section = 0;
   let indexInSection = 0;
+  let indexInLesson = 0;
   for (const token of tokens) {
     if (token.kind === 'section') {
       section += 1;
@@ -120,10 +147,16 @@ export function scanEquationLabels(markdown) {
       continue;
     }
     indexInSection += 1;
+    indexInLesson += 1;
     if (token.key == null) continue;
     labels.push({
       key: token.key,
-      number: equationNumber(section, indexInSection),
+      number: displayEquationNumber({
+        chapter,
+        section,
+        indexInSection,
+        indexInLesson,
+      }),
       section,
       indexInSection,
     });
@@ -135,12 +168,14 @@ export function scanEquationLabels(markdown) {
  * The mdast equivalent of `scanEquationLabels` for *every* display equation:
  * walk the tree in document order, advancing the section counter on every
  * depth-2 heading and emitting a record for every `math` node. `key` is the
- * `\label{eq:…}` payload when present, else `null`.
+ * `\label{eq:…}` payload when present, else `null`. `chapter` is threaded the
+ * same way as in `scanEquationLabels`.
  */
-export function collectDisplayEquations(tree) {
+export function collectDisplayEquations(tree, chapter) {
   const equations = [];
   let section = 0;
   let indexInSection = 0;
+  let indexInLesson = 0;
 
   // Only top-level blocks: a `$$…$$` nested in an MDX component (a
   // `<CompactExample>` worked example, an `<Aside>`) is illustrative, not part
@@ -155,11 +190,17 @@ export function collectDisplayEquations(tree) {
     }
     if (node.type === 'math') {
       indexInSection += 1;
+      indexInLesson += 1;
       EQ_LABEL_PATTERN.lastIndex = 0;
       const label = EQ_LABEL_PATTERN.exec(String(node.value ?? ''));
       equations.push({
         key: label ? label[1] : null,
-        number: equationNumber(section, indexInSection),
+        number: displayEquationNumber({
+          chapter,
+          section,
+          indexInSection,
+          indexInLesson,
+        }),
         section,
         indexInSection,
         node,
@@ -173,8 +214,8 @@ export function collectDisplayEquations(tree) {
  * The keyed subset of `collectDisplayEquations` — the tree-walk counterpart of
  * `scanEquationLabels`. Numbers reflect position among all display equations.
  */
-export function collectEquationLabels(tree) {
-  return collectDisplayEquations(tree).filter(
+export function collectEquationLabels(tree, chapter) {
+  return collectDisplayEquations(tree, chapter).filter(
     (equation) => equation.key != null,
   );
 }

package/dist/reference/figures-validate.d.ts

@@ -0,0 +1,21 @@
+import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } from './keyed-float-validate.js';
+
+/** `validateKeyedFloats` for `<Figure>` — see `keyed-float-validate.ts`. */
+
+type FigureDiagnosticCode = 'fig-invalid-key' | 'fig-duplicate-key' | 'fig-ref-resolves' | 'fig-key-unused';
+interface FigureDiagnostic {
+    readonly code: FigureDiagnosticCode;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly file?: string;
+    readonly lessonId?: string;
+    readonly key?: string;
+}
+type FigureLabelRecord = KeyedFloatLabelRecord;
+type FigureLessonInput = KeyedFloatLessonInput;
+interface FigureValidation extends KeyedFloatValidation {
+    readonly diagnostics: readonly FigureDiagnostic[];
+}
+declare function validateFigures(lessons: readonly FigureLessonInput[]): FigureValidation;
+
+export { type FigureDiagnostic, type FigureDiagnosticCode, type FigureLabelRecord, type FigureLessonInput, type FigureValidation, validateFigures };

package/dist/reference/figures-validate.js

@@ -0,0 +1,13 @@
+import {
+  validateKeyedFloats
+} from "./keyed-float-validate.js";
+function validateFigures(lessons) {
+  return validateKeyedFloats(lessons, {
+    tagName: "Figure",
+    prefix: "fig",
+    noun: "figure"
+  });
+}
+export {
+  validateFigures
+};

package/dist/reference/keyed-float-validate.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Keyed-float validation for `<Table>`/`<Figure>`, run inside
+ * `compileManifest()` — the same three checks `equations-validate.ts` runs
+ * for equations, parameterized over the float kind so the logic exists once:
+ *
+ * - `<prefix>-invalid-key` (error): an `id` must match the key grammar.
+ * - `<prefix>-duplicate-key` (error): an `id` is unique per lesson.
+ * - `<prefix>-ref-resolves` (error): every `[[<prefix>-key]]` /
+ *   `[[slug#<prefix>-key]]` points at a `<Table>`/`<Figure>` with that `id`.
+ * - `<prefix>-key-unused` (warning): a keyed float never referenced.
+ *
+ * `tables-validate.ts` and `figures-validate.ts` are thin wrappers over this
+ * so callers import `validateTables` / `validateFigures` with their own
+ * 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`. */
+    readonly tagName: string;
+    /** The `[[<prefix>-key]]` reference prefix, e.g. `tab` or `fig`. */
+    readonly prefix: string;
+    /** Lowercase noun used in diagnostic messages, e.g. `table` or `figure`. */
+    readonly noun: string;
+}
+interface KeyedFloatLabelRecord {
+    readonly key: string;
+    readonly number: string;
+    readonly lessonId: string;
+    readonly slug: string;
+    readonly section: number;
+    readonly indexInSection: number;
+}
+interface KeyedFloatRefRecord {
+    readonly key: string;
+    readonly lessonId: string;
+    /** Target lesson slug for a cross-page reference; `undefined` = same page. */
+    readonly targetSlug?: string;
+}
+interface KeyedFloatDiagnostic {
+    readonly code: string;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly file?: string;
+    readonly lessonId?: string;
+    readonly key?: string;
+}
+interface KeyedFloatValidation {
+    /** Every keyed float, sorted by lesson then appearance. */
+    readonly labels: readonly KeyedFloatLabelRecord[];
+    /** `slug -> { key -> number }` — the render path's cross-page lookup table. */
+    readonly numbersBySlug: Record<string, Record<string, string>>;
+    readonly diagnostics: readonly KeyedFloatDiagnostic[];
+}
+interface KeyedFloatLessonInput {
+    readonly lessonId: string;
+    readonly slug: string;
+    readonly file: string;
+    readonly body: string;
+    /**
+     * The lesson's 1-based ordinal in the course. When set, floats are numbered
+     * `‹chapter›.‹n›`; when omitted, the legacy `##`-section scheme.
+     */
+    readonly chapter?: number;
+}
+declare function validateKeyedFloats(lessons: readonly KeyedFloatLessonInput[], kind: KeyedFloatKind): KeyedFloatValidation;
+
+export { type KeyedFloatDiagnostic, type KeyedFloatKind, type KeyedFloatLabelRecord, type KeyedFloatLessonInput, type KeyedFloatRefRecord, type KeyedFloatValidation, validateKeyedFloats };

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,
+      chapter: lesson.chapter
+    })) {
+      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
+};