explico 0.2.0 → 0.4.0

package/src/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/src/reference/figures-validate.ts

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

package/src/reference/keyed-float-validate.ts

@@ -0,0 +1,210 @@
+/**
+ * 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.
+ */
+
+import {
+  KEYED_FLOAT_KEY_PATTERN,
+  parseKeyedFloatRef,
+  scanKeyedJsxFloats,
+} from './keyed-jsx-floats.mjs';
+
+export 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;
+}
+
+export interface KeyedFloatLabelRecord {
+  readonly key: string;
+  readonly number: string;
+  readonly lessonId: string;
+  readonly slug: string;
+  readonly section: number;
+  readonly indexInSection: number;
+}
+
+export interface KeyedFloatRefRecord {
+  readonly key: string;
+  readonly lessonId: string;
+  /** Target lesson slug for a cross-page reference; `undefined` = same page. */
+  readonly targetSlug?: string;
+}
+
+export interface KeyedFloatDiagnostic {
+  readonly code: string;
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+  readonly file?: string;
+  readonly lessonId?: string;
+  readonly key?: string;
+}
+
+export 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[];
+}
+
+export 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 };
+}
+
+const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
+
+function stripCode(text: string): string {
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/~~~[\s\S]*?~~~/g, ' ')
+    .replace(/`[^`\n]*`/g, ' ');
+}
+
+function bodyFloatRefs(
+  lesson: KeyedFloatLessonInput,
+  prefix: string,
+): KeyedFloatRefRecord[] {
+  const refs: KeyedFloatRefRecord[] = [];
+  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;
+}
+
+export function validateKeyedFloats(
+  lessons: readonly KeyedFloatLessonInput[],
+  kind: KeyedFloatKind,
+): KeyedFloatValidation {
+  const { tagName, prefix, noun } = kind;
+  const labels: KeyedFloatLabelRecord[] = [];
+  const diagnostics: KeyedFloatDiagnostic[] = [];
+  const numbersBySlug: Record<string, Record<string, string>> = {};
+
+  for (const lesson of [...lessons].sort((a, b) =>
+    a.lessonId.localeCompare(b.lessonId),
+  )) {
+    const seen = new Set<string>();
+    const table: Record<string, string> = {};
+    for (const raw of scanKeyedJsxFloats(lesson.body, {
+      tagName,
+      numbering: lesson.numbering,
+    }) as {
+      key: string | null;
+      number: string;
+      section: number;
+      indexInSection: number;
+    }[]) {
+      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 — 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 = new Set<string>();
+  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 === undefined) {
+        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 };
+}

package/src/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;
+}
+