explico 0.4.0 → 0.6.0

package/docs/authoring/structure-rules.md

@@ -0,0 +1,69 @@
+# Structure rules
+
+`S` rules govern the shape of a lesson's headings and the short titles on its
+keyed floats — the parts of a page a reader scans before reading prose. This
+is not [structure.md](structure.md), which is the taxonomy these rules (and
+the rest of the engine) speak in, not a rule set itself.
+
+See [README.md](README.md) for what "strong recommendation", "Build-enforced",
+and "Review-only" mean here, and how to amend a rule.
+
+---
+
+## S1
+
+**No heading, and no figure/diagram/memo/short-note title, runs past 65
+characters.**
+
+This caps every Markdown heading (`##` through `######`), a lesson's own
+`frontmatter.title` (rendered as the page's `<h1>`), and the short `title` /
+`label` prop on `Figure`, `Diagram`, `Memo`, and `ShortNote` — the text shown
+on a collapsed title bar, a diagram's caption line, or a chapter's sidebar
+entry. `Table` is exempt: it has only a `caption`, no separate `title`, and
+that caption is the LaTeX-convention full sentence shown above the table.
+
+A heading or float title that runs long is usually doing a caption's job. Move
+the rest of the sentence into the paragraph right after a heading, or into the
+float's own `caption`.
+
+```mdx
+<!-- Over the limit: the title carries the whole explanation. -->
+<Figure
+  id="ar1-forecast-fan"
+  caption="Multi-step AR(1) forecast: the conditional mean (teal) decays geometrically to the unconditional mean while the Gaussian 95% band (shaded) widens toward the stationary dispersion Γ₀; the coral line is one seeded future path."
+>
+
+<!-- At the limit: a short label, the rest moved into `caption`. -->
+<Figure
+  id="ar1-forecast-fan"
+  title="Multi-step AR(1) forecast"
+  caption="The conditional mean (teal) decays geometrically to the unconditional mean while the Gaussian 95% band (shaded) widens toward the stationary dispersion Γ₀; the coral line is one seeded future path."
+>
+```
+
+_Rationale._ A `Figure`'s `title` falls back to `caption` when omitted (see
+`Figure.astro`), so an unset `title` on a long-captioned figure silently
+becomes the text on the always-visible collapsible title bar — the reader
+sees the entire caption twice, once as the "heading" and once again in
+`<figcaption>` once they expand it. The same abuse happens with a heading
+authored as a full sentence instead of a label: the sidebar, the table of
+contents, and every anchor link now carry a paragraph instead of a title.
+Sixty-five characters is roughly one sidebar line at normal zoom before
+Starlight starts wrapping or truncating it.
+
+_How to apply._ Write the heading or `title` as a short noun phrase (a topic,
+not a claim about it); put the claim in the prose or the `caption`. If a
+`Figure` needs no distinct title beyond its caption's own first clause,
+extract that clause into `title` explicitly rather than omitting the prop and
+relying on the fallback — an omitted `title` on a long caption is exactly the
+failure this rule exists to catch.
+
+_Enforcement._ Build-enforced (`gate-heading-length.ts`, `pnpm
+validate:content`) for every Markdown heading in a lesson body and every
+`Figure`/`Diagram`/`Memo`/`ShortNote` `title`/`label` prop. Review-only for a
+lesson's `frontmatter.title` — the gate scans lesson body text and cannot see
+frontmatter, so a long page title (`<h1>`) is caught by a reviewer, not the
+build.
+
+_Exceptions._ None — a heading or float title that must exceed the limit
+should not be a heading or a float title; find the shorter label first.

package/docs/authoring/structure.md

@@ -105,12 +105,14 @@ Part 2  Projectile motion
 
 ## Numbering
 
-A display equation, `<Table>`, or `<Figure>` is numbered **`‹part›.‹n›`**:
+A display equation, `<Table>`, `<Figure>`, `<Diagram>`, or knowledge check is
+numbered **`‹part›.‹n›`**:
 
 - **`part`** is the part's 1-based position in `courseConfig.parts`.
