explico 0.4.0 → 0.5.0

package/src/reference/remark-notation.mjs

@@ -33,7 +33,11 @@
 
 export const NOTATION_KEY_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
 
-import { GlyphResolutionError, resolveMathGlyphs } from './math-glyphs.mjs';
+import {
+  GlyphResolutionError,
+  resolveMathGlyphs,
+  stripNotationMarkers,
+} from './math-glyphs.mjs';
 import {
   EQ_LABEL_PATTERN,
   collectDisplayEquations,
@@ -47,6 +51,12 @@ import {
   keyedFloatAnchorId,
   parseKeyedFloatRef,
 } from './keyed-jsx-floats.mjs';
+import { collectRawFloats } from './raw-floats.mjs';
+import {
+  knowledgeCheckAnchorId,
+  parseKnowledgeCheckRef,
+} from './knowledge-checks.mjs';
+import { injectMdxStringAttributes } from './mdx-attributes.mjs';
 
 const PROSE_SKIP_TYPES = new Set([
   'code',
@@ -313,13 +323,58 @@ function defaultHref(definition, key, base = '') {
   return `${base.replace(/\/$/, '')}/glossary/#notation-${key}`;
 }
 
+/** A non-mdast hast element (a `<div>`, `<button>`, `<svg>`, …) built through
+ *  the same `data.hName`/`hProperties` override `equationNode` already uses
+ *  for its own wrapper — mdast-to-hast renders exactly what these say
+ *  regardless of the carrier node's own `type`. */
+function el(hName, hProperties, children = []) {
+  return { type: 'paragraph', data: { hName, hProperties }, children };
+}
+
+/** Feather/Lucide's "copy" glyph (two overlapping rounded rects), matching
+ *  the stroke-icon-button style `LessonExportActions.astro` already uses for
+ *  lesson-level actions. */
+function copyIconNode() {
+  return el('svg', { viewBox: '0 0 24 24', 'aria-hidden': 'true' }, [
+    el('rect', { x: '9', y: '9', width: '10', height: '10', rx: '1' }),
+    el('path', {
+      d: 'M6 15H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2v1',
+    }),
+  ]);
+}
+
+/**
+ * Wrap an inline `$…$` `math` node in an inert `<span data-latex>` so a
+ * reader can trigger the same "click an unexplained part to copy" gesture
+ * a display equation gets (`KeyedFloatEnhancer.astro`), without a
+ * `.keyed-equation` block's room for a dedicated button — a persistent
+ * button here would break the reading line (see `global.css`, which gives
+ * this wrapper no visible styling of its own). `mathNode.value` is read
+ * after the resolver above has already bound the page's glyphs into it, same
+ * as `equationNode` below.
+ */
+function inlineEquationNode(mathNode) {
+  const latex = stripNotationMarkers(String(mathNode.value ?? ''));
+  return el('span', { className: ['inline-equation'], 'data-latex': latex }, [
+    mathNode,
+  ]);
+}
+
 /**
  * Wrap a display `$$…$$` `math` node so the container survives `rehype-katex`
  * (which splices the inner `math-display` element out). Every display equation
  * in a lesson is numbered; a keyed one anchors at `#eq-<key>`, an unkeyed one
  * at its positional `#eq-<section>-<index>`. The visible number is a focusable
  * `<a>` sibling — never authored, never inside KaTeX — so it survives print and
- * screen readers name it "Equation 2.4".
+ * screen readers name it "Equation 2.4". A "Copy LaTeX" button sits beside it
+ * (`.keyed-equation__controls`, styled in `global.css`) — the equation's own
+ * copy affordance, distinct from the notation popup card's (`NotationLayer.astro`),
+ * which only exists for a symbol with a registry entry, not a bare display
+ * equation. `mathNode.value` is read here — after the resolver above has
+ * already bound the page's glyphs into it (`replaceMathSource`) — so an
+ * auto-bound symbol's `\explain{…}` marker gets stripped same as an
+ * author-written one; either way the reader copies plain LaTeX, never this
+ * system's own notation-key plumbing (`math-glyphs.mjs:stripNotationMarkers`).
  */
 function equationNode(mathNode, { key, number }) {
   const id = equationAnchorId({ key, number });
@@ -331,31 +386,47 @@ function equationNode(mathNode, { key, number }) {
   if (key) hProperties['data-eq-key'] = key;
   else hProperties['data-eq-auto'] = '';
 
+  const latex = stripNotationMarkers(String(mathNode.value ?? ''));
+
   return {
     type: 'paragraph',
     data: { hName: 'div', hProperties },
     children: [
       mathNode,
-      {
-        type: 'link',
-        url: `#${id}`,
-        children: [{ type: 'text', value: `(${number})` }],
-        data: {
-          hProperties: {
-            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',
+      el('div', { className: ['keyed-equation__controls'] }, [
+        {
+          type: 'link',
+          url: `#${id}`,
+          children: [{ type: 'text', value: `(${number})` }],
+          data: {
+            hProperties: {
+              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',
+            },
           },
         },
-      },
+        el(
+          'button',
+          {
+            type: 'button',
+            className: ['keyed-equation__copy'],
+            'data-eq-copy': '',
+            'data-latex': latex,
+            'aria-label': `Copy LaTeX for Equation ${number}`,
+            title: 'Copy LaTeX',
+          },
+          [copyIconNode()],
+        ),
+      ]),
     ],
   };
 }
 
 /**
- * Give a `<Table>`/`<Figure>` `mdxJsxFlowElement` its computed `number` and
+ * Give a `<Table>`/`<Figure>`/`<Diagram>` `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
@@ -367,17 +438,10 @@ function injectFloatNumberAttributes(node, float, prefix) {
     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 },
-  );
+  injectMdxStringAttributes(node, {
+    number: float.number,
+    anchorId,
+  });
 }
 
 /** Resolve a `[[eq-key]]` / `[[slug#eq-key]]` reference to `{ number, href }`. */
@@ -409,7 +473,7 @@ function resolveEquationRef(eqRef, eqCtx, file, node) {
 
 /**
  * Resolve a `[[<prefix>-key]]` / `[[slug#<prefix>-key]]` reference (a
- * `<Table>`/`<Figure>` float) to `{ number, href }` — the table/figure
+ * `<Table>`/`<Figure>`/`<Diagram>` float) to `{ number, href }` — the keyed-float
  * equivalent of `resolveEquationRef`.
  */
 function resolveKeyedFloatRef(floatRef, ctx, { prefix, tagName }, file, node) {
@@ -438,6 +502,33 @@ function resolveKeyedFloatRef(floatRef, ctx, { prefix, tagName }, file, node) {
   return { number, href: `#${prefix}-${floatRef.key}` };
 }
 
+/** Resolve a numbered knowledge check declared by a lesson's `.checks.yml`. */
+function resolveKnowledgeCheckRef(checkRef, ctx, file, node) {
+  if (checkRef.lesson) {
+    const number = ctx.crossPage?.[checkRef.lesson]?.[checkRef.key];
+    if (number === undefined) {
+      fail(
+        file,
+        `Unknown knowledge-check reference [[${checkRef.lesson}#check-${checkRef.key}]]: that lesson's .checks.yml does not list "${checkRef.key}".`,
+        node,
+      );
+    }
+    return {
+      number,
+      href: `${ctx.base.replace(/\/$/, '')}/${checkRef.lesson}/#${knowledgeCheckAnchorId(checkRef.key)}`,
+    };
+  }
+  const number = ctx.pageLabels.get(checkRef.key);
+  if (number === undefined) {
+    fail(
+      file,
+      `Unknown knowledge-check reference [[check-${checkRef.key}]]: this lesson's .checks.yml does not list "${checkRef.key}".`,
+      node,
+    );
+  }
+  return { number, href: `#${knowledgeCheckAnchorId(checkRef.key)}` };
+}
+
 function proseNodes(
   value,
   resolve,
@@ -447,6 +538,8 @@ function proseNodes(
   eqCtx,
   tableCtx,
   figureCtx,
+  diagramCtx,
+  checkCtx,
 ) {
   const base = eqCtx?.base ?? '';
   const strayExplain = firstUnescaped(value, EXPLAIN);
@@ -474,10 +567,20 @@ function proseNodes(
       !eqRef && !tableRef && figureCtx
         ? parseKeyedFloatRef(key, { prefix: 'fig' })
         : undefined;
+    const diagramRef =
+      !eqRef && !tableRef && !figureRef && diagramCtx
+        ? parseKeyedFloatRef(key, { prefix: 'dia' })
+        : undefined;
+    const checkRef =
+      !eqRef && !tableRef && !figureRef && !diagramRef && checkCtx
+        ? parseKnowledgeCheckRef(key)
+        : undefined;
     if (
       !eqRef &&
       !tableRef &&
       !figureRef &&
+      !diagramRef &&
+      !checkRef &&
       !NOTATION_KEY_PATTERN.test(key)
     ) {
       fail(file, `Invalid notation key "${key}" in [[...]].`, node);
@@ -510,14 +613,44 @@ function proseNodes(
       continue;
     }
 
-    const floatRef = tableRef ?? figureRef;
+    if (checkRef) {
+      const { number, href } = resolveKnowledgeCheckRef(
+        checkRef,
+        checkCtx,
+        file,
+        node,
+      );
+      output.push({
+        type: 'link',
+        url: href,
+        children: [{ type: 'text', value: `Knowledge check ${number}` }],
+        data: {
+          hProperties: {
+            className: ['knowledge-check-ref'],
+            'data-check-ref': checkRef.key,
+            ...(checkRef.lesson
+              ? { 'data-check-lesson': checkRef.lesson }
+              : {}),
+          },
+        },
+      });
+      references.push({
+        key: checkRef.key,
+        kind: 'knowledge-check',
+        ...(checkRef.lesson ? { lesson: checkRef.lesson } : {}),
+      });
+      cursor = match.index + match[0].length;
+      continue;
+    }
+
+    const floatRef = tableRef ?? figureRef ?? diagramRef;
     if (floatRef) {
-      const kind = tableRef ? 'table' : 'figure';
-      const prefix = tableRef ? 'tab' : 'fig';
-      const tagName = tableRef ? 'Table' : 'Figure';
+      const kind = tableRef ? 'table' : figureRef ? 'figure' : 'diagram';
+      const prefix = tableRef ? 'tab' : figureRef ? 'fig' : 'dia';
+      const tagName = tableRef ? 'Table' : figureRef ? 'Figure' : 'Diagram';
       const { number, href } = resolveKeyedFloatRef(
         floatRef,
-        tableRef ? tableCtx : figureCtx,
+        tableRef ? tableCtx : figureRef ? figureCtx : diagramCtx,
         { prefix, tagName },
         file,
         node,
@@ -676,14 +809,16 @@ function inspectExplainCalls(value, resolve, file, node, references) {
  *
  * Every number on a page comes from two places that MUST agree: the page's own
  * counters (`numbering`) and the manifest tables a cross-page `[[slug#eq-key]]`
- * is resolved against (`equations` / `tables` / `figures`). Deriving all four
- * from the same manifest in one step is what stops a course config from
+ * is resolved against (`equations` / `tables` / `figures` / `diagrams` /
+ * `checks`).
+ * Deriving every input from the same manifest in one step stops a course config from
  * supplying one without the other — the omission that produced page-local
  * `(2.2)` and cross-page `(4.5)` for the same equation.
  *
- * `numbering` maps a lesson slug to `{ part, equations, tables, figures }`:
- * the part's ordinal (the number before the dot) and, per kind of float, how
- * many of them the earlier lessons of that part already used.
+ * `numbering` maps a lesson slug to
+ * `{ part, equations, tables, figures, diagrams, checks }`: the part's ordinal
+ * (the number before the dot) and, per numbered kind, how many earlier lessons
+ * of that part already used.
  */
 export function numberingFromManifest(manifest) {
   if (!manifest || typeof manifest !== 'object') return {};
@@ -691,6 +826,8 @@ export function numberingFromManifest(manifest) {
     equations: manifest.equations?.numbersBySlug ?? {},
     tables: manifest.tables?.numbersBySlug ?? {},
     figures: manifest.figures?.numbersBySlug ?? {},
+    diagrams: manifest.diagrams?.numbersBySlug ?? {},
+    checks: manifest.checks?.numbersBySlug ?? {},
     numbering: Object.fromEntries(
       (manifest.lessons ?? []).map((lesson) => [
         lesson.slug,
@@ -699,12 +836,44 @@ export function numberingFromManifest(manifest) {
           equations: lesson.numbering?.equations ?? 0,
           tables: lesson.numbering?.tables ?? 0,
           figures: lesson.numbering?.figures ?? 0,
+          diagrams: lesson.numbering?.diagrams ?? 0,
+          checks: lesson.numbering?.checks ?? 0,
         },
       ]),
     ),
   };
 }
 
+/**
+ * The options object `remarkNotation` needs for one manifest, in one call.
+ *
+ * A consumer used to hand-assemble `definitions`, `equations`, `tables`,
+ * `figures`, and `chapters` separately — easy to do partially, which is how a
+ * page ends up numbered under the legacy `##`-section scheme while the
+ * manifest (and every cross-page reference to that page) uses the part
+ * scheme. This does not return that literal four-map-plus-chapters shape:
+ * `chapters` is the superseded per-lesson form (see `pageNumbering` below),
+ * and passing `manifest` through already makes `numberingFromManifest()`
+ * derive `numbering` plus every `equations`/`tables`/`figures`/`diagrams`/
+ * `checks` map from the same source in one step — strictly more correct than
+ * reconstructing `chapters` by hand.
+ *
+ * `overrides` is spread last, so a caller can add `strict`, `unknown`,
+ * `resolve`, `base`, or override anything above:
+ *
+ *   [remarkNotation, createRemarkNotationOptions(manifest, { strict: true })]
+ *
+ * @param {object} manifest - a compiled Explico manifest (`compileManifest()`).
+ * @param {object} [overrides] - additional/overriding `remarkNotation` options.
+ */
+export function createRemarkNotationOptions(manifest, overrides = {}) {
+  return {
+    definitions: manifest?.notation?.raw ?? [],
+    manifest,
+    ...overrides,
+  };
+}
+
 /**
  * `{ prefix, offset }` for one kind of float on one page, from whichever
  * numbering option the caller supplied. `numbering` is the current form;
@@ -773,31 +942,71 @@ function assertManifestNumberParity({
   }
 }
 
+/**
+ * Strict-mode guard: a catalogued lesson (one `remarkNotation` is told the
+ * slug of) that contains at least one equation/`<Table>`/`<Figure>` — keyed or
+ * not — must have both a `numbering` placement and a cross-page number table
+ * entry. Without this, `assertManifestNumberParity` above only ever catches a
+ * missing/wrong map for *keyed* items (it walks `pageLabels`, which unkeyed
+ * equations/floats never enter — see `keyed-jsx-floats.mjs`), so a lesson
+ * whose only floats are unkeyed can silently fall back to `##`-section
+ * numbering with no diagnostic at all. `Diagram` is deliberately excluded by
+ * every caller: `Diagram.astro` already tolerates an unplaced diagram
+ * rendering without a number, by design.
+ */
+function assertStrictNumbering({ file, slug, noun, count, placement, crossPage }) {
+  if (!slug || count === 0) return;
+  const plural = count === 1 ? '' : 's';
+  if (placement === undefined) {
+    fail(
+      file,
+      `Strict mode: ${slug} has ${count} ${noun}${plural} but remarkNotation ` +
+        `has no \`numbering\` entry for this lesson, so it would silently ` +
+        `fall back to the legacy ##-section numbering. Pass \`manifest\` ` +
+        `(e.g. via createRemarkNotationOptions) or add a \`numbering\` entry ` +
+        `for "${slug}".`,
+    );
+    return;
+  }
+  if (crossPage?.[slug] === undefined) {
+    fail(
+      file,
+      `Strict mode: ${slug} has ${count} ${noun}${plural} but remarkNotation ` +
+        `has no cross-page ${noun} number table entry for this lesson. Pass ` +
+        `\`manifest\` (e.g. via createRemarkNotationOptions) so every ` +
+        `catalogued lesson is covered.`,
+    );
+  }
+}
+
 /**
  * @param {{
  *   definitions?: Map<string, object> | readonly object[] | Record<string, object> | (() => Map<string, object> | readonly object[] | Record<string, object>),
  *   resolve?: (key: string, context: object) => object | undefined,
  *   unknown?: 'error' | 'warn' | 'ignore',
+ *   strict?: boolean,
  *   base?: string,
  *   manifest?: object,
  *   equations?: Record<string, Record<string, string>>,
  *   tables?: Record<string, Record<string, string>>,
  *   figures?: Record<string, Record<string, string>>,
- *   numbering?: Record<string, { part: number, equations: number, tables: number, figures: number }>,
+ *   diagrams?: Record<string, Record<string, string>>,
+ *   checks?: Record<string, Record<string, string>>,
+ *   numbering?: Record<string, { part: number, equations: number, tables: number, figures: number, diagrams: number, checks: number }>,
  *   chapters?: Record<string, number>,
  * }} [options]
  *
- * `manifest` is the preferred wiring: pass the compiled manifest and the four
+ * `manifest` is the preferred wiring: pass the compiled manifest and all
  * numbering inputs below are read off it together, so they cannot drift apart.
  * They stay available individually for hand-built trees, and an explicitly
  * supplied one still wins over the manifest.
  *
  * `numbering` maps a lesson slug to its **part** (the number before the dot)
  * and, per kind of float, how many the earlier lessons of that part already
- * used. Every display equation / `<Table>` / `<Figure>` on the page is then
+ * used. Every display equation / `<Table>` / `<Figure>` / `<Diagram>` on the page is then
  * numbered `‹part›.‹offset + n›`, with `##` and `###` headings ignored; with no
  * entry the legacy `##`-section scheme applies. It must agree with
- * `manifest.lessons[]`, which is what feeds `equations`/`tables`/`figures`
+ * `manifest.lessons[]`, which is what feeds `equations`/`tables`/`figures`/`diagrams`
  * above — supplying the tables without `numbering` numbers the same equation
  * twice, and `assertManifestNumberParity` turns that into a build error rather
  * than a page whose references disagree with their targets.
@@ -805,9 +1014,18 @@ function assertManifestNumberParity({
  * `chapters` is the superseded per-lesson form (slug → the lesson's course
  * ordinal, no running offset). Still read when `numbering` has no entry, so a
  * config written against the old option keeps building.
+ *
+ * `strict` (default `false`) additionally fails the build when a catalogued
+ * lesson contains an equation/`<Table>`/`<Figure>` — keyed or not — but has no
+ * `numbering` placement or no cross-page number table entry, instead of
+ * silently rendering it under the legacy `##`-section scheme. Off by default
+ * for backward compatibility; `createRemarkNotationOptions(manifest, { strict:
+ * true })` is the recommended way to turn it on for a course whose manifest
+ * covers every catalogued lesson.
  */
 export default function remarkNotation(options = {}) {
   const unknown = options.unknown ?? 'error';
+  const strict = options.strict ?? false;
   // The manifest supplies every numbering input at once; an explicit option
   // still overrides it, so existing per-field wiring keeps working.
   const numbering = { ...numberingFromManifest(options.manifest), ...options };
@@ -878,8 +1096,18 @@ export default function remarkNotation(options = {}) {
     const equationByNode = new Map(
       displayEquations.map((equation) => [equation.node, equation]),
     );
+    if (strict) {
+      assertStrictNumbering({
+        file,
+        slug: lessonSlug,
+        noun: 'equation',
+        count: displayEquations.length,
+        placement: equationNumbering,
+        crossPage: numbering.equations,
+      });
+    }
 
-    // Keyed floats (F-tables-figures): every `<Table>`/`<Figure>` on a lesson
+    // Keyed floats: every `<Table>`/`<Figure>`/`<Diagram>` 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, kind) => {
@@ -908,6 +1136,17 @@ export default function remarkNotation(options = {}) {
         noun: tagName,
         syntax: (key) => `<${tagName} id="${key}">`,
       });
+      // Diagram is deliberately excluded — see `assertStrictNumbering`'s doc.
+      if (strict && tagName !== 'Diagram') {
+        assertStrictNumbering({
+          file,
+          slug: lessonSlug,
+          noun: tagName,
+          count: floats.length,
+          placement: floatNumbering,
+          crossPage,
+        });
+      }
       return {
         ctx: {
           base: options.base ?? '',
@@ -927,6 +1166,18 @@ export default function remarkNotation(options = {}) {
       numbering.figures,
       'figures',
     );
+    const { ctx: diagramCtx, byNode: diagramByNode } = makeFloatCtx(
+      'Diagram',
+      numbering.diagrams,
+      'diagrams',
+    );
+    const checkCtx = {
+      base: options.base ?? '',
+      pageLabels: new Map(
+        Object.entries(numbering.checks?.[lessonSlug] ?? {}),
+      ),
+      crossPage: numbering.checks ?? {},
+    };
 
     const resolve = (key, kind, node) => {
       const context = {
@@ -1048,6 +1299,8 @@ export default function remarkNotation(options = {}) {
             eqCtx,
             tableCtx,
             figureCtx,
+            diagramCtx,
+            checkCtx,
           );
           if (replacement) {
             node.children.splice(index, 1, ...replacement);
@@ -1058,14 +1311,72 @@ 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 (lessonId && child?.type === 'inlineMath') {
+          // Scoped to lesson pages, same as `displayEquations` above — a
+          // registry/glossary page's inline math is left exactly as before.
+          node.children[index] = inlineEquationNode(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');
+        } else if (child?.type === 'mdxJsxFlowElement' && diagramByNode.has(child)) {
+          injectFloatNumberAttributes(child, diagramByNode.get(child), 'dia');
         }
       }
     };
 
+    // Render-time defense in depth for content invisible to keyed-float
+    // validation — the manifest builder runs the same check via
+    // `validateRawFloats`/`scanRawFloats` (raw-floats.mjs); this catches
+    // content added since the manifest was last compiled.
+    if (lessonId) {
+      const rawFloats = collectRawFloats(tree);
+      const plural = (count, noun) => (count === 1 ? noun : `${noun}s`);
+      if (rawFloats.markdownTableNodes.length > 0) {
+        warn(
+          file,
+          `${lessonSlug} has ${rawFloats.markdownTableNodes.length} raw ` +
+            `Markdown ${plural(rawFloats.markdownTableNodes.length, 'table')} ` +
+            `not wrapped in <Table>; it has no stable number and cannot be ` +
+            `referenced with [[tab-…]]. Wrap it in <Table id="…">…</Table> ` +
+            `to give it one.`,
+          rawFloats.markdownTableNodes[0],
+        );
+      }
+      if (rawFloats.htmlTableNodes.length > 0) {
+        warn(
+          file,
+          `${lessonSlug} has ${rawFloats.htmlTableNodes.length} raw HTML ` +
+            `<table> ${plural(rawFloats.htmlTableNodes.length, 'element')} ` +
+            `not wrapped in <Table>; it has no stable number and cannot be ` +
+            `referenced with [[tab-…]]. Wrap it in <Table id="…">…</Table> ` +
+            `to give it one.`,
+          rawFloats.htmlTableNodes[0],
+        );
+      }
+      if (rawFloats.unkeyedDiagramNodes.length > 0) {
+        warn(
+          file,
+          `${lessonSlug} has ${rawFloats.unkeyedDiagramNodes.length} ` +
+            `<Diagram> ${plural(rawFloats.unkeyedDiagramNodes.length, 'component')} ` +
+            `with no id; it cannot be referenced with [[dia-…]]. Add an id ` +
+            `to give it a stable reference.`,
+          rawFloats.unkeyedDiagramNodes[0],
+        );
+      }
+      if (rawFloats.nestedDiagramNodes.length > 0) {
+        warn(
+          file,
+          `${lessonSlug} has ${rawFloats.nestedDiagramNodes.length} ` +
+            `<Diagram> ${plural(rawFloats.nestedDiagramNodes.length, 'component')} ` +
+            `nested inside another component; it is invisible to diagram ` +
+            `numbering. Move it to the top level (or inside ` +
+            `<Memo>/<ShortNote>), or wrap it in <Figure> to give it identity.`,
+          rawFloats.nestedDiagramNodes[0],
+        );
+      }
+    }
+
     visit(tree);
 
     file.data.notationReferences = references;
@@ -1089,5 +1400,6 @@ export default function remarkNotation(options = {}) {
         }));
     file.data.tableLabels = floatLabelData(tableByNode);
     file.data.figureLabels = floatLabelData(figureByNode);
+    file.data.diagramLabels = floatLabelData(diagramByNode);
   };
 }