explico 0.3.0 → 0.5.0

package/docs/authoring/structure.md

@@ -0,0 +1,251 @@
+# Course structure — the taxonomy
+
+> **Status: adopted.** The engine implements these names and this numbering.
+> `courseConfig.parts` is the current field; `sections` still works and is
+> removed in the next MINOR release.
+
+A course built on explico has five nested structural levels. Two of them are
+currently called by more than one name, and two different levels are both
+called "section". This file fixes one name per level so the words stop
+overlapping.
+
+## The five levels
+
+| Level | What it physically is | Where it is declared | Names it used to carry |
+| --- | --- | --- | --- |
+| 1 | The whole material | `courseConfig.title` | course |
+| 2 | **Part** — a collapsible group in the left sidebar; one content directory | `courseConfig.parts[] = { dir, label }` | `CourseSection`, **"section"**, **"chapter"** (sidebar UI) |
+| 3 | **Chapter** — one `.mdx` file = one page = one URL | `content/docs/<dir>/<name>.mdx` | `lesson`, **"subchapter"** (sidebar UI) |
+| 4 | **Section** — an `##` heading inside a lesson | the `.mdx` body | — |
+| 5 | **Subsection** — a `###` heading inside a lesson | the `.mdx` body | *(unnamed)* |
+
+A **track** (`content/tracks/*.json`) is not one of these levels. It is an
+ordered learning path over lesson ids; it feeds the order lessons appear in
+inside their sidebar group, and it may span groups. It is never displayed as a
+container.
+
+### The two collisions this resolved
+
+**"Section" meant both level 2 and level 4.** `courseConfig.sections` was a
+sidebar group; the `section` counter in `src/reference/equations.mjs` and
+`src/reference/keyed-jsx-floats.mjs` counts `##` headings inside one lesson.
+They are two levels apart and nothing in the names says so.
+
+**"Chapter" meant both level 2 and level 3.** The numbering code said a chapter
+was a lesson — `manifest.lessons[].chapter` was the lesson's 1-based ordinal read
+straight down the sidebar, and it was the number before the dot in `(4.5)`. The
+sidebar UI said a chapter is a *group*: from the engine changelog, "Chapter
+groups in the left sidebar now start collapsed, retain compact **subchapter**
+icons … and expand to the full lesson names when the chapter title is opened."
+So the reader was shown "chapter = group, subchapter = lesson" while the numbers
+were built on "chapter = lesson". A number could not be read without knowing
+which of the two vocabularies the writer had in mind.
+
+## The names
+
+One name per level, borrowed from the book metaphor a reader already has:
+
+| Level | Proposed name | Playground example | time-series example |
+| --- | --- | --- | --- |
+| 1 | **Course** | Explico Playground | MTH 9893 Time Series Analysis |
+| 2 | **Part** | "Motion in the plane" (`motion/`) | "L1 · Foundations & evidence" |
+| 3 | **Chapter** — one lesson, one page, one URL | "Position and Coordinate Systems" | "Dependence: ACF and PACF" |
+| 4 | **Section** — an `##` heading | "Two ways to name the same point" | — |
+| 5 | **Subsection** — a `###` heading | "From Cartesian to polar" | — |
+
+Consequences:
+
+- `courseConfig.sections` is renamed `courseConfig.parts`. "Section" now only
+  ever means an `##` heading. `sections` is still accepted, and is removed in
+  the next MINOR release.
+- The sidebar UI no longer says "chapter" for a group or "subchapter" for a
+  lesson; a group is a **part**, and the thing inside it is a **chapter**.
+- "Lesson" and "chapter" stay as two words for level 3 on purpose: *lesson* is
+  the pedagogical unit (it teaches competencies, carries assessments), *chapter*
+  is that same unit's position in the reading order. A file is a lesson; its
+  ordinal is its chapter number.
+
+## What the playground demonstrates
+
+The playground is the worked example for every level. It was deliberately
+extended for this: until now it had a single sidebar group, which made levels 2
+and 3 indistinguishable — one group with four lessons numbers identically
+whether you count groups or lessons, which is why a numbering bug and this
+naming collision both stayed invisible.
+
+```
+Course        Explico Playground
+├── Part 1    Motion in the plane                     content/docs/motion/
+│   ├── Ch 1  Position and Coordinate Systems         position-and-coordinates.mdx
+│   │   ├── § Locating a point in the plane           ##
+│   │   ├── § Two ways to name the same point         ##
+│   │   │   ├── §§ From Cartesian to polar            ###
+│   │   │   └── §§ From polar to Cartesian            ###
+│   │   ├── § Velocity and acceleration as derivatives ##
+│   │   └── § The special case: constant acceleration  ##
+│   │       ├── §§ Integrating once: velocity          ###
+│   │       └── §§ Integrating twice: position         ###
+│   └── Ch 2  Velocity Under Constant Acceleration    constant-acceleration.mdx
+└── Part 2    Projectile motion                       content/docs/projectiles/
+    ├── Ch 1  Projectile Range                        projectile-range.mdx
+    └── Ch 2  Optimal Launch Angle                    optimal-launch-angle.mdx
+```
+
+Which numbers every float like this — the part supplies the prefix, and the
+index carries on across the part's chapters:
+
+```
+Part 1  Motion in the plane
+  Ch 1  Position and Coordinate Systems   (1.1) (1.2) (1.3) (1.4) (1.5) (1.6) (1.7)
+  Ch 2  Velocity Under Constant Accel.    (1.8)
+Part 2  Projectile motion
+  Ch 1  Projectile Range                  (2.1) (2.2)
+  Ch 2  Optimal Launch Angle              (2.3) (2.4) (2.5) (2.6)
+```
+
+## Numbering
+
+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 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
+  takes a number and a positional anchor (`#eq-2-4`); it just cannot be
+  referenced by name.
+
+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,diagrams,checks}` —
+the running count each chapter starts from.
+
+### The invariant, and why it is build-enforced
+
+The number a page prints beside an equation and the number a cross-page
+`[[slug#eq-key]]` prints for it are computed by two code paths from the same
+content. `remarkNotation` cross-checks them for every keyed float and fails the
+build on any disagreement, naming the key and both numbers.
+
+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 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 and its text description; 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.3.0",
+  "version": "0.5.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

@@ -0,0 +1,332 @@
+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 { 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,
+  authoredKeys: readonly string[],
+  renderedKeys: readonly string[],
+): void {
+  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.`,
+  );
+}
+
+/** 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);
+    return;
+  }
+  if (
+    !target ||
+    !source ||
+    typeof target !== 'object' ||
+    typeof source !== 'object'
+  ) {
+    return;
+  }
+  const mutable = target as Record<string, unknown>;
+  const fresh = source as Record<string, unknown>;
+  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;
+    }
+  }
+}
+
+/**
+ * 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).
+ */
+export function explicoContentRefresh(
+  courseConfig: CourseConfig,
+  manifest: Manifest,
+): AstroIntegration {
+  let developmentConfig: Pick<AstroConfig, 'root' | 'base'> | undefined;
+  return {
+    name: 'explico-content-refresh',
+    hooks: {
+      '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);
+          if (!absolute.startsWith(contentRoot) || restarting) return;
+          if (timer) clearTimeout(timer);
+          timer = setTimeout(async () => {
+            restarting = true;
+            try {
+              const fresh = await compileManifest(courseConfig);
+              writeManifest(fresh);
+              // Astro/Vite retains the configuration object during a server
+              // restart. Update it recursively so remark plugin option arrays
+              // and maps captured from `manifest` also see the new model.
+              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);
+
+        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);
+      },
+    },
+  };
+}