explico 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -14,6 +14,385 @@ under **Breaking** below; a PATCH never breaks.
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-16
+
+### Breaking
+
+- **New build-enforced authoring rule S1: no Markdown heading (`##` through
+  `######`) and no `<Figure title>` / `<Diagram label>` / `<Memo title>` /
+  `<ShortNote title>` may run past 65 characters.** A `<Figure>` with a long
+  `caption` and no explicit `title` was silently using the whole caption as
+  its always-visible collapsible title-bar text — the reader saw the full
+  sentence twice. `gate-heading-length.ts` scans every lesson body; a course
+  with an over-limit heading or float title anywhere will now fail
+  `pnpm validate:content` / `astro build`. `<Table>` is exempt — it has only
+  a `caption`, not a separate `title`. A lesson's own `frontmatter.title`
+  (the page `<h1>`) is Review-only, not build-enforced — the gate scans body
+  text and cannot see frontmatter. See
+  `docs/authoring/structure-rules.md#s1`.
+
+- **Removed the "Pin explanation" button from the "Page notation" panel**
+  (`.notation-pin`, `[data-notation-control]` — both gone from the DOM). Pin
+  a card from the list the same way an inline prose symbol always has: click
+  its glyph, now also Tab + Enter/Space-operable (`role="button"`,
+  `tabindex="0"`, `aria-pressed`) since it was the button's only remaining
+  job. A course's own CSS or tests targeting either selector need updating.
+
+- **`NotationLayer.astro`'s separate "Page notation" `<h2>` is gone** —
+  the panel had two headings back to back ("Page notation" over "Notation
+  used on this page (N)"), saying the same thing twice. The panel's
+  `<summary>` is now the only heading, and `.notation-layer-heading` no
+  longer exists.
+
+- **`Diagram`'s `description` prop and its collapsed "Diagram description"
+  fallback block are gone** (`.diagram-fallback` no longer exists in the
+  DOM). The caption (`label`) is the diagram's one authored piece of text,
+  matching how a LaTeX figure/table caption already tells the whole story —
+  a separate always-present description block was inventing a second text
+  category most courses never wanted and that only added visible chrome
+  under every diagram. Drop any `description="…"` passed to `<Diagram>`;
+  the build no longer accepts it (`astro check` fails on an excess prop).
+
+### Added
+
+- **`NotationLayer.astro`'s "Page notation" panel and `remark-citation.mjs`'s
+  generated "References" section are both properly collapsible now** — same
+  native, persisted, deep-linkable disclosure `Figure`/`CollapsibleSections`
+  already use, not the always-native-default `<details>` "Page notation" had
+  before (no persistence, no course-configurable default, no anchor).
+  - `NotationLayer` gains `defaultOpen`/`rememberState` props (mirroring
+    `Figure`'s) and a hover-reveal permalink anchor next to its title bar
+    (`#page-notation` by default).
+  - `remark-citation.mjs`'s generated References heading now carries the
+    same `[collapsible]`/`[collapsed]` marker an authored `##` heading uses,
+    via a new `defaultOpen` plugin option — so it rides the *same*
+    `rehypeHeadingAnchors` / `CollapsibleSections` machinery every other
+    heading does, with no engine changes needed on that side. This only
+    takes visible effect on a course whose `astro.config.mjs` wires
+    `rehypeHeadingAnchors` into its rehype pipeline.
+  - New `CourseConfig.disclosureDefaults` (the manifest schema is now v14,
+    additive):
+    `{ notation?, references? }`, each `true` = open, closed (the engine's
+    own default) when omitted or the whole block is absent. Both are
+    engine-authored sections, not written by a lesson, so they get their own
+    default independent of `defaultCollapsible.sections`/`.subsections` (an
+    author's own `##` headings). See `docs/authoring`,
+    `playground/astro.config.mjs` for the wiring convention.
+
+### Fixed
+
+- **A symbol explained once via `\explain{key}{…}` can now auto-resolve at
+  every later bare occurrence of the same declared `latex` on the page — this
+  previously failed silently (no tooltip, no build error) for several common
+  shapes.** A definition whose whole canonical form is a roman label
+  (`\mathrm{SSR}`, `\mathrm{SST}`) never entered the auto-annotator's
+  signature index at all, so a bare occurrence of such a symbol could never
+  resolve, anywhere on the page, independent of position. Also fixed: a bare
+  symbol sitting immediately next to an `\explain{…}{…}` call, a canonical
+  match found by seeing through an already-explicit call's own wrapping, and
+  a partial `\explain{key}{…}` wrap covering only part of a declared
+  multi-token form — all three previously either dropped the symbol silently
+  or produced malformed, unparseable output. All of these now resolve
+  correctly, or fail loudly as "Unresolved notation" (`resolveMathGlyphs`,
+  shared by lesson-body rendering and `gate-math.ts`'s `pnpm validate:content`
+  check — so a regression here fails the build immediately rather than
+  passing silently through to a render-time surprise). One side effect: the
+  fix also restores the `ambiguous-canonical-notation` check for
+  `\operatorname{…}`/`\mathrm{…}`-only glyphs, which the same bug had
+  silently disabled — a course with two different notation keys declaring
+  structurally identical LaTeX (e.g. two keys both `\operatorname{Var}`) will
+  now correctly fail `pnpm validate:content` where it previously built with a
+  silent, unresolvable ambiguity. See
+  [`docs/authoring/notation.md`](docs/authoring/notation.md).
+
+## [0.5.0] - 2026-09-15
+
+### Added
+
+- New `createRemarkNotationOptions(manifest, overrides?)` helper
+  (`remark-notation.mjs`) returns `{ definitions: manifest.notation.raw,
+  manifest, ...overrides }` — the options `remarkNotation` needs, read off one
+  manifest in one call, so a course no longer hand-assembles `definitions`,
+  `equations`, `tables`, `figures`, and the superseded `chapters` map
+  separately (easy to do partially, which is how a page numbered itself under
+  the legacy `##`-section scheme while every cross-page reference to it read
+  the manifest). `playground/astro.config.mjs`, `README.md`, and
+  `src/compiler/cli.ts`'s own `content check` pipeline now wire the plugin
+  this way.
+
+- New `strict` option on `remarkNotation` (default `false`, so existing wiring
+  keeps building unchanged). The existing manifest/number-table cross-check
+  only ever caught a disagreement for a *keyed* equation or `<Table>`/
+  `<Figure>` — an unkeyed one still silently fell back to legacy
+  `##`-section numbering with no diagnostic at all if its lesson had no
+  `numbering` placement or cross-page entry. `strict: true` fails the build in
+  that case too, for any catalogued lesson with at least one equation,
+  `<Table>`, or `<Figure>` (keyed or not). `<Diagram>` is exempt — it already
+  renders unnumbered by design when it has no placement.
+  `createRemarkNotationOptions(manifest, { strict: true })` is the recommended
+  way to turn it on.
+
+- New raw/unwrapped-float diagnostics (`src/reference/raw-floats.mjs`,
+  `raw-floats-validate.ts`): a raw Markdown table or raw HTML `<table>` never
+  wrapped in `<Table>`/`<Figure>`, an `<Diagram>` with no `id`, or an
+  `<Diagram>` nested inside anything but `<Memo>`/`<ShortNote>`/`<Table>`/
+  `<Figure>` are all invisible to keyed-float validation — they render fine
+  but can never get a stable number or `[[…]]` reference. New codes
+  `raw-table-markdown`, `raw-table-html`, `diagram-unkeyed`, `diagram-nested`
+  surface this in `manifest.diagnostics.rawFloats` (warning-severity,
+  aggregated the same way as `tables`/`figures`/`diagrams`/`checks` in
+  `cli.ts` and `playground/scripts/compile-manifest.ts`); `remarkNotation`
+  reports the same at render time as a defense-in-depth check for content
+  added since the manifest was last compiled. See
+  [`docs/authoring/structure.md`](docs/authoring/structure.md#raw-and-unwrapped-floats).
+
+- Courses can opt into a per-lesson **Print / save as PDF** action with
+  `lessonExports.print`. It opens the native browser print dialog—no generated
+  PDF artifact or server-side renderer—and prepares a chrome-free, paper-safe
+  lesson layout: disclosures, complete tables, diagrams, and assessment items
+  are exposed; non-printable controls are removed; linked text stays visibly
+  green and remains a real PDF link with canonical destinations; lazy
+  interactive plots are hydrated before the print dialog opens; and the reader's
+  exact disclosure state is restored after printing without changing saved
+  preferences.
+
+- Courses can opt into fully functional per-lesson standalone HTML with
+  `lessonExports.standaloneHtml` and `canonicalBaseUrl`. The Astro build now
+  emits `downloads/<lesson-slug>.html` files that open through `file://`, embed
+  the complete style/font/media/module graph, hydrate Astro React islands from
+  one shared browser bundle, preserve local lesson interactions, remove site
+  chrome, and rewrite deliberate outbound course links to the canonical site.
+  Builds fail before publishing an artifact when a render dependency cannot be
+  embedded. Downloads retain an offline Light/Dark/Auto theme control. Lesson
+  pages expose the download in the top-right header cluster, and the development
+  server generates and serves the artifact on demand.
+
+- Rule N14: every acronym (`OLS`, `MSE`) or dotted abbreviation (`w.r.t.`,
+  `i.i.d.`) a lesson uses in plain prose must now be universal (the shipped
+  `base-abbreviations.mjs` baseline plus `abbreviations.allow`/`deny` in
+  `course.config.ts`), carry an entry in the new, lighter-weight
+  `abbreviations` content collection (`content/abbreviations/*.md` — a name
+  resolution only, no formula or units), or already be explained as a math
+  quantity via [N8](docs/authoring/notation.md#n8)/[N10](docs/authoring/notation.md#n10).
+  Build-enforced (`gate-abbreviations.ts`), same error-severity, no-warm-up
+  shape as N9. A new "Abbreviations" section on the glossary page
+  (`AbbreviationGlossary.astro`) lists every catalogued entry, and the first
+  occurrence of a table-resolved abbreviation on a lesson page is now also an
+  inline hover/click card (`remark-abbreviations.mjs` +
+  `AbbreviationLayer.astro`), the same card shell the math-notation and
+  citation systems use, linking to its glossary entry.
+
+### Fixed
+
+- Standalone lesson links no longer return 404 during `astro dev`; the first
+  local request now builds the same audited artifact emitted by a static build.
+
+- Expanded keyed tables retain their native `<figure>` semantics inside a valid
+  landmark wrapper instead of applying an invalid ARIA `region` role directly
+  to the figure. Their overflow controls also remain distinguishable from the
+  separate row-pagination toggle.
+
+- Nested Astro component math can no longer emit a working-looking
+  `data-notation-key` without shipping its popup definition. `Diagram` and
+  `NotationFormula` register their rendered keys in request-local page scope,
+  `labMathScope` accepts component context for lab templates, and the Astro
+  integration checks final generated HTML for trigger/payload parity. Known
+  component-only shared keys now receive cards without making the entire global
+  registry page-wide; unknown keys fail with lesson/component/formula context.
+
+### Changed
+
+- Every published engine version must now ship an agent-readable section in
+  `docs/authoring/migrating.md`, with exact downstream content/config/script
+  steps or an explicit no-action statement. The release checklist and downstream
+  agent guide now treat this as part of the release artifact, and a new
+  `prepack` guard rejects a version without its matching migration section or
+  without the guide included in `package.json#files`.
+
+### Breaking
+
+- **The compiler manifest schema is now v13.** It adds
+  `diagnostics.rawFloats` (see Added above). The change is additive, but
+  consumers that validate `MANIFEST_SCHEMA_VERSION` must accept the new
+  version.
+
+- **The compiler manifest schema is now v12.** It adds `manifest.abbreviations`
+  — the `abbreviations` content collection (N14), flattened to plain
+  `{key, abbr, expansion, aliases, domain?}` records sorted by key, so the new
+  `remarkAbbreviations` plugin can wrap the first occurrence of a known
+  abbreviation in a lesson's prose. The change is additive, but consumers that
+  validate `MANIFEST_SCHEMA_VERSION` must accept the new version.
+
+- **The compiler manifest schema is now v11.** It adds the normalized
+  `manifest.lessonExports` settings used by the build integration and lesson
+  UI. The change is additive, but consumers that validate
+  `MANIFEST_SCHEMA_VERSION` must accept the new version.
+
+- **The compiler manifest schema is now v10.** Numbered knowledge checks add
+  `manifest.checks`, `lessons[].knowledgeChecks`, `lessons[].numbering.checks`,
+  and `diagnostics.checks`. The change is additive, but consumers that
+  validate `MANIFEST_SCHEMA_VERSION` must accept the new version.
+
+- **The compiler manifest schema is now v9.** Diagrams are first-class keyed
+  floats with their own `manifest.diagrams`, `lessons[].diagrams`,
+  `lessons[].numbering.diagrams`, and `diagnostics.diagrams` fields. The
+  change is additive, but consumers that validate `MANIFEST_SCHEMA_VERSION`
+  must accept the new version.
+
+- **New build-enforced authoring rule N9: a physical quantity, unit, or math
+  operator must be typeset in `$…$`, never as plain text, anywhere on a
+  lesson page (prose or a table cell).** `gate-prose-notation.ts` fails
+  `pnpm validate:content` / `astro build` on a numeral glued to an
+  abbreviated unit (`45 m/s`), a bare unit in parens (`(s)`, `(m/s²)`), an
+  escaped `\|` standing in for an absolute-value bar, a hand-typed `_`/`^`
+  sub/superscript, or a `/` between two symbol-like tokens outside a small
+  reviewed idiom allowlist. A downstream course with existing plain-text
+  notation in a lesson body or table will now fail the build; see
+  `docs/authoring/notation.md#n9` for the fix (wrap it in `$…$`, unit
+  included — `\text{}`-wrapped and folded into the same span as its symbol,
+  e.g. `$t\ \text{(s)}$`) — there is no `lint-ignore.yml` escape hatch for
+  this one. The rule does not apply inside a JSX component prop
+  (`caption="…"`, `title="…"`), since that text never reaches KaTeX. N9 now
+  also scans every assessment item's `prompt` / `explanation` string the same
+  way (`gateProseNotationInAssessments`) — same fix, same "no escape hatch."
+- **New `rehype-table-header-labels.mjs` gives an automatic accessible name
+  to a table `<th>` that ends up 100% KaTeX (every symbol *and* unit now in
+  `$…$` per N9 above, so a bare `$t\ \text{(s)}$` column has no plain DOM
+  text at all).** axe-core's `empty-table-header` rule requires real text
+  content — not just an `aria-label` (confirmed by reading the rule itself:
+  it runs only `has-visible-text`, with none of the
+  `aria-label`/`aria-labelledby` fallbacks most other axe name-checking rules
+  allow) — so this plugin inserts a visually-hidden `<span class="sr-only">`
+  (Starlight's own clip-based utility, not `display:none`) composed from the
+  `\explain{key}{…}` key(s) the header's LaTeX names and that key's own
+  `label` / `units` notation metadata, already authored for hover cards
+  elsewhere. Wired into `playground/astro.config.mjs`'s `rehypePlugins`
+  right after `rehypeKatex`. A `\mathrm{…}` compound (`\mathrm{KE}/m`) needs
+  each side explicitly `\explain{}`-wrapped for the plugin to have anything
+  to read, since the glyph resolver never looks inside a bare `\mathrm{}`
+  body — every bare symbol column resolves automatically the same way it
+  already did for hover cards.
+- **`AssessmentRunner` now renders `prompt` / `explanation` through the same
+  KaTeX pipeline as lesson body math, instead of showing the raw authored
+  string.** The gate that checks an assessment math span's glyphs resolve
+  (context `assessment` in `gate-math.ts`) is promoted from a Tier-3 warning
+  to a build error for the same reason `formula` was at D15: an unresolved
+  glyph is now a visible hole in the rendered UI, not an invisible warning. A
+  downstream course with an unresolved glyph in assessment math, or
+  plain-text notation in an assessment `prompt` / `explanation` (see N9
+  above), will now fail the build. Manifest schema is now **v8**:
+  `assessmentContent` is new — every assessment item's `prompt` /
+  `explanation`, pre-split into text/math segments and resolved against the
+  scope of the lesson that embeds it; `AssessmentSet.astro` renders each
+  `math` segment via `renderNotationMath` before handing the result to
+  `AssessmentRunner`, so `AssessmentRunner`'s `Item` props changed shape:
+  `prompt` / `explanation` (`string`) are now `promptContent` /
+  `explanationContent` (`MixedContentNode[]`, rendered with the new
+  `RenderedContent` component) — a host embedding `AssessmentRunner` directly
+  (bypassing `AssessmentSet.astro`) needs to pre-render the same way.
+
+- **New build-enforced authoring rule N13: a nonlinear function must take a
+  parenthesized argument, even a single symbol — `\sin x` is now a hard
+  error, `\sin(x)` is required.** Covers every trigonometric,
+  inverse-trigonometric, and hyperbolic function plus `exp`/`log`/`ln`/`lg`
+  (the new `PARENTHESIZED_FUNCTIONS` set in `base-operators.mjs`).
+  `resolveMathGlyphs` (`math-glyphs.mjs`) walks the parsed KaTeX tree of
+  every rendered-math context — lesson body, `notation.formula`, assessment
+  `prompt`/`explanation`, a `Diagram` node's `formula`, interactive lab math
+  — since all of them already call this one resolver; a violation fails
+  `pnpm validate:content` / `astro build` the same way an unresolved glyph
+  does, with no `lint-ignore.yml` escape hatch, like N9. `Diagram` and
+  `NotationFormula` formulas render through `renderNotationFormula`
+  (`render-notation-math.ts`), which previously caught *any*
+  `resolveMathGlyphs` failure and degraded to an inert fallback (or, for
+  `Diagram`, a generic "could not bind to notation scope" error); it now
+  rethrows this specific error instead, so a violation there fails loudly
+  with the actual fix rather than a misleading message. A downstream course
+  with `\sin\theta`, `\log x`, `\exp t`, etc. anywhere in rendered math will
+  now fail the build; see `docs/authoring/notation.md#n13`.
+
+- **New build-enforced authoring rule N15: a nested visible delimiter — `(`,
+  `[`, `\{`, or `|` inside another one of them — must use its `\left`/`\right`
+  sizing form, not the bare character.** The moment a second one of these four
+  glyphs sits inside the first — same type or mixed, e.g. `(a + [b])` — every
+  level of that nest switches to the sizing form: `\sin(2(90°-\theta))` is now
+  a hard error, `\sin\left(2\left(90°-\theta\right)\right)` is required.
+  `findNestedBareDelimiters` (`math-glyphs.mjs`) walks the same parsed KaTeX
+  tree `resolveMathGlyphs` and N13 already build; a violation fails
+  `pnpm validate:content` / `astro build` with no `lint-ignore.yml` escape
+  hatch, like N9/N13. A single, non-nested bare delimiter (`(x)`) is
+  untouched, and a delimiter inside `\text{…}` (a unit per N9) is unaffected.
+  A downstream course with a nested bare delimiter anywhere in rendered math
+  will now fail the build; see `docs/authoring/notation.md#n15`.
+
+### Added
+
+- **Numbered, referenceable, collapsible knowledge checks.** Assessment ids in
+  each lesson's `.checks.yml` now form an independent part-wide number stream.
+  `<AssessmentSet>` renders the assessment record's title as the sole heading,
+  with a stable `#check-<assessment-id>` permalink; `[[check-<assessment-id>]]`
+  and cross-page `[[lesson/slug#check-<assessment-id>]]` references render the
+  published number. The check heading reuses the standard section disclosure,
+  including persistence, hover peek, deep-link opening, print expansion, and
+  the hidden-until-hover expanded chevron. Single-choice answer options are
+  Fisher–Yates shuffled in the browser for every full page view while grading
+  remains keyed by stable option ids. The manifest schema is now v10, adding
+  `checks`, `lessons[].knowledgeChecks`, `lessons[].numbering.checks`, and
+  `diagnostics.checks`.
+
+- **Detailed memos and inline short notes.** A flow `<Memo>` is now a
+  subsection-like optional derivation that can be placed later and cited from
+  prose as `[[memo-id]]`; references, the memo's visible `[n]`, and a familiar
+  chain-icon permalink beside its title share a URL fragment. Memo blocks
+  retain persistent collapse, hover previews,
+  deep-link reveal, and print behavior. The new `remark-short-note.mjs` adapter
+  and `components/memo/ShortNote.astro` provide the complementary inline form:
+  its author-supplied link text expands in place into arbitrary block Markdown
+  and restores the intact sentence on collapse. Equations, tables, figures,
+  and diagrams inside either detail form remain in their normal numbering
+  streams.
+
+- New authoring rule N10: a `\mathrm{…}` multi-letter label (`\mathrm{KE}`,
+  `\mathrm{PV}`) must be on the shipped/course roman-label baseline
+  (`base-roman-labels.mjs`, `course.config.ts` `romanLabels`) or carry a
+  notation entry the reader can hover — the `\mathrm{…}` counterpart to N8's
+  `operator-explained`, since N3 requires the format but the glyph resolver
+  skips a `\mathrm{}` body whole either way, so nothing previously checked
+  whether it was ever explained. Surfaced as a `roman-label-explained` Tier-3
+  warning by `pnpm validate:content`, same rollout and `lint-ignore.yml`
+  shape as N8.
+
+### Added
+
+- **Independent diagram numbering and references.** A top-level
+  `<Diagram id="…">` is numbered in its own `‹part›.‹n›` stream, renders a
+  `#dia-<id>` anchor, and can be cited with `[[dia-<id>]]` (including cross-page
+  references). Wide diagrams emit an author-facing build warning above the
+  configurable `warnAboveWidth` threshold and gain an unobtrusive horizontal
+  expand/shrink control. Expansion moves the original diagram into a non-modal,
+  vertically scrollable in-page overlay that follows its document position.
+  Diagram titles also minimize/restore the body with an animated chevron,
+  permalink icon, and persistent reader state while retaining a complete
+  no-JavaScript fallback.
+
+### Fixed
+
+- `Diagram` now preserves its build-time SVG dimensions inside its horizontal
+  scroller instead of inheriting Starlight's responsive SVG shrinking. This
+  keeps the HTML/KaTeX embedded in `foreignObject` nodes aligned with their
+  boxes on iOS WebKit (Safari and Chrome), which does not reliably scale mixed
+  SVG/HTML content as one unit.
+- Clicking a same-page diagram reference now dismisses its hover card and
+  navigates immediately; the card also closes once scrolling has made the
+  target diagram fully visible. Preview SVG ids are isolated so cloned arrow
+  markers cannot interfere with the original diagram.
+- An expanded diagram title now hides its down-pointing disclosure chevron
+  after the interaction, matching collapsible sections and subsections; the
+  right-pointing chevron remains visible while the diagram is minimized.
+- Expanded tables and diagrams now remain beneath the sticky site header as
+  they scroll upward. Escape now restores an expanded diagram, matching the
+  existing expanded-table shortcut.
+
 ## [0.4.0] - 2026-09-09
 
 ### Breaking
@@ -165,7 +544,9 @@ under **Breaking** below; a PATCH never breaks.
   system with its completeness gate, the curriculum-graph validator, the
   Astro/Starlight UI, the LMS / session / analytics seams, and the `content` CLI.
 
-[Unreleased]: https://github.com/danieltuzes/explico/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/danieltuzes/explico/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/danieltuzes/explico/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/danieltuzes/explico/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/danieltuzes/explico/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/danieltuzes/explico/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/danieltuzes/explico/compare/v0.1.1...v0.2.0

package/README.md

@@ -71,7 +71,11 @@ export { collections } from 'explico/content-config';
 // astro.config.mjs
 import { explicoContentRefresh } from 'explico/compiler/astro.js';
 import { loadManifest } from 'explico/compiler/manifest.js';
-import remarkNotation from 'explico/reference/remark-notation.mjs';
+import remarkMemo from 'explico/reference/remark-memo.mjs';
+import remarkNotation, {
+  createRemarkNotationOptions,
+} from 'explico/reference/remark-notation.mjs';
+import remarkShortNote from 'explico/reference/remark-short-note.mjs';
 import remarkCitation from 'explico/reference/remark-citation.mjs';
 import { createNotationKatexOptions } from 'explico/reference/katex-options.mjs';
 import rehypeFailKatexErrors from 'explico/reference/rehype-fail-katex-errors.mjs';
@@ -80,13 +84,15 @@ import { courseConfig } from './content/course.config.ts';
 const manifest = await loadManifest(courseConfig);
 // markdown.remarkPlugins: [
 //   remarkMath,
-//   // One `manifest` carries every numbering input — the equation / table /
-//   // figure number tables *and* the part each lesson sits in. Pass the
-//   // tables without the placement and the page numbers its equations by `##`
-//   // section while references to it read the part scheme, so the same
-//   // equation reads (2.2) at home and (4.5) abroad; the plugin rejects that
-//   // at build time rather than shipping it.
-//   [remarkNotation, { definitions: manifest.notation.raw, manifest }],
+//   remarkShortNote,
+//   remarkMemo,
+//   // `createRemarkNotationOptions` reads every numbering input off one
+//   // manifest — the equation / table / figure number tables *and* the part
+//   // each lesson sits in — so they can't drift apart. `strict: true` fails
+//   // the build when a catalogued lesson has equations/tables/figures but no
+//   // numbering or cross-page entry, instead of silently numbering it by
+//   // `##` section while references to it read the part scheme.
+//   [remarkNotation, createRemarkNotationOptions(manifest, { strict: true })],
 //   [remarkCitation, { sources: manifest.sources }],
 // ]
 // … integrations: [explicoContentRefresh(courseConfig, manifest),
@@ -102,6 +108,85 @@ and restarts the development server when any file under `content/` is added,
 changed, or removed, keeping Markdown transforms and UI components on the same
 model without an editor-specific task.
 
+A memo is a substantial optional derivation: it behaves like a collapsible,
+numbered subsection without adding a heading to the page outline. Cite it from
+earlier prose with `[[memo-id]]`, then place the block wherever it best fits.
+The citation, the block's own number, and its chain icon link to the same URL
+fragment:
+
+```mdx
+The omitted calculation is recorded in [[memo-full-check]].
+
+Several paragraphs may intervene.
+
+<Memo id="full-check" title="Full check" description="The omitted algebra and evidence.">
+
+The longer derivation can contain paragraphs, equations, tables, and figures.
+
+</Memo>
+```
+
+For a reveal that really belongs inside one sentence, import
+`explico/components/memo/ShortNote.astro` and use `<ShortNote>`. Its `title` is
+the collapsed inline link; expanding replaces that link with the block-capable
+body, then rejoins the sentence when collapsed:
+
+```mdx
+The derivative agrees <ShortNote id="derivative" title="(show how)" description="Show the calculus calculation.">
+
+Differentiate the polynomial, set the result to zero, and solve.
+
+</ShortNote>. But symmetry is quicker.
+```
+
+Both components require literal `id`, `title`, and `description` strings.
+Memos start collapsed and persist reader state unless `rememberState={false}`;
+short notes always start collapsed.
+
+### Lesson exports
+
+A course can opt into a self-contained HTML download and browser-native printing
+for each lesson:
+
+```ts
+export const courseConfig: CourseConfig = {
+  // ...the normal course fields
+  lessonExports: {
+    standaloneHtml: true,
+    print: true,
+    canonicalBaseUrl: 'https://example.edu/course/',
+  },
+};
+```
+
+The existing `explicoContentRefresh(courseConfig, manifest)` integration emits
+`downloads/<lesson-slug>.html` after Astro's static build and adds a download
+control to the top-right header cluster on each lesson. During `astro dev`, the
+first download request runs an isolated static build and streams the resulting
+file; later requests use that result until a watched source file changes. The
+downloaded file contains its CSS,
+KaTeX fonts, images, client scripts, Astro island components, and renderer; it
+opens directly through `file://` without a server or network access. Search,
+sidebars, pagination, and other site chrome are omitted. Same-page references
+stay local, while links that leave the lesson use `canonicalBaseUrl` and
+cross-lesson hover previews degrade to ordinary links. A retained theme control
+lets an offline reader choose Light, Dark, or Auto; Auto follows changes to the
+viewer’s system color scheme.
+
+The **Print / save as PDF** action calls the browser's native print dialog; it
+does not download or build a `.pdf` file itself. The print layout removes site
+chrome, expands disclosures and complete data surfaces without changing saved
+reader state, hides controls that have no paper equivalent while retaining their
+current visual result, and keeps linked text clickable with canonical destinations.
+Paper size, margins, browser-added headers/footers, final filename, and the
+choice to save as PDF remain browser and reader settings.
+
+Set `canonicalBaseUrl` to the deployed course root whenever retained lesson
+content links elsewhere in the course. If such a link exists without the base,
+the build fails rather than shipping a dead local link. An unresolved or remote
+stylesheet, script, font, image, iframe, media source, worker, WASM file, or CSS
+URL likewise fails the standalone export audit.
+
 ```jsonc
 // package.json — the read-side CLI
 "scripts": { "validate:content": "tsx scripts/compile-manifest.ts" }
@@ -135,6 +220,10 @@ version and `content/CHANGELOG.md` move with a content change (area `C`,
 surfaced to readers in the About `[?]` panel).
 [`docs/authoring/README.md`](docs/authoring/README.md) is the governance: rule
 IDs, enforcement levels, and how to amend.
+[`docs/authoring/components.md`](docs/authoring/components.md) is a syntax
+catalog of what a lesson body can contain — native tooltips, tables, figures,
+diagrams, memos, abbreviations, citations — for an author who wants "what's
+available" rather than "why this rule."
 
 ## Build
 
@@ -164,5 +253,11 @@ content — `about.version` in `content/course.config.ts`, tracked in the course
 For AI authors: [`AGENTS.md`](AGENTS.md) says which changelog and which version a
 given change updates.
 
+When upgrading an existing course, use the migration guide shipped with the
+target package at `node_modules/explico/docs/authoring/migrating.md`. Every
+published version has a section, including versions that require no course-side
+changes, so an agent can update content, configuration, and scripts from the
+installed artifact rather than guessing from the changelog.
+
 Status: extracted from the `equations` project; API not yet stable (pre-1.0);
 the license is undecided (`UNLICENSED` until chosen).

package/dist/compiler/astro.d.ts

@@ -10,13 +10,21 @@ import '../reference/equations-validate.js';
 import '../reference/tables-validate.js';
 import '../reference/keyed-float-validate.js';
 import '../reference/figures-validate.js';
+import '../reference/diagrams-validate.js';
+import '../reference/knowledge-checks-validate.js';
+import '../reference/raw-floats-validate.js';
 import '../reference/gate-math.js';
+import '../reference/mixed-content.js';
 import '../reference/gloss.js';
 import './knowledge-version.js';
 import './lesson-derivation.js';
 
+/** Match only a configured lesson artifact below Astro's deployment base. */
+declare function matchStandaloneDownload(pathname: string, base: string, lessonSlugs: readonly string[]): string | undefined;
 /** Fail loudly instead of rendering math triggers whose local cards are stale. */
 declare function assertLocalNotationParity(lessonId: string, authoredKeys: readonly string[], renderedKeys: readonly string[]): void;
+/** Fail an Astro build if final rendered HTML contains an unusable trigger. */
+declare function assertNotationPayloadHtml(page: string, html: string): void;
 /**
  * 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
@@ -27,4 +35,4 @@ declare function assertLocalNotationParity(lessonId: string, authoredKeys: reado
  */
 declare function explicoContentRefresh(courseConfig: CourseConfig, manifest: Manifest): AstroIntegration;
 
-export { assertLocalNotationParity, explicoContentRefresh };
+export { assertLocalNotationParity, assertNotationPayloadHtml, explicoContentRefresh, matchStandaloneDownload };