-- **`n`** counts that kind of float across the *whole part*, in document order,
-  running unbroken from one chapter into the next. Each kind counts on its own,
-  so a `<Table>` never advances the `<Figure>` sequence.
+- **`n`** counts that kind of numbered item across the *whole part*, in document
+  order, running unbroken from one chapter into the next. Each kind counts on
+  its own, so a `<Table>` never advances the `<Figure>`, `<Diagram>`, or
+  knowledge-check sequence.
 - **Sections and subsections do not participate.** Neither `##` nor `###`
   resets `n` or appears in the number.
 - **Keyed or not, everything counts.** An equation with no `\label{eq:…}` still
@@ -121,8 +123,8 @@ In the playground: part 1 runs `1.1` … `1.7` through chapter 1 and continues
 `1.8` in chapter 2; part 2 opens at `2.1`.
 
 `manifest.lessons[]` carries what the render path needs to reproduce this:
-`part`, `chapter`, and `numbering.{equations,tables,figures}` — the running
-count each chapter starts from.
+`part`, `chapter`, and `numbering.{equations,tables,figures,diagrams,checks}` —
+the running count each chapter starts from.
 
 ### The invariant, and why it is build-enforced
 
@@ -135,5 +137,115 @@ This exists because the disagreement is otherwise silent and shipped: a course
 config that passed the manifest number tables without the placement map
 numbered its pages by `##` section while every reference to them read the
 manifest, so one equation was `(2.2)` on its own page and `(4.5)` everywhere
-else. Wire the plugin by handing it the whole manifest — `[remarkNotation,
-{ definitions: manifest.notation.raw, manifest }]` — and the two cannot drift.
+else. Wire the plugin with `createRemarkNotationOptions`, which reads
+`definitions`, `manifest`, and every numbering input off one manifest in one
+call so they cannot drift apart:
+
+```js
+import remarkNotation, {
+  createRemarkNotationOptions,
+} from 'explico/reference/remark-notation.mjs';
+
+// [remarkNotation, createRemarkNotationOptions(manifest, { strict: true })]
+```
+
+That cross-check only ever caught a disagreement for a *keyed* equation or
+float — an unkeyed one still took a number, but nothing compared it against
+the manifest, so a lesson whose only equations/tables/figures were unkeyed
+could still silently fall back to `##`-section numbering with no error at all.
+`strict: true` closes that: it fails the build when a catalogued lesson
+contains any equation, `<Table>`, or `<Figure>` — keyed or not — but has no
+`numbering` placement or no cross-page number table entry for its slug.
+`<Diagram>` is exempt, since `Diagram.astro` already renders one without a
+number by design when it has none. `strict` defaults to `false`, so existing
+non-strict wiring keeps building unchanged; turn it on once a course's
+manifest covers every catalogued lesson.
+
+### Raw and unwrapped floats
+
+A raw Markdown pipe table or a raw HTML `<table>` written directly into a
+lesson — never wrapped in `<Table>` — renders fine but never enters keyed-float
+validation: it has no number and `[[tab-…]]` cannot reach it. The same is true
+of an `<Diagram>` with no `id`, and of a `<Diagram>` nested inside anything but
+`<Memo>`/`<ShortNote>`/`<Table>`/`<Figure>` — `keyed-jsx-floats.mjs` only scans
+top-level (and `<Memo>`/`<ShortNote>`-nested) occurrences, so a diagram buried
+inside e.g. `<CompactExample>` never reaches diagram numbering at all.
+
+The compiled manifest flags all four as warnings in `diagnostics.rawFloats`
+(`raw-table-markdown`, `raw-table-html`, `diagram-unkeyed`, `diagram-nested`),
+and `remarkNotation` reports the same at render time as a defense-in-depth
+check for content added since the manifest was last compiled. None of these
+fail the build — they are advisory, independent of `strict` — but a course
+that wants them addressed should wrap the table in `<Table id="…">`/
+`<Figure id="…">`, or give the diagram an `id` and move it to the top level (or
+inside `<Memo>`/`<ShortNote>`), or wrap it in `<Figure>`.
+
+### Knowledge checks
+
+An assessment title is authored once, in `content/assessments/<id>.json`. Put
+that id in the lesson's colocated `.checks.yml`, then render `<AssessmentSet />`;
+do not add a separate “Check yourself” heading. The component renders
+`Knowledge check ‹number› — ‹title›` as a permalinked, collapsible section at
+`#check-<id>`. Cite it on the same page with `[[check-<id>]]`, or from another
+lesson with `[[lesson/slug#check-<id>]]`. Single-choice options are shuffled
+when the browser views the check; option ids, correctness, and authored content
+remain unchanged.
+
+## Detailed memos and inline short notes
+
+Headings define the page's conceptual hierarchy: they belong in the outline and
+should help every reader navigate the main argument. A `<Memo>` instead holds
+optional depth — a long derivation, proof, robustness check, edge case, or
+alternative method — without pretending that material is another section of
+the lecture. It keeps the subsection-like card, background, and border, but is
+collapsed and independently numbered.
+
+Register `remarkShortNote` and then `remarkMemo` after `remarkMath` in
+`astro.config.mjs`. Import `explico/components/memo/Memo.astro`, cite a memo with
+`[[memo-id]]` wherever it is relevant, and place the flow block later:
+
+```mdx
+The full calculation is available in [[memo-supporting-check]].
+
+Several paragraphs may intervene before the detailed material.
+
+<Memo id="supporting-check" title="Supporting check" description="The detailed calculation behind the claim.">
+
+The body can contain ordinary Markdown, display equations, `<Table>`, and
+`<Figure>` components.
+
+</Memo>
+```
+
+`[[memo-supporting-check]]` renders as `[1]`. Clicking it opens and scrolls to
+the block and updates the URL to `#memo-supporting-check`; the `[1]` shown on
+the memo itself remains a numbered permalink, and the chain icon beside its
+title provides the same explicit anchor affordance used by headings and
+figures. `id`, `title`, and `description` are required literal strings. The
+block is collapsed on a reader's first visit and remembers later open/closed
+choices unless `rememberState={false}` is set. Memo numbering is independent
+of equation, table, figure, and diagram numbering. Those numbered items remain
+in their normal page/part streams inside a memo.
+
+For print and PDF export, the memo opens at its reading-order position. It does
+not move to the bottom of the page: browser support for CSS footnote floats is
+not reliable enough to make that layout portable.
+
+Use `<ShortNote>` for the smaller, genuinely inline interaction. Import
+`explico/components/memo/ShortNote.astro` and put it exactly where its collapsed
+link belongs:
+
+```mdx
+The derivative agrees <ShortNote id="derivative" title="(show how)" description="Show the full calculus calculation.">
+
+Take the derivative, set it to zero, and solve. The body may also contain
+display equations, figures, or other block Markdown.
+
+</ShortNote>. But symmetry is quicker.
+```
+
+While collapsed, the surrounding sentence remains one paragraph and only the
+`title` text is visible. Activating it hides that link, inserts the body at that
+point in the reading flow, and exposes a “Show less” control that restores the
+original sentence. Short notes are for a locally optional explanation, not for
+material that needs a number or citations elsewhere; use a memo for that.

