explico 0.7.0 → 0.11.0

package/docs/authoring/visualizations.md

@@ -2,8 +2,8 @@
 
 `V` rules govern anything a lesson draws: diagrams, static charts, and hydrated
 interactive figures. The engine assumes no single plotting approach — these
-rules make the choice per figure predictable and keep every figure accessible
-and deterministic.
+rules make the choice per figure predictable, keep every figure's math
+gate-checked, and keep its drawing deterministic.
 
 See [README.md](README.md) for what "strong recommendation", "Build-enforced",
 and "Review-only" mean here, and how to amend a rule.
@@ -47,15 +47,21 @@ an independent diagram number, a `#dia-<id>` anchor, and references of the form
 `[[dia-<id>]]` or `[[lesson/slug#dia-<id>]]`. Diagram numbers do not advance the
 equation, table, or figure sequences.
 
+A diagram is named like every float: a long `caption`, shown below the graph
+in the same caption line a figure has (`Diagram 2.1.1`, a chain icon that
+copies the diagram's link, the caption), and an optional `short` caption for
+the `[[dia-…]]` preview card
+([components.md § The caption pair](components.md#the-caption-pair)).
+
 The component preserves the build-time canvas size and scrolls horizontally
-when the work area is narrower. A compact control on the title line can expand
-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; this state is remembered per page by default
-(`defaultOpen` / `rememberState` configure it).
-The title also carries the same chain-link permalink treatment as headings.
+when the work area is narrower. Then a widen button ↔ at the end of the
+caption line — the boxed button a table's caption has — expands the original
+diagram toward the full in-page region and shrinks 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 button again,
+or Escape, restores its original width. A diagram never folds by itself: it
+is its graph and then its caption line, in every state. To let a reader fold
+it away, put it in a collapsible section.
 
 By default a laid-out width above `800px` emits a compile-time warning. Treat
 that warning as a prompt to try
@@ -103,8 +109,8 @@ _Exceptions._ None — this rule _is_ the exception process.
 
 ## V3
 
-**Interactive figures: a hydrated island, the `renderLabMath` seam for
-equations, and a text alternative.**
+**Interactive figures: a hydrated island and the `renderLabMath` seam for
+equations.**
 
 An interactive figure is a React island, hydrated `client:visible` (or
 `client:idle`). It carries:
@@ -119,18 +125,60 @@ An interactive figure is a React island, hydrated `client:visible` (or
   in this page's popup payload. See
   `playground/content/labs/ProjectileRangeExplorer.tsx` +
   `ProjectileRangeMath.astro`.
-- **An accessible name and description** — `ariaLabel` / `ariaDescription` on
-  the plot, marks that are decorative set `ariaHidden`.
-- **A text alternative.** A `<details>` block with the model's assumptions and a
-  small table of representative values, so the figure is usable with no JS and
-  by a screen reader.
-- **Labelled controls.** Every control is a labelled `<input>`; where precision
+- **Labelled controls.** Every control is a labelled `<input>` — the visible
+  label is how any reader knows what a slider sets; where precision
   matters, pair a `range` slider with a `number` field (see `RangeField` in
   `ProjectileRangeExplorer.tsx`).
+- **No title or caption of its own.** The island sits in a `<Figure>`, and the
+  figure's `caption` (with an optional `short`) names the whole lab. The lab
+  adds no heading, no inner `<figure>` / `<figcaption>`, and no
+  `aria-labelledby` pointing at one: one object has one name. A sentence
+  that describes the plot ("the dot marks the landing point") belongs in the
+  figure's caption.
+- **Picture, then caption, then tools.** A lab is laid out as a LaTeX figure
+  with its controls after it (docs/plans/figures-and-short-captions.md,
+  decision 3). The plot goes in the `<Figure>`'s default slot — its
+  picture — and the controls in its `tools` slot: an instruction line, the
+  sliders and fields, the live equation. The two are separate islands that
+  share their values. The tools render after the caption line, in a tray of
+  their own, and are the only part that folds: the fold button ⌃ / ⌄ ends the
+  caption line, and folded tools leave a "Hidden here: 2 sliders, 1
+  equation" line that unfolds them. Whether they start open is the course's
+  `disclosure.figures`, or `defaultOpen` on the one figure; the reader's
+  choice is remembered per page. Print and export show the picture and the
+  caption; the tools never print.
+- **A live end to the caption.** The caption ends with a clause stating the
+  case shown — "Shown for v₀ = 20 m/s and θ = 30°: range 35.3 m, time of
+  flight 2.04 s." The lab writes it with `setFigureState(element, runs)`
+  (`explico/components/figure/figure-state.ts`), `element` being any element
+  of its own inside the figure and `runs` plain text, `{ text, italic: true }`
+  or `{ sub }` — never HTML. The clause prints with the caption; a reader
+  of the long caption elsewhere (a preview card, a fold's bar) sees the
+  caption alone.
+- **Which text goes where.** The caption names the figure and says what it
+  shows — its subject, its marks and symbols, the case shown — and may state
+  the one thing to notice. The argument drawn from the figure is lesson
+  text, after the figure. Instructions for the controls belong to the
+  controls: the tools' first line, not the caption.
+- **A preview shows the plot.** A same-page `[[fig-…]]` reference to a lab
+  previews a still copy of its plot as drawn; the tools are never copied. A
+  plot not drawn yet — or one on another page, drawn only in the browser —
+  leaves the card to the caption and number, so a lab no longer needs
+  `previewable={false}`.
+
+The figure itself never hides; a lab that should fold away whole, with the
+prose around it, goes in a `<Fold>` or a collapsible section.
+
+The lab writes no accessible name, description or text alternative: the
+`<Figure>` renders a real `<figure>` and `<figcaption>`, so its caption is
+already the figure's accessible name
+([Accessibility](README.md#accessibility)). A plot option such as
+`ariaLabel` / `ariaDescription` / `ariaHidden` may stay where it is written;
+nothing asks for one.
 
 _Rationale._ The seam is the only reason interactive math is not a silent
-exception to the completeness gate. The text alternative and aria wiring are the
-difference between a figure and an inaccessible one.
+exception to the completeness gate. One name per object means the reader, a
+`[[fig-…]]` reference and a screen reader all call the lab the same thing.
 
 _How to apply._ Keep the island's job to "patch numbers and redraw". Domain
 math lives in a plain module (`playground/content/domain/motion.ts`), not in the
@@ -226,3 +274,77 @@ _Enforcement._ Review-only.
 _Exceptions._ A figure where the meaningful range is a known physical bound
 (a probability on `[0, 1]`, an angle on `[0°, 360°]`) uses that bound instead —
 state it in a comment.
+
+---
+
+## V6
+
+**Every quantitative axis of a chart shows at least three labelled values.**
+
+A chart that draws an x axis and a y axis — a hand-drawn SVG, an Observable
+Plot, an interactive island, a printed pgfplots figure — labels at least three
+tick values on each quantitative axis, as numbers at their positions. An axis
+_name_ (`feature x`, `density`) does not count, and neither does an annotation
+of one special point (`\mu`, `\bar{x}`, a threshold).
+
+_Rationale._ Values are what make a chart readable rather than decorative.
+One value pins a single point. Two values give a scale only if the reader
+already knows the axis is linear, and two labels on a log axis look exactly
+like two on a linear one. Three values show where the axis starts, how big a
+unit is, and whether the spacing is linear or logarithmic. Only then can a
+reader read a value off the curve, compare two panels, or check the figure
+against a number in the prose beside it.
+
+_How to apply._
+
+- Use round values: steps of 1, 2, 2.5, or 5 times a power of ten, inside the
+  axis domain. Let the library choose them where it can. Observable Plot's
+  automatic ticks satisfy the rule at any ordinary chart size; `ticks: 5`
+  pins a count. In pgfplots the automatic ticks satisfy it; never set
+  `xtick=\empty` or `ytick=\empty` on a quantitative axis.
+- A hand-drawn SVG computes its values from the domain and falls back to a
+  finer step until at least three fit:
+
+  ```ts
+  const NICE_STEPS = [1, 2, 2.5, 5];
+
+  function axisTicks([lo, hi]: readonly [number, number], target = 5): number[] {
+    let exponent = Math.floor(Math.log10((hi - lo) / target));
+    let index = NICE_STEPS.findIndex((n) => n * 10 ** exponent >= (hi - lo) / target);
+    if (index < 0) [index, exponent] = [0, exponent + 1];
+    for (;;) {
+      const step = NICE_STEPS[index] * 10 ** exponent;
+      const values: number[] = [];
+      for (let v = Math.ceil(lo / step - 1e-9) * step; v <= hi + step * 1e-9; v += step) {
+        values.push(Number(v.toFixed(10)));
+      }
+      if (values.length >= 3) return values;
+      if (--index < 0) [index, exponent] = [NICE_STEPS.length - 1, exponent - 1];
+    }
+  }
+  ```
+
+  Draw a short tick mark at each value and the number beside it.
+- The values follow the domain. When a control changes an axis range
+  ([V5](#v5)), recompute the values from the new range in the same step.
+- A density or likelihood axis gets values too. "The vertical scale does not
+  matter here" is a reason to say so in the caption, not to hide the scale.
+- A log axis labels its decades (`10`, `100`, `1000`).
+- Special-point annotations stay, next to the values rather than instead of
+  them.
+- Stacked panels that share an axis, aligned and said to be shared, may
+  label it once, on the panel nearest the axis. Every other axis of every
+  panel carries its own values.
+
+_Enforcement._ Review-only. The engine cannot tell a chart from any other
+drawing. A course can make it build-enforced in its own browser tests by
+marking each axis's value group and counting the values in it.
+
+_Exceptions._
+
+- A figure without axes has nothing to label: a node-edge diagram, a
+  bullseye target, an illustration.
+- A categorical axis shows its categories instead of numbers, even if there
+  are only two.
+- A sketch that draws axes is a chart. If the axes are worth drawing, their
+  scale is worth labelling.

package/docs/katex-bracket-scaling.md

@@ -0,0 +1,191 @@
+# Auto-scaling brackets in KaTeX (and MathJax)
+
+> **Status in this repo.** Solution 2 is implemented, but as *code* rather than
+> as a `patches/` file: [`src/reference/katex-delimiters.mjs`](../src/reference/katex-delimiters.mjs)
+> applies the same one-constant change at import time, so it ships inside the
+> published `explico` package and a downstream course inherits it with no
+> install step. Rule [N17](authoring/notation.md#n17) depends on it. The
+> sections below are the derivation; see
+> [How this repo applies it](#how-this-repo-applies-it).
+
+## The problem
+
+In LaTeX, `\left[ ... \right]` sizes a bracket to fit its content — but nested brackets often come out **the same size**, because the sizing rule only requires the delimiter to be *close enough* to the content's height, not strictly bigger.
+
+Example:
+
+```latex
+$$\left[ \left[ \sqrt{\frac{\int\limits_0^{10}\sqrt{a^2+b^2}}{2}} \right] + 1 \right]$$
+```
+
+The outer `[` and inner `[` render at the same size, even though the outer one wraps strictly more content. The alternative — manually choosing `\bigl`, `\Bigl`, `\biggl`, `\Biggl` — fixes the sizing but abandons `\left`/`\right`'s automatic "match the height of everything inside" behavior, since those are fixed-size delimiters that don't adapt to content.
+
+So there are two properties you want simultaneously, and the two standard tools each give you only one:
+
+1. **Strict growth outward** — each nesting level's bracket must be visibly bigger than the one inside it.
+2. **Full coverage** — every bracket must span the full height of its content, with no gap.
+
+`\bigl`/`\Bigl`/`\biggl`/`\Biggl` give you (1) but not (2) (fixed sizes don't track arbitrary content). `\left`/`\right` give you (2) but not (1) (the sizing rule allows equal-looking sizes at different nesting depths).
+
+## Why it happens: the underlying rule
+
+TeX sizes a `\left`/`\right` pair using this rule (TeXbook, Appendix G, rule 19):
+
+```
+s_min = max( 2·δ₀ · f / 1000 , 2·δ₀ − l )
+```
+
+TeX then picks the smallest available delimiter glyph whose total size `s` satisfies `s ≥ s_min`.
+
+| Symbol | Meaning |
+|---|---|
+| `h` | height of the content: how far it reaches above the baseline |
+| `d` | depth of the content: how far it reaches below the baseline |
+| `a` | axis height — the line fraction bars and minus signs sit on; delimiters are centered on this line |
+| `δ₀` | `max(h − a, d + a)` — how far the content reaches from the axis, on whichever side is farther |
+| `f` | `\delimiterfactor`, default **901** |
+| `l` | `\delimitershortfall`, default **5pt** |
+| `s_min` | the smallest total bracket size TeX will accept |
+| `s` | the size of the delimiter TeX actually picks |
+
+With the default `l = 5pt`, `s_min` can be *smaller* than the content's own height (since `901/1000 ≈ 0.9`), so a delimiter that already matches the inner bracket's height passes the test for the outer bracket too — no forced growth. The same slack also means a delimiter can legally fall up to 5pt short of the content, i.e. requirement (2) isn't fully guaranteed by default either.
+
+**The fix in real LaTeX:** set `\delimitershortfall` to a *negative* value (e.g. `-1pt`). Then `s_min = 2δ₀ + 1pt`, which is always larger than the content's own extent — forcing outward growth at every level, automatically, with no per-formula work. This is a document-wide setting, not something you write per equation:
+
+```latex
+\delimitershortfall=-1pt
+\left[ \left[ \sqrt{\frac{\int\limits_0^{10}\sqrt{a^2+b^2}}{2}} \right] + 1 \right]
+```
+
+Verified by rendering with `pdflatex`: default nesting produces equal-sized brackets; the same source with `\delimitershortfall=-1pt` produces strictly increasing sizes at every depth, and small content (`(x)`, `((x))`, `(((x)))`) is unaffected since the correction is tiny relative to normal delimiter jumps.
+
+## Why it doesn't carry over to the web
+
+`\delimitershortfall` is a TeX engine primitive. **Neither KaTeX nor MathJax expose it or honor it** — I tested both directly:
+
+- KaTeX: `\delimitershortfall=-1pt` throws `ParseError: Expected group after '\delimitershortfall'` (undefined control sequence).
+- MathJax v3: the command is silently dropped/renders as an error span; no effect on sizing.
+
+So the web renderers need a different fix.
+
+## Solution 1: a `\grow` macro (portable, works in *any* KaTeX/MathJax page)
+
+Since neither engine's *rule* can be changed from user-level TeX, the workaround changes the **content** being measured instead. Wrap everything inside a bracket pair (except the innermost level) in an invisible padding macro that makes the content measure as slightly taller and deeper than it visually is. Then the normal `\left`/`\right` sizing — which *does* work correctly in both engines — is forced to pick a bigger glyph at each level, because the content it measures really is bigger.
+
+**Mechanism:** for content `#1`, stack a raised zero-width phantom copy 0.5em above it and a lowered zero-width phantom copy 0.5em below it. `\vphantom{#1}` takes zero horizontal space and is invisible, but claims the same height/depth as `#1`. Raising and lowering copies of it extends the *measured* bounding box by 0.5em on each side — 1em of forced growth per wrap — without changing what's visually drawn.
+
+**KaTeX** (verified — `\raisebox` only accepts a text-mode argument, so the phantom must be re-entered as math and forced to `\displaystyle`; without that it silently shrinks to inline size and the trick does nothing):
+
+```latex
+\newcommand{\grow}[1]{#1\raisebox{0.5em}{$\displaystyle\vphantom{#1}$}\raisebox{-0.5em}{$\displaystyle\vphantom{#1}$}}
+```
+
+**MathJax** (verified — `\raisebox` doesn't exist here; plain-TeX `\raise`/`\lower` take a math argument directly and preserve the current style):
+
+```latex
+\newcommand{\grow}[1]{#1\raise{0.5em}{\vphantom{#1}}\lower{0.5em}{\vphantom{#1}}}
+```
+
+**Usage** — wrap the content of every bracket pair except the innermost:
+
+```latex
+\left[ \grow{ \left[ \sqrt{\frac{\int\limits_0^{10}\sqrt{a^2+b^2}}{2}} \right] + 1 } \right]
+```
+
+Verified by rendering with real KaTeX 0.18.7 and MathJax 3.2.2 (headless Chromium screenshots): both show strictly increasing bracket sizes across 2–3 nesting levels, matching the pdfLaTeX reference.
+
+**Trade-offs:**
+- Manual — you place `\grow{}` yourself at each level; it isn't automatic like the LaTeX-engine setting.
+- The two spellings aren't interchangeable: `\raisebox` errors out in MathJax, `\raise`/`\lower` don't exist in KaTeX. Pick the one matching your renderer.
+- Can be defined once (in MathJax's `tex.macros` config, or KaTeX's `macros` render option) so you only write `\grow{...}` per formula, not the full definition each time.
+
+## Solution 2: patch KaTeX directly (better fit for a site you build/host yourself)
+
+Since you control the build (an Astro site rendering KaTeX server-side), you don't need the macro workaround at all — you can restore the actual `\delimitershortfall` behavior by editing the one place KaTeX hard-codes it.
+
+**The code.** KaTeX's delimiter-sizing function (`makeLeftRightDelim`, in the compiled bundle since no per-file TS source ships in the npm package) contains:
+
+```js
+const delimiterFactor = 901;                                   // TeX's \delimiterfactor
+const delimiterExtend = 5.0 / options.fontMetrics().ptPerEm;   // TeX's \delimitershortfall = 5pt
+```
+
+This is the exact same formula from the TeXbook rule above, with the same two constants. Changing `5.0` to `-1.0` is precisely `\delimitershortfall=-1pt` — `delimiterFactor` doesn't need to change, since a negative shortfall always makes the second term of the `max(...)` dominate anyway.
+
+**Verified:** I applied this one-line edit to the installed `katex` package and rendered plain, unmodified `\left[...\right]` source (no `\grow` macro anywhere) through the patched build. Result: strict growth across 4 nesting levels, small content (`(x)`, `((x))`, `(((x)))`) unaffected, and — critically — the LaTeX source embedded in KaTeX's output for copy/paste (`<annotation encoding="application/x-tex">`) stays exactly what you typed, since only the *sizing*, not the *content*, is touched.
+
+**Where the line lives** (npm package, KaTeX 0.16.47):
+
+| File | Used by | Patched here |
+|---|---|---|
+| `src/delimiter.ts` | the readable source the bundles are built from | yes |
+| `dist/katex.mjs` | ESM import — what an Astro/Vite build resolves to | yes |
+| `dist/katex.js` | CJS `require` | yes |
+| `dist/katex.min.js` | only if KaTeX is also loaded client-side via `<script>` | **no** — see below |
+
+`dist/katex.min.js` is left alone on purpose. explico renders every formula at
+build time and ships only `katex.min.css` plus fonts to the browser, so nothing
+here loads that bundle — and because it is a single ~270 KB line, including it
+turns a 2 KB patch into a 550 KB one that no reviewer can read and no KaTeX
+upgrade can rebase. A course that *does* render KaTeX in the browser has to
+patch it too; the minified form of the same line is
+`l=5/n.fontMetrics().ptPerEm` inside `makeLeftRightDelim`.
+
+## How this repo applies it
+
+A `pnpm patch` would work, and is what the section above describes, but it is
+**project-local**: pnpm records it in the consuming repo's
+`pnpm-workspace.yaml`, so it cannot travel inside the published `explico`
+package. Every downstream course would have to reapply it, and a course that
+forgot would render flat nests while its linter told authors the engine handled
+sizing. Documenting that in a migration guide only narrows the window for the
+mistake; it does not close it.
+
+So the engine does the same edit in code, at import time, in
+[`src/reference/katex-delimiters.mjs`](../src/reference/katex-delimiters.mjs):
+
+1. read KaTeX's own ESM bundle off disk (`katex/dist/katex.mjs`);
+2. rewrite that one constant, throwing if it is not found verbatim;
+3. `import()` the rewritten source as a `data:` URL — the bundle has no imports
+   of its own, so it needs no base to resolve against;
+4. move `render`, `renderToString`, `__renderToDomTree` and
+   `__renderToHTMLTree` onto the shared `katex` object every consumer in the
+   process already imported;
+5. render a known nest and throw unless the sizes actually grew.
+
+Step 4 is what makes it reach lesson-body math. `rehype-katex` does its own
+`import katex from 'katex'`, but it calls `katex.renderToString(...)` — a
+property read at call time — and KaTeX's default export is a plain mutable
+object. Replacing the function on that object is therefore enough; the plugin
+does not have to be forked or aliased.
+
+**A course inherits this with no changes.** `astro.config.mjs` already imports
+`createNotationKatexOptions` from `explico/reference/katex-options.mjs`, and
+that module imports the installer for its side effect, so the sizing is in
+place before Astro renders anything. The engine's own non-Astro paths
+(`math-glyphs.mjs`, `render-lab-math.ts`, and therefore `validate:content`)
+import it directly.
+
+**It cannot fail quietly.** Steps 2 and 5 throw. A KaTeX upgrade that moves the
+constant, or anything that renders before the installer runs, stops the build
+with an explicit message instead of silently reverting to stock spacing — which
+is the failure mode a patch file plus a migration note could not rule out.
+
+**Trade-offs.** It is a monkey-patch of a third-party module object, so it
+rests on three upstream properties: the constant is a literal in the shipped
+bundle, the bundle is self-contained, and the default export is mutable. All
+three are asserted at install time rather than assumed. It also holds a second
+copy of the KaTeX module in memory (~600 KB of source, ~50 ms to load) for the
+duration of a build, which is not worth optimising away.
+
+## Why the patch is the better fit here
+
+Your original idea — keep writing `\left[` everywhere, run a build-time preprocessing step that inserts `\grow{}` at each nesting level, then swap in the original source for a "copy" button — would work, but has two costs the patch avoids:
+
+1. **The preprocessor needs a real TeX parser**, not a regex. It has to track bracket nesting depth correctly across `\text{...}`, comments, `\right.` (null right delimiters), and — critically — macros. If you ever define something like `\norm{...}` that *expands* to `\left\lVert...\right\rVert`, a source-level preprocessor can't see the nesting hidden inside the macro and will miscount levels. The patch operates after macro expansion, inside KaTeX's own layout engine, so it can't miss anything.
+2. **The copy-button problem disappears.** KaTeX already embeds your literal input in the hidden MathML `<annotation>` tag — that's what the standard `copy-tex` extension reads. With preprocessing, that annotation would contain the `\grow`-polluted string, so you'd have to intercept the copy handler and substitute the original text yourself. With the patch, the *displayed* math and the *embedded source* never diverge in the first place, because nothing was ever inserted into the source.
+
+## Caveats
+
+- If your pipeline actually renders to **SVG** rather than HTML+CSS, you're using MathJax's `tex-svg` output, not KaTeX (KaTeX renders to HTML spans, not SVG). MathJax's stretchy-delimiter logic lives in the output stage rather than one constants block, so the equivalent patch would be far more invasive there — the `\grow` macro is the practical option for MathJax.
+- On an Astro build, KaTeX runs at build time (via `remark-math`/`rehype-katex` or similar) and only sends finished HTML + `katex.css` + fonts to the browser — the patched JS never ships to visitors, it only needs to be present in your build environment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.7.0",
+  "version": "0.11.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",
@@ -30,6 +30,7 @@
     "README.md",
     "CHANGELOG.md",
     "docs/VERSIONING.md",
+    "docs/katex-bracket-scaling.md",
     "docs/authoring"
   ],
   "dependencies": {
@@ -63,7 +64,7 @@
     "vitest": "4.1.11"
   },
   "scripts": {
-    "build": "tsup && node scripts/copy-assets.mjs && node scripts/fix-esm-extensions.mjs && tsc -p tsconfig.dts-mjs.json",
+    "build": "tsup && node scripts/copy-assets.mjs && node scripts/fix-esm-extensions.mjs && tsc -p tsconfig.dts-mjs.json && node scripts/gen-rules-schema.mjs",
     "check:release-migration": "node scripts/check-release-migration.mjs",
     "test": "vitest run",
     "test:watch": "vitest"