explico 0.4.0 → 0.6.0

package/docs/authoring/migrating.md

@@ -1,15 +1,29 @@
 # Upgrading the explico engine
 
-What a course repo has to change when it bumps its `explico` dependency across a
-version that carries **Breaking** notes. Each section is the concrete work; the
-matching `CHANGELOG.md` entry (shipped in the installed package) is the full
-list of what moved and why.
+This is the agent-readable migration artifact shipped with `explico`. It lives
+at `node_modules/explico/docs/authoring/migrating.md` in an installed course, so
+the instructions always accompany the engine version they describe.
+
+There is one newest-first section for **every** published version, not only for a
+version whose changelog contains **Breaking** notes. A section contains the
+concrete work for consumer-owned content, configuration, source wiring, scripts,
+dependencies, and generated artifacts. When a release needs none of those, its
+section says **No course changes required** explicitly. The matching
+`CHANGELOG.md` entry (also shipped in the package) remains the full list of what
+moved and why; it is context, not a replacement for these steps.
 
 The pattern every time:
 
-1. `pnpm add -D explico@<version>`
-2. Do the per-version steps below.
-3. `pnpm validate:content` (run it **twice** — the first run regenerates
+1. Record the currently installed version before changing it:
+   `node -p "require('explico/package.json').version"`.
+2. `pnpm add -D explico@<version>`.
+3. Read this file from the newly installed package and apply **every** section
+   after the old version through the target version, oldest first. Do not skip a
+   section merely because its changelog entry is not labelled **Breaking**.
+4. Make every required course-side change named by those sections, including
+   changes under `content/`, Astro/source configuration, and course scripts; do
+   not stop after changing the dependency declaration.
+5. `pnpm validate:content` (run it **twice** — the first run regenerates
    `build/resolution/*` and reports it stale; the second is clean), then
    `pnpm content check --changed`, then `astro check`, then `astro build`.
    Each stage names what it doesn't like; fix and re-run.
@@ -19,6 +33,260 @@ required config block throws with the section of this file to read.
 
 ---
 
+## 0.5.0 → 0.6.0
+
+### 1. Rule S1: no heading or float title runs past 65 characters
+
+Every Markdown heading (`##` through `######`), a lesson's own
+`frontmatter.title`, and the `title`/`label` prop on `Figure`, `Diagram`,
+`Memo`, and `ShortNote` is now capped at 65 characters; `Table` is exempt (it
+has only a `caption`). No wiring is required — the check runs as part of
+`pnpm validate:content` / `astro build` the same as N9/N13/N15. Audit for
+existing violations and shorten them, moving the rest of the sentence into
+the paragraph after a heading or into a float's `caption`. See
+[`docs/authoring/structure-rules.md#s1`](structure-rules.md#s1).
+
+### 2. Removed markup: `.notation-pin`, `[data-notation-control]`, `.notation-layer-heading`
+
+The "Page notation" panel's "Pin explanation" button (`.notation-pin`,
+`[data-notation-control]`) and its separate `<h2>` (`.notation-layer-heading`)
+are both gone from the rendered DOM. Pinning a card now works the same way an
+inline prose symbol always has — click its glyph — and the panel's
+`<summary>` is its only heading. Update any course-owned CSS or end-to-end
+test that targets these selectors; no other action is required.
+
+### 3. Removed prop: `<Diagram description>`
+
+`Diagram`'s `description` prop and its collapsed "Diagram description"
+fallback block (`.diagram-fallback`) no longer exist. `astro check` fails on
+an excess prop, so remove every `description="…"` passed to `<Diagram>`; fold
+that text into the diagram's `label` (caption) instead.
+
+### 4. Optional: collapsible "Page notation" panel and References section
+
+`NotationLayer` gains `defaultOpen`/`rememberState` props (mirroring
+`Figure`'s own), and `remark-citation.mjs`'s generated References heading now
+accepts a `defaultOpen` plugin option — both ride the same persisted,
+deep-linkable disclosure machinery `Figure`/`CollapsibleSections` already use,
+in place of the previous always-native-default `<details>`. No action is
+required to keep building: both default to closed, matching prior behavior,
+and the References option only takes effect on a course whose
+`astro.config.mjs` already wires `rehypeHeadingAnchors` into its rehype
+pipeline. To opt into a different default, set `CourseConfig.disclosureDefaults`:
+
+```ts
+disclosureDefaults: {
+  notation: true, // "Page notation" panel starts open for a reader with nothing saved yet
+  references: true, // generated References section starts open
+},
+```
+
+### 5. Manifest schema is now v14 (additive: v13 → v14)
+
+`CourseConfig.disclosureDefaults` is new and additive — nothing existing
+changed shape — but a client asserting on `MANIFEST_SCHEMA_VERSION` by exact
+equality needs the bump.
+
+### 6. Re-run `pnpm validate:content` — the notation auto-annotator's silent-failure bugs are fixed
+
+Several shapes that previously either dropped a symbol's tooltip silently (no
+build error) or produced malformed output are now fixed at the resolver
+(`resolveMathGlyphs`), not just documented as traps to avoid: a bare
+`\mathrm{…}`-only symbol (`\mathrm{SSR}`, `\mathrm{SST}`) can now auto-resolve
+at every later bare occurrence, a bare symbol immediately next to an
+`\explain{…}{…}` call no longer has its span corrupted, and a partial
+`\explain{key}{…}` wrap no longer produces unparseable doubled output. No
+course-side wiring changes, but re-running `pnpm validate:content` may surface
+two new classes of error that previously passed silently:
+
+- **"Unresolved notation"** for a symbol that was relying on one of the fixed
+  bugs to appear resolved when it was not (rare — the bugs mostly hid symbols
+  entirely rather than falsely resolving them) or for the uncovered remainder
+  of a partial `\explain{key}{…}` wrap. Fix by explaining the symbol, or by
+  wrapping the key's *entire* declared `latex`, not just its base glyph.
+- **"Page glyphs … have structurally identical LaTeX"** for two different
+  notation keys whose declared `latex` is the same `\operatorname{…}` or
+  `\mathrm{…}` form (e.g. two keys both `\operatorname{Var}`) — this check
+  previously silently skipped every such glyph and could not catch this. Give
+  the colliding keys distinct canonical forms, or reach for
+  `\explain{key}{…}` at every occurrence of whichever one keeps the shared
+  form.
+
+## 0.4.x → 0.5.0
+
+### 1. Rule N9: wrap every plain-text quantity, unit, and operator in `$…$`
+
+Every physical quantity, unit abbreviation, or math operator ever typed as
+plain text — in lesson prose, a table cell, or (new in 0.5.0) an assessment
+item's `prompt` / `explanation` string — must now be inside `$…$`. `45 m/s`,
+`t (s)`, `vx`, `\|v\|`, `KE/m` are all the same mistake. This is build-enforced
+with **no `lint-ignore.yml` escape hatch**: `pnpm validate:content` / `astro
+build` fails on every existing violation. Fix per
+[`docs/authoring/notation.md#n9`](notation.md#n9) — wrap the symbol in `$…$`
+and fold its unit into the *same* span as `\text{}` (`$t\ \text{(s)}$`, not two
+adjacent spans).
+
+Also wire the accessible-table-header plugin this rule ships with — the build
+works without it, but a table header that is now 100% KaTeX (a bare `$t$`
+column, since its unit moved inside `$…$` too) renders with no
+screen-reader-visible name until this is wired:
+
+```diff
++ import rehypeTableHeaderLabels from 'explico/reference/rehype-table-header-labels.mjs';
+  …
+  rehypePlugins: [
+    [rehypeKatex, createNotationKatexOptions()],
+    rehypeFailKatexErrors,
++   rehypeTableHeaderLabels,
+  ]
+```
+
+It reads the `\explain{key}{…}` key(s) a header's LaTeX names and backfills an
+`sr-only` label from that key's notation metadata — the one prerequisite is
+that the header's symbol resolves to a key at all, so a `\mathrm{…}` compound
+(`\mathrm{KE}/m`) needs each side explicitly `\explain{}`-wrapped.
+
+### 2. Rule N13: a nonlinear function always takes a parenthesized argument
+
+`\sin x`, `\log t`, `\exp\theta` — every trig/inverse-trig/hyperbolic function
+plus `exp`/`log`/`ln`/`lg` — is now a hard error unless its argument is
+parenthesized: `\sin(x)` or `\sin\left(x\right)` is required. Same enforcement
+shape as N9: build-enforced, no `lint-ignore.yml` escape. It fires on lesson
+body math, `notation.formula`, assessment `prompt`/`explanation`, `Diagram`
+formulas, and interactive lab math alike, since all of them resolve through
+the same glyph walker. Fix every occurrence; see
+[`docs/authoring/notation.md#n13`](notation.md#n13).
+
+### 3. Rule N15: size every level of a nested visible delimiter
+
+Once a `(`, `[`, `\{`, or `|` sits inside another one of those four — same
+type or mixed, e.g. `(a + [b])` — **every level of that nest** must switch to
+`\left`/`\right` sizing: `\sin(2(90°-\theta))` is now a hard error,
+`\sin\left(2\left(90°-\theta\right)\right)` is required. Same enforcement
+shape as N9/N13: build-enforced, no escape hatch. A single, non-nested bare
+delimiter (`(x)`) is untouched. Fix every nest; see
+[`docs/authoring/notation.md#n15`](notation.md#n15).
+
+### 4. Rule N14: catalogue every abbreviation used in lesson prose
+
+Every acronym (`OLS`, `MSE`) or dotted abbreviation (`w.r.t.`, `i.i.d.`) used in
+plain prose must now be on the shipped baseline
+(`base-abbreviations.mjs`), listed in `course.config.ts`'s new
+`abbreviations.allow` / `abbreviations.deny`, given an entry in the new
+`content/abbreviations/*.md` collection, or already explained as a math
+quantity via N8/N10. This is build-enforced, same error-severity and
+no-`lint-ignore.yml`-escape-hatch shape as N9.
+
+```ts
+export const courseConfig = {
+  // …existing fields…
+  abbreviations: {
+    allow: ['GDP'],   // treat as universal, skip the check
+    deny: ['ETA'],    // demote a baseline entry back to "must be explained"
+  },
+} satisfies CourseConfig;
+```
+
+```markdown
+---
+key: ols
+abbr: OLS
+expansion: Ordinary least squares
+aliases: []
+---
+```
+
+Run `pnpm validate:content` (twice) and `pnpm content check --changed`. Fix
+every `abbreviation-explained` diagnostic by adding a
+`content/abbreviations/<key>.md` entry or an `allow` entry in
+`course.config.ts`.
+
+The catalog check above runs regardless of Astro wiring, but the inline
+hover/click card on a lesson page's first occurrence of a catalogued
+abbreviation needs its remark plugin wired in too:
+
+```diff
++ import remarkAbbreviations from 'explico/reference/remark-abbreviations.mjs';
+  …
+  remarkPlugins: [
+    …
+    [remarkCitation, { sources: manifest.sources }],
++   [remarkAbbreviations, { abbreviations: manifest.abbreviations }],
+  ]
+```
+
+### 5. Optional: rule N10 warns on an unexplained `\mathrm{…}` label
+
+A `\mathrm{…}` multi-letter label (`\mathrm{KE}`, `\mathrm{PV}`) not on the
+shipped roman-label baseline (`base-roman-labels.mjs`) or `course.config.ts`'s
+new `romanLabels.allow` now needs a notation entry the reader can hover — the
+`\mathrm{…}` counterpart to N8. Unlike N9/N13/N14/N15, this is a **Tier-3
+warning** (`roman-label-explained`), not a build failure: it never blocks
+`astro build`, and an existing violation can be silenced with a reviewed
+`lint-ignore.yml` line (`roman-label-explained:KE — <reason>`) while content is
+cleaned up. `pnpm validate:content` surfaces it. See
+[`docs/authoring/notation.md#n10`](notation.md#n10).
+
+### 6. Only if you render `AssessmentRunner` directly (bypassing `AssessmentSet.astro`)
+
+`AssessmentRunner`'s `Item` props changed shape: `prompt` / `explanation`
+(`string`) are now `promptContent` / `explanationContent`
+(`MixedContentNode[]`), rendered with the new `RenderedContent` component,
+because `AssessmentSet.astro` now pre-renders assessment math through the same
+KaTeX pipeline as lesson body math instead of handing `AssessmentRunner` a raw
+string. A course that only uses `<AssessmentSet>` needs no change here — this
+only applies to a course that imports and renders `AssessmentRunner` itself.
+
+### 7. Manifest schema is v13 (additive: v7 → v8 → v9 → v10 → v11 → v12 → v13)
+
+Every step is additive — nothing existing changed shape — but a client
+asserting on `MANIFEST_SCHEMA_VERSION` by exact equality needs the final
+number:
+
+- **v8** — `assessmentContent`: every assessment item's `prompt` /
+  `explanation`, pre-split and resolved for `AssessmentSet.astro` (see item 6
+  above).
+- **v9** — `diagrams`, `lessons[].diagrams`, `lessons[].numbering.diagrams`,
+  `diagnostics.diagrams`: `<Diagram>` becomes a first-class keyed float with
+  its own number stream and `[[dia-<id>]]` references.
+- **v10** — `checks`, `lessons[].knowledgeChecks`, `lessons[].numbering.checks`,
+  `diagnostics.checks`: numbered, referenceable knowledge checks.
+- **v11** — `lessons[].lessonExports`-derived fields: standalone HTML / print
+  export settings (item 8 below).
+- **v12** — `manifest.abbreviations` (rule N14, item 4 above).
+- **v13** — `manifest.diagnostics.rawFloats`: a raw Markdown/HTML table, an
+  unkeyed `<Diagram>`, or a `<Diagram>` nested outside
+  `<Memo>`/`<ShortNote>`/`<Table>`/`<Figure>` — none of these reach
+  keyed-float validation, so this diagnostic flags them separately.
+
+### 8. Optional: enable standalone HTML / print lesson exports
+
+No action required to keep building. To opt in, add to
+`content/course.config.ts`:
+
+```ts
+lessonExports: {
+  standaloneHtml: true,
+  print: true,
+},
+canonicalBaseUrl: 'https://your-course.example.com',
+```
+
+### 9. Optional: turn on strict numbering cross-checks
+
+`remarkNotation`'s new `strict: true` option — recommended via
+`createRemarkNotationOptions(manifest, { strict: true })` — fails the build on
+any catalogued lesson that has an equation, `<Table>`, or `<Figure>` (keyed or
+not) with no placement, instead of silently falling back to legacy `##`-section
+numbering. Off by default; turn it on once existing content is clean.
+
+### Verification
+
+`pnpm validate:content` (run it twice), then `pnpm content check --changed`,
+then `astro check`, then `astro build`.
+
+---
+
 ## 0.3.x → 0.4.0
 
 ### 1. Rename `sections` to `parts` in `content/course.config.ts`