explico 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,173 @@
+# Changelog
+
+All notable changes to the **`explico` engine** are recorded here. The installed
+`package.json` `version` is the single source of truth for what you have; this
+file says what changed between versions and [`docs/VERSIONING.md`](docs/VERSIONING.md)
+says what a version bump means.
+
+A course built on explico keeps its **own** knowledge version — see the course's
+`content/CHANGELOG.md` and [`docs/authoring/versioning.md`](docs/authoring/versioning.md).
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project is pre-1.0: a MINOR bump may carry a breaking change, always listed
+under **Breaking** below; a PATCH never breaks.
+
+## [Unreleased]
+
+## [0.4.0] - 2026-09-09
+
+### Breaking
+
+- **Equation, table, and figure numbers are now `‹part›.‹n›`, not
+  `‹lesson›.‹n›`.** A *part* is a sidebar group; `n` counts that kind of float
+  across the whole part, running unbroken from one chapter into the next.
+  Previously the prefix was the lesson's ordinal down the entire course and `n`
+  restarted on every page, so a sixteen-lesson course had sixteen prefixes.
+  Every number in an existing course changes. Nothing an author wrote changes —
+  numbers were never hand-typed — but a published link of the form `#eq-2-4`
+  (the positional anchor of an *unkeyed* equation) moves; a keyed `#eq-<key>`
+  anchor is unaffected. Manifest schema is now **v7**: `lessons[].part` is new,
+  `lessons[].chapter` is redefined as the lesson's ordinal *within its part*,
+  and `lessons[].numbering` carries the per-kind running counts.
+- **`courseConfig.sections` is renamed `courseConfig.parts`.** "Section" now
+  only ever means an `##` heading inside a lesson. The old name still works and
+  is removed in the next MINOR release; `CourseSection` is a deprecated alias
+  for `CoursePart`.
+
+### Added
+
+- [`docs/authoring/structure.md`](docs/authoring/structure.md) — the structural
+  taxonomy the rest of the docs speak in: course → part → chapter → section →
+  subsection, which levels a number counts, and why the numbering invariant is
+  build-enforced. Two levels were previously both called "section", and two
+  were both called "chapter".
+- `remarkNotation` accepts a `manifest` option that supplies every numbering
+  input at once — `equations`, `tables`, `figures`, and the part/offset
+  placement map, all read off the same compiled manifest. This is now the recommended wiring in
+  `astro.config.mjs`; the individual options remain, and an explicit one still
+  wins over the manifest. `numberingFromManifest(manifest)` is exported for
+  callers that need the derived object on its own.
+- `explicoContentRefresh(courseConfig, manifest)` recompiles the manifest and
+  restarts Astro development after any `content/` change, independent of the
+  editor making it.
+
+### Fixed
+
+- **Equation, table, and figure numbers no longer disagree between a page and
+  the references to it (WERN).** A course that passed the manifest number tables
+  to `remarkNotation` without the placement map silently numbered every page by
+  `##` section — restarting at `1.1` on each page — while cross-page references
+  kept reading the manifest, so one equation was `(2.2)` on its own page and
+  `(4.5)` everywhere else. `remarkNotation` now cross-checks the number
+  it computes for each keyed equation / table / figure against the manifest
+  number for the same key and fails the build on any disagreement, naming the
+  key, both numbers, and the missing placement. The same omission was
+  present in `explico content check`, which therefore validated lessons under a
+  numbering scheme the real build never used; it now shares the manifest wiring.
+
+### Changed
+
+- Parts in the left sidebar now start collapsed, retain compact chapter icons
+  with hover/focus labels, and expand to the full chapter names when the part
+  title is opened. (Previously described as "chapter groups" with "subchapter"
+  icons — the same UI, named per the taxonomy.)
+
+### Fixed
+
+- `loadManifest(courseConfig)` now always compiles current course content, and
+  `LessonFooter` rejects local-notation key drift. Current math hover markers can
+  no longer be silently paired with stale cards from a persisted manifest.
+- Notation hover markers inside `\sqrt{…}` (and under an extensible arrow such
+  as `\xrightarrow`) are reachable again: KaTeX paints the radical/arrow SVG as
+  an absolutely-positioned overlay on top of the content it decorates, which
+  was swallowing the pointer. `NotationLayer` now sets `pointer-events: none`
+  on that overlay layer, matching the existing fraction/subscript workaround.
+
+## [0.3.0] - 2026-09-05
+
+### Breaking
+
+- `CourseConfig` now requires an `about` block (`materialName?`, `summary?`,
+  `version`, `authors`, `disclaimer`, `changelogHref?`). It carries the course's
+  reader-facing identity and its **knowledge version**. Add one to
+  `content/course.config.ts`.
+- Manifest gains `manifest.about` (engine identity + the course `about` block +
+  the knowledge version resolved from `content/CHANGELOG.md`) and
+  `manifest.diagnostics.knowledge`; `schemaVersion` bumped. Additive — existing
+  fields are unchanged.
+- `EquationRefLayer` / `EquationEnhancer` are replaced by `FloatRefLayer` +
+  `KeyedFloatEnhancer`, one hover/pin/jump engine shared by equation, table, and
+  figure references. Update the wiring in your Starlight `Footer` override.
+
+### Added
+
+- **Figures and tables as first-class keyed floats.** New `Figure` and `Table`
+  components with appearance-order numbering, `#fig-<id>` / `#tab-<id>` anchors,
+  and `[[fig-<id>]]` / `[[tab-<id>]]` cross-references that highlight the target
+  when it is on screen and preview it when it is not — the same model equations
+  already had. New build gates `reference/figures-validate.ts`,
+  `reference/tables-validate.ts`, `reference/keyed-float-validate.ts`, and the
+  `reference/keyed-jsx-floats.mjs` remark pass.
+- **About `[?]` panel.** `components/starlight/AboutPanel.astro` +
+  `LayoutSocialIcons.astro` render a header control, on every route, showing the
+  material name and summary, the knowledge version and date, the engine version,
+  the authors and contact, the disclaimer, and a link to the content changelog.
+  Wire it with `components: { SocialIcons: 'explico/components/starlight/LayoutSocialIcons.astro' }`.
+- **Knowledge versioning.** `compiler/knowledge-version.ts` parses
+  `content/CHANGELOG.md` and checks it against `about.version`; drift is a Tier-3
+  `knowledge-version-mismatch` / `knowledge-changelog-missing` /
+  `knowledge-version-invalid` warning (never fails the build). Governed by new
+  authoring area **C** (`docs/authoring/versioning.md`, rules C1–C4).
+- `Diagram` component (Dagre + build-time KaTeX), with an `LR` direction and an
+  optional hand-written `description` for the text fallback.
+- Notation engine: a base **operator** library (`reference/base-operators.mjs`)
+  alongside the base glyph library, wider automatic glyph resolution in
+  `reference/math-glyphs.mjs`, and `\explain{key}{latex}` support inside notation
+  `formula:` fields and `Diagram` node formulas.
+- `content status` now reports the course's knowledge version.
+- Course-author docs in the published package: `docs/authoring/agents.md`
+  (working on a course repo with an AI agent) and `docs/authoring/migrating.md`
+  (per-version upgrade steps). The published `files` are `dist`, `src`,
+  `README.md`, `CHANGELOG.md`, `docs/VERSIONING.md`, `docs/authoring/` — the
+  repo's own `AGENTS.md` is engine-development guidance and is **no longer
+  shipped** (it described `src/` internals a consumer does not have).
+- `compileManifest` throws a named error, pointing at `migrating.md`, when a
+  course upgrading from 0.2.x has no `about` block — instead of a bare
+  `Cannot read properties of undefined`.
+- `scripts/agent/` (`verify`, `fresh`, `shot`) and a generated, staleness-gated
+  repo map in the repo's `AGENTS.md` (`scripts/agent/gen-map.mjs`) — repo tooling,
+  not part of the package.
+
+### Changed
+
+- Deep-linkable heading anchors (`rehype-heading-anchors` +
+  `HeadingAnchorEnhancer`) and numbered lesson equations are on by default.
+- `remark-notation` and `consistency` gained substantial coverage for the
+  keyed-float syntax, operator resolution, and `\explain` handling.
+
+## [0.2.0] - 2026-09-04
+
+- Two-tier notation vocabulary: named operators (rule N8) are a Tier-3
+  `operator-explained` warning against a shipped baseline plus a per-course
+  `operators.allow` / `operators.deny` list, softer than the identifier gate.
+- Heading deep links: `rehype-heading-anchors` + `HeadingAnchorEnhancer.astro`.
+- `popup-stack.ts` — nested, independently positioned notation popups.
+
+## [0.1.1] - 2026-09-03
+
+- Make the published build load under Node ESM (`.mjs` extension fixups, `dist/`
+  resolution).
+
+## [0.1.0] - 2026-09-03
+
+- Initial import of the explico engine, extracted from the `equations` project:
+  the one manifest compiler, the notation / citation / equation reference
+  system with its completeness gate, the curriculum-graph validator, the
+  Astro/Starlight UI, the LMS / session / analytics seams, and the `content` CLI.
+
+[Unreleased]: https://github.com/danieltuzes/explico/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/danieltuzes/explico/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/danieltuzes/explico/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/danieltuzes/explico/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/danieltuzes/explico/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/danieltuzes/explico/releases/tag/v0.1.0

