explico 0.2.0 → 0.4.0

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,16 @@ interface EquationLessonInput {
     readonly slug: string;
     readonly file: string;
     readonly body: string;
+    /**
+     * `{ prefix, offset }` — the part's 1-based ordinal among the sidebar groups,
+     * and how many display equations earlier lessons of that part already used.
+     * When set, equations are numbered `‹part›.‹offset + n›`; when omitted, the
+     * legacy `##`-section scheme. See `docs/authoring/structure.md`.
+     */
+    readonly numbering?: {
+        readonly prefix: number;
+        readonly offset: 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.numbering)) {
       if (seen.has(raw.key)) {
         diagnostics.push({
           code: "eq-duplicate-key",

package/dist/reference/equations.d.mts

@@ -8,31 +8,89 @@ 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;
+/**
+ * Normalise the numbering input to `{ prefix, offset }`.
+ *
+ * `prefix` is the number before the dot — the **part**'s ordinal (its position
+ * among the sidebar groups). `offset` is how many display equations already
+ * appeared in earlier lessons of that same part, so `n` runs continuously
+ * across a part instead of restarting on every page. A bare number is the
+ * legacy per-lesson form (`prefix = n`, `offset = 0`) and is still accepted so
+ * hand-built trees and unit tests keep working. `undefined`/`null`/`0` ⇒ the
+ * `##`-section fallback for non-lesson pages.
+ */
+export function resolveNumbering(input: any): {
+    prefix: any;
+    offset: number;
+};
+/**
+ * The visible number for one display equation. With a `prefix` (the part's
+ * ordinal) the scheme is `‹part›.‹offset + indexInLesson›` and `##` headings
+ * are ignored; without it, the legacy `##`-section scheme.
+ */
+export function displayEquationNumber({ prefix, offset, section, indexInSection, indexInLesson, }: {
+    prefix: any;
+    offset?: number | undefined;
+    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;
 /**
- * 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.
+ * 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 scanEquationLabels(markdown: any): {
-    key: string;
+export function stripJsxComponents(markdown: any, keep: any): string;
+/**
+ * Every display equation in a Markdown body, keyed or not, in appearance order
+ * with its assigned number. `$$…$$` blocks only. With `numbering`
+ * (`{ prefix, offset }`, the part's ordinal and the count of display equations
+ * in earlier lessons of that part) the number is `‹part›.‹offset + 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 scanDisplayEquations(markdown: any, numbering: any): {
+    key: string | null | undefined;
+    number: string;
+    section: number;
+    indexInSection: number;
+}[];
+/** The keyed subset of `scanDisplayEquations` — the manifest builder's view. */
+export function scanEquationLabels(markdown: any, numbering: any): {
+    key: string | null | undefined;
     number: string;
     section: number;
     indexInSection: number;
 }[];
+/**
+ * How many display equations a lesson body holds. This is what makes `n` run
+ * continuously across a part: a lesson's `offset` is the sum of this over every
+ * earlier lesson in the same part.
+ */
+export function countDisplayEquations(markdown: any): number;
 /**
  * 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`. `numbering` is threaded the
+ * same way as in `scanEquationLabels`.
  */
-export function collectDisplayEquations(tree: any): {
+export function collectDisplayEquations(tree: any, numbering: any): {
     key: string | null;
     number: string;
     section: number;
@@ -43,7 +101,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, numbering: any): {
     key: string | null;
     number: string;
     section: number;
@@ -53,9 +111,18 @@ 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 `numbering`
+ * (`{ prefix, offset }` — see `resolveNumbering`), the number is
+ * `‹part›.‹offset + n›`: the prefix is the **part**'s ordinal among the sidebar
+ * groups, `n` counts every display equation in the lesson, and `offset` carries
+ * the count from earlier lessons of the same part so the sequence runs
+ * continuously across a part rather than restarting on every page. `##` and
+ * `###` headings never affect it — `(2.4)` is the fourth display equation of
+ * part 2, wherever in that part it sits. See `docs/authoring/structure.md` for
+ * the level names. With no `numbering` 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,18 @@
 /**
  * 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 `numbering`
+ * (`{ prefix, offset }` — see `resolveNumbering`), the number is
+ * `‹part›.‹offset + n›`: the prefix is the **part**'s ordinal among the sidebar
+ * groups, `n` counts every display equation in the lesson, and `offset` carries
+ * the count from earlier lessons of the same part so the sequence runs
+ * continuously across a part rather than restarting on every page. `##` and
+ * `###` headings never affect it — `(2.4)` is the fourth display equation of
+ * part 2, wherever in that part it sits. See `docs/authoring/structure.md` for
+ * the level names. With no `numbering` 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 +67,51 @@ function equationNumber(section, index) {
   return section > 0 ? `${section}.${index}` : String(index);
 }
 
+/**
+ * Normalise the numbering input to `{ prefix, offset }`.
+ *
+ * `prefix` is the number before the dot — the **part**'s ordinal (its position
+ * among the sidebar groups). `offset` is how many display equations already
+ * appeared in earlier lessons of that same part, so `n` runs continuously
+ * across a part instead of restarting on every page. A bare number is the
+ * legacy per-lesson form (`prefix = n`, `offset = 0`) and is still accepted so
+ * hand-built trees and unit tests keep working. `undefined`/`null`/`0` ⇒ the
+ * `##`-section fallback for non-lesson pages.
+ */
+export function resolveNumbering(input) {
+  if (input == null) return { prefix: undefined, offset: 0 };
+  if (typeof input === 'number') {
+    return { prefix: input || undefined, offset: 0 };
+  }
+  return {
+    prefix: input.prefix || undefined,
+    offset: Number(input.offset) || 0,
+  };
+}
+
+/**
+ * The visible number for one display equation. With a `prefix` (the part's
+ * ordinal) the scheme is `‹part›.‹offset + indexInLesson›` and `##` headings
+ * are ignored; without it, the legacy `##`-section scheme.
+ */
+export function displayEquationNumber({
+  prefix,
+  offset = 0,
+  section,
+  indexInSection,
+  indexInLesson,
+}) {
+  return prefix == null
+    ? equationNumber(section, indexInSection)
+    : `${prefix}.${offset + 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 +124,31 @@ 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.
+ * Every display equation in a Markdown body, keyed or not, in appearance order
+ * with its assigned number. `$$…$$` blocks only. With `numbering`
+ * (`{ prefix, offset }`, the part's ordinal and the count of display equations
+ * in earlier lessons of that part) the number is `‹part›.‹offset + 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 scanDisplayEquations(markdown, numbering) {
+  const { prefix, offset } = resolveNumbering(numbering);
   const text = stripJsxComponents(stripFencedCode(markdown));
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
@@ -113,6 +170,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 +178,16 @@ export function scanEquationLabels(markdown) {
       continue;
     }
     indexInSection += 1;
-    if (token.key == null) continue;
+    indexInLesson += 1;
     labels.push({
       key: token.key,
-      number: equationNumber(section, indexInSection),
+      number: displayEquationNumber({
+        prefix,
+        offset,
+        section,
+        indexInSection,
+        indexInLesson,
+      }),
       section,
       indexInSection,
     });
@@ -131,16 +195,35 @@ export function scanEquationLabels(markdown) {
   return labels;
 }
 
+/** The keyed subset of `scanDisplayEquations` — the manifest builder's view. */
+export function scanEquationLabels(markdown, numbering) {
+  return scanDisplayEquations(markdown, numbering).filter(
+    (equation) => equation.key != null,
+  );
+}
+
+/**
+ * How many display equations a lesson body holds. This is what makes `n` run
+ * continuously across a part: a lesson's `offset` is the sum of this over every
+ * earlier lesson in the same part.
+ */
+export function countDisplayEquations(markdown) {
+  return scanDisplayEquations(markdown).length;
+}
+
 /**
  * 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`. `numbering` is threaded the
+ * same way as in `scanEquationLabels`.
  */
-export function collectDisplayEquations(tree) {
+export function collectDisplayEquations(tree, numbering) {
+  const { prefix, offset } = resolveNumbering(numbering);
   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 +238,18 @@ 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({
+          prefix,
+          offset,
+          section,
+          indexInSection,
+          indexInLesson,
+        }),
         section,
         indexInSection,
         node,
@@ -173,8 +263,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, numbering) {
+  return collectDisplayEquations(tree, numbering).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,73 @@
+/**
+ * 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;
+    /**
+     * `{ 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>`.
+     */
+    readonly numbering?: {
+        readonly prefix: number;
+        readonly offset: number;
+    };
+}
+declare function validateKeyedFloats(lessons: readonly KeyedFloatLessonInput[], kind: KeyedFloatKind): KeyedFloatValidation;
+
+export { type KeyedFloatDiagnostic, type KeyedFloatKind, type KeyedFloatLabelRecord, type KeyedFloatLessonInput, type KeyedFloatRefRecord, type KeyedFloatValidation, validateKeyedFloats };