explico 0.2.0 → 0.3.0

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

@@ -0,0 +1,56 @@
+/** 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 `chapter` (the lesson's course ordinal) the number is `‹chapter›.‹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, chapter }: {
+    tagName: any;
+    chapter: any;
+}): {
+    key: string | null | undefined;
+    number: string;
+    section: number;
+    indexInSection: 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`. `chapter`
+ * is threaded the same way as in `scanKeyedJsxFloats`.
+ */
+export function collectKeyedJsxFloats(tree: any, { tagName, chapter }: {
+    tagName: any;
+    chapter: 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,167 @@
+/**
+ * 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 { 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 `chapter` (the lesson's course
+ * ordinal) the scheme is `‹chapter›.‹indexInLesson›` and `##` headings are
+ * ignored; without it, the legacy `##`-section scheme. Mirrors
+ * `displayEquationNumber` in `equations.mjs`.
+ */
+function keyedFloatNumber({ chapter, section, indexInSection, indexInLesson }) {
+  return chapter == null
+    ? floatNumber(section, indexInSection)
+    : `${chapter}.${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 `chapter` (the lesson's course ordinal) the number is `‹chapter›.‹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, chapter }) {
+  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({
+        chapter,
+        section,
+        indexInSection,
+        indexInLesson,
+      }),
+      section,
+      indexInSection,
+    });
+  }
+  return labels;
+}
+
+/**
+ * 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`. `chapter`
+ * is threaded the same way as in `scanKeyedJsxFloats`.
+ */
+export function collectKeyedJsxFloats(tree, { tagName, chapter }) {
+  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({
+          chapter,
+          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

@@ -5,7 +5,16 @@
  *   unknown?: 'error' | 'warn' | 'ignore',
  *   base?: string,
  *   equations?: Record<string, Record<string, string>>,
+ *   tables?: Record<string, Record<string, string>>,
+ *   figures?: Record<string, Record<string, string>>,
+ *   chapters?: Record<string, number>,
  * }} [options]
+ *
+ * `chapters` maps a lesson slug to its 1-based course ordinal. When the
+ * current page has one, every display equation / `<Table>` / `<Figure>` is
+ * numbered `‹chapter›.‹n›` (`##` headings ignored); with no entry the legacy
+ * `##`-section scheme applies. It must agree with `manifest.lessons[].chapter`,
+ * which is what feeds `equations`/`tables`/`figures` above.
  */
 export default function remarkNotation(options?: {
     definitions?: Map<string, object> | readonly object[] | Record<string, object> | (() => Map<string, object> | readonly object[] | Record<string, object>);
@@ -13,6 +22,9 @@ export default function remarkNotation(options?: {
     unknown?: "error" | "warn" | "ignore";
     base?: string;
     equations?: Record<string, Record<string, string>>;
+    tables?: Record<string, Record<string, string>>;
+    figures?: Record<string, Record<string, string>>;
+    chapters?: Record<string, number>;
 }): (tree: any, file: any) => void;
 /**
  * Remark adapter for semantic notation references.

package/dist/reference/remark-notation.mjs

@@ -42,6 +42,11 @@ import {
   parseEquationRef,
   stripEquationLabels,
 } from './equations.mjs';
+import {
+  collectKeyedJsxFloats,
+  keyedFloatAnchorId,
+  parseKeyedFloatRef,
+} from './keyed-jsx-floats.mjs';
 
 const PROSE_SKIP_TYPES = new Set([
   'code',
@@ -340,6 +345,8 @@ function equationNode(mathNode, { key, number }) {
             className: ['keyed-equation__number'],
             'data-eq-number': number,
             'aria-label': `Equation ${number}`,
+            // Plain hover tooltip — the number is a permalink to this equation.
+            title: 'Anchor to this equation',
           },
         },
       },
@@ -347,6 +354,32 @@ function equationNode(mathNode, { key, number }) {
   };
 }
 
+/**
+ * Give a `<Table>`/`<Figure>` `mdxJsxFlowElement` its computed `number` and
+ * `anchorId` as real JSX attributes, so the actual Astro component (which
+ * renders the numbered anchor, unlike `equationNode`'s synthesized hast div)
+ * receives them as props. The compiler is the single source of truth for
+ * both — the component only renders what it's given.
+ */
+function injectFloatNumberAttributes(node, float, prefix) {
+  const anchorId = keyedFloatAnchorId({
+    key: float.key,
+    number: float.number,
+    prefix,
+  });
+  node.attributes = (node.attributes ?? []).filter(
+    (attribute) =>
+      !(
+        attribute?.type === 'mdxJsxAttribute' &&
+        (attribute.name === 'number' || attribute.name === 'anchorId')
+      ),
+  );
+  node.attributes.push(
+    { type: 'mdxJsxAttribute', name: 'number', value: float.number },
+    { type: 'mdxJsxAttribute', name: 'anchorId', value: anchorId },
+  );
+}
+
 /** Resolve a `[[eq-key]]` / `[[slug#eq-key]]` reference to `{ number, href }`. */
 function resolveEquationRef(eqRef, eqCtx, file, node) {
   if (eqRef.lesson) {
@@ -374,7 +407,47 @@ function resolveEquationRef(eqRef, eqCtx, file, node) {
   return { number, href: `#eq-${eqRef.key}` };
 }
 
-function proseNodes(value, resolve, file, node, references, eqCtx) {
+/**
+ * Resolve a `[[<prefix>-key]]` / `[[slug#<prefix>-key]]` reference (a
+ * `<Table>`/`<Figure>` float) to `{ number, href }` — the table/figure
+ * equivalent of `resolveEquationRef`.
+ */
+function resolveKeyedFloatRef(floatRef, ctx, { prefix, tagName }, file, node) {
+  if (floatRef.lesson) {
+    const number = ctx.crossPage?.[floatRef.lesson]?.[floatRef.key];
+    if (number === undefined) {
+      fail(
+        file,
+        `Unknown ${tagName} reference [[${floatRef.lesson}#${prefix}-${floatRef.key}]]: lesson ${floatRef.lesson} has no <${tagName}> with id="${floatRef.key}".`,
+        node,
+      );
+    }
+    return {
+      number,
+      href: `${ctx.base.replace(/\/$/, '')}/${floatRef.lesson}/#${prefix}-${floatRef.key}`,
+    };
+  }
+  const number = ctx.pageLabels.get(floatRef.key);
+  if (number === undefined) {
+    fail(
+      file,
+      `Unknown ${tagName} reference [[${prefix}-${floatRef.key}]]: no <${tagName}> on this page carries id="${floatRef.key}".`,
+      node,
+    );
+  }
+  return { number, href: `#${prefix}-${floatRef.key}` };
+}
+
+function proseNodes(
+  value,
+  resolve,
+  file,
+  node,
+  references,
+  eqCtx,
+  tableCtx,
+  figureCtx,
+) {
   const base = eqCtx?.base ?? '';
   const strayExplain = firstUnescaped(value, EXPLAIN);
   if (strayExplain !== -1) {
@@ -395,7 +468,18 @@ function proseNodes(value, resolve, file, node, references, eqCtx) {
 
     const key = match[1].trim();
     const eqRef = eqCtx ? parseEquationRef(key) : undefined;
-    if (!eqRef && !NOTATION_KEY_PATTERN.test(key)) {
+    const tableRef =
+      !eqRef && tableCtx ? parseKeyedFloatRef(key, { prefix: 'tab' }) : undefined;
+    const figureRef =
+      !eqRef && !tableRef && figureCtx
+        ? parseKeyedFloatRef(key, { prefix: 'fig' })
+        : undefined;
+    if (
+      !eqRef &&
+      !tableRef &&
+      !figureRef &&
+      !NOTATION_KEY_PATTERN.test(key)
+    ) {
       fail(file, `Invalid notation key "${key}" in [[...]].`, node);
     }
 
@@ -426,9 +510,46 @@ function proseNodes(value, resolve, file, node, references, eqCtx) {
       continue;
     }
 
+    const floatRef = tableRef ?? figureRef;
+    if (floatRef) {
+      const kind = tableRef ? 'table' : 'figure';
+      const prefix = tableRef ? 'tab' : 'fig';
+      const tagName = tableRef ? 'Table' : 'Figure';
+      const { number, href } = resolveKeyedFloatRef(
+        floatRef,
+        tableRef ? tableCtx : figureCtx,
+        { prefix, tagName },
+        file,
+        node,
+      );
+      output.push({
+        type: 'link',
+        url: href,
+        children: [{ type: 'text', value: `${tagName} ${number}` }],
+        data: {
+          hProperties: {
+            className: [`${kind}-ref`],
+            [`data-${prefix}-ref`]: floatRef.key,
+            ...(floatRef.lesson ? { [`data-${prefix}-lesson`]: floatRef.lesson } : {}),
+          },
+        },
+      });
+      references.push({
+        key: floatRef.key,
+        kind,
+        ...(floatRef.lesson ? { lesson: floatRef.lesson } : {}),
+      });
+      cursor = match.index + match[0].length;
+      continue;
+    }
+
     const definition = resolve(key, 'prose', node);
-    const title = definition?.title ?? key;
-    const summary = definition?.summary;
+    // `title`/`summary` are the pre-C1b field names, kept as the first
+    // fallback for a caller still supplying them; real content authors
+    // `label`/`meaning` (see `content-config.ts`), which raw frontmatter
+    // (`manifest.notation.raw`, a page's own `notation.local`) carries as-is.
+    const title = definition?.title ?? definition?.label ?? key;
+    const summary = definition?.summary ?? definition?.meaning;
     const href = defaultHref(definition, key, base);
 
     const properties = {
@@ -557,7 +678,16 @@ function inspectExplainCalls(value, resolve, file, node, references) {
  *   unknown?: 'error' | 'warn' | 'ignore',
  *   base?: string,
  *   equations?: Record<string, Record<string, string>>,
+ *   tables?: Record<string, Record<string, string>>,
+ *   figures?: Record<string, Record<string, string>>,
+ *   chapters?: Record<string, number>,
  * }} [options]
+ *
+ * `chapters` maps a lesson slug to its 1-based course ordinal. When the
+ * current page has one, every display equation / `<Table>` / `<Figure>` is
+ * numbered `‹chapter›.‹n›` (`##` headings ignored); with no entry the legacy
+ * `##`-section scheme applies. It must agree with `manifest.lessons[].chapter`,
+ * which is what feeds `equations`/`tables`/`figures` above.
  */
 export default function remarkNotation(options = {}) {
   const unknown = options.unknown ?? 'error';
@@ -573,6 +703,10 @@ export default function remarkNotation(options = {}) {
     );
     const localDefinitions = localDefinitionsFromFile(file);
     const lessonId = lessonIdFrom(file);
+    // The lesson's course ordinal (see the `chapters` option). Falsy / missing
+    // ⇒ the legacy `##`-section numbering, so `0` and `undefined` behave alike.
+    const chapter =
+      (lessonId && options.chapters?.[lessonId.replace(/\./g, '/')]) || undefined;
     const registryFile = isNotationRegistryFile(file);
     const mathScope = pageGlyphScope(
       localDefinitions,
@@ -582,10 +716,10 @@ export default function remarkNotation(options = {}) {
     const references = [];
     const resolved = new Map();
 
-    // Equation identity (D7): assign every `\label{eq:…}` its section-scoped
-    // number before any math node is rewritten, so a `[[eq-key]]` earlier in
-    // the page still resolves.
-    const equationLabels = collectEquationLabels(tree);
+    // Equation identity (D7): assign every `\label{eq:…}` its number before any
+    // math node is rewritten, so a `[[eq-key]]` earlier in the page still
+    // resolves. `chapter` picks the `‹chapter›.‹n›` vs `##`-section scheme.
+    const equationLabels = collectEquationLabels(tree, chapter);
     const pageLabels = new Map();
     for (const label of equationLabels) {
       if (pageLabels.has(label.key)) {
@@ -606,11 +740,50 @@ export default function remarkNotation(options = {}) {
     // Number and anchor every display equation on a lesson page, keyed or
     // not (F3). Non-lesson pages (notation registry, stray docs) keep the
     // keyed-only behaviour so their body math is left untouched.
-    const displayEquations = lessonId ? collectDisplayEquations(tree) : [];
+    const displayEquations = lessonId
+      ? collectDisplayEquations(tree, chapter)
+      : [];
     const equationByNode = new Map(
       displayEquations.map((equation) => [equation.node, equation]),
     );
 
+    // Keyed floats (F-tables-figures): every `<Table>`/`<Figure>` on a lesson
+    // page is numbered and anchored, keyed or not — same rule as equations,
+    // via the shared engine in `keyed-jsx-floats.mjs`.
+    const makeFloatCtx = (tagName, crossPage) => {
+      const floats = lessonId
+        ? collectKeyedJsxFloats(tree, { tagName, chapter })
+        : [];
+      const pageFloatLabels = new Map();
+      for (const float of floats) {
+        if (float.key == null) continue;
+        if (pageFloatLabels.has(float.key)) {
+          fail(
+            file,
+            `Duplicate <${tagName} id="${float.key}"> on this page; an id is unique per lesson.`,
+            float.node,
+          );
+        }
+        pageFloatLabels.set(float.key, float.number);
+      }
+      return {
+        ctx: {
+          base: options.base ?? '',
+          pageLabels: pageFloatLabels,
+          crossPage: crossPage ?? {},
+        },
+        byNode: new Map(floats.map((float) => [float.node, float])),
+      };
+    };
+    const { ctx: tableCtx, byNode: tableByNode } = makeFloatCtx(
+      'Table',
+      options.tables,
+    );
+    const { ctx: figureCtx, byNode: figureByNode } = makeFloatCtx(
+      'Figure',
+      options.figures,
+    );
+
     const resolve = (key, kind, node) => {
       const context = {
         file,
@@ -729,6 +902,8 @@ export default function remarkNotation(options = {}) {
             child,
             references,
             eqCtx,
+            tableCtx,
+            figureCtx,
           );
           if (replacement) {
             node.children.splice(index, 1, ...replacement);
@@ -739,6 +914,10 @@ export default function remarkNotation(options = {}) {
         visit(child, false);
         if (child && child.type === 'math' && equationByNode.has(child)) {
           node.children[index] = equationNode(child, equationByNode.get(child));
+        } else if (child?.type === 'mdxJsxFlowElement' && tableByNode.has(child)) {
+          injectFloatNumberAttributes(child, tableByNode.get(child), 'tab');
+        } else if (child?.type === 'mdxJsxFlowElement' && figureByNode.has(child)) {
+          injectFloatNumberAttributes(child, figureByNode.get(child), 'fig');
         }
       }
     };
@@ -755,5 +934,16 @@ export default function remarkNotation(options = {}) {
         indexInSection,
       }),
     );
+    const floatLabelData = (byNode) =>
+      [...byNode.values()]
+        .filter((float) => float.key != null)
+        .map(({ key, number, section, indexInSection }) => ({
+          key,
+          number,
+          section,
+          indexInSection,
+        }));
+    file.data.tableLabels = floatLabelData(tableByNode);
+    file.data.figureLabels = floatLabelData(figureByNode);
   };
 }

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

@@ -0,0 +1,21 @@
+import { KeyedFloatLabelRecord, KeyedFloatLessonInput, KeyedFloatValidation } from './keyed-float-validate.js';
+
+/** `validateKeyedFloats` for `<Table>` — see `keyed-float-validate.ts`. */
+
+type TableDiagnosticCode = 'tab-invalid-key' | 'tab-duplicate-key' | 'tab-ref-resolves' | 'tab-key-unused';
+interface TableDiagnostic {
+    readonly code: TableDiagnosticCode;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly file?: string;
+    readonly lessonId?: string;
+    readonly key?: string;
+}
+type TableLabelRecord = KeyedFloatLabelRecord;
+type TableLessonInput = KeyedFloatLessonInput;
+interface TableValidation extends KeyedFloatValidation {
+    readonly diagnostics: readonly TableDiagnostic[];
+}
+declare function validateTables(lessons: readonly TableLessonInput[]): TableValidation;
+
+export { type TableDiagnostic, type TableDiagnosticCode, type TableLabelRecord, type TableLessonInput, type TableValidation, validateTables };