package/README.md

@@ -14,7 +14,10 @@ What it gives a course:
   meaning; a **completeness gate** fails the build if any identifier in any
   rendered-math context (lesson body, `notation.formula`, `checks.yml`,
   assessment prompts, component slots) does not resolve to a key. One meaning
-  per glyph per page, enforced corpus-wide.
+  per glyph per page, enforced corpus-wide. Named operators get the same
+  treatment one tier softer: a lesson's `\operatorname{Var}` is a warning
+  (`operator-explained`) until it carries an entry or the course lists it in
+  `operators.allow`; a shipped baseline (`\exp`, `\int`, trig, …) is exempt.
 - **Inline citations** — `[@source-id; locator]` → numbered marker + generated
   reference list, resolved against a schema-checked source collection.
 - **Equation identity** — `\label{eq:key}` gives a display equation a stable
@@ -28,6 +31,14 @@ What it gives a course:
 - **Shared Astro/Starlight UI** — a hover-panel primitive shared by the
   notation and citation layers, a glossary, a curriculum map, compact examples,
   layout overrides.
+- **Interactive figures, with room to grow** — a `labMathScope`/`renderLabMath`
+  seam compiles a `\slot{}`-templated formula against the page's real notation
+  at build time, so a client-side island only ever patches numbers into
+  pre-rendered KaTeX. Hand-rolled SVG is the default chart (zero dependency,
+  covers a single custom figure); reach for D3 once a figure needs real
+  tick-labeled axes, log scales, or several series sharing a scale; Observable
+  Plot pays off once a course is authoring many charts per lecture. Pick per
+  figure — nothing in the engine assumes one plotting approach.
 - **LMS / analytics / identity seams** — framework-free interfaces shipped as
   no-ops; a host supplies real implementations without touching a component.
 - **A `content` CLI** — `status`, `context <lesson>`, `check <lesson>` (compiles
@@ -58,6 +69,7 @@ export { collections } from 'explico/content-config';
 
 ```js
 // astro.config.mjs
+import { explicoContentRefresh } from 'explico/compiler/astro.js';
 import { loadManifest } from 'explico/compiler/manifest.js';
 import remarkNotation from 'explico/reference/remark-notation.mjs';
 import remarkCitation from 'explico/reference/remark-citation.mjs';
@@ -66,11 +78,30 @@ import rehypeFailKatexErrors from 'explico/reference/rehype-fail-katex-errors.mj
 import { courseConfig } from './content/course.config.ts';
 
 const manifest = await loadManifest(courseConfig);
-// … starlight({ customCss: ['explico/styles/global.css'],
-//               components: { Footer: 'explico/components/starlight/LessonFooter.astro', … } })
-// … markdown.remarkPlugins / rehypePlugins from the manifest
+// markdown.remarkPlugins: [
+//   remarkMath,
+//   // One `manifest` carries every numbering input — the equation / table /
+//   // figure number tables *and* the part each lesson sits in. Pass the
+//   // tables without the placement and the page numbers its equations by `##`
+//   // section while references to it read the part scheme, so the same
+//   // equation reads (2.2) at home and (4.5) abroad; the plugin rejects that
+//   // at build time rather than shipping it.
+//   [remarkNotation, { definitions: manifest.notation.raw, manifest }],
+//   [remarkCitation, { sources: manifest.sources }],
+// ]
+// … integrations: [explicoContentRefresh(courseConfig, manifest),
+//                  starlight({ customCss: ['explico/styles/global.css'],
+//               components: { Footer: 'explico/components/starlight/LessonFooter.astro',
+//                             SocialIcons: 'explico/components/starlight/LayoutSocialIcons.astro', … } })
+// … rehypePlugins: [[rehypeKatex, createNotationKatexOptions()], rehypeFailKatexErrors]
 ```
 
+`loadManifest(courseConfig)` always recompiles current content before Astro
+starts. `explicoContentRefresh(courseConfig, manifest)` recompiles the manifest
+and restarts the development server when any file under `content/` is added,
+changed, or removed, keeping Markdown transforms and UI components on the same
+model without an editor-specific task.
+
 ```jsonc
 // package.json — the read-side CLI
 "scripts": { "validate:content": "tsx scripts/compile-manifest.ts" }
@@ -92,6 +123,19 @@ discounting → bonds → credit/CDS → derivatives and options.
 | `src/content-config.ts`                           | the Zod collection schemas (Astro re-exports them)                                                                                          |
 | `src/styles/`                                     | `global.css` (notation panel, keyed-equation flash, KaTeX)                                                                                  |
 
+## Authoring
+
+Course content follows the rules in [`docs/authoring/`](docs/authoring/) —
+strong recommendations for human and AI authors covering notation spelling
+(`\mathcal{N}` for the normal, `\mathbb{P}` for probability, upright `\mathrm{d}`
+for the differential, …), which library draws a diagram or
+chart (`Diagram` for graphs; SVG → D3 → Observable Plot for charts), how
+randomised interactive figures pick their axes, and how the course's knowledge
+version and `content/CHANGELOG.md` move with a content change (area `C`,
+surfaced to readers in the About `[?]` panel).
+[`docs/authoring/README.md`](docs/authoring/README.md) is the governance: rule
+IDs, enforcement levels, and how to amend.
+
 ## Build
 
 ```bash
@@ -102,7 +146,23 @@ pnpm build   # tsup → dist/ (ESM + .d.ts) for the .ts core; .astro / .tsx / .c
 Published `exports` resolve to `dist/` for the typed core and to `src/` for the
 Astro components and styles (see `publishConfig` in `package.json`).
 
-## Status
+## Versioning
+
+The engine follows [semver](https://semver.org). The **golden source** for the
+version is the installed `package.json` (`explico`'s own `version`); the About
+`[?]` panel reads it at build time and the docs never repeat a number.
+
+- [`CHANGELOG.md`](CHANGELOG.md) — what changed between engine versions.
+- [`docs/VERSIONING.md`](docs/VERSIONING.md) — what a MAJOR / MINOR / PATCH bump
+  means here, the public surface it is measured against, and the pre-1.0 clause.
+
+A course built on explico carries an **independent knowledge version** over its
+content — `about.version` in `content/course.config.ts`, tracked in the course's
+`content/CHANGELOG.md`, surfaced to readers in the same `[?]` panel. See
+[`docs/authoring/versioning.md`](docs/authoring/versioning.md).
+
+For AI authors: [`AGENTS.md`](AGENTS.md) says which changelog and which version a
+given change updates.
 
-`0.1.x` — extracted from the `equations` project. API not yet stable; the
-license is undecided (`UNLICENSED` until chosen).
+Status: extracted from the `equations` project; API not yet stable (pre-1.0);
+the license is undecided (`UNLICENSED` until chosen).

package/dist/compiler/astro.d.ts

@@ -0,0 +1,30 @@
+import { AstroIntegration } from 'astro';
+import { CourseConfig } from './course-config.js';
+import { Manifest } from './manifest.js';
+import '../curriculum/validation.js';
+import '../reference/consistency.js';
+import './collections.js';
+import '../reference/types.js';
+import '../reference/lint-ignore.js';
+import '../reference/equations-validate.js';
+import '../reference/tables-validate.js';
+import '../reference/keyed-float-validate.js';
+import '../reference/figures-validate.js';
+import '../reference/gate-math.js';
+import '../reference/gloss.js';
+import './knowledge-version.js';
+import './lesson-derivation.js';
+
+/** Fail loudly instead of rendering math triggers whose local cards are stale. */
+declare function assertLocalNotationParity(lessonId: string, authoredKeys: readonly string[], renderedKeys: readonly string[]): void;
+/**
+ * Restart Astro when an authored content file changes. Astro reloads MDX on
+ * its own, but Explico's manifest is created by `astro.config.mjs`; a restart
+ * is what makes the remark plugins and page UI consume the same fresh model.
+ *
+ * Add this integration once to `integrations` in `astro.config.mjs`. The
+ * restart is automatic and editor-agnostic (change/add/unlink all work).
+ */
+declare function explicoContentRefresh(courseConfig: CourseConfig, manifest: Manifest): AstroIntegration;
+
+export { assertLocalNotationParity, explicoContentRefresh };

package/dist/compiler/astro.js

@@ -0,0 +1,79 @@
+import { resolve, sep } from "node:path";
+import {
+  compileManifest,
+  writeManifest
+} from "./manifest.js";
+const watchedServers = /* @__PURE__ */ new WeakSet();
+function assertLocalNotationParity(lessonId, authoredKeys, renderedKeys) {
+  const authored = [...new Set(authoredKeys)].sort();
+  const rendered = [...new Set(renderedKeys)].sort();
+  if (authored.length === rendered.length && authored.every((key, index) => key === rendered[index])) {
+    return;
+  }
+  throw new Error(
+    `Stale Explico manifest for ${lessonId}: lesson notation.local has [${authored.join(", ")}], but the page notation bundle has [${rendered.join(", ")}]. Pass courseConfig to loadManifest() and add explicoContentRefresh() to the Astro integrations.`
+  );
+}
+function replaceInPlace(target, source) {
+  if (Array.isArray(target) && Array.isArray(source)) {
+    target.splice(0, target.length, ...source);
+    return;
+  }
+  if (!target || !source || typeof target !== "object" || typeof source !== "object") {
+    return;
+  }
+  const mutable = target;
+  const fresh = source;
+  for (const key of Object.keys(mutable)) {
+    if (!(key in fresh)) delete mutable[key];
+  }
+  for (const [key, value] of Object.entries(fresh)) {
+    const current = mutable[key];
+    if (Array.isArray(current) && Array.isArray(value) || current && value && typeof current === "object" && typeof value === "object" && !Array.isArray(current) && !Array.isArray(value)) {
+      replaceInPlace(current, value);
+    } else {
+      mutable[key] = value;
+    }
+  }
+}
+function explicoContentRefresh(courseConfig, manifest) {
+  return {
+    name: "explico-content-refresh",
+    hooks: {
+      "astro:server:setup": ({ server }) => {
+        if (watchedServers.has(server)) return;
+        watchedServers.add(server);
+        const contentRoot = `${resolve(process.cwd(), "content")}${sep}`;
+        let timer;
+        let restarting = false;
+        const refresh = (path) => {
+          const absolute = resolve(path);
+          if (!absolute.startsWith(contentRoot) || restarting) return;
+          if (timer) clearTimeout(timer);
+          timer = setTimeout(async () => {
+            restarting = true;
+            try {
+              const fresh = await compileManifest(courseConfig);
+              writeManifest(fresh);
+              replaceInPlace(manifest, fresh);
+              await server.restart();
+            } catch (error) {
+              server.config.logger.error(
+                `Explico could not refresh the content manifest: ${error instanceof Error ? error.message : String(error)}`
+              );
+            } finally {
+              restarting = false;
+            }
+          }, 50);
+        };
+        server.watcher.on("add", refresh);
+        server.watcher.on("change", refresh);
+        server.watcher.on("unlink", refresh);
+      }
+    }
+  };
+}
+export {
+  assertLocalNotationParity,
+  explicoContentRefresh
+};

package/dist/compiler/cli.d.ts

@@ -6,8 +6,12 @@ import './collections.js';
 import '../reference/types.js';
 import '../reference/lint-ignore.js';
 import '../reference/equations-validate.js';
+import '../reference/tables-validate.js';
+import '../reference/keyed-float-validate.js';
+import '../reference/figures-validate.js';
 import '../reference/gate-math.js';
 import '../reference/gloss.js';
+import './knowledge-version.js';
 import './lesson-derivation.js';
 
 /**
@@ -91,6 +95,8 @@ interface DomainFileSignatures {
     readonly signatures: readonly string[];
 }
 interface StatusReport {
+    /** The course's published knowledge version (`about.version`). */
+    readonly knowledgeVersion: string;
     readonly counts: {
         readonly lessons: number;
         readonly competencies: number;
@@ -99,6 +105,8 @@ interface StatusReport {
         readonly tracks: number;
         readonly notationDefinitions: number;
         readonly keyedEquations: number;
+        readonly keyedTables: number;
+        readonly keyedFigures: number;
     };
     readonly draftDebt: {
         readonly lessons: readonly string[];
@@ -145,6 +153,14 @@ interface ContextReport {
         key: string;
         number: string;
     }[];
+    readonly tables: readonly {
+        key: string;
+        number: string;
+    }[];
+    readonly figures: readonly {
+        key: string;
+        number: string;
+    }[];
     readonly sources: readonly {
         id: string;
         title: string;

package/dist/compiler/cli.js

@@ -8,6 +8,7 @@ import {
 } from "@astrojs/markdown-remark";
 import rehypeKatex from "rehype-katex";
 import remarkMath from "remark-math";
+import remarkMdx from "remark-mdx";
 import { createNotationKatexOptions } from "../reference/katex-options.mjs";
 import rehypeFailKatexErrors from "../reference/rehype-fail-katex-errors.mjs";
 import remarkCitation from "../reference/remark-citation.mjs";
@@ -81,6 +82,20 @@ function lessonDiagnostics(manifest, lesson) {
       ...withFile(diagnostic.file)
     });
   }
+  for (const diagnostic of [
+    ...manifest.diagnostics.tables,
+    ...manifest.diagnostics.figures
+  ]) {
+    if (diagnostic.lessonId !== id && diagnostic.file !== file && !mentions(diagnostic.message, id, file)) {
+      continue;
+    }
+    out.push({
+      code: diagnostic.code,
+      severity: diagnostic.severity === "warning" ? "warning" : "error",
+      message: diagnostic.message,
+      ...withFile(diagnostic.file)
+    });
+  }
   for (const diagnostic of manifest.diagnostics.consistency) {
     if (diagnostic.file !== file && diagnostic.lessonId !== id) continue;
     out.push({
@@ -100,14 +115,17 @@ function processorFor(manifest) {
     syntaxHighlight: false,
     smartypants: false,
     remarkPlugins: [
+      // Syntax only (no JSX evaluation) — teaches the parser `<Table>` /
+      // `<Figure>` / `<CompactExample>` are `mdxJsxFlowElement` nodes, same
+      // as the real Astro/MDX build, so `remarkNotation` sees the same tree
+      // shape here that it does there (D7/F-tables-figures parity).
+      remarkMdx,
       remarkMath,
-      [
-        remarkNotation,
-        {
-          definitions: manifest.notation.raw,
-          equations: manifest.equations.numbersBySlug
-        }
-      ],
+      // `manifest` carries the number tables *and* the part/offset placement
+      // together, so this check numbers a page exactly as the Astro build
+      // does. Passing the tables alone silently numbered pages by `##` section
+      // here while cross-page references read the part-scheme manifest.
+      [remarkNotation, { definitions: manifest.notation.raw, manifest }],
       [remarkCitation, { sources: manifest.sources }]
     ],
     rehypePlugins: [
@@ -279,16 +297,28 @@ function contentStatus(manifest) {
     ...manifest.diagnostics.alignment.map((d) => d.severity),
     ...manifest.diagnostics.math.map((d) => d.severity),
     ...manifest.diagnostics.equations.map((d) => d.severity),
-    ...manifest.diagnostics.consistency.map(() => "warning")
+    ...manifest.diagnostics.tables.map((d) => d.severity),
+    ...manifest.diagnostics.figures.map((d) => d.severity),
+    ...manifest.diagnostics.consistency.map(() => "warning"),
+    ...manifest.diagnostics.knowledge.map((d) => d.severity)
   ];
   const keyedEquations = manifest.lessons.reduce(
     (count, lesson) => count + lesson.equations.length,
     0
   );
+  const keyedTables = manifest.lessons.reduce(
+    (count, lesson) => count + lesson.tables.length,
+    0
+  );
+  const keyedFigures = manifest.lessons.reduce(
+    (count, lesson) => count + lesson.figures.length,
+    0
+  );
   const assessments = new Set(
     manifest.lessons.flatMap((lesson) => lesson.assessments)
   ).size;
   return {
+    knowledgeVersion: manifest.about.knowledge.version,
     counts: {
       lessons: manifest.lessons.length,
       competencies: manifest.competencies.length,
@@ -296,7 +326,9 @@ function contentStatus(manifest) {
       sources: manifest.sources.length,
       tracks: manifest.tracks.length,
       notationDefinitions: manifest.notation.definitions.length,
-      keyedEquations
+      keyedEquations,
+      keyedTables,
+      keyedFigures
     },
     draftDebt: { lessons: draftLessons, notation: draftNotation },
     orphans,
@@ -350,6 +382,8 @@ function contentContext(manifest, rawId) {
       ...definition.formula === void 0 ? {} : { formula: definition.formula }
     })),
     equations: lesson.equations.map((equation) => ({ ...equation })),
+    tables: lesson.tables.map((table) => ({ ...table })),
+    figures: lesson.figures.map((figure) => ({ ...figure })),
     sources: lesson.sources.map((id) => {
       const record = sourceById.get(id);
       return {

package/dist/compiler/collections.js

@@ -3,6 +3,7 @@ import { basename, join, relative } from "node:path";
 import { parseFrontmatter } from "@astrojs/markdown-remark";
 import { isSubstantiveMeaning } from "../reference/prose.js";
 import { parseEquationRef } from "../reference/equations.mjs";
+import { parseKeyedFloatRef } from "../reference/keyed-jsx-floats.mjs";
 import { resolveLabel } from "../reference/label.js";
 import { resolveGlosses } from "../reference/gloss.js";
 import {
@@ -136,7 +137,9 @@ function extractNotationReferences(text, file, kind) {
   for (const [pattern, referenceKind] of patterns) {
     for (const match of searchable.matchAll(pattern)) {
       const key = (match[1] ?? "").trim();
-      if (parseEquationRef(key)) continue;
+      if (parseEquationRef(key) || parseKeyedFloatRef(key, { prefix: "tab" }) || parseKeyedFloatRef(key, { prefix: "fig" })) {
+        continue;
+      }
       references.push({
         key,
         kind: referenceKind,