package/docs/authoring/visualizations.md

@@ -31,11 +31,40 @@ identically in print and with JS off.
 _How to apply._ Pass `nodes` / `edges` and, if any node has a `formula`, a
 `scope` from `labMathScope` — see
 `playground/content/labs/DerivationDiagram.astro`. A `formula` node's symbols
-must resolve against the page glyph table, same as `NotationFormula`. If
+must resolve against the page glyph table, same as `NotationFormula`. Pass the
+component's formula source to `labMathScope`; when it names a shared key that
+the lesson MDX does not, also pass
+`{ locals: Astro.locals, context: '<ComponentName> <formula context>' }` so the
+key joins that page's notation payload. `Diagram` independently registers the
+keys it ultimately emits, which protects wrapper components and supplies a
+node-specific build diagnostic. If
 `Diagram` genuinely cannot express the picture, raise it as an engine gap
 rather than reaching for another library.
 
-_Enforcement._ Review-only.
+A top-level lesson diagram must expose an authored `id` on an MDX element named
+`Diagram` (a wrapper component may be imported under that name). It then receives
+an independent diagram number, a `#dia-<id>` anchor, and references of the form
+`[[dia-<id>]]` or `[[lesson/slug#dia-<id>]]`. Diagram numbers do not advance the
+equation, table, or figure sequences.
+
+The component preserves the build-time canvas size and scrolls horizontally
+when the work area is narrower. A compact control on the title line can expand
+the original diagram toward the full in-page region and shrink it back; it is
+not modal, follows the diagram's document position while the page scrolls, and
+adds internal vertical scrolling when the viewport is too short. The shrink
+control or Escape restores its original width. Clicking the title minimizes/
+restores the diagram; this state is remembered per page by default
+(`defaultOpen` / `rememberState` configure it).
+The title also carries the same chain-link permalink treatment as headings.
+
+By default a laid-out width above `800px` emits a compile-time warning. Treat
+that warning as a prompt to try
+`direction="TB"`, shorter labels, or explicit node sizes before accepting the
+wide layout. Set `warnAboveWidth={false}` only when horizontal overflow is
+intentional, or set a positive pixel value when the course needs a different
+review threshold.
+
+_Enforcement._ Review-only, with a compile-time width warning from `Diagram`.
 
 _Exceptions._ A one-off illustrative schematic that is not a graph (a labelled
 photo, a geometric figure) is a [V2](#v2) figure, not a `Diagram`.
@@ -83,7 +112,11 @@ An interactive figure is a React island, hydrated `client:visible` (or
 - **Gate-checked math.** Any equation shown in the figure goes through the
   `labMathScope` / `renderLabMath` / `\slot{}` seam so its symbols are resolved
   against the page's real notation at build time and the island only patches
-  numbers into pre-rendered KaTeX. See
+  numbers into pre-rendered KaTeX. A wrapper whose template names notation not
+  otherwise present in lesson MDX passes
+  `{ locals: Astro.locals, context: '<ComponentName> <template>' }` as the third
+  `labMathScope` argument; that is the declaration that ships those definitions
+  in this page's popup payload. See
   `playground/content/labs/ProjectileRangeExplorer.tsx` +
   `ProjectileRangeMath.astro`.
 - **An accessible name and description** — `ariaLabel` / `ariaDescription` on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Build-time engine for prerequisite-aware, notation-rigorous course content: one validated content model, a semantic notation/citation/equation system with a completeness gate, and a deterministic JSON manifest.",
   "type": "module",
   "license": "UNLICENSED",
@@ -33,7 +33,9 @@
     "docs/authoring"
   ],
   "dependencies": {
-    "@dagrejs/dagre": "3.1.1"
+    "@dagrejs/dagre": "3.1.1",
+    "esbuild": "0.27.7",
+    "parse5": "7.3.0"
   },
   "peerDependencies": {
     "@astrojs/markdown-remark": "7.2.4",
@@ -62,6 +64,7 @@
   },
   "scripts": {
     "build": "tsup && node scripts/copy-assets.mjs && node scripts/fix-esm-extensions.mjs && tsc -p tsconfig.dts-mjs.json",
+    "check:release-migration": "node scripts/check-release-migration.mjs",
     "test": "vitest run",
     "test:watch": "vitest"
   }

package/src/compiler/astro.ts

@@ -1,17 +1,101 @@
-import { resolve, sep } from 'node:path';
+import { mkdtemp, readdir, readFile, rm } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawn } from 'node:child_process';
 
