explico 0.11.1 → 0.12.0

package/src/compiler/manifest.ts

@@ -84,6 +84,10 @@ import {
   validateRawFloats,
   type RawFloatDiagnostic,
 } from '../reference/raw-floats-validate';
+import {
+  validateLabKatexImports,
+  type LabKatexDiagnostic,
+} from '../reference/lab-katex-validate';
 import {
   gateContentMath,
   pageScope,
@@ -102,6 +106,7 @@ import { gateCourseRules } from '../reference/gate-course-rules';
 import { gateHeadingLength } from '../reference/gate-heading-length';
 import { gateHeadingStructure } from '../reference/gate-heading-structure';
 import { gatePartPages } from '../reference/gate-part-pages';
+import { gateNonChapterPages } from '../reference/gate-non-chapter-pages';
 import {
   scanSectionHeadings,
   scanTitledBlocks,
@@ -161,6 +166,7 @@ import {
   loadCurriculumCatalog,
   loadNotationDefinitions,
   loadNotationRegistryInput,
+  loadNonChapterPages,
   loadNotationSpecs,
   loadPartOverviews,
   loadSourceRecords,
@@ -290,8 +296,14 @@ import {
  * state of a `<Fold>`; `disclosure.figures` now says whether a lab's tools
  * start open; `diagnostics.folds` holds `fold-unnamed`
  * (docs/plans/figures-and-short-captions.md, Parts 1–2).
+ *
+ * v25 (cards on non-chapter pages, rule S10): `pages` — every docs page that
+ * is not a chapter (the landing page, a part's overview page, …) with its
+ * `id`, `slug`, `file` and a `notation` bundle of the lesson shape, so the
+ * footer renders the cards its `[[key]]` terms and math open.
+ * `notation.bundles` and `notation.backlinks` now carry those pages' ids too.
  */
-export const MANIFEST_SCHEMA_VERSION = 24;
+export const MANIFEST_SCHEMA_VERSION = 25;
 
 const REPOSITORY_ROOT = process.cwd();
 // Content is the top-level `content/` folder; the build output is `build/`
@@ -502,6 +514,20 @@ export interface ManifestLesson {
   };
 }
 
+/**
+ * A docs page that is not a chapter (v25, rule S10) — the landing page, a
+ * part's overview page, any page outside a part directory. It numbers
+ * nothing, so it carries only what its cards need: the notation bundle its
+ * `[[key]]` terms and math reach, shared entries only.
+ */
+export interface ManifestPage {
+  /** `index`, `motion.index`, `glossary` — `lessonIdFromSlug` of the slug; never a lesson id. */
+  readonly id: string;
+  readonly slug: string;
+  readonly file: string;
+  readonly notation: ManifestLesson['notation'];
+}
+
 /** The reader-facing "about this material" bundle — the `[?]` panel's data. */
 export interface ManifestAbout {
   /** `explico`'s own identity, from its `package.json` (the version's golden source). */
@@ -597,6 +623,8 @@ export interface Manifest {
   /** The course's parts in config order, with their chapters and overview pages. */
   readonly parts: readonly ManifestPart[];
   readonly lessons: readonly ManifestLesson[];
+  /** Every docs page that is not a chapter, by id (v25). */
+  readonly pages: readonly ManifestPage[];
   /** Full competency prerequisite graph. */
   readonly prereqEdges: readonly PrereqEdge[];
   /** Equation identity (D7): every labelled display equation + the render-path lookup. */
@@ -660,8 +688,12 @@ export interface Manifest {
     readonly equations: readonly EquationDiagnostic[];
     /** `<Table>` identity checks (F-tables-figures) — same codes, `tab-` prefixed. */
     readonly tables: readonly TableDiagnostic[];
-    /** `<Figure>` identity checks (F-tables-figures) — same codes, `fig-` prefixed. */
-    readonly figures: readonly FigureDiagnostic[];
+    /**
+     * `<Figure>` identity checks (F-tables-figures) — same codes, `fig-`
+     * prefixed — and rule V3's `lab-katex-direct`: a file a lesson imports
+     * that calls KaTeX itself.
+     */
+    readonly figures: readonly (FigureDiagnostic | LabKatexDiagnostic)[];
     /** `<Diagram>` identity checks — same codes, `dia-` prefixed. */
     readonly diagrams: readonly DiagramDiagnostic[];
     /** Knowledge-check identity and `[[check-…]]` reference checks. */
@@ -925,7 +957,19 @@ export async function compileManifest(
     loadAbbreviationRegistryInput(),
   ]);
 
-  const registry = buildNotationRegistry(notationInput);
+  // Rule S10: a page that is not a chapter explains its symbols like a
+  // chapter does, so its references resolve through the same registry and its
+  // text and math pass the same gates. It stays out of `notationInput.lessons`,
+  // which is the chapter list every numbering and curriculum pass reads.
+  const nonChapterPages = loadNonChapterPages();
+  const withPages: typeof notationInput = {
+    ...notationInput,
+    lessons: [
+      ...notationInput.lessons,
+      ...nonChapterPages.map((page) => page.notation),
+    ],
+  };
+  const registry = buildNotationRegistry(withPages);
   // Cards a `formula` may name with `\explain{key}` (D15). Shared entries
   // only: a page-local symbol is not addressable from another entry.
   const cardsByKey = new Map<string, GlyphScopeEntry>(
@@ -956,7 +1000,7 @@ export async function compileManifest(
   };
   const mathIssues = [
     ...gateContentMath({
-      notationInput,
+      notationInput: withPages,
       assessments: assessmentsInput,
       lessonAssessments: catalog.lessons.map((lesson) => ({
         lessonId: lesson.id,
@@ -965,7 +1009,7 @@ export async function compileManifest(
     }),
     ...(rules.isEnabled('N9')
       ? [
-          ...gateProseNotation(notationInput.lessons, {
+          ...gateProseNotation(withPages.lessons, {
             allowSpelledUnits: rules.strings('N9', 'allow'),
           }),
           ...gateProseNotationInAssessments(assessmentsInput, {
@@ -975,13 +1019,13 @@ export async function compileManifest(
       : []),
     ...(rules.isEnabled('N12')
       ? [
-          ...gateMathPunctuation(notationInput.lessons, mathEndAbbreviations),
+          ...gateMathPunctuation(withPages.lessons, mathEndAbbreviations),
           ...gateMathPunctuationInAssessments(assessmentsInput, mathEndAbbreviations),
         ]
       : []),
     ...(rules.isEnabled('N14')
       ? gateAbbreviations({
-          notationInput,
+          notationInput: withPages,
           abbreviations: abbreviationsInput,
           courseAbbreviations: rules.settings('N14'),
         })
@@ -998,7 +1042,9 @@ export async function compileManifest(
     // The course's own rules (`courseRules`): one pass for every enabled `X`
     // rule that carries a `forbid` pattern. A disabled one, and a guide rule
     // with no pattern, do no work here.
-    ...gateCourseRules(notationInput.lessons, rules.course),
+    ...gateCourseRules(withPages.lessons, rules.course),
+    // S10 is locked: a float on a non-chapter page has no number to render.
+    ...gateNonChapterPages(nonChapterPages),
   ];
 
   // Pre-render every assessment `prompt` / `explanation` into text/math
@@ -1077,10 +1123,12 @@ export async function compileManifest(
   }
   // Per-place waivers: drop the located findings each one covers, and
   // report the waivers themselves — a stale one is a warning, a bad one an
-  // error. Only lesson bodies are scanned; a part page has no waivable rule.
+  // error. Chapters and non-chapter pages are scanned alike, since the text
+  // and math gates run on both; S2 and S10 are per-file or locked, so no
+  // waiver reaches them.
   const waiverDiagnostics: WaiverDiagnostic[] = [];
   const waiverRules = { courseRules: rules.course };
-  const waivers = notationInput.lessons.flatMap((lesson) => {
+  const waivers = withPages.lessons.flatMap((lesson) => {
     const collected = collectWaivers(lesson, waiverRules);
     waiverDiagnostics.push(...collected.diagnostics);
     return collected.waivers;
@@ -1369,6 +1417,16 @@ export async function compileManifest(
       },
     );
   };
+  // Rule V3: the course files a lesson's imports reach draw math through
+  // `renderLabMath`, never KaTeX itself.
+  const labKatexDiagnostics = validateLabKatexImports(
+    notationInput.lessons.map((lesson) => ({
+      lessonId: lesson.lessonId,
+      file: lesson.source.file,
+      body: lesson.body,
+    })),
+    REPOSITORY_ROOT,
+  );
   const rawFloatDiagnostics = validateRawFloats(
     notationInput.lessons.map((lesson) => ({
       lessonId: lesson.lessonId,
@@ -1446,10 +1504,27 @@ export async function compileManifest(
     });
   }
   lessons.sort((a, b) => a.id.localeCompare(b.id));
+  const pages: ManifestPage[] = nonChapterPages
+    .map((page) => ({
+      id: page.id,
+      slug: page.slug,
+      file: page.file,
+      notation: lessonNotationBundle(
+        bundlesByLesson.get(page.id),
+        definitionsById,
+        lessonNotationResolution(
+          page.notation,
+          definitionsById,
+          availableDefinitionIds,
+        ),
+        cardsByKey,
+      ),
+    }))
+    .sort((a, b) => a.id.localeCompare(b.id));
 
   const consistencyIssues = runConsistencyChecks({
     registry,
-    notationInput,
+    notationInput: withPages,
     specs: loadNotationSpecs(),
     catalog,
     lintIgnore: loadLintIgnore(),
@@ -1543,6 +1618,7 @@ export async function compileManifest(
     sidebar,
     parts: manifestParts,
     lessons,
+    pages,
     prereqEdges,
     equations: {
       labels: equationValidation.labels,
@@ -1578,7 +1654,7 @@ export async function compileManifest(
       consistency: dropDisabled(consistencyIssues, off),
       equations: dropDisabled(equationValidation.diagnostics, off),
       tables: dropDisabled(tableValidation.diagnostics, off),
-      figures: dropDisabled(figureValidation.diagnostics, off),
+      figures: dropDisabled([...figureValidation.diagnostics, ...labKatexDiagnostics], off),
       diagrams: dropDisabled(diagramValidation.diagnostics, off),
       checks: dropDisabled(checkValidation.diagnostics, off),
       examples: dropDisabled(exampleValidation.diagnostics, off),

package/src/components/CourseContents.astro

@@ -121,6 +121,12 @@ const hours = (range: { min: number; max: number }) => {
     margin-block-start: 1.5rem;
   }
 
+  /* `.not-content` keeps Starlight's Markdown link colour out, so the
+     contents set the course accent on their own links. */
+  .course-contents a {
+    color: var(--sl-color-text-accent);
+  }
+
   .course-meta,
   .part-line {
     display: flex;

package/src/components/PartOverview.astro

@@ -262,6 +262,12 @@ const hasRail =
     margin-block-start: 1.5rem;
   }
 
+  /* `.not-content` keeps Starlight's Markdown link colour out, so the
+     overview sets the course accent on its own links. */
+  .part-overview a {
+    color: var(--sl-color-text-accent);
+  }
+
   .part-meta {
     display: flex;
     flex-wrap: wrap;

package/src/components/abbreviation/AbbreviationGlossary.astro

@@ -21,8 +21,8 @@ const entries = (await getCollection('abbreviations')).sort((left, right) =>
   ) : (
     <dl class="abbreviation-glossary">
       {entries.map((entry) => (
-        <div class="abbreviation-entry" id={`abbr-${entry.data.key}`}>
-          <dt>
+        <div class="abbreviation-entry">
+          <dt id={`abbr-${entry.data.key}`}>
             {entry.data.abbr}
             {entry.data.aliases.length > 0 && (
               <span class="abbreviation-aliases">
@@ -46,6 +46,9 @@ const entries = (await getCollection('abbreviations')).sort((left, right) =>
     row-gap: 0.75rem;
   }
 
+  /* The wrapper puts each `<dt>`/`<dd>` pair straight into the grid, so it
+     has no box of its own: the entry's anchor id sits on the `<dt>`, since
+     an element with no box can never be scrolled to. */
   .abbreviation-entry {
     display: contents;
   }
@@ -53,6 +56,7 @@ const entries = (await getCollection('abbreviations')).sort((left, right) =>
   .abbreviation-entry dt {
     font-weight: 600;
     white-space: nowrap;
+    scroll-margin-block-start: 5rem;
   }
 
   .abbreviation-entry dd {

package/src/components/disclosure/print-as-shown.ts

@@ -16,6 +16,15 @@
  * never prints, open or folded, and is left exactly as it is: no note, not
  * opened for an export.
  *
+ * A note never goes inside an Astro island. An island still waiting to
+ * hydrate (`client:visible` — every knowledge check) that starts while the
+ * page is prepared for print would find a node its framework never rendered
+ * and throw away its server render (React's error #418); a hydrated one's
+ * markup is its framework's to own either way. A closed disclosure inside
+ * an island gets its note after the outermost island instead, once per
+ * target URL: the folded questions of one check all point at the check's
+ * own anchor, so one note after the check says it for all of them.
+ *
  * Two callers share this module:
  * - `LessonExportActions.astro`, the print controller a course gets with
  *   `lessonExports.print`: `'as-shown'` for its print button and the
@@ -90,6 +99,15 @@ function anchorIdFor(element: Element): string | undefined {
   return undefined;
 }
 
+/** The outermost `<astro-island>` around an element, if any. */
+function outermostIsland(element: Element): Element | null {
+  let island: Element | null = null;
+  for (let node = element.parentElement; node; node = node.parentElement) {
+    if (node.tagName === 'ASTRO-ISLAND') island = node;
+  }
+  return island;
+}
+
 function createNote(href: string): HTMLElement {
   const note = document.createElement('div');
   note.className = COLLAPSED_NOTE_CLASS;
@@ -152,20 +170,38 @@ export function prepareDisclosures(
     const insideClosed = (element: Element) =>
       !!element.parentElement?.closest('details:not([open])');
 
+    // The notes already placed after each island: the last one, which the
+    // next follows, and the URLs they name.
+    const afterIsland = new Map<Element, { last: Element; hrefs: Set<string> }>();
+    const place = (element: Element, where: 'before' | 'after') => {
+      const href = options.noteHref(anchorIdFor(element));
+      const island = outermostIsland(element);
+      if (!island) {
+        const note = createNote(href);
+        element[where](note);
+        notes.push(note);
+        return;
+      }
+      const placed = afterIsland.get(island) ?? { last: island, hrefs: new Set<string>() };
+      if (placed.hrefs.has(href)) return;
+      const note = createNote(href);
+      placed.last.after(note);
+      placed.last = note;
+      placed.hrefs.add(href);
+      afterIsland.set(island, placed);
+      notes.push(note);
+    };
+
     for (const details of main.querySelectorAll('details:not([open]):not([data-print-omit])')) {
       if (insideClosed(details)) continue;
-      const note = createNote(options.noteHref(anchorIdFor(details)));
-      details.after(note);
-      notes.push(note);
+      place(details, 'after');
     }
     // Disclosures built on `hidden` rather than `<details>`.
     for (const element of main.querySelectorAll(
       ':is(.short-note, .assessment-panel)[hidden]',
     )) {
       if (insideClosed(element)) continue;
-      const note = createNote(options.noteHref(anchorIdFor(element)));
-      element.before(note);
-      notes.push(note);
+      place(element, 'before');
     }
   }
 

package/src/components/figure/Figure.astro

@@ -84,7 +84,7 @@ if (short !== undefined && (typeof short !== 'string' || !short.trim())) {
 }
 if (!number || !anchorId) {
   throw new Error(
-    'Figure is missing its computed `number`/`anchorId` — this page must run remark-notation with a `figures` cross-page table configured (see astro.config.mjs).',
+    `Figure is missing its computed \`number\`/\`anchorId\`. remark-notation numbers a <Figure> only on a lesson page, at its top level or in a <Memo>, <ShortNote> or <Fold>: elsewhere (a worked example) show the content without <Figure>, and on a page that is not a chapter (rule S10) link the chapter's figure. At a lesson's top level, this page is not running remark-notation with the manifest's \`figures\` (see astro.config.mjs).`,
   );
 }
 
@@ -176,8 +176,13 @@ const name = `Figure ${number}`;
      Q8). A figure that should read as set apart goes in a `### … [card]`
      section. The caption line is styled once for every float, in
      `global.css` (`.float-caption`). */
+  /* A wide picture scrolls sideways. `overflow-x: auto` alone computes
+     `overflow-y` to `auto` too, and a body with no fixed height overflows
+     vertically only by rounding (a fractional height at a browser zoom),
+     which drew a one-pixel vertical scrollbar beside the figure. */
   .keyed-figure__body {
     overflow-x: auto;
+    overflow-y: hidden;
   }
 
   /* A lab's tools: a tray of their own after the caption line — a thin

package/src/components/figure/figure-state.ts

@@ -7,35 +7,44 @@
  * caption (a preview card, a fold's bar, the list of figures) still reads the
  * caption alone, and it prints with the caption.
  *
- * A lab passes its clause as runs of text, never HTML: a string is plain
- * text, `{ text, italic: true }` an italic run (a symbol), `{ sub }` a
- * subscript. There is no `aria-live`: the controls already announce their
- * values.
+ * A lab passes its clause as runs, never its own HTML: a string is plain
+ * text, and `{ math }` is a symbol or a formula — lab math rendered at build
+ * time by `renderLabMath(template, scope, { display: false })`, so each of
+ * its symbols is bound to the page's notation and opens its card, as it
+ * does in the lesson (rule N4). A symbol typed as text — the italic and
+ * subscript runs this took before — opened no card and was not even the
+ * corpus glyph (an italic `x` for a bold `\mathbf{x}`), so they are gone.
+ * There is no `aria-live`: the controls already announce their values.
  */
 
-export type FigureStateRun =
-  | string
-  | { readonly text: string; readonly italic?: boolean }
-  | { readonly sub: string };
+import type { RenderedLabMath } from '../../reference/lab-math-slot';
+
+export type FigureStateRun = string | { readonly math: RenderedLabMath };
 
 type NodeFactory = Pick<Document, 'createElement' | 'createTextNode'>;
 
-/** The nodes for `runs`, made by `doc`. Markup in a run stays text. */
+/**
+ * The nodes for `runs`, made by `doc`. Markup in a text run stays text; a
+ * math run is `renderLabMath`'s own KaTeX, made at build time.
+ */
 export function figureStateNodes(
   runs: readonly FigureStateRun[],
   doc: NodeFactory,
 ): Node[] {
   return runs.map((run) => {
     if (typeof run === 'string') return doc.createTextNode(run);
-    if ('sub' in run) {
-      const sub = doc.createElement('sub');
-      sub.textContent = run.sub;
-      return sub;
+    if (typeof run === 'object' && run !== null && typeof run.math?.html === 'string') {
+      const math = doc.createElement('span');
+      math.className = 'float-caption__math';
+      math.innerHTML = run.math.html;
+      return math;
     }
-    if (!run.italic) return doc.createTextNode(run.text);
-    const italic = doc.createElement('i');
-    italic.textContent = run.text;
-    return italic;
+    throw new TypeError(
+      'setFigureState takes text and { math } runs. A symbol in the clause is ' +
+        'lab math, rendered with renderLabMath(template, scope, { display: false }) ' +
+        'and passed to the island, so that it opens its notation card; an italic ' +
+        'or a sub run no longer exists.',
+    );
   });
 }
 

package/src/components/starlight/LessonFooter.astro

@@ -5,6 +5,11 @@
  * footer. Both layers are optional progressive enhancements over static
  * markup that the remark adapters and the content collections already emit.
  *
+ * A page that is not a chapter (rule S10: the landing page, a part's overview
+ * page) gets the card layers too — notation, citation, abbreviation and float
+ * reference — from its own manifest bundle. The layers that serve a chapter's
+ * numbered floats and outline stay on chapters.
+ *
  * The resolved notation bundle comes from the one compiler manifest (Phase
  * D5); this component never rebuilds the registry.
  */
@@ -38,6 +43,15 @@ const routeSlug = Astro.locals.starlightRoute.entry.id;
 const lessonId = isLessonSlug(routeSlug)
   ? lessonIdFromSlug(routeSlug)
   : undefined;
+const manifest = await loadManifest();
+// A chapter, or a non-chapter page the manifest knows (not the 404 route).
+// The glob loader shortens `<dir>/index.mdx` to the id `<dir>`, and may give
+// the landing page an empty one, so match the page's docs slug either way.
+const routeSlugs = new Set(
+  routeSlug === '' ? ['index'] : [routeSlug, `${routeSlug}/index`],
+);
+const pageId =
+  lessonId ?? manifest.pages.find((page) => routeSlugs.has(page.slug))?.id;
 
 const glossaryBase = `${import.meta.env.BASE_URL.replace(/\/$/, '')}/glossary/`;
 
@@ -45,10 +59,11 @@ const definitions: NotationLayerDefinition[] = [];
 let notationDefaultOpen = false;
 let numberAliases = false;
 let suspended: NotationSuspension[] = [];
-if (lessonId) {
-  const manifest = await loadManifest();
+if (pageId) {
   notationDefaultOpen = manifest.disclosure.notation.defaultOpen;
   numberAliases = manifest.numbering.aliases;
+}
+if (lessonId) {
   const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
   const routeData = Astro.locals.starlightRoute.entry.data as {
     notation?: {
@@ -74,10 +89,15 @@ if (lessonId) {
     .filter((definition) => definition.scope === 'local')
     .map((definition) => definition.key);
   assertLocalNotationParity(lessonId, authoredLocalKeys, renderedLocalKeys);
+}
+if (pageId) {
+  // A non-chapter page renders the bundle its body compiled to, and nothing a
+  // component registered: the glossary's formulas are its own layer's cards,
+  // and rule S10 keeps the floats that would register more off the page.
   const renderedDefinitions = notationDefinitionsForRenderedPage(
     manifest,
-    lessonId,
-    pageNotationDependencies(Astro.locals),
+    pageId,
+    lessonId ? pageNotationDependencies(Astro.locals) : [],
   );
   for (const definition of renderedDefinitions) {
     definitions.push({
@@ -107,10 +127,10 @@ if (lessonId) {
   suspended={suspended}
 />
 <AnchorScrollEnhancer />
-{lessonId && <CitationLayer />}
-{lessonId && <AbbreviationLayer />}
+{pageId && <CitationLayer />}
+{pageId && <AbbreviationLayer />}
 {lessonId && <KeyedFloatEnhancer aliases={numberAliases} />}
-{lessonId && <FloatRefLayer />}
+{pageId && <FloatRefLayer />}
 {lessonId && <CollapsibleSections />}
 {lessonId && <TableOverflowExpander />}
 <DiagramEnhancer />

package/src/components/table/Table.astro

@@ -49,7 +49,7 @@ if (short !== undefined && (typeof short !== 'string' || !short.trim())) {
 }
 if (!number || !anchorId) {
   throw new Error(
-    'Table is missing its computed `number`/`anchorId` — this page must run remark-notation with a `tables` cross-page table configured (see astro.config.mjs).',
+    `Table is missing its computed \`number\`/\`anchorId\`. remark-notation numbers a <Table> only on a lesson page, at its top level or in a <Memo>, <ShortNote> or <Fold>: elsewhere (a worked example) write a plain Markdown table, and on a page that is not a chapter (rule S10) link the chapter's table. At a lesson's top level, this page is not running remark-notation with the manifest's \`tables\` (see astro.config.mjs).`,
   );
 }
 ---

package/src/reference/base-operators.mjs

@@ -13,6 +13,12 @@
  * baseline — trig, the exponential and logarithms, limits, extrema, and the
  * big operators — kept greppable and small like the base library.
  *
+ * Only the plain limit, `\lim`, is baseline. `\limsup` / `\liminf` and the
+ * category-theory `\injlim` / `\projlim` / `\varlimsup` / `\varliminf` /
+ * `\varinjlim` / `\varprojlim` read fine to someone who already knows them,
+ * but none is "everyone knows this" the way `\lim` or `\max` is — a course
+ * that uses one owes it a notation entry, like any other domain operator.
+ *
  * A domain operator (`Var`, `Cov`, `Corr`, `sgn`, `erf`, `Tr`, `argmax`, …) is
  * written `\operatorname{…}` and is NOT here: it earns a card, a
  * `notation.local` entry, or an explicit line in `course.config.ts`
@@ -47,14 +53,6 @@ export const BASE_OPERATORS = Object.freeze(
     'coth',
     // limits
     'lim',
-    'limsup',
-    'liminf',
-    'injlim',
-    'projlim',
-    'varlimsup',
-    'varliminf',
-    'varinjlim',
-    'varprojlim',
     // extrema
     'max',
     'min',