explico 0.11.0 → 0.12.0

package/docs/authoring/migrating.md

@@ -33,6 +33,277 @@ required config block throws with the section of this file to read.
 
 ---
 
+## 0.11.1 → 0.12.0
+
+**Course changes may be required.** Four changes can fail a build that
+passed on 0.11.1:
+
+- a lab that calls KaTeX itself (rule V3, rule N4; step 2);
+- a caption run typed as text in `setFigureState` (step 3);
+- a numbered float, a lab, an equation label or a notation block on the
+  landing page or a part's overview page (rule S10; step 4);
+- a symbol that page shows without introducing it, now that its math binds
+  like a chapter's (rule S10, rule N4; step 5).
+
+The rest is additive, or a fix a course may clean up after (steps 6–9).
+Nothing in `astro.config.mjs` changes, and no `CourseConfig` field is added
+or removed. The manifest schema is now v25 (step 8).
+
+### 1. Update the dependency
+
+```bash
+pnpm add -D explico@0.12.0
+```
+
+### 2. A lab never calls KaTeX itself (rule V3, rule N4)
+
+`pnpm validate:content` now follows each lesson's relative imports into the
+course's components and fails, as `lab-katex-direct`, a file that imports
+`katex` (a type-only import and `katex/dist/katex.min.css` are fine). It
+names the chain of imports that reaches the file. `astro build` then fails
+any letter KaTeX drew inside a `<Figure>` outside a notation binding
+(`figure-symbols.ts`). Upright text (`\text{}`, `\mathrm{}`, `\sin`) is
+exempt. Find the offenders:
+
+```bash
+rg -n "from ['\"]katex['\"]|require\(['\"]katex['\"]\)" content src
+```
+
+For each helper that renders math with `katex.renderToString` (an
+`InlineMath`, an SVG label, a legend), render the math at build time in the
+lab's `.astro` wrapper instead, and hand it to the island as a prop:
+
+```astro
+---
+import { labMathScope } from 'explico/reference/lab-math-scope';
+import { renderLabMath, type RenderedLabMath } from 'explico/reference/render-lab-math';
+
+const entry = Astro.locals.starlightRoute.entry;
+const scope = await labMathScope(
+  (entry.data as { notation?: { local?: Array<{ key: string; latex: string }> } }).notation,
+  `${entry.body ?? ''}\n${Object.values(MY_LAB_MATH).join('\n')}`,
+  { locals: Astro.locals, context: 'MyLab symbols' },
+);
+const symbols: Record<string, RenderedLabMath> = {};
+for (const [id, template] of Object.entries(MY_LAB_MATH)) {
+  symbols[id] = renderLabMath(template, scope, { display: false });
+}
+---
+<MyLabPlot client:visible symbols={symbols} />
+```
+
+`{ display: false }` is new in this release. It renders inline math for a
+legend entry, an axis title or a control label, and it never scrolls. The
+island then places the pre-rendered HTML where it drew text before.
+`playground/content/labs/ProjectileRangePicture.astro` and
+`LaunchAnglePicture.astro` in the explico repository are complete examples,
+and `node_modules/explico/docs/authoring/visualizations.md#v3` is the rule.
+
+If the course has browser tests, add the same check for what an island draws
+only in the browser:
+
+```ts
+import { unboundFigureSymbols } from 'explico/reference/figure-symbols';
+expect(unboundFigureSymbols(await figure.evaluate((el) => el.outerHTML))).toEqual([]);
+```
+
+### 3. `setFigureState` runs: a string or `{ math }`
+
+```bash
+rg -n "setFigureState|italic:\s*true|\{\s*sub:" content src
+```
+
+The `{ text, italic: true }`, `{ text }` and `{ sub }` runs are gone. One
+passed anyway throws, naming the fix, and `astro check` fails it, since
+`FigureStateRun` is now `string | { math: RenderedLabMath }`. Write plain
+text as a string. Write a symbol as `{ math: symbols.launchSpeed }`, rendered
+as in step 2 with `renderLabMath(…, { display: false })`. The caption's
+symbol then opens its card. `ProjectileRangeExplorer.tsx` in the playground
+shows the finished clause.
+
+### 4. A page that is not a chapter numbers nothing (rule S10)
+
+This covers `content/docs/index.mdx`, every `content/docs/<part>/index.mdx`,
+and any other page outside a part directory. `pnpm validate:content` fails
+each of the following there. The rule is locked, so it cannot be turned off
+or waived.
+
+```bash
+rg -n "<(Table|Figure|Diagram|CompactExamples|AssessmentSet)[\s/>]|client:|\\\\label\{eq:" \
+  content/docs/*.mdx content/docs/*/index.mdx
+```
+
+| Diagnostic | What it found | The edit |
+| --- | --- | --- |
+| `non-chapter-float` | `<Table>`, `<Figure>`, `<Diagram>`, `<CompactExamples>`, `<AssessmentSet>` | Move it into the chapter it belongs to, and link it from here with `[[<chapter>#tab-<key>]]` (`fig-`, `dia-`, `ex-`, `check-`). The link's card previews it. A `<Diagram>` rendered here unnumbered on 0.11.1. |
+| `non-chapter-float` | a component imported from a `labs/` module, or any `client:*` island | Move it into a chapter's `<Figure>` and link that figure. |
+| `non-chapter-float` | `\label{eq:…}` | Drop the label (the equation shows unnumbered), or link the chapter's equation with `[[<chapter>#eq-<key>]]`. |
+| `non-chapter-local-notation` | `notation.local` or `notation.suspend` in the frontmatter | Move the entry to the chapter that introduces the symbol, or to shared notation (`content/notation/`), and name it with `[[key]]`. |
+| `non-chapter-plain-text` | `$…$` or `[[…]]` in `hero.title`, `hero.tagline` or a `<PartOverview chain>` step | Write words. These strings are plain text and print markup literally; a symbol with its card goes in the page body. |
+
+A plain Markdown table has no caption and no number, so it stays allowed.
+
+### 5. Math on such a page binds like a chapter's (rule S10, rule N4)
+
+The landing page and the overview pages now open cards: `[[key]]`, bound
+math, citations, abbreviations and `[[chapter#tab-key]]` links, from the
+page's own notation bundle. That bundle holds shared entries only. The same
+gates as a chapter's now scan these pages: rule N4, rule N8, rule N9,
+rule N10, rule N12, rule N14, rule N22, and the course's `X` rules. Plain
+`$v$` that rendered with no card on 0.11.1 now fails the build. Run
+`pnpm validate:content` and fix each finding as in a chapter:
+
+- **An unresolved symbol:** introduce it with `[[key]]` in the prose before
+  it, or wrap it in `\explain{key}{…}`. The key must be a shared one.
+- **A quantity, unit or operator in prose (rule N9), a `\mathrm{}` label
+  (rule N10), punctuation after display math (rule N12), an abbreviation
+  (rule N14), a decoration (rule N22):** fix it as the rule page says.
+  A waivable rule can be waived at one place with
+  `{/* explico-allow <ID>: <reason> */}` here as in a chapter.
+
+Rule S2's "its math and `[[key]]` references render" in a part page's
+`<PartBridge>` and `<PartScope>` now holds. A course that kept symbols off
+its overview pages because `[[key]]` failed the build (data-science-I's
+`tests/source-structure.test.mjs` check, for example) can drop that
+workaround and write its recaps with symbols.
+
+### 6. The operator baseline keeps only `\lim` (rule N8)
+
+`\limsup`, `\liminf`, `\injlim`, `\projlim`, `\varlimsup`, `\varliminf`,
+`\varinjlim` and `\varprojlim` left `BASE_OPERATORS`. A course that uses one
+now gets rule N8's `operator-explained` warning.
+
+```bash
+rg -n '\\(lim(sup|inf)|injlim|projlim|varlim(sup|inf)|varinjlim|varprojlim)\b' content
+```
+
+For each hit, give the operator a notation entry, or allow it for the whole
+course in `rules.N8.allow` (`course.settings.json`, or `rules` in
+`course.config.ts`):
+
+```json
+"rules": { "N8": { "allow": ["limsup", "liminf"] } }
+```
+
+### 7. Clean-ups the fixes allow
+
+Each is conditional; no hit means nothing to do.
+
+- **Rule S3 waivers for a table in a worked example.** A table inside
+  `<CompactExamples>` no longer reports `raw-table-markdown` or
+  `raw-table-html`, so a waiver written for it is now reported as
+  `waiver-unused`. Delete each
+  `{/* explico-allow S3: … */}` that `pnpm validate:content` names.
+- **Link colour on part pages and in `<CourseContents>`.** Links there use
+  `--sl-color-text-accent` now. Drop a course rule that set it
+  (`rg -n "\.part-overview a|\.course-contents a" src content`).
+- **Workarounds for the menu button under the header on a phone, the
+  abbreviation glossary's anchors (`#abbr-…`), a figure's one-pixel vertical
+  scrollbar, or a 2 px scroll on a display equation that just fits.** Each
+  is fixed in the engine's stylesheet or component; drop the course's own
+  rule for it.
+- **A `lint-ignore.yml` line for a kebab-case key.** A `<detail>` may now
+  hold a hyphen (`- notation-units:arg-min — …`). A course that shortened or
+  dropped such a line to get the file to load can write it as intended.
+- **An `unused-definition` acknowledgement for a `notation.local` entry a
+  page uses only by shape** (rule N22's `{}'` for `w'`) is no longer needed.
+  The page's own local entries now seed its bundle.
+
+### 8. Manifest schema v25, and other code-facing changes
+
+Only for course code that reads `build/manifest.json` or calls engine
+helpers directly:
+
+- The manifest schema is now v25. A new `pages` array lists every docs page
+  that is not a chapter, each with an `id` (`index`, `<part>.index`,
+  `glossary`), a `slug`, a `file` and a `notation` bundle of the lesson
+  shape. `notation.bundles` and `notation.backlinks` now carry these page
+  ids too, so code that looks each id up in `lessons` must skip one it does
+  not find. Update any `schemaVersion` assertion to 25.
+- `notationDefinitionsForRenderedPage(manifest, pageId, dependencies)` takes
+  a lesson id or a `manifest.pages[].id`. Its errors, and the local-notation
+  parity error, are reworded ("on page …", "notation mismatch"). Update a
+  test that matched the old text.
+- `.lab-math` no longer scrolls or pads; its `.katex-display` does. A
+  float's caption line is at least `1.5rem` tall while it shows a tool
+  button.
+
+### 9. Things readers see, with no course action
+
+A link the author wrote to another chapter now shows that chapter's full
+title as its tooltip (a `title` attribute), unless it has a title of its
+own. An indented `[[key]]` inside a component in an `.mdx` page (a Starlight
+`<Card>`, say) reaches the page's bundle, where 0.11.1 failed the build.
+Printing a page no longer breaks a knowledge check. Re-record screenshots
+that show a caption line, a lab's math, or a chapter link's tooltip.
+
+### 10. Verify
+
+```bash
+pnpm validate:content        # run twice: the first run regenerates build/resolution/*
+pnpm content check --changed
+astro check
+astro build
+```
+
+Then run the course's browser tests, if it has any.
+
+## 0.11.0 → 0.11.1
+
+**No course changes required.** This release has one fix, in the engine's
+stylesheet. A label in the navigation or the "On this page" panel that does
+not fit now wraps onto more lines instead of scrolling sideways, and that
+includes a panel the reader resized. No authoring rule, `CourseConfig` field,
+Astro wiring, course script or CLI command changes. The manifest schema stays
+v24.
+
+### 1. Update the dependency
+
+```bash
+pnpm add -D explico@0.11.1
+```
+
+**Coming from 0.8.0:** follow the "Coming from 0.8.0" note of "0.10.0 →
+0.11.0" below, and install 0.11.1 wherever it says to install 0.11.0.
+
+### 2. Only if your course CSS or browser tests reach into the side panels
+
+```bash
+rg -n 'data-(navigation|contents)-resized|\.sidebar-pane|\.right-sidebar|layout-(navigation|page-sidebar)-content' src content tests
+```
+
+No hit means nothing to do. Otherwise:
+
+- **A resized panel's labels** have `white-space: normal` (it was `nowrap`),
+  and the panel never scrolls sideways. A test that asserted `nowrap`, or
+  `scrollWidth > clientWidth` after narrowing a panel, now asserts that the
+  labels wrap and stay inside the panel.
+- **`.sidebar-pane`** has `overflow-x: hidden` at every width. The resized
+  "On this page" panel no longer sets `overflow-x: auto` or
+  `scrollbar-width: thin`, so it hides its scrollbar, as Starlight does by
+  default.
+- **In a resized "On this page" panel**, the column
+  (`.right-sidebar-panel .sl-container`) fills the panel. Its width used to
+  come from the navigation's `--sl-sidebar-width`. The default,
+  shrink-to-fit rail is unchanged.
+- **Word breaking.** Both panels' labels take `overflow-wrap: break-word`
+  and `hyphens: auto`, which replaces Starlight's `overflow-wrap: anywhere`
+  on the contents links. To break words differently, set these properties
+  on `.layout-navigation-content`, `.layout-page-sidebar-content` and
+  `.layout-page-sidebar-content a` in the course CSS.
+- **Screenshots** of a narrowed panel need re-recording.
+
+### 3. Verify
+
+```bash
+pnpm validate:content        # run twice: the first run regenerates build/resolution/*
+pnpm content check --changed
+astro check
+astro build
+```
+
+Then run the course's browser tests, if it has any.
+
 ## 0.10.0 → 0.11.0
 
 **Course changes are required.** Figures and diagrams no longer compact.

package/docs/authoring/notation.md

@@ -225,7 +225,10 @@ validate:content`; `astro build` re-runs the same resolver) fails on an
 unresolved glyph (`unresolved-glyph`) in every rendered-math context;
 `consistency.ts` adds the corpus-level lints `glyph-unique-in-corpus`
 (warning), `weak-local`, `gloss-wants-promoting`, `card-wants-demoting`
-(info); a final rendered-trigger/payload parity check backs it at render time.
+(info); a final rendered-trigger/payload parity check backs it at render time,
+and a last pass over every built page fails a symbol a figure shows that KaTeX
+drew outside a notation binding (`figure-symbols.ts`: a lab that called KaTeX
+itself — see [V3](visualizations.md#v3)).
 This rule is **locked** — the notation layer is this rule, so a course cannot
 turn it off.
 

package/docs/authoring/structure-rules.md

@@ -1,7 +1,8 @@
 # Structure rules
 
 `S` rules govern the shape of a lesson's headings, the short captions on its
-keyed floats, the paragraphs that open a part page, and how a table, a
+keyed floats, the paragraphs that open a part page, what a page that is not
+a chapter may carry, and how a table, a
 diagram, or a convention is declared so the rest of the course can reach it —
 the parts of a page a reader scans, links to, or cites. This
 is not [structure.md](structure.md), which is the taxonomy these rules (and
@@ -109,7 +110,8 @@ launch angle that gives the largest range.
 ```
 
 Keep a blank line inside each tag, so MDX parses the paragraph as Markdown and
-its math and `[[key]]` references render.
+its math and `[[key]]` references render with their cards
+([S10](#s10)). A part page recalls symbols; it defines none.
 
 The word range is a course setting, `rules.S2` in `course.settings.json`
 (`CourseConfig.rules`). Each end defaults to 30–150 words; list only what
@@ -184,9 +186,13 @@ validate:content`) — a warning per lesson (`raw-table-markdown`,
 `raw-table-html`); `remarkNotation` repeats it at render time for content
 added since the manifest was compiled. It does not fail the build.
 
-_Exceptions._ A table inside a component that already gives it identity is
-out of scope: the scan only counts tables at the top level of the lesson
-body.
+_Exceptions._ The scan counts a table only where a `<Table>` would number
+it: at the top level of the lesson body, or in a `<Memo>`, `<ShortNote>` or
+`<Fold>`, which keep their place in the reading order. A table already inside
+a `<Table>` or `<Figure>` has its identity. A table in a worked example
+(`<CompactExample>`) or in another component is illustrative, like an
+equation there: leave it a plain Markdown table. A `<Table>` there gets no
+number, and the build fails on it with that reason.
 
 ## S4
 
@@ -449,3 +455,67 @@ title from one that builds on it.
 _Exceptions._ A float that needs no name of its own may go without a
 `short`; the "Figures and tables" page then lists it by its long caption,
 muted.
+
+## S10
+
+**A page that is not a chapter — the landing page, a part’s overview page —
+explains its symbols like a chapter, but carries no numbered float: it links
+the chapter’s float instead.**
+
+This applies to `content/docs/index.mdx`, to every
+`content/docs/<part>/index.mdx`, and to any other page outside a part
+directory. What makes a card works there as in a chapter:
+
+- a `[[key]]` term and `\explain{key}{…}` in math, each opening its card;
+- plain math, bound symbol by symbol, so every symbol it shows is explained;
+- a citation `[@id]`, an abbreviation, and a link to a chapter’s float,
+  `[[motion/constant-acceleration#tab-kinematics-summary]]`, whose card
+  previews the table.
+
+The math and prose rules hold there too ([N4](notation.md#n4),
+[N9](notation.md#n9), [N10](notation.md#n10), [N14](notation.md#n14), and a
+course’s `X` rules). What such a page may not carry:
+
+| Not here | Instead |
+| --- | --- |
+| `<Table>`, `<Figure>`, `<Diagram>`, `<CompactExamples>`, `<AssessmentSet>` | Link the chapter’s float: `[[<chapter>#tab-<key>]]` (`fig-`, `dia-`, …). |
+| A lab, or any `client:*` island | Link the chapter’s `<Figure>` that holds it. |
+| `\label{eq:…}` on a display equation | Drop the label (the equation shows unnumbered), or link the chapter’s equation. |
+| `notation.local`, `notation.suspend` | Define the symbol in the chapter that introduces it, or in shared notation, and name it with `[[key]]`. |
+| `$…$` or `[[…]]` in `hero.title`, `hero.tagline`, a `<PartOverview chain>` step | Write words; these strings are plain text and print markup literally. |
+
+```mdx
+<PartScope>
+
+Part 1 ended on a point that moves under a constant acceleration
+[[motion.acceleration]]. The worked examples in
+[[motion/constant-acceleration#tab-kinematics-summary]] give its velocity.
+
+</PartScope>
+```
+
+A plain Markdown table is ordinary text on such a page: it has no caption and
+no number, so it is not a float.
+
+_Rationale._ A float number starts with its chapter’s number, and a page that
+is not a chapter has none: a table on a part page would need a number that
+collides with a chapter’s, or no number, which makes it the one float in the
+course a reference cannot reach. A part page in a printed book points to the
+chapters’ floats and does not copy them. The reference card gives the reader
+the same view without the copy. Symbols are different: an overview that
+recalls a result needs its symbols, and a symbol without its card breaks the
+promise every other page keeps.
+
+_How to apply._ Write the overview’s recap with the chapter’s own symbols,
+each introduced with `[[key]]`. Where the recap leans on a table, figure or
+equation, link it instead of repeating it. If a symbol has no shared entry,
+recall it in words or give it one in `content/notation/`.
+
+_Enforcement._ Build-enforced (`gate-non-chapter-pages.ts`,
+`pnpm validate:content`): `non-chapter-float` for a numbered block, a lab or
+an equation label; `non-chapter-local-notation` for a notation block;
+`non-chapter-plain-text` for markup in a plain-text string. `astro build`
+fails the same numbered block and equation label at render time. This rule is
+**locked**: turning it off would not give the page a number to print.
+
+_Exceptions._ None.

package/docs/authoring/structure.md

@@ -154,6 +154,14 @@ missing, holds more than one paragraph, or falls outside the course's
 takes no float numbers, and never appears in `manifest.lessons` or a track. A
 course adds one part at a time; a part without one behaves exactly as before.
 
+**It explains its symbols, and links its floats**
+([S10](structure-rules.md#s10)). A `[[key]]` term, math, a citation, an
+abbreviation and a `[[chapter#tab-key]]` link each open their card on an
+overview page, as on the landing page and any other page outside a part; the
+manifest lists each such page under `pages` with its notation bundle. A
+`<Table>`, `<Figure>`, `<Diagram>`, lab or `\label{eq:…}` stays in its
+chapter, which alone can number it, and the overview links it.
+
 `<PartOverview>` reads the manifest for everything it lists — chapters in
 reading order with their descriptions, the competencies the part teaches, the
 parts it builds on and leads to — so the page cannot fall out of date with the
@@ -432,6 +440,12 @@ that wants them addressed should wrap the table in `<Table id="…">`/
 `<Figure id="…">`, or give the diagram an `id` and move it to the top level (or
 inside `<Memo>`/`<ShortNote>`), or wrap it in `<Figure>`.
 
+A raw table counts only where a `<Table>` would number it: at the top level,
+or in a `<Memo>`, `<ShortNote>` or `<Fold>`. One in a worked example
+(`<CompactExample>`) or another component is illustrative, like an equation
+there, and stays a plain table: a `<Table>` or a `<Figure>` there gets no
+number, and the build fails on it, naming the component it sits in.
+
 ### Knowledge checks
 
 An assessment title is authored once, in `content/assessments/<id>.json`, and

package/docs/authoring/visualizations.md

@@ -115,11 +115,15 @@ equations.**
 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
+- **Gate-checked math.** Every symbol the figure shows — an equation, a
+  legend entry, an axis title, a slider label — 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. A wrapper whose template names notation not
-  otherwise present in lesson MDX passes
+  numbers into pre-rendered KaTeX. `renderLabMath(template, scope)` renders a
+  display equation; `renderLabMath(template, scope, { display: false })`
+  renders inline math for a formula that sits in a line, which never scrolls.
+  A lab never calls KaTeX itself: its symbols would open no card. A wrapper
+  whose template names notation not otherwise present in lesson MDX passes
   `{ locals: Astro.locals, context: '<ComponentName> <template>' }` as the third
   `labMathScope` argument; that is the declaration that ships those definitions
   in this page's popup payload. See
@@ -136,8 +140,7 @@ An interactive figure is a React island, hydrated `client:visible` (or
   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
+  with its controls after it. 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
@@ -151,10 +154,13 @@ An interactive figure is a React island, hydrated `client:visible` (or
   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.
+  of its own inside the figure and each run a string of plain text or
+  `{ math }`, a symbol rendered at build time with
+  `renderLabMath(template, scope, { display: false })` and handed to the
+  island — never HTML, and never a symbol typed as text, which would open no
+  card. `ProjectileRangePicture.astro` renders the playground's. 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
@@ -184,7 +190,17 @@ _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.
+_Enforcement._ Partly build-enforced. `pnpm validate:content` follows each
+lesson's relative imports to the course's components and fails one that
+imports `katex` itself (`lab-katex-validate.ts`, `lab-katex-direct`, an
+error), naming the chain of imports that reaches it. `astro build` then reads
+every figure it rendered and fails a symbol KaTeX drew outside a notation
+binding (`figure-symbols.ts`, rule [N4](notation.md#n4)); a course's browser
+test runs the same `unboundFigureSymbols` on a hydrated figure's
+`outerHTML`, which also holds what an island draws only in the browser, as
+the playground's `labs.spec.ts` does. `setFigureState` takes no symbol typed
+as text, so `astro check` fails an italic or a `sub` run. That a lab labels
+its controls and names nothing of its own is review-only.
 
 _Exceptions._ None.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.11.0",
+  "version": "0.12.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/astro.ts

@@ -12,6 +12,7 @@ import {
   writeManifest,
 } from './manifest';
 import { missingNotationPayloadKeys } from '../reference/page-notation';
+import { assertFigureSymbolsBound } from '../reference/figure-symbols';
 import { writeStandaloneLessonExports } from './exports/standalone-html';
 import remarkAbbreviations from '../reference/remark-abbreviations.mjs';
 import remarkCitation from '../reference/remark-citation.mjs';
@@ -99,7 +100,12 @@ async function buildDevelopmentDownloads(
   }
 }
 
-/** Fail loudly instead of rendering math triggers whose local cards are stale. */
+/**
+ * Fail loudly instead of rendering math triggers whose local cards are
+ * missing. The manifest bundles every `notation.local` entry with its page,
+ * so the two lists differ only when the manifest is older than the page, or
+ * when `validate:content` rejected an entry.
+ */
 export function assertLocalNotationParity(
   lessonId: string,
   authoredKeys: readonly string[],
@@ -114,10 +120,13 @@ export function assertLocalNotationParity(
     return;
   }
   throw new Error(
-    `Stale Explico manifest for ${lessonId}: lesson notation.local has ` +
-      `[${authored.join(', ')}], but the page notation bundle has ` +
-      `[${rendered.join(', ')}]. Pass courseConfig to loadManifest() and add ` +
-      `explicoContentRefresh() to the Astro integrations.`,
+    `Explico notation mismatch for ${lessonId}: the page's frontmatter ` +
+      `notation.local declares [${authored.join(', ')}], but the manifest's ` +
+      `notation bundle for the page holds [${rendered.join(', ')}]. The ` +
+      `manifest bundles every notation.local entry with its page, so either ` +
+      `it is stale — pass courseConfig to loadManifest() and add ` +
+      `explicoContentRefresh() to the Astro integrations — or ` +
+      `\`pnpm validate:content\` rejected an entry: fix the errors it reports.`,
   );
 }
 
@@ -228,7 +237,9 @@ async function validateGeneratedNotationPayloads(directory: URL): Promise<void>
       if (entry.isDirectory()) {
         await walk(child);
       } else if (entry.isFile() && entry.name.endsWith('.html')) {
-        assertNotationPayloadHtml(relative(root, child), await readFile(child, 'utf8'));
+        const html = await readFile(child, 'utf8');
+        assertNotationPayloadHtml(relative(root, child), html);
+        assertFigureSymbolsBound(relative(root, child), html);
       }
     }
   };

package/src/compiler/collections.ts

@@ -238,15 +238,21 @@ function sourceSpan(file: string, text?: string, index?: number): SourceSpan {
   };
 }
 
-function maskMarkdownLiterals(text: string): string {
+/**
+ * Blank code, keeping every newline. An indented line is code only in `.md`:
+ * MDX has no indented code block, so text indented inside a component
+ * (`<Card>`, `<Memo>`) is prose, and its `[[key]]` renders a term.
+ */
+function maskMarkdownLiterals(text: string, mdx: boolean): string {
   const mask = (value: string) => value.replace(/[^\n]/g, ' ');
-  return text
-    .replace(
-      /(^|\n)[ \t]{0,3}(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?:\n[ \t]{0,3}\2[^\n]*(?=\n|$)|$)/g,
-      mask,
-    )
-    .replace(/^(?: {4}|\t).*$/gm, mask)
-    .replace(/(`+)(?!`)([^\n]*?)\1/g, mask);
+  const fenced = text.replace(
+    /(^|\n)[ \t]{0,3}(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?:\n[ \t]{0,3}\2[^\n]*(?=\n|$)|$)/g,
+    mask,
+  );
+  return (mdx ? fenced : fenced.replace(/^(?: {4}|\t).*$/gm, mask)).replace(
+    /(`+)(?!`)([^\n]*?)\1/g,
+    mask,
+  );
 }
 
 /**
@@ -259,7 +265,7 @@ export function extractNotationReferences(
   kind: NotationReferenceInput['kind'] | undefined,
 ): NotationReferenceInput[] {
   const references: NotationReferenceInput[] = [];
-  const searchable = maskMarkdownLiterals(text);
+  const searchable = maskMarkdownLiterals(text, file.endsWith('.mdx'));
   const patterns: readonly [RegExp, NotationReferenceInput['kind']][] = [
     [/\[\[\s*([^\][]+?)\s*\]\]/g, kind ?? 'prose'],
     [/\\explain\{([^{}]+)\}/g, kind ?? 'math'],
@@ -635,6 +641,58 @@ function notationLessonEntries(): NotationLessonInput[] {
   return lessons;
 }
 
+/**
+ * A docs page that is **not a chapter** (rule S10): the landing page, a part's
+ * overview page, and any other page outside a part directory — every slug
+ * `isLessonSlug` rejects. Such a page may explain its symbols like a chapter,
+ * but it recalls them only: it takes no `notation.local` and no float numbers.
+ */
+export interface NonChapterPage {
+  /** `lessonIdFromSlug(slug)` — `index`, `motion.index`, `glossary`. Never a lesson id. */
+  readonly id: string;
+  /** Docs slug without extension, e.g. `motion/index`. */
+  readonly slug: string;
+  readonly file: string;
+  readonly data: Record<string, unknown>;
+  readonly body: string;
+  readonly bodyLine: number;
+  /**
+   * The page as notation input — no local entries, no suspensions — so the
+   * registry resolves its `[[key]]` references and the text and math gates
+   * scan it exactly as they scan a chapter.
+   */
+  readonly notation: NotationLessonInput;
+}
+
+export function loadNonChapterPages(): NonChapterPage[] {
+  const pages: NonChapterPage[] = [];
+  for (const path of filesBelow(join(CONTENT_ROOT, 'docs'), ['.md', '.mdx'])) {
+    const slug = docSlug(path);
+    if (isLessonSlug(slug)) continue;
+    const { file, data, body, bodyLine } = parseDocument(path);
+    const id = lessonIdFromSlug(slug);
+    pages.push({
+      id,
+      slug: slug.replace(/\.(md|mdx)$/, ''),
+      file,
+      data,
+      body,
+      bodyLine,
+      notation: {
+        lessonId: id,
+        status: status(data.editorialStatus ?? 'draft', `${file} editorialStatus`),
+        localDefinitions: [],
+        suspended: [],
+        references: extractNotationReferences(body, file, undefined),
+        body,
+        bodyLine,
+        source: { file },
+      },
+    });
+  }
+  return pages;
+}
+
 export async function loadNotationRegistryInput(): Promise<NotationRegistryInput> {
   return {
     sharedDefinitions: sharedNotationEntries(),