-import type { AstroIntegration } from 'astro';
+import type { AstroConfig, AstroIntegration } from 'astro';
 import type { CourseConfig } from './course-config';
 import {
   compileManifest,
   type Manifest,
   writeManifest,
 } from './manifest';
+import { missingNotationPayloadKeys } from '../reference/page-notation';
+import { writeStandaloneLessonExports } from './exports/standalone-html';
 
 // Vite keeps its server object across a restart. Do not accumulate watcher
 // callbacks each time Astro reloads its configuration.
 const watchedServers = new WeakSet<object>();
 
+function normalizedBasePath(base: string): string {
+  const segment = base.replace(/^\/+|\/+$/gu, '');
+  return segment ? `/${segment}/` : '/';
+}
+
+/** Match only a configured lesson artifact below Astro's deployment base. */
+export function matchStandaloneDownload(
+  pathname: string,
+  base: string,
+  lessonSlugs: readonly string[],
+): string | undefined {
+  const prefix = `${normalizedBasePath(base)}downloads/`;
+  if (!pathname.startsWith(prefix) || !pathname.endsWith('.html')) return undefined;
+  const slug = pathname.slice(prefix.length, -'.html'.length);
+  return lessonSlugs.includes(slug) ? slug : undefined;
+}
+
+async function buildDevelopmentDownloads(
+  config: Pick<AstroConfig, 'root'>,
+  lessonSlugs: readonly string[],
+): Promise<ReadonlyMap<string, Buffer>> {
+  const temporaryRoot = await mkdtemp(join(tmpdir(), 'explico-standalone-'));
+  const outputRoot = join(temporaryRoot, 'dist');
+  try {
+    const projectRoot = fileURLToPath(config.root);
+    const astroEntry = fileURLToPath(import.meta.resolve('astro'));
+    const astroCli = resolve(dirname(astroEntry), '..', 'bin', 'astro.mjs');
+    await new Promise<void>((resolveBuild, rejectBuild) => {
+      const child = spawn(
+        process.execPath,
+        [
+          astroCli,
+          'build',
+          '--root',
+          projectRoot,
+          '--outDir',
+          outputRoot,
+          '--silent',
+        ],
+        {
+          cwd: projectRoot,
+          env: { ...process.env, NODE_ENV: 'production' },
+          stdio: ['ignore', 'pipe', 'pipe'],
+        },
+      );
+      let diagnostic = '';
+      const capture = (chunk: Buffer) => {
+        if (diagnostic.length < 16_000) diagnostic += chunk.toString('utf8');
+      };
+      child.stdout.on('data', capture);
+      child.stderr.on('data', capture);
+      child.once('error', rejectBuild);
+      child.once('close', (code) => {
+        if (code === 0) {
+          resolveBuild();
+          return;
+        }
+        rejectBuild(
+          new Error(
+            `Astro's standalone development build exited with code ${code}.` +
+              (diagnostic.trim() ? `\n${diagnostic.trim()}` : ''),
+          ),
+        );
+      });
+    });
+    return new Map(
+      await Promise.all(
+        lessonSlugs.map(async (slug) => [
+          slug,
+          await readFile(join(outputRoot, 'downloads', `${slug}.html`)),
+        ] as const),
+      ),
+    );
+  } finally {
+    await rm(temporaryRoot, { recursive: true, force: true });
+  }
+}
+
 /** Fail loudly instead of rendering math triggers whose local cards are stale. */
 export function assertLocalNotationParity(
   lessonId: string,
@@ -34,6 +118,35 @@ export function assertLocalNotationParity(
   );
 }
 
+/** Fail an Astro build if final rendered HTML contains an unusable trigger. */
+export function assertNotationPayloadHtml(page: string, html: string): void {
+  const missing = missingNotationPayloadKeys(html);
+  if (missing.length === 0) return;
+  throw new Error(
+    `Explico notation payload invariant failed for rendered page "${page}": ` +
+      `${missing.map((key) => `data-notation-key="${key}"`).join(', ')} ` +
+      `${missing.length === 1 ? 'has' : 'have'} no matching ` +
+      '`data-notation-entry` popup definition. A nested Astro component that ' +
+      'emits notation must register its formula dependencies; use Diagram, ' +
+      'NotationFormula, or labMathScope(..., { locals: Astro.locals, context }).',
+  );
+}
+
+async function validateGeneratedNotationPayloads(directory: URL): Promise<void> {
+  const root = fileURLToPath(directory);
+  const walk = async (path: string): Promise<void> => {
+    for (const entry of await readdir(path, { withFileTypes: true })) {
+      const child = join(path, entry.name);
+      if (entry.isDirectory()) {
+        await walk(child);
+      } else if (entry.isFile() && entry.name.endsWith('.html')) {
+        assertNotationPayloadHtml(relative(root, child), await readFile(child, 'utf8'));
+      }
+    }
+  };
+  await walk(root);
+}
+
 function replaceInPlace(target: unknown, source: unknown): void {
   if (Array.isArray(target) && Array.isArray(source)) {
     target.splice(0, target.length, ...source);
@@ -82,15 +195,43 @@ export function explicoContentRefresh(
   courseConfig: CourseConfig,
   manifest: Manifest,
 ): AstroIntegration {
+  let developmentConfig: Pick<AstroConfig, 'root' | 'base'> | undefined;
   return {
     name: 'explico-content-refresh',
     hooks: {
-      'astro:server:setup': ({ server }) => {
+      'astro:config:setup': ({ command, config }) => {
+        if (command === 'dev') {
+          developmentConfig = { root: config.root, base: config.base };
+        }
+      },
+      'astro:server:setup': ({ server, logger }) => {
         if (watchedServers.has(server)) return;
         watchedServers.add(server);
         const contentRoot = `${resolve(process.cwd(), 'content')}${sep}`;
         let timer: ReturnType<typeof setTimeout> | undefined;
         let restarting = false;
+        let developmentDownloads:
+          | Promise<ReadonlyMap<string, Buffer>>
+          | undefined;
+        const developmentRoot = developmentConfig
+          ? fileURLToPath(developmentConfig.root)
+          : process.cwd();
+        const generatedDevelopmentRoots = [
+          '.astro',
+          'build',
+          'dist',
+          'node_modules',
+        ].map((directory) => `${resolve(developmentRoot, directory)}${sep}`);
+
+        const invalidateDevelopmentDownloads = (path: string) => {
+          const absolute = resolve(path);
+          if (
+            generatedDevelopmentRoots.some((root) => absolute.startsWith(root))
+          ) {
+            return;
+          }
+          developmentDownloads = undefined;
+        };
 
         const refresh = (path: string) => {
           const absolute = resolve(path);
@@ -121,6 +262,70 @@ export function explicoContentRefresh(
         server.watcher.on('add', refresh);
         server.watcher.on('change', refresh);
         server.watcher.on('unlink', refresh);
+
+        const configuredDevelopment = developmentConfig;
+        if (manifest.lessonExports?.standaloneHtml && configuredDevelopment) {
+          server.watcher.on('add', invalidateDevelopmentDownloads);
+          server.watcher.on('change', invalidateDevelopmentDownloads);
+          server.watcher.on('unlink', invalidateDevelopmentDownloads);
+          server.middlewares.use(async (request, response, next) => {
+            if (request.method !== 'GET' && request.method !== 'HEAD') return next();
+            let pathname: string;
+            try {
+              pathname = decodeURIComponent(
+                new URL(request.url ?? '/', 'http://localhost').pathname,
+              );
+            } catch {
+              return next();
+            }
+            const slug = matchStandaloneDownload(
+              pathname,
+              configuredDevelopment.base,
+              manifest.lessons.map((lesson) => lesson.slug),
+            );
+            if (!slug) return next();
+
+            try {
+              logger.info(
+                developmentDownloads
+                  ? `Serving cached standalone lesson ${slug}.html`
+                  : 'Building standalone lesson downloads for local development…',
+              );
+              developmentDownloads ??= buildDevelopmentDownloads(
+                configuredDevelopment,
+                manifest.lessons.map((lesson) => lesson.slug),
+              );
+              const currentDownloads = developmentDownloads;
+              currentDownloads.catch(() => {
+                if (developmentDownloads === currentDownloads) {
+                  developmentDownloads = undefined;
+                }
+              });
+              const artifact = (await currentDownloads).get(slug);
+              if (!artifact) return next();
+              const filename = `${slug.split('/').at(-1) ?? 'lesson'}.html`;
+              response.statusCode = 200;
+              response.setHeader('Content-Type', 'text/html; charset=utf-8');
+              response.setHeader('Content-Length', artifact.byteLength);
+              response.setHeader(
+                'Content-Disposition',
+                `attachment; filename="${filename}"`,
+              );
+              response.setHeader('Cache-Control', 'no-store');
+              response.end(request.method === 'HEAD' ? undefined : artifact);
+            } catch (error) {
+              const message = error instanceof Error ? error.message : String(error);
+              logger.error(`Could not build standalone lesson downloads: ${message}`);
+              response.statusCode = 500;
+              response.setHeader('Content-Type', 'text/plain; charset=utf-8');
+              response.end(`Could not build standalone lesson download.\n${message}\n`);
+            }
+          });
+        }
+      },
+      'astro:build:done': async ({ dir }) => {
+        await validateGeneratedNotationPayloads(dir);
+        await writeStandaloneLessonExports(dir, manifest);
       },
     },
   };

package/src/compiler/cli.ts

@@ -40,7 +40,11 @@ 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';
-import remarkNotation from '../reference/remark-notation.mjs';
+import remarkMemo from '../reference/remark-memo.mjs';
+import remarkNotation, {
+  createRemarkNotationOptions,
+} from '../reference/remark-notation.mjs';
+import remarkShortNote from '../reference/remark-short-note.mjs';
 import type { Manifest, ManifestLesson } from './manifest';
 import { isLessonSlug, lessonIdFromSlug } from './lesson-derivation';
 
@@ -173,6 +177,9 @@ export function lessonDiagnostics(
   for (const diagnostic of [
     ...manifest.diagnostics.tables,
     ...manifest.diagnostics.figures,
+    ...manifest.diagnostics.diagrams,
+    ...manifest.diagnostics.checks,
+    ...manifest.diagnostics.rawFloats,
   ]) {
     if (
       diagnostic.lessonId !== id &&
@@ -221,11 +228,18 @@ function processorFor(manifest: Manifest) {
       // shape here that it does there (D7/F-tables-figures parity).
       remarkMdx,
       remarkMath,
+      remarkShortNote,
+      remarkMemo,
       // `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 }],
+      // No `strict: true` here: `renderLesson()` below is also called
+      // directly with a synthetic path/body that has no manifest entry at all
+      // (fixture renderability checks — see its own doc comment), which
+      // strict mode would reject as "catalogued lesson with no numbering",
+      // even though it was never meant to be catalogued in the first place.
+      [remarkNotation, createRemarkNotationOptions(manifest)],
       [remarkCitation, { sources: manifest.sources }],
     ],
     rehypePlugins: [
@@ -476,6 +490,7 @@ export interface StatusReport {
     readonly keyedEquations: number;
     readonly keyedTables: number;
     readonly keyedFigures: number;
+    readonly keyedDiagrams: number;
   };
   readonly draftDebt: {
     readonly lessons: readonly string[];
@@ -521,6 +536,9 @@ export function contentStatus(manifest: Manifest): StatusReport {
     ...manifest.diagnostics.equations.map((d) => d.severity),
     ...manifest.diagnostics.tables.map((d) => d.severity),
     ...manifest.diagnostics.figures.map((d) => d.severity),
+    ...manifest.diagnostics.diagrams.map((d) => d.severity),
+    ...manifest.diagnostics.checks.map((d) => d.severity),
+    ...manifest.diagnostics.rawFloats.map((d) => d.severity),
     ...manifest.diagnostics.consistency.map(() => 'warning' as const),
     ...manifest.diagnostics.knowledge.map((d) => d.severity),
   ];
@@ -537,6 +555,10 @@ export function contentStatus(manifest: Manifest): StatusReport {
     (count, lesson) => count + lesson.figures.length,
     0,
   );
+  const keyedDiagrams = manifest.lessons.reduce(
+    (count, lesson) => count + lesson.diagrams.length,
+    0,
+  );
   const assessments = new Set(
     manifest.lessons.flatMap((lesson) => lesson.assessments),
   ).size;
@@ -553,6 +575,7 @@ export function contentStatus(manifest: Manifest): StatusReport {
       keyedEquations,
       keyedTables,
       keyedFigures,
+      keyedDiagrams,
     },
     draftDebt: { lessons: draftLessons, notation: draftNotation },
     orphans,
@@ -593,6 +616,8 @@ export interface ContextReport {
   readonly equations: readonly { key: string; number: string }[];
   readonly tables: readonly { key: string; number: string }[];
   readonly figures: readonly { key: string; number: string }[];
+  readonly diagrams: readonly { key: string; number: string }[];
+  readonly knowledgeChecks: readonly { key: string; number: string }[];
   readonly sources: readonly {
     id: string;
     title: string;
@@ -663,6 +688,8 @@ export function contentContext(
     equations: lesson.equations.map((equation) => ({ ...equation })),
     tables: lesson.tables.map((table) => ({ ...table })),
     figures: lesson.figures.map((figure) => ({ ...figure })),
+    diagrams: lesson.diagrams.map((diagram) => ({ ...diagram })),
+    knowledgeChecks: lesson.knowledgeChecks.map((check) => ({ ...check })),
     sources: lesson.sources.map((id) => {
       const record = sourceById.get(id) as Record<string, unknown> | undefined;
       return {