explico 0.5.0 → 0.6.0

package/docs/authoring/migrating.md

@@ -33,9 +33,141 @@ 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 N14: catalogue every abbreviation used in lesson prose
+### 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
@@ -69,14 +201,65 @@ every `abbreviation-explained` diagnostic by adding a
 `content/abbreviations/<key>.md` entry or an `allow` entry in
 `course.config.ts`.
 
-### 2. Manifest schema is v13 (additive: v10 → v11 → v12 → v13)
+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:
 
-`lessons[].lessonExports`-derived fields (v11), `manifest.abbreviations` (v12),
-and `manifest.diagnostics.rawFloats` (v13) are new. A client asserting on
-`MANIFEST_SCHEMA_VERSION` by exact equality needs the bump; nothing existing
-changed shape.
+```diff
++ import remarkAbbreviations from 'explico/reference/remark-abbreviations.mjs';
+  …
+  remarkPlugins: [
+    …
+    [remarkCitation, { sources: manifest.sources }],
++   [remarkAbbreviations, { abbreviations: manifest.abbreviations }],
+  ]
+```
 
-### 3. Optional: enable standalone HTML / print lesson exports
+### 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`:
@@ -89,7 +272,7 @@ lessonExports: {
 canonicalBaseUrl: 'https://your-course.example.com',
 ```
 
-### 4. Optional: turn on strict numbering cross-checks
+### 9. Optional: turn on strict numbering cross-checks
 
 `remarkNotation`'s new `strict: true` option — recommended via
 `createRemarkNotationOptions(manifest, { strict: true })` — fails the build on

package/docs/authoring/notation.md

@@ -131,6 +131,61 @@ _How to apply._ See the engine README's notation section and the `notation`
 collection schema. A letter that exists only so one entry's own `formula` can
 be stated is a **gloss**, not a card — it creates no curriculum edge.
 
+Do not satisfy this rule by dumping every `[[key]]` a page uses into one
+trailing "Notation used on this page" (or similarly named) section near the
+end of the lesson. `LessonFooter.astro` already injects an interactive
+"Page notation" panel — built from the page's actual notation manifest, with
+hover/click cards — into every lesson's footer automatically; a hand-written
+list repeats the same term set as flat, non-interactive prose immediately
+above it. Introduce each shared symbol inline, in the sentence where it is
+first defined or used, the way `[[eq-key]]` and other cross-references are
+already used inline elsewhere in these lessons. The completeness gate only
+checks that a `[[key]]`/`\explain{key}` appears *somewhere* in the page body
+(document order does not matter to it), but inline-at-first-use is what keeps
+the rendered page free of a redundant list — and matches what a reader
+actually wants: the symbol explained where it shows up, not gathered into an
+appendix.
+
+A page's own `notation.local` entries (declared in frontmatter) are already in
+scope everywhere on that page for the *math completeness gate* — a bare
+occurrence of a local symbol never trips "Unresolved notation" even with zero
+`[[key]]`/`\explain` references. But a **different** check,
+`assertLocalNotationParity` (run at `astro build`, not `pnpm validate:content`),
+still requires every `notation.local` entry to be *referenced* somewhere in
+the body — otherwise the build fails with "Stale Explico manifest for
+‹lesson›: lesson notation.local has […], but the page notation bundle has
+[…]." So every local entry still needs one `\explain{key}{…}` (or `[[key]]`)
+mention, even though the math gate alone wouldn't ask for it.
+
+The auto-annotator (`resolveMathGlyphs` in `math-glyphs.mjs`) re-derives every
+`\explain{…}` marker's insertion point from KaTeX's own parsed offsets, then
+re-applies those offsets to the raw source. Three shapes used to corrupt that
+offset math badly enough to either silently drop a symbol (no tooltip, no
+error) or emit unparseable output: a bare roman-label symbol (`\mathrm{SSR}`)
+could never auto-resolve at all regardless of where it sat on the page; a bare
+symbol immediately adjacent to an explicit `\explain{…}{…}` call could have
+its span swallow the whole following command; and a canonical whole-form
+match could be found _through_ an explicit call's own wrapping and extend
+past its span. All three are fixed at the resolver, not just detected — a
+bare `\mathrm{SST}`, `\epsilon\explain{feature-function}{h}`, and similar
+shapes now resolve correctly with no special authoring care required, and
+`gate-math.ts` exercises the same resolver at `pnpm validate:content` time
+(it reuses `resolveMathGlyphs` directly), so a regression here fails the
+build immediately rather than passing silently through to a render-time
+surprise.
+
+One related shape is still worth knowing, because it is a genuine authoring
+mistake rather than a resolver bug: a partial `\explain{key}{…}` wrap that
+covers only part of the key's declared `latex`. If `latex: Z_N` and you write
+`\explain{z-statistic}{Z}_N` (base wrapped, subscript left outside), the
+resolver no longer corrupts the output — but the uncovered remainder (`N`)
+has no binding of its own and correctly fails loudly as "Unresolved
+notation," at `pnpm validate:content` time. Wrap the whole declared form —
+`\explain{z-statistic}{Z_N}` — instead; bare `Z_N` elsewhere on the page then
+resolves automatically. The same applies to accent-wrapped forms
+(`latex: \widehat{\theta}`): wrap the accent and its argument together, not
+just the inner letter.
+
 Math authored inside a nested Astro component is outside the lesson MDX scan,
 so the component must declare the formula text at render time. `Diagram` and
 `NotationFormula` do this automatically from the notation keys they actually

package/docs/authoring/structure-rules.md

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

package/docs/authoring/visualizations.md

@@ -53,8 +53,8 @@ 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).
+restores the diagram; this state is remembered per page by default
+(`defaultOpen` / `rememberState` configure it).
 The title also carries the same chain-link permalink treatment as headings.
 
 By default a laid-out width above `800px` emits a compile-time warning. Treat

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Build-time engine for prerequisite-aware, notation-rigorous course content: one validated content model, a semantic notation/citation/equation system with a completeness gate, and a deterministic JSON manifest.",
   "type": "module",
   "license": "UNLICENSED",

package/src/compiler/course-config.ts

@@ -116,6 +116,43 @@ export interface CourseAbout {
   readonly changelogHref?: string;
 }
 
+/**
+ * A course's chosen initial open/closed state for the engine's own built-in
+ * collapsible sections — the "Page notation" panel (`NotationLayer.astro`)
+ * and the generated "References" section (`remark-citation.mjs`). Each is
+ * independent of `defaultCollapsible.sections`/`.subsections` (an author's
+ * own `##` headings): both of these are engine-authored, not written by a
+ * lesson, so they need their own default rather than inheriting the site's
+ * general heading default.
+ *
+ * `true` starts open, `false` (or omitted) starts closed — the engine's own
+ * default is closed either way, matching a long panel a reader usually
+ * doesn't need open on arrival.
+ */
+export interface CourseDisclosureDefaults {
+  /** Initial state of the "Page notation" panel. Default: closed. */
+  readonly notation?: boolean;
+  /** Initial state of the generated "References" section. Default: closed. */
+  readonly references?: boolean;
+}
+
+/** The stable, non-optional form `NormalizedLessonExports` mirrors. */
+export interface NormalizedDisclosureDefaults {
+  readonly notation: boolean;
+  readonly references: boolean;
+}
+
+/** Validate and canonicalize `CourseConfig.disclosureDefaults`. Absent (or
+ *  an absent sub-field) resolves to closed, the engine's own default. */
+export function normalizeDisclosureDefaults(
+  config: CourseConfig,
+): NormalizedDisclosureDefaults {
+  return {
+    notation: config.disclosureDefaults?.notation === true,
+    references: config.disclosureDefaults?.references === true,
+  };
+}
+
 /** Optional, build-time lesson artifacts exposed to readers. */
 export interface LessonExportsConfig {
   /** Emit one self-contained, offline-capable HTML file per lesson. */
@@ -162,6 +199,9 @@ export interface CourseConfig {
   readonly abbreviations?: CourseAbbreviations;
   /** Per-lesson export actions and downloadable artifacts. Disabled when omitted. */
   readonly lessonExports?: LessonExportsConfig;
+  /** Initial open/closed state for the engine's own built-in collapsible
+   *  sections ("Page notation", "References"). Closed when omitted. */
+  readonly disclosureDefaults?: CourseDisclosureDefaults;
 }
 
 /** Validate and canonicalize the build-facing lesson-export configuration. */

package/src/compiler/manifest.ts

@@ -88,6 +88,7 @@ import {
   gateProseNotationInAssessments,
 } from '../reference/gate-prose-notation';
 import { gateAbbreviations } from '../reference/gate-abbreviations';
+import { gateHeadingLength } from '../reference/gate-heading-length';
 import {
   splitMixedContent,
   type ContentSegment,
@@ -109,8 +110,10 @@ import type {
 import {
   coursePartsOf,
   normalizeLessonExports,
+  normalizeDisclosureDefaults,
   type CourseConfig,
   type NormalizedLessonExports,
+  type NormalizedDisclosureDefaults,
 } from './course-config';
 import {
   resolveKnowledgeVersion,
@@ -177,8 +180,14 @@ import {
  * validation and can never get a stable number or `[[…]]` reference; this
  * flags it (warning-only — the manifest shape a client already reads is
  * unchanged).
+ * v14 (disclosure defaults, additive): `disclosureDefaults` — the resolved
+ * initial open/closed state for the "Page notation" panel and the generated
+ * "References" section, from `CourseConfig.disclosureDefaults`. Both are
+ * engine-authored sections, not written by a lesson, so they get their own
+ * default independent of a course's `##` heading default; closed unless the
+ * course sets one.
  */
-export const MANIFEST_SCHEMA_VERSION = 13;
+export const MANIFEST_SCHEMA_VERSION = 14;
 
 const REPOSITORY_ROOT = process.cwd();
 // Content is the top-level `content/` folder; the build output is `build/`
@@ -382,6 +391,8 @@ export interface Manifest {
   readonly schemaVersion: number;
   /** Normalized build/UI settings for opt-in per-lesson exports. */
   readonly lessonExports: NormalizedLessonExports;
+  /** Initial open/closed state for "Page notation" and "References". */
+  readonly disclosureDefaults: NormalizedDisclosureDefaults;
   /** Reader-facing identity + versions (the `[?]` About panel). */
   readonly about: ManifestAbout;
   readonly notation: {
@@ -703,6 +714,7 @@ export async function compileManifest(
       abbreviations: abbreviationsInput,
       courseAbbreviations: courseConfig.abbreviations,
     }),
+    ...gateHeadingLength(notationInput.lessons),
   ];
 
   // Pre-render every assessment `prompt` / `explanation` into text/math
@@ -1052,6 +1064,7 @@ export async function compileManifest(
   return {
     schemaVersion: MANIFEST_SCHEMA_VERSION,
     lessonExports: normalizeLessonExports(courseConfig),
+    disclosureDefaults: normalizeDisclosureDefaults(courseConfig),
     about,
     notation: {
       definitions: registry.definitions,

package/src/components/diagram/Diagram.astro

@@ -70,12 +70,6 @@ export interface Props {
    * Set `false` only when horizontal overflow is deliberate. Default: `800`.
    */
   warnAboveWidth?: number | false;
-  /**
-   * Prose text alternative for the SVG. When omitted, the fallback is
-   * generated from the node labels and the edge chain — readable, but a
-   * hand-written sentence usually reads better for a screen-reader user.
-   */
-  description?: string;
 }
 
 const {
@@ -85,7 +79,6 @@ const {
   edges,
   scope = [],
   direction = 'TB',
-  description,
   number,
   anchorId,
   defaultOpen = true,
@@ -190,12 +183,6 @@ if (warnAboveWidth !== false && layout.width > warnAboveWidth) {
   );
 }
 
-/** A node's human label for the text fallback — never the internal id. */
-function fallbackLabel(nodeId: string): string {
-  const node = nodeById.get(nodeId);
-  return node?.text ?? node?.formula ?? nodeId;
-}
-
 function pathFrom(points: readonly { x: number; y: number }[]): string {
   if (points.length === 0) return '';
   const [first, ...rest] = points;
@@ -318,33 +305,6 @@ function pathFrom(points: readonly { x: number; y: number }[]): string {
             </div>
           </div>
         </div>
-
-        <details class="diagram-fallback">
-          <summary>Diagram description</summary>
-          {
-            description ? (
-              <p>{description}</p>
-            ) : (
-              <Fragment>
-                <ol>
-                  {rendered.map((node) => (
-                    <li>{fallbackLabel(node.id)}</li>
-                  ))}
-                </ol>
-                {edges.length > 0 && (
-                  <p class="diagram-fallback-flow">
-                    {edges.map((edge, index) => (
-                      <Fragment>
-                        {index > 0 && '; '}
-                        {fallbackLabel(edge.from)} → {fallbackLabel(edge.to)}
-                      </Fragment>
-                    ))}
-                  </p>
-                )}
-              </Fragment>
-            )
-          }
-        </details>
       </div>
     </details>
 
@@ -635,21 +595,6 @@ function pathFrom(points: readonly { x: number; y: number }[]): string {
       fill: var(--sl-color-gray-4);
     }
 
-    .diagram-fallback {
-      margin-block-start: 0.5rem;
-      color: var(--sl-color-gray-3);
-      font-size: var(--sl-text-sm);
-    }
-
-    .diagram-fallback ol,
-    .diagram-fallback p {
-      margin: 0.35rem 0 0;
-    }
-
-    .diagram-fallback ol {
-      padding-inline-start: 1.25rem;
-    }
-
     @media print {
       .diagram-toolbar,
       .diagram__title-anchor,