explico 0.2.0 → 0.3.0

package/docs/authoring/versioning.md

@@ -0,0 +1,116 @@
+# Versioning rules
+
+`C` rules govern the course's **knowledge version** — semver over the
+learning-facing content, independent of the `explico` engine's own version. The
+declared value is `about.version` in `content/course.config.ts`; the history and
+the reader-facing notes are in `content/CHANGELOG.md`. Both are surfaced to
+readers by the About `[?]` panel.
+
+See [README.md](README.md) for what "Build-enforced" and "Review-only" mean here.
+The engine's own versioning is a separate policy —
+[`docs/VERSIONING.md`](../VERSIONING.md).
+
+---
+
+## C1
+
+**Every content change lands with a `content/CHANGELOG.md` entry under
+`## [Unreleased]`.**
+
+A change to any lesson `.mdx`, notation entry, assessment, competency, source,
+`content/domain/` file, or `course.config.ts` gets a bullet under
+`## [Unreleased]` in the same commit.
+
+_Rationale._ The knowledge version is meaningless without a record of what moved
+between two values of it. A reader who sees "knowledge v1.4.0" in the `[?]` panel
+can follow `changelogHref` to find out what 1.4.0 means.
+
+_How to apply._ Keep a Changelog shape. One bullet per user-visible change,
+written for a reader, not a commit log:
+
+```markdown
+## [Unreleased]
+
+- Reworked the "Optimal Launch Angle" derivation to use the identity
+  `sin(2θ) = 2 sinθ cosθ` explicitly.
+- New lesson: "Projectile Range with Drag" (motion.range-drag).
+```
+
+_Enforcement._ Review-only. Rule [C3](#c3) partially enforces it: a content
+change with no matching version bump eventually trips the mismatch warning.
+
+_Exceptions._ A pure typo fix in prose that changes no rendered symbol, no
+number, and no outcome. When in doubt, add the bullet.
+
+---
+
+## C2
+
+**The knowledge version is semver over learning-facing content.**
+
+Pick the bump by the largest change in the release:
+
+- **MAJOR** — a lesson, competency, or notation `key` is removed or renamed; a
+  stated learning outcome (`teaches`, a competency `outcome`) changes; a result
+  or convention a reader may have memorised changes.
+- **MINOR** — something new and backward-compatible: a new lesson, section,
+  notation entry, assessment, or worked example.
+- **PATCH** — a fix or clarification: corrected arithmetic, better prose, a added
+  or fixed `[@source]`, a non-semantic notation tweak.
+
+_Rationale._ A downstream consumer of the content (an LMS import, a printed
+reader, a course that forks this one) needs the same "did this break me?" signal
+from the knowledge version that a library gets from a package version.
+
+_How to apply._ Decide the bump when you move `## [Unreleased]` to a dated
+heading ([C4](#c4)); set `about.version` to match.
+
+_Enforcement._ Review-only.
+
+_Exceptions._ None. If a change does not fit a tier, it is PATCH.
+
+---
+
+## C3
+
+**`about.version` equals the newest `## [x.y.z]` heading in
+`content/CHANGELOG.md`.**
+
+_Rationale._ Two sources of the same fact must not drift. The manifest — and so
+the `[?]` panel — reads `about.version`; a reader chasing "what changed" reads
+the changelog. If they disagree, one is lying.
+
+_How to apply._ On a release, edit both in the same commit ([C4](#c4)). Between
+releases, `about.version` stays at the last released value while
+`## [Unreleased]` accumulates bullets.
+
+_Enforcement._ Build-enforced (Tier-3). `pnpm validate:content` emits
+`knowledge-version-mismatch` when they differ, `knowledge-changelog-missing`
+when there is no released heading, and `knowledge-version-invalid` when
+`about.version` is not `x.y.z`. All are warnings — they never fail the build, but
+CI may choose to.
+
+_Exceptions._ None.
+
+---
+
+## C4
+
+**On a release, move `## [Unreleased]` to `## [x.y.z] - YYYY-MM-DD` and bump
+`about.version` in the same commit.**
+
+_Rationale._ A release is the atomic moment the two records agree again
+([C3](#c3)). Splitting it across commits leaves a window where the build warns
+and the panel is wrong.
+
+_How to apply._
+
+1. Choose `x.y.z` from the accumulated `## [Unreleased]` bullets and [C2](#c2).
+2. Rename the heading to `## [x.y.z] - <today>`; add a fresh empty
+   `## [Unreleased]` above it.
+3. Set `about.version` in `content/course.config.ts` to `x.y.z`.
+4. `pnpm validate:content` — no `knowledge-*` warning.
+
+_Enforcement._ Review-only (the end state is checked by [C3](#c3)).
+
+_Exceptions._ None.

package/docs/authoring/visualizations.md

@@ -0,0 +1,195 @@
+# Visualization rules
+
+`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.
+
+See [README.md](README.md) for what "strong recommendation", "Build-enforced",
+and "Review-only" mean here, and how to amend a rule.
+
+---
+
+## V1
+
+**Graphs and flowcharts use the `Diagram` component.**
+
+Any node-and-edge picture — a derivation pipeline, a dependency graph, a state
+machine, a decision tree — is built with
+`explico/components/diagram/Diagram.astro`. It does build-time layout with
+`@dagrejs/dagre` and renders KaTeX-labelled nodes as static SVG through the same
+trust boundary as lesson math.
+
+Do not add Mermaid, cytoscape, react-flow, elkjs, or any other runtime graph or
+layout library. Nothing client-side lays out a graph.
+
+_Rationale._ One diagram primitive means node math is gate-checked and
+hover-explained exactly like prose math (an unresolved glyph fails the build
+with the node id), zero runtime layout code ships, and diagrams render
+identically in print and with JS off.
+
+_How to apply._ Pass `nodes` / `edges` and, if any node has a `formula`, a
+`scope` from `labMathScope` — see
+`playground/content/labs/DerivationDiagram.astro`. A `formula` node's symbols
+must resolve against the page glyph table, same as `NotationFormula`. If
+`Diagram` genuinely cannot express the picture, raise it as an engine gap
+rather than reaching for another library.
+
+_Enforcement._ Review-only.
+
+_Exceptions._ A one-off illustrative schematic that is not a graph (a labelled
+photo, a geometric figure) is a [V2](#v2) figure, not a `Diagram`.
+
+---
+
+## V2
+
+**Static charts: hand-rolled SVG first, then D3, then Observable Plot — chosen
+per figure.**
+
+- **Hand-rolled inline SVG** is the default: zero dependency, covers a single
+  bespoke figure.
+- **D3** once a figure needs real tick-labelled axes, log scales, or several
+  series sharing a scale.
+- **Observable Plot** (`@observablehq/plot`) once a course is authoring many
+  charts per lecture and the per-chart boilerplate of D3 is the bottleneck.
+
+Decide per figure. A lesson may hold an SVG sketch and a Plot chart side by
+side. Whatever the choice, the chart is produced at build time or inside a
+`client:*` island — never a CDN `<script>`.
+
+_Rationale._ The cost curve is real: SVG is free but unscalable, D3 is powerful
+but verbose, Plot is concise but a dependency and a bundle. Matching the tool to
+the figure keeps both the bundle and the authoring effort down.
+
+_How to apply._ For a static (non-interactive) chart, prefer rendering in an
+`.astro` component so nothing hydrates. Reach for an island only when the figure
+responds to input — then it is a [V3](#v3) figure.
+
+_Enforcement._ Review-only.
+
+_Exceptions._ None — this rule _is_ the exception process.
+
+---
+
+## V3
+
+**Interactive figures: a hydrated island, the `renderLabMath` seam for
+equations, and a text alternative.**
+
+An interactive figure is a React island, hydrated `client:visible` (or
+`client:idle`). It carries:
+
+- **Gate-checked math.** Any equation shown in the figure goes through the
+  `labMathScope` / `renderLabMath` / `\slot{}` seam so its symbols are resolved
+  against the page's real notation at build time and the island only patches
+  numbers into pre-rendered KaTeX. 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
+  matters, pair a `range` slider with a `number` field (see `RangeField` in
+  `ProjectileRangeExplorer.tsx`).
+
+_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.
+
+_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
+component.
+
+_Enforcement._ Review-only.
+
+_Exceptions._ None.
+
+---
+
+## V4
+
+**A randomised figure exposes an adjustable, deterministic seed.**
+
+Any figure that draws random numbers has a visible **seed** control — an
+integer, default `0` — shown near the figure. The same seed always produces the
+same figure.
+
+_Rationale._ A figure that reshuffles on every render can't be pointed at ("look
+at the outlier near x = 3"), can't be reproduced in a question, and can't be
+regression-tested. A seed makes randomness a parameter the reader controls.
+
+_How to apply._
+
+- Thread the seed through a real PRNG (e.g. a small `mulberry32` /
+  `splitmix32`), never `Math.random()`.
+- The seed is a control like any other — a `number` field, or a slider over a
+  small range plus a field.
+- Label it plainly ("Random seed") and show its current value.
+
+_Enforcement._ Review-only.
+
+_Exceptions._ None. If the figure is deterministic, there is no seed to show.
+
+---
+
+## V5
+
+**Axis ranges span the first 10 seeds, evaluated at the current values of every
+other control.**
+
+Fix each axis `domain` explicitly. Compute it as the min and max of the plotted
+quantity over **seeds 0–9**, with every non-seed control at its current value.
+Then:
+
+- **Some points, for some seeds, will fall outside the drawn range.** That is
+  expected and fine — clip them. Do **not** autoscale the axis per seed: a
+  domain that jumps as the seed changes defeats the comparison the seed control
+  exists for.
+- **Recompute the domain when any non-seed control changes** (a slider, a
+  toggle). Its old range no longer describes the new family of curves.
+- **Do not recompute the domain when only the seed changes.** The range is a
+  property of the control setting, not of the current draw.
+- Pad the computed range by a small fixed fraction (≈ 5%) so extremes don't sit
+  on the frame.
+- Keep the sample count (`10`) a named constant so it can be tuned in one place.
+
+_Rationale._ A reader steps through seeds to see how much the outcome varies. A
+fixed frame makes that variation legible — points move, the axes don't. Ten
+seeds is enough to size the frame for the typical spread without chasing every
+tail.
+
+_How to apply._ A `useMemo` keyed on all non-seed inputs (not the seed) builds
+the domain:
+
+```ts
+const SEED_SAMPLE_COUNT = 10;
+const RANGE_PAD = 0.05;
+
+const yDomain = useMemo(() => {
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (let seed = 0; seed < SEED_SAMPLE_COUNT; seed++) {
+    for (const point of series({ ...controls, seed })) {
+      if (point.y < lo) lo = point.y;
+      if (point.y > hi) hi = point.y;
+    }
+  }
+  const pad = (hi - lo) * RANGE_PAD || 1;
+  return [lo - pad, hi + pad] as const;
+}, [controls.a, controls.b /* every non-seed control, not seed */]);
+
+// Plot.plot({ y: { domain: yDomain, ... }, ... })
+```
+
+Both axes get this treatment if both carry random spread. If one axis is a
+deterministic sweep (angle 0–90°), give it its natural domain and apply the rule
+only to the random axis.
+
+_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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -27,8 +27,14 @@
   "files": [
     "dist",
     "src",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "docs/VERSIONING.md",
+    "docs/authoring"
   ],
+  "dependencies": {
+    "@dagrejs/dagre": "3.1.1"
+  },
   "peerDependencies": {
     "@astrojs/markdown-remark": "7.2.4",
     "@astrojs/react": "6.0.4",
@@ -38,16 +44,25 @@
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "rehype-katex": "7.0.1",
-    "remark-math": "6.0.0"
+    "remark-math": "6.0.0",
+    "remark-mdx": "3.1.1"
   },
   "devDependencies": {
+    "@astrojs/markdown-remark": "7.2.4",
     "@types/node": "24.13.3",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.5",
+    "katex": "0.16.47",
+    "rehype-katex": "7.0.1",
+    "remark-math": "6.0.0",
+    "remark-mdx": "3.1.1",
     "tsup": "8.5.1",
-    "typescript": "6.0.2"
+    "typescript": "6.0.2",
+    "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",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

package/src/compiler/cli.ts

@@ -35,6 +35,7 @@ import {
 } from '@astrojs/markdown-remark';
 import rehypeKatex from 'rehype-katex';
 import remarkMath from 'remark-math';
+import remarkMdx from 'remark-mdx';
 
 import { createNotationKatexOptions } from '../reference/katex-options.mjs';
 import rehypeFailKatexErrors from '../reference/rehype-fail-katex-errors.mjs';
@@ -169,6 +170,25 @@ export function lessonDiagnostics(
     });
   }
 
+  for (const diagnostic of [
+    ...manifest.diagnostics.tables,
+    ...manifest.diagnostics.figures,
+  ]) {
+    if (
+      diagnostic.lessonId !== id &&
+      diagnostic.file !== file &&
+      !mentions(diagnostic.message, id, file)
+    ) {
+      continue;
+    }
+    out.push({
+      code: diagnostic.code,
+      severity: diagnostic.severity === 'warning' ? 'warning' : 'error',
+      message: diagnostic.message,
+      ...withFile(diagnostic.file),
+    });
+  }
+
   for (const diagnostic of manifest.diagnostics.consistency) {
     if (diagnostic.file !== file && diagnostic.lessonId !== id) continue;
     out.push({
@@ -195,12 +215,19 @@ function processorFor(manifest: Manifest) {
     syntaxHighlight: false,
     smartypants: false,
     remarkPlugins: [
+      // Syntax only (no JSX evaluation) — teaches the parser `<Table>` /
+      // `<Figure>` / `<CompactExample>` are `mdxJsxFlowElement` nodes, same
+      // as the real Astro/MDX build, so `remarkNotation` sees the same tree
+      // shape here that it does there (D7/F-tables-figures parity).
+      remarkMdx,
       remarkMath,
       [
         remarkNotation,
         {
           definitions: manifest.notation.raw,
           equations: manifest.equations.numbersBySlug,
+          tables: manifest.tables.numbersBySlug,
+          figures: manifest.figures.numbersBySlug,
         },
       ],
       [remarkCitation, { sources: manifest.sources }],
@@ -441,6 +468,8 @@ function domainSignaturesForSection(section: string): DomainFileSignatures[] {
 // --- content status ------------------------------------------------------
 
 export interface StatusReport {
+  /** The course's published knowledge version (`about.version`). */
+  readonly knowledgeVersion: string;
   readonly counts: {
     readonly lessons: number;
     readonly competencies: number;
@@ -449,6 +478,8 @@ export interface StatusReport {
     readonly tracks: number;
     readonly notationDefinitions: number;
     readonly keyedEquations: number;
+    readonly keyedTables: number;
+    readonly keyedFigures: number;
   };
   readonly draftDebt: {
     readonly lessons: readonly string[];
@@ -492,18 +523,30 @@ export function contentStatus(manifest: Manifest): StatusReport {
     ...manifest.diagnostics.alignment.map((d) => d.severity),
     ...manifest.diagnostics.math.map((d) => d.severity),
     ...manifest.diagnostics.equations.map((d) => d.severity),
+    ...manifest.diagnostics.tables.map((d) => d.severity),
+    ...manifest.diagnostics.figures.map((d) => d.severity),
     ...manifest.diagnostics.consistency.map(() => 'warning' as const),
+    ...manifest.diagnostics.knowledge.map((d) => d.severity),
   ];
 
   const keyedEquations = manifest.lessons.reduce(
     (count, lesson) => count + lesson.equations.length,
     0,
   );
+  const keyedTables = manifest.lessons.reduce(
+    (count, lesson) => count + lesson.tables.length,
+    0,
+  );
+  const keyedFigures = manifest.lessons.reduce(
+    (count, lesson) => count + lesson.figures.length,
+    0,
+  );
   const assessments = new Set(
     manifest.lessons.flatMap((lesson) => lesson.assessments),
   ).size;
 
   return {
+    knowledgeVersion: manifest.about.knowledge.version,
     counts: {
       lessons: manifest.lessons.length,
       competencies: manifest.competencies.length,
@@ -512,6 +555,8 @@ export function contentStatus(manifest: Manifest): StatusReport {
       tracks: manifest.tracks.length,
       notationDefinitions: manifest.notation.definitions.length,
       keyedEquations,
+      keyedTables,
+      keyedFigures,
     },
     draftDebt: { lessons: draftLessons, notation: draftNotation },
     orphans,
@@ -550,6 +595,8 @@ export interface ContextReport {
     formula?: string;
   }[];
   readonly equations: readonly { key: string; number: string }[];
+  readonly tables: readonly { key: string; number: string }[];
+  readonly figures: readonly { key: string; number: string }[];
   readonly sources: readonly {
     id: string;
     title: string;
@@ -618,6 +665,8 @@ export function contentContext(
         : { formula: definition.formula }),
     })),
     equations: lesson.equations.map((equation) => ({ ...equation })),
+    tables: lesson.tables.map((table) => ({ ...table })),
+    figures: lesson.figures.map((figure) => ({ ...figure })),
     sources: lesson.sources.map((id) => {
       const record = sourceById.get(id) as Record<string, unknown> | undefined;
       return {

package/src/compiler/collections.ts

@@ -36,6 +36,7 @@ import type {
 } from '../reference/types';
 import { isSubstantiveMeaning } from '../reference/prose';
 import { parseEquationRef } from '../reference/equations.mjs';
+import { parseKeyedFloatRef } from '../reference/keyed-jsx-floats.mjs';
 import { resolveLabel } from '../reference/label';
 import { resolveGlosses } from '../reference/gloss';
 import {
@@ -229,9 +230,17 @@ export function extractNotationReferences(
   for (const [pattern, referenceKind] of patterns) {
     for (const match of searchable.matchAll(pattern)) {
       const key = (match[1] ?? '').trim();
-      // `[[eq:key]]` / `[[slug#eq:key]]` are equation references (D7), resolved
-      // by the remark pass and the manifest, not notation keys.
-      if (parseEquationRef(key)) continue;
+      // `[[eq-key]]` / `[[slug#eq-key]]` are equation references (D7), and
+      // `[[tab-key]]`/`[[fig-key]]` (and their cross-page forms) are
+      // `<Table>`/`<Figure>` references (F-tables-figures) — all resolved by
+      // the remark pass and the manifest, not notation keys.
+      if (
+        parseEquationRef(key) ||
+        parseKeyedFloatRef(key, { prefix: 'tab' }) ||
+        parseKeyedFloatRef(key, { prefix: 'fig' })
+      ) {
+        continue;
+      }
       references.push({
         key,
         kind: referenceKind,

package/src/compiler/course-config.ts

@@ -21,6 +21,56 @@ export interface CourseConventions {
   readonly cashFlowPerspectiveCompetency: string;
 }
 
+/**
+ * A course's edits to the shipped named-operator baseline (`BASE_OPERATORS`),
+ * consumed by the `operator-explained` consistency check (rule N8). An operator
+ * a lesson uses is fine when it is on the baseline plus `allow` minus `deny`;
+ * otherwise it needs a notation entry the reader can hover.
+ *
+ * Names are the KaTeX command without its backslash (`erf`, not `\erf`) for a
+ * built-in, and the verbatim body for an `\operatorname{…}` operator (`Var`).
+ */
+export interface CourseOperators {
+  /** Operators this course also treats as universal (`Var`, `Cov`, `sgn`, …). */
+  readonly allow?: readonly string[];
+  /** Baseline operators this course wants explained anyway. */
+  readonly deny?: readonly string[];
+}
+
+/** One person or team credited for the study material. */
+export interface CourseAuthor {
+  readonly name: string;
+  /**
+   * Email, URL, or handle. Rendered in the About panel as a link when it looks
+   * like a `mailto:` or `https:` target, plain text otherwise.
+   */
+  readonly contact?: string;
+}
+
+/**
+ * The reader-facing "about this material" block, surfaced by the `[?]` panel in
+ * the header (`components/starlight/AboutPanel.astro`) on every page.
+ *
+ * `version` is the course's **knowledge version** — semver over the
+ * learning-facing content, independent of the `explico` engine's own version.
+ * It must equal the newest entry in `content/CHANGELOG.md`; a mismatch is a
+ * Tier-3 `knowledge-version-mismatch` warning (rule C3, `docs/authoring/versioning.md`).
+ */
+export interface CourseAbout {
+  /** Display name of the material. Defaults to {@link CourseConfig.title}. */
+  readonly materialName?: string;
+  /** One or two sentences on what the material covers. Defaults to {@link CourseConfig.description}. */
+  readonly summary?: string;
+  /** Knowledge version — semver; equals the latest `content/CHANGELOG.md` heading. */
+  readonly version: string;
+  /** Who authored / maintains the material. At least one entry. */
+  readonly authors: readonly CourseAuthor[];
+  /** Shown verbatim in the About panel — scope, warranty, AI-assistance note. */
+  readonly disclaimer: string;
+  /** Link to the published content changelog (repo blob, docs page, …). */
+  readonly changelogHref?: string;
+}
+
 export interface CourseConfig {
   readonly title: string;
   readonly description: string;
@@ -29,4 +79,8 @@ export interface CourseConfig {
   /** Namespaces used by competency / notation `domain` fields. */
   readonly domains: readonly string[];
   readonly conventions: CourseConventions;
+  /** Reader-facing identity + knowledge version (the `[?]` About panel). */
+  readonly about: CourseAbout;
+  /** Edits to the shipped named-operator baseline (rule N8). Optional. */
+  readonly operators?: CourseOperators;
 }