explico 0.2.0 → 0.4.0

package/docs/authoring/structure.md

@@ -0,0 +1,139 @@
+# 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>`, or `<Figure>` 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.
+- **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}` — 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 by handing it the whole manifest — `[remarkNotation,
+{ definitions: manifest.notation.raw, manifest }]` — and the two cannot drift.

package/docs/authoring/versioning.md

@@ -0,0 +1,116 @@
+# Versioning rules
+
+`C` rules govern the course's **knowledge version** — semver over the
+learning-facing content, independent of the `explico` engine's own version. The
+declared value is `about.version` in `content/course.config.ts`; the history and
+the reader-facing notes are in `content/CHANGELOG.md`. Both are surfaced to
+readers by the About `[?]` panel.
+
+See [README.md](README.md) for what "Build-enforced" and "Review-only" mean here.
+The engine's own versioning is a separate policy —
+[`docs/VERSIONING.md`](../VERSIONING.md).
+
+---
+
+## C1
+
+**Every content change lands with a `content/CHANGELOG.md` entry under
+`## [Unreleased]`.**
+
+A change to any lesson `.mdx`, notation entry, assessment, competency, source,
+`content/domain/` file, or `course.config.ts` gets a bullet under
+`## [Unreleased]` in the same commit.
+
+_Rationale._ The knowledge version is meaningless without a record of what moved
+between two values of it. A reader who sees "knowledge v1.4.0" in the `[?]` panel
+can follow `changelogHref` to find out what 1.4.0 means.
+
+_How to apply._ Keep a Changelog shape. One bullet per user-visible change,
+written for a reader, not a commit log:
+
+```markdown
+## [Unreleased]
+
+- Reworked the "Optimal Launch Angle" derivation to use the identity
+  `sin(2θ) = 2 sinθ cosθ` explicitly.
+- New lesson: "Projectile Range with Drag" (motion.range-drag).
+```
+
+_Enforcement._ Review-only. Rule [C3](#c3) partially enforces it: a content
+change with no matching version bump eventually trips the mismatch warning.
+
+_Exceptions._ A pure typo fix in prose that changes no rendered symbol, no
+number, and no outcome. When in doubt, add the bullet.
+
+---
+
+## C2
+
+**The knowledge version is semver over learning-facing content.**
+
+Pick the bump by the largest change in the release:
+
+- **MAJOR** — a lesson, competency, or notation `key` is removed or renamed; a
+  stated learning outcome (`teaches`, a competency `outcome`) changes; a result
+  or convention a reader may have memorised changes.
+- **MINOR** — something new and backward-compatible: a new lesson, section,
+  notation entry, assessment, or worked example.
+- **PATCH** — a fix or clarification: corrected arithmetic, better prose, a added
+  or fixed `[@source]`, a non-semantic notation tweak.
+
+_Rationale._ A downstream consumer of the content (an LMS import, a printed
+reader, a course that forks this one) needs the same "did this break me?" signal
+from the knowledge version that a library gets from a package version.
+
+_How to apply._ Decide the bump when you move `## [Unreleased]` to a dated
+heading ([C4](#c4)); set `about.version` to match.
+
+_Enforcement._ Review-only.
+
+_Exceptions._ None. If a change does not fit a tier, it is PATCH.
+
+---
+
+## C3
+
+**`about.version` equals the newest `## [x.y.z]` heading in
+`content/CHANGELOG.md`.**
+
+_Rationale._ Two sources of the same fact must not drift. The manifest — and so
+the `[?]` panel — reads `about.version`; a reader chasing "what changed" reads
+the changelog. If they disagree, one is lying.
+
+_How to apply._ On a release, edit both in the same commit ([C4](#c4)). Between
+releases, `about.version` stays at the last released value while
+`## [Unreleased]` accumulates bullets.
+
+_Enforcement._ Build-enforced (Tier-3). `pnpm validate:content` emits
+`knowledge-version-mismatch` when they differ, `knowledge-changelog-missing`
+when there is no released heading, and `knowledge-version-invalid` when
+`about.version` is not `x.y.z`. All are warnings — they never fail the build, but
+CI may choose to.
+
+_Exceptions._ None.
+
+---
+
+## C4
+
+**On a release, move `## [Unreleased]` to `## [x.y.z] - YYYY-MM-DD` and bump
+`about.version` in the same commit.**
+
+_Rationale._ A release is the atomic moment the two records agree again
+([C3](#c3)). Splitting it across commits leaves a window where the build warns
+and the panel is wrong.
+
+_How to apply._
+
+1. Choose `x.y.z` from the accumulated `## [Unreleased]` bullets and [C2](#c2).
+2. Rename the heading to `## [x.y.z] - <today>`; add a fresh empty
+   `## [Unreleased]` above it.
+3. Set `about.version` in `content/course.config.ts` to `x.y.z`.
+4. `pnpm validate:content` — no `knowledge-*` warning.
+
+_Enforcement._ Review-only (the end state is checked by [C3](#c3)).
+
+_Exceptions._ None.

package/docs/authoring/visualizations.md

@@ -0,0 +1,195 @@
+# Visualization rules
+
+`V` rules govern anything a lesson draws: diagrams, static charts, and hydrated
+interactive figures. The engine assumes no single plotting approach — these
+rules make the choice per figure predictable and keep every figure accessible
+and deterministic.
+
+See [README.md](README.md) for what "strong recommendation", "Build-enforced",
+and "Review-only" mean here, and how to amend a rule.
+
+---
+
+## V1
+
+**Graphs and flowcharts use the `Diagram` component.**
+
+Any node-and-edge picture — a derivation pipeline, a dependency graph, a state
+machine, a decision tree — is built with
+`explico/components/diagram/Diagram.astro`. It does build-time layout with
+`@dagrejs/dagre` and renders KaTeX-labelled nodes as static SVG through the same
+trust boundary as lesson math.
+
+Do not add Mermaid, cytoscape, react-flow, elkjs, or any other runtime graph or
+layout library. Nothing client-side lays out a graph.
+
+_Rationale._ One diagram primitive means node math is gate-checked and
+hover-explained exactly like prose math (an unresolved glyph fails the build
+with the node id), zero runtime layout code ships, and diagrams render
+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
+`Diagram` genuinely cannot express the picture, raise it as an engine gap
+rather than reaching for another library.
+
+_Enforcement._ Review-only.
+
+_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`.
+
+---
+
+## V2
+
+**Static charts: hand-rolled SVG first, then D3, then Observable Plot — chosen
+per figure.**
+
+- **Hand-rolled inline SVG** is the default: zero dependency, covers a single
+  bespoke figure.
+- **D3** once a figure needs real tick-labelled axes, log scales, or several
+  series sharing a scale.
+- **Observable Plot** (`@observablehq/plot`) once a course is authoring many
+  charts per lecture and the per-chart boilerplate of D3 is the bottleneck.
+
+Decide per figure. A lesson may hold an SVG sketch and a Plot chart side by
+side. Whatever the choice, the chart is produced at build time or inside a
+`client:*` island — never a CDN `<script>`.
+
+_Rationale._ The cost curve is real: SVG is free but unscalable, D3 is powerful
+but verbose, Plot is concise but a dependency and a bundle. Matching the tool to
+the figure keeps both the bundle and the authoring effort down.
+
+_How to apply._ For a static (non-interactive) chart, prefer rendering in an
+`.astro` component so nothing hydrates. Reach for an island only when the figure
+responds to input — then it is a [V3](#v3) figure.
+
+_Enforcement._ Review-only.
+
+_Exceptions._ None — this rule _is_ the exception process.
+
+---
+
+## V3
+
+**Interactive figures: a hydrated island, the `renderLabMath` seam for
+equations, and a text alternative.**
+
+An interactive figure is a React island, hydrated `client:visible` (or
+`client:idle`). It carries:
+
+- **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
+  `playground/content/labs/ProjectileRangeExplorer.tsx` +
+  `ProjectileRangeMath.astro`.
+- **An accessible name and description** — `ariaLabel` / `ariaDescription` on
+  the plot, marks that are decorative set `ariaHidden`.
+- **A text alternative.** A `<details>` block with the model's assumptions and a
+  small table of representative values, so the figure is usable with no JS and
+  by a screen reader.
+- **Labelled controls.** Every control is a labelled `<input>`; where precision
+  matters, pair a `range` slider with a `number` field (see `RangeField` in
+  `ProjectileRangeExplorer.tsx`).
+
+_Rationale._ The seam is the only reason interactive math is not a silent
+exception to the completeness gate. The text alternative and aria wiring are the
+difference between a figure and an inaccessible one.
+
+_How to apply._ Keep the island's job to "patch numbers and redraw". Domain
+math lives in a plain module (`playground/content/domain/motion.ts`), not in the
+component.
+
+_Enforcement._ Review-only.
+
+_Exceptions._ None.
+
+---
+
+## V4
+
+**A randomised figure exposes an adjustable, deterministic seed.**
+
+Any figure that draws random numbers has a visible **seed** control — an
+integer, default `0` — shown near the figure. The same seed always produces the
+same figure.
+
+_Rationale._ A figure that reshuffles on every render can't be pointed at ("look
+at the outlier near x = 3"), can't be reproduced in a question, and can't be
+regression-tested. A seed makes randomness a parameter the reader controls.
+
+_How to apply._
+
+- Thread the seed through a real PRNG (e.g. a small `mulberry32` /
+  `splitmix32`), never `Math.random()`.
+- The seed is a control like any other — a `number` field, or a slider over a
+  small range plus a field.
+- Label it plainly ("Random seed") and show its current value.
+
+_Enforcement._ Review-only.
+
+_Exceptions._ None. If the figure is deterministic, there is no seed to show.
+
+---
+
+## V5
+
+**Axis ranges span the first 10 seeds, evaluated at the current values of every
+other control.**
+
+Fix each axis `domain` explicitly. Compute it as the min and max of the plotted
+quantity over **seeds 0–9**, with every non-seed control at its current value.
+Then:
+
+- **Some points, for some seeds, will fall outside the drawn range.** That is
+  expected and fine — clip them. Do **not** autoscale the axis per seed: a
+  domain that jumps as the seed changes defeats the comparison the seed control
+  exists for.
+- **Recompute the domain when any non-seed control changes** (a slider, a
+  toggle). Its old range no longer describes the new family of curves.
+- **Do not recompute the domain when only the seed changes.** The range is a
+  property of the control setting, not of the current draw.
+- Pad the computed range by a small fixed fraction (≈ 5%) so extremes don't sit
+  on the frame.
+- Keep the sample count (`10`) a named constant so it can be tuned in one place.
+
+_Rationale._ A reader steps through seeds to see how much the outcome varies. A
+fixed frame makes that variation legible — points move, the axes don't. Ten
+seeds is enough to size the frame for the typical spread without chasing every
+tail.
+
+_How to apply._ A `useMemo` keyed on all non-seed inputs (not the seed) builds
+the domain:
+
+```ts
+const SEED_SAMPLE_COUNT = 10;
+const RANGE_PAD = 0.05;
+
+const yDomain = useMemo(() => {
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (let seed = 0; seed < SEED_SAMPLE_COUNT; seed++) {
+    for (const point of series({ ...controls, seed })) {
+      if (point.y < lo) lo = point.y;
+      if (point.y > hi) hi = point.y;
+    }
+  }
+  const pad = (hi - lo) * RANGE_PAD || 1;
+  return [lo - pad, hi + pad] as const;
+}, [controls.a, controls.b /* every non-seed control, not seed */]);
+
+// Plot.plot({ y: { domain: yDomain, ... }, ... })
+```
+
+Both axes get this treatment if both carry random spread. If one axis is a
+deterministic sweep (angle 0–90°), give it its natural domain and apply the rule
+only to the random axis.
+
+_Enforcement._ Review-only.
+
+_Exceptions._ A figure where the meaningful range is a known physical bound
+(a probability on `[0, 1]`, an angle on `[0°, 360°]`) uses that bound instead —
+state it in a comment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.2.0",
+  "version": "0.4.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",
@@ -27,8 +27,14 @@
   "files": [
     "dist",
     "src",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "docs/VERSIONING.md",
+    "docs/authoring"
   ],
+  "dependencies": {
+    "@dagrejs/dagre": "3.1.1"
+  },
   "peerDependencies": {
     "@astrojs/markdown-remark": "7.2.4",
     "@astrojs/react": "6.0.4",
@@ -38,16 +44,25 @@
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "rehype-katex": "7.0.1",
-    "remark-math": "6.0.0"
+    "remark-math": "6.0.0",
+    "remark-mdx": "3.1.1"
   },
   "devDependencies": {
+    "@astrojs/markdown-remark": "7.2.4",
     "@types/node": "24.13.3",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.5",
+    "katex": "0.16.47",
+    "rehype-katex": "7.0.1",
+    "remark-math": "6.0.0",
+    "remark-mdx": "3.1.1",
     "tsup": "8.5.1",
-    "typescript": "6.0.2"
+    "typescript": "6.0.2",
+    "vitest": "4.1.11"
   },
   "scripts": {
-    "build": "tsup && node scripts/copy-assets.mjs && node scripts/fix-esm-extensions.mjs && tsc -p tsconfig.dts-mjs.json"
+    "build": "tsup && node scripts/copy-assets.mjs && node scripts/fix-esm-extensions.mjs && tsc -p tsconfig.dts-mjs.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

package/src/compiler/astro.ts

@@ -0,0 +1,127 @@
+import { resolve, sep } from 'node:path';
+
+import type { AstroIntegration } from 'astro';
+import type { CourseConfig } from './course-config';
+import {
+  compileManifest,
+  type Manifest,
+  writeManifest,
+} from './manifest';
+
+// Vite keeps its server object across a restart. Do not accumulate watcher
+// callbacks each time Astro reloads its configuration.
+const watchedServers = new WeakSet<object>();
+
+/** 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.`,
+  );
+}
+
+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 {
+  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: ReturnType<typeof setTimeout> | undefined;
+        let restarting = false;
+
+        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);
+      },
+    },
+  };
+}