explico 0.3.0 → 0.4.0

package/dist/reference/remark-notation.mjs

@@ -671,26 +671,146 @@ function inspectExplainCalls(value, resolve, file, node, references) {
   }
 }
 
+/**
+ * The numbering inputs a lesson page needs, read off one manifest.
+ *
+ * Every number on a page comes from two places that MUST agree: the page's own
+ * counters (`numbering`) and the manifest tables a cross-page `[[slug#eq-key]]`
+ * is resolved against (`equations` / `tables` / `figures`). Deriving all four
+ * from the same manifest in one step is what stops a course config from
+ * supplying one without the other — the omission that produced page-local
+ * `(2.2)` and cross-page `(4.5)` for the same equation.
+ *
+ * `numbering` maps a lesson slug to `{ part, equations, tables, figures }`:
+ * the part's ordinal (the number before the dot) and, per kind of float, how
+ * many of them the earlier lessons of that part already used.
+ */
+export function numberingFromManifest(manifest) {
+  if (!manifest || typeof manifest !== 'object') return {};
+  return {
+    equations: manifest.equations?.numbersBySlug ?? {},
+    tables: manifest.tables?.numbersBySlug ?? {},
+    figures: manifest.figures?.numbersBySlug ?? {},
+    numbering: Object.fromEntries(
+      (manifest.lessons ?? []).map((lesson) => [
+        lesson.slug,
+        {
+          part: lesson.part,
+          equations: lesson.numbering?.equations ?? 0,
+          tables: lesson.numbering?.tables ?? 0,
+          figures: lesson.numbering?.figures ?? 0,
+        },
+      ]),
+    ),
+  };
+}
+
+/**
+ * `{ prefix, offset }` for one kind of float on one page, from whichever
+ * numbering option the caller supplied. `numbering` is the current form;
+ * `chapters` is the superseded per-lesson form (prefix = the lesson's ordinal,
+ * no offset) and is still read so an unmigrated config keeps working.
+ */
+function pageNumbering(options, slug, kind) {
+  if (!slug) return undefined;
+  const placement = options.numbering?.[slug];
+  if (placement?.part) {
+    return { prefix: placement.part, offset: placement[kind] ?? 0 };
+  }
+  const chapter = options.chapters?.[slug];
+  return chapter ? { prefix: chapter, offset: 0 } : undefined;
+}
+
+/**
+ * Fail when the number this page just computed for a keyed float disagrees
+ * with the number the manifest publishes for the same key (WERN — a reference
+ * that shows a different number than its target). The two are produced by the
+ * same algorithm from the same content, so any disagreement means the render
+ * path and the manifest were fed different inputs; in practice, an
+ * `astro.config.mjs` that passes the manifest number tables but not
+ * `numbering`, which silently drops the page back to the legacy `##`-section
+ * scheme.
+ */
+function assertManifestNumberParity({
+  file,
+  slug,
+  pageLabels,
+  crossPage,
+  placement,
+  noun,
+  syntax,
+}) {
+  // No entry for this slug at all means the caller supplied no manifest table
+  // (hand-built test trees, non-lesson pages) — nothing to cross-check.
+  const published = crossPage?.[slug];
+  if (!published) return;
+
+  for (const [key, number] of pageLabels) {
+    const expected = published[key];
+    if (expected === undefined) {
+      fail(
+        file,
+        `Stale Explico manifest for ${slug}: this page numbers ${noun} ` +
+          `${syntax(key)} as (${number}), but the manifest lists no such ` +
+          `${noun} for the lesson. Recompile the manifest before rendering.`,
+      );
+    }
+    if (expected !== number) {
+      fail(
+        file,
+        `Inconsistent ${noun} numbering for ${syntax(key)} in ${slug}: this ` +
+          `page renders it as (${number}) while a cross-page reference to it ` +
+          `resolves to (${expected}). ` +
+          (placement === undefined
+            ? 'The remarkNotation options carry the manifest number tables ' +
+              'but no `numbering` entry for this lesson, so the page fell ' +
+              'back to the legacy `##`-section scheme. Pass `manifest` to ' +
+              'remarkNotation so both sides use the part scheme.'
+            : 'The page counters and the manifest disagree; recompile the ' +
+              'manifest from the current content.'),
+      );
+    }
+  }
+}
+
 /**
  * @param {{
  *   definitions?: Map<string, object> | readonly object[] | Record<string, object> | (() => Map<string, object> | readonly object[] | Record<string, object>),
  *   resolve?: (key: string, context: object) => object | undefined,
  *   unknown?: 'error' | 'warn' | 'ignore',
  *   base?: string,
+ *   manifest?: object,
  *   equations?: Record<string, Record<string, string>>,
  *   tables?: Record<string, Record<string, string>>,
  *   figures?: Record<string, Record<string, string>>,
+ *   numbering?: Record<string, { part: number, equations: number, tables: number, figures: number }>,
  *   chapters?: Record<string, number>,
  * }} [options]
  *
- * `chapters` maps a lesson slug to its 1-based course ordinal. When the
- * current page has one, every display equation / `<Table>` / `<Figure>` is
- * numbered `‹chapter›.‹n›` (`##` headings ignored); with no entry the legacy
- * `##`-section scheme applies. It must agree with `manifest.lessons[].chapter`,
- * which is what feeds `equations`/`tables`/`figures` above.
+ * `manifest` is the preferred wiring: pass the compiled manifest and the four
+ * numbering inputs below are read off it together, so they cannot drift apart.
+ * They stay available individually for hand-built trees, and an explicitly
+ * supplied one still wins over the manifest.
+ *
+ * `numbering` maps a lesson slug to its **part** (the number before the dot)
+ * and, per kind of float, how many the earlier lessons of that part already
+ * used. Every display equation / `<Table>` / `<Figure>` on the page is then
+ * numbered `‹part›.‹offset + n›`, with `##` and `###` headings ignored; with no
+ * entry the legacy `##`-section scheme applies. It must agree with
+ * `manifest.lessons[]`, which is what feeds `equations`/`tables`/`figures`
+ * above — supplying the tables without `numbering` numbers the same equation
+ * twice, and `assertManifestNumberParity` turns that into a build error rather
+ * than a page whose references disagree with their targets.
+ *
+ * `chapters` is the superseded per-lesson form (slug → the lesson's course
+ * ordinal, no running offset). Still read when `numbering` has no entry, so a
+ * config written against the old option keeps building.
  */
 export default function remarkNotation(options = {}) {
   const unknown = options.unknown ?? 'error';
+  // The manifest supplies every numbering input at once; an explicit option
+  // still overrides it, so existing per-field wiring keeps working.
+  const numbering = { ...numberingFromManifest(options.manifest), ...options };
 
   return function transform(tree, file) {
     const suppliedDefinitions =
@@ -703,10 +823,10 @@ export default function remarkNotation(options = {}) {
     );
     const localDefinitions = localDefinitionsFromFile(file);
     const lessonId = lessonIdFrom(file);
-    // The lesson's course ordinal (see the `chapters` option). Falsy / missing
-    // ⇒ the legacy `##`-section numbering, so `0` and `undefined` behave alike.
-    const chapter =
-      (lessonId && options.chapters?.[lessonId.replace(/\./g, '/')]) || undefined;
+    const lessonSlug = lessonId ? lessonId.replace(/\./g, '/') : undefined;
+    // `{ prefix, offset }` per kind of float — see the `numbering` option.
+    // Missing ⇒ the legacy `##`-section numbering.
+    const equationNumbering = pageNumbering(numbering, lessonSlug, 'equations');
     const registryFile = isNotationRegistryFile(file);
     const mathScope = pageGlyphScope(
       localDefinitions,
@@ -718,8 +838,9 @@ export default function remarkNotation(options = {}) {
 
     // Equation identity (D7): assign every `\label{eq:…}` its number before any
     // math node is rewritten, so a `[[eq-key]]` earlier in the page still
-    // resolves. `chapter` picks the `‹chapter›.‹n›` vs `##`-section scheme.
-    const equationLabels = collectEquationLabels(tree, chapter);
+    // resolves. `equationNumbering` picks the `‹part›.‹n›` vs `##`-section
+    // scheme.
+    const equationLabels = collectEquationLabels(tree, equationNumbering);
     const pageLabels = new Map();
     for (const label of equationLabels) {
       if (pageLabels.has(label.key)) {
@@ -734,14 +855,25 @@ export default function remarkNotation(options = {}) {
     const eqCtx = {
       base: options.base ?? '',
       pageLabels,
-      crossPage: options.equations ?? {},
+      crossPage: numbering.equations ?? {},
     };
+    // WERN guard: what this page prints next to the equation must be what a
+    // reference from another page prints for it.
+    assertManifestNumberParity({
+      file,
+      slug: lessonSlug,
+      pageLabels,
+      crossPage: eqCtx.crossPage,
+      placement: equationNumbering,
+      noun: 'equation',
+      syntax: (key) => `eq:${key}`,
+    });
 
     // Number and anchor every display equation on a lesson page, keyed or
     // not (F3). Non-lesson pages (notation registry, stray docs) keep the
     // keyed-only behaviour so their body math is left untouched.
     const displayEquations = lessonId
-      ? collectDisplayEquations(tree, chapter)
+      ? collectDisplayEquations(tree, equationNumbering)
       : [];
     const equationByNode = new Map(
       displayEquations.map((equation) => [equation.node, equation]),
@@ -750,9 +882,10 @@ export default function remarkNotation(options = {}) {
     // Keyed floats (F-tables-figures): every `<Table>`/`<Figure>` on a lesson
     // page is numbered and anchored, keyed or not — same rule as equations,
     // via the shared engine in `keyed-jsx-floats.mjs`.
-    const makeFloatCtx = (tagName, crossPage) => {
+    const makeFloatCtx = (tagName, crossPage, kind) => {
+      const floatNumbering = pageNumbering(numbering, lessonSlug, kind);
       const floats = lessonId
-        ? collectKeyedJsxFloats(tree, { tagName, chapter })
+        ? collectKeyedJsxFloats(tree, { tagName, numbering: floatNumbering })
         : [];
       const pageFloatLabels = new Map();
       for (const float of floats) {
@@ -766,6 +899,15 @@ export default function remarkNotation(options = {}) {
         }
         pageFloatLabels.set(float.key, float.number);
       }
+      assertManifestNumberParity({
+        file,
+        slug: lessonSlug,
+        pageLabels: pageFloatLabels,
+        crossPage: crossPage ?? {},
+        placement: floatNumbering,
+        noun: tagName,
+        syntax: (key) => `<${tagName} id="${key}">`,
+      });
       return {
         ctx: {
           base: options.base ?? '',
@@ -777,11 +919,13 @@ export default function remarkNotation(options = {}) {
     };
     const { ctx: tableCtx, byNode: tableByNode } = makeFloatCtx(
       'Table',
-      options.tables,
+      numbering.tables,
+      'tables',
     );
     const { ctx: figureCtx, byNode: figureByNode } = makeFloatCtx(
       'Figure',
-      options.figures,
+      numbering.figures,
+      'figures',
     );
 
     const resolve = (key, kind, node) => {

package/docs/authoring/README.md

@@ -38,6 +38,10 @@ this folder, reviewed like any other change.
 
 ## How a rule is written
 
+[`structure.md`](structure.md) is not a rule set — it is the taxonomy the rules
+speak in: what a part, a chapter, a section, and a subsection are, and which of
+them an equation number counts.
+
 Each rule has a stable ID — a letter for its area (`N` notation,
 `V` visualizations, `C` versioning) plus a number — and this shape:
 

package/docs/authoring/migrating.md

@@ -19,6 +19,68 @@ required config block throws with the section of this file to read.
 
 ---
 
+## 0.3.x → 0.4.0
+
+### 1. Rename `sections` to `parts` in `content/course.config.ts`
+
+A sidebar group is now a **part** — "section" only ever means an `##` heading
+inside a lesson. See [`structure.md`](structure.md) for the full taxonomy.
+
+```diff
+-  sections: [
++  parts: [
+     { dir: 'foundations', label: 'Foundations' },
+     { dir: 'bonds', label: 'Bonds' },
+   ],
+```
+
+`sections` is still read, so this is not urgent; it is removed in the next
+MINOR release.
+
+### 2. Pass the manifest to `remarkNotation`
+
+Replace the individual numbering options with the manifest itself. This is what
+guarantees the number a page prints and the number a reference to it prints are
+computed from the same inputs — supplying one without the other is what made an
+equation read `(2.2)` on its own page and `(4.5)` everywhere else.
+
+```diff
+   [remarkNotation, {
+     definitions: manifest.notation.raw,
+-    equations: manifest.equations.numbersBySlug,
++    manifest,
+     base: publicBase,
+   }],
+```
+
+The engine now cross-checks the two and **fails the build** when they disagree,
+so a config left half-wired errors instead of shipping wrong numbers.
+
+### 3. Expect every equation, table, and figure number to change
+
+Numbers are now `‹part›.‹n›`: the prefix is the part's ordinal, and `n` runs
+across the whole part rather than restarting on each page. A course whose
+lessons were chapters 1…16 now has as many prefixes as it has sidebar groups.
+
+Nothing in `content/` needs editing — numbers were never hand-typed, and every
+`[[eq-key]]` / `[[slug#eq-key]]` reference keeps resolving. Two things to check:
+
+- **Prose that spells a number out** ("as equation 4.5 showed") was already
+  against rule N-references; find it with `grep -rnE '\((1?[0-9])\.[0-9]+\)'
+  content/` and convert it to a `[[eq-key]]` reference.
+- **External links to a positional anchor** (`#eq-2-4`, an *unkeyed* equation)
+  now point elsewhere. Keyed anchors (`#eq-<key>`) are stable and unaffected —
+  give an equation a `\label{eq:…}` if you need to link to it from outside.
+
+### 4. Manifest schema is v7
+
+`lessons[].part` is new; `lessons[].chapter` now means the lesson's ordinal
+*within its part*, not down the whole course; `lessons[].numbering` carries the
+running float counts each chapter starts from. A client asserting on
+`MANIFEST_SCHEMA_VERSION` needs the bump.
+
+---
+
 ## 0.2.x → 0.3.0
 
 ### 1. Add the required `about` block to `content/course.config.ts`

package/docs/authoring/notation.md

@@ -147,13 +147,14 @@ If prose points back at a display equation — this page or another — the equa
 has `\label{eq:key}` and the reference is `[[eq-key]]`. Do not hand-number
 equations in the text.
 
-_Rationale._ The engine numbers every display equation `‹chapter›.‹n›` — the
-chapter is the lesson's position in the course, `n` counts the display
-equations in the lesson in appearance order (`##` sub-headings do not affect
-it) — and derives the anchor and any cross-lesson link from the label. A
-hand-typed "(3)" goes stale the moment an equation is inserted above it, or the
-lesson moves in the course order. `<Table>` and `<Figure>` are numbered the
-same way, each with its own counter.
+_Rationale._ The engine numbers every display equation `‹part›.‹n›` — the part
+is the sidebar group's position in `courseConfig.parts`, `n` counts the display
+equations across that whole part in appearance order, continuing from one
+chapter into the next (`##` and `###` headings do not affect it; see
+[`structure.md`](structure.md)) — and derives the anchor and any cross-lesson
+link from the label. A hand-typed "(3)" goes stale the moment an equation is
+inserted above it, or the chapter moves within its part. `<Table>` and
+`<Figure>` are numbered the same way, each with its own counter.
 
 _How to apply._ Only label equations you actually reference; an unlabelled
 display equation is still fine.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.3.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",

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);
+      },
+    },
+  };
+}

package/src/compiler/cli.ts

@@ -221,15 +221,11 @@ function processorFor(manifest: Manifest) {
       // shape here that it does there (D7/F-tables-figures parity).
       remarkMdx,
       remarkMath,
-      [
-        remarkNotation,
-        {
-          definitions: manifest.notation.raw,
-          equations: manifest.equations.numbersBySlug,
-          tables: manifest.tables.numbersBySlug,
-          figures: manifest.figures.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: [