explico 0.3.0 → 0.4.0

package/src/reference/keyed-jsx-floats.mjs

@@ -22,7 +22,11 @@
  * `equations.test.ts` holds equations to.
  */
 
-import { stripFencedCode, stripJsxComponents } from './equations.mjs';
+import {
+  resolveNumbering,
+  stripFencedCode,
+  stripJsxComponents,
+} from './equations.mjs';
 
 /** Same shape as `EQ_KEY_PATTERN` — the notation-key grammar without dots. */
 export const KEYED_FLOAT_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -33,15 +37,22 @@ function floatNumber(section, index) {
 }
 
 /**
- * The visible number for one float. With `chapter` (the lesson's course
- * ordinal) the scheme is `‹chapter›.‹indexInLesson›` and `##` headings are
- * ignored; without it, the legacy `##`-section scheme. Mirrors
- * `displayEquationNumber` in `equations.mjs`.
+ * The visible number for one float. With a `prefix` (the part's ordinal) the
+ * scheme is `‹part›.‹offset + indexInLesson›` and `##` headings are ignored;
+ * without it, the legacy `##`-section scheme. Mirrors `displayEquationNumber`
+ * in `equations.mjs`. Each kind of float counts on its own — a `<Table>` never
+ * advances the `<Figure>` sequence — so `offset` is per kind too.
  */
-function keyedFloatNumber({ chapter, section, indexInSection, indexInLesson }) {
-  return chapter == null
+function keyedFloatNumber({
+  prefix,
+  offset = 0,
+  section,
+  indexInSection,
+  indexInLesson,
+}) {
+  return prefix == null
     ? floatNumber(section, indexInSection)
-    : `${chapter}.${indexInLesson}`;
+    : `${prefix}.${offset + indexInLesson}`;
 }
 
 /** The anchor id for a float, e.g. `{prefix:'tab', key:'foo'}` → `tab-foo`. */
@@ -71,13 +82,15 @@ function readIdAttribute(attributesSource) {
 /**
  * The raw-text equivalent of `collectKeyedJsxFloats`, mirroring
  * `scanEquationLabels`: every top-level `<TagName …>` in appearance order.
- * With `chapter` (the lesson's course ordinal) the number is `‹chapter›.‹n›`,
- * `n` sequential over the whole lesson; without it, `##` headings advance a
- * section counter. Other JSX components' bodies are blanked first so a
- * `<Table>` nested inside e.g. `<CompactExample>` (and any `##`-like text
- * inside an unrelated component) is never counted.
+ * With `numbering` (`{ prefix, offset }` — the part's ordinal and the count of
+ * this kind of float in earlier lessons of that part) the number is
+ * `‹part›.‹offset + n›`, `n` sequential over the whole lesson; without it, `##`
+ * headings advance a section counter. Other JSX components' bodies are blanked
+ * first so a `<Table>` nested inside e.g. `<CompactExample>` (and any `##`-like
+ * text inside an unrelated component) is never counted.
  */
-export function scanKeyedJsxFloats(markdown, { tagName, chapter }) {
+export function scanKeyedJsxFloats(markdown, { tagName, numbering }) {
+  const { prefix, offset } = resolveNumbering(numbering);
   const text = stripJsxComponents(stripFencedCode(markdown), tagName);
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
@@ -106,7 +119,8 @@ export function scanKeyedJsxFloats(markdown, { tagName, chapter }) {
     labels.push({
       key: token.key,
       number: keyedFloatNumber({
-        chapter,
+        prefix,
+        offset,
         section,
         indexInSection,
         indexInLesson,
@@ -118,14 +132,23 @@ export function scanKeyedJsxFloats(markdown, { tagName, chapter }) {
   return labels;
 }
 
+/**
+ * How many floats of this kind a lesson body holds — the input to the next
+ * lesson's `offset` within the same part.
+ */
+export function countKeyedJsxFloats(markdown, { tagName }) {
+  return scanKeyedJsxFloats(markdown, { tagName }).length;
+}
+
 /**
  * The mdast equivalent of `scanKeyedJsxFloats`: walk the tree's *top-level*
  * children in document order, advancing the section counter on every
  * depth-2 heading and emitting a record for every `mdxJsxFlowElement` named
- * `tagName` — keyed or not, exactly like `collectDisplayEquations`. `chapter`
+ * `tagName` — keyed or not, exactly like `collectDisplayEquations`. `numbering`
  * is threaded the same way as in `scanKeyedJsxFloats`.
  */
-export function collectKeyedJsxFloats(tree, { tagName, chapter }) {
+export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
+  const { prefix, offset } = resolveNumbering(numbering);
   const floats = [];
   let section = 0;
   let indexInSection = 0;
@@ -151,7 +174,8 @@ export function collectKeyedJsxFloats(tree, { tagName, chapter }) {
       floats.push({
         key: key ?? null,
         number: keyedFloatNumber({
-          chapter,
+          prefix,
+          offset,
           section,
           indexInSection,
           indexInLesson,

package/src/reference/remark-notation.mjs

@@ -671,26 +671,146 @@ function inspectExplainCalls(value, resolve, file, node, references) {
   }
 }
 
+/**
+ * The numbering inputs a lesson page needs, read off one manifest.
+ *
+ * Every number on a page comes from two places that MUST agree: the page's own
+ * counters (`numbering`) and the manifest tables a cross-page `[[slug#eq-key]]`
+ * is resolved against (`equations` / `tables` / `figures`). Deriving all four
+ * from the same manifest in one step is what stops a course config from
+ * supplying one without the other — the omission that produced page-local
+ * `(2.2)` and cross-page `(4.5)` for the same equation.
+ *
+ * `numbering` maps a lesson slug to `{ part, equations, tables, figures }`:
+ * the part's ordinal (the number before the dot) and, per kind of float, how
+ * many of them the earlier lessons of that part already used.
+ */
+export function numberingFromManifest(manifest) {
+  if (!manifest || typeof manifest !== 'object') return {};
+  return {
+    equations: manifest.equations?.numbersBySlug ?? {},
+    tables: manifest.tables?.numbersBySlug ?? {},
+    figures: manifest.figures?.numbersBySlug ?? {},
+    numbering: Object.fromEntries(
+      (manifest.lessons ?? []).map((lesson) => [
+        lesson.slug,
+        {
+          part: lesson.part,
+          equations: lesson.numbering?.equations ?? 0,
+          tables: lesson.numbering?.tables ?? 0,
+          figures: lesson.numbering?.figures ?? 0,
+        },
+      ]),
+    ),
+  };
+}
+
+/**
+ * `{ prefix, offset }` for one kind of float on one page, from whichever
+ * numbering option the caller supplied. `numbering` is the current form;
+ * `chapters` is the superseded per-lesson form (prefix = the lesson's ordinal,
+ * no offset) and is still read so an unmigrated config keeps working.
+ */
+function pageNumbering(options, slug, kind) {
+  if (!slug) return undefined;
+  const placement = options.numbering?.[slug];
+  if (placement?.part) {
+    return { prefix: placement.part, offset: placement[kind] ?? 0 };
+  }
+  const chapter = options.chapters?.[slug];
+  return chapter ? { prefix: chapter, offset: 0 } : undefined;
+}
+
+/**
+ * Fail when the number this page just computed for a keyed float disagrees
+ * with the number the manifest publishes for the same key (WERN — a reference
+ * that shows a different number than its target). The two are produced by the
+ * same algorithm from the same content, so any disagreement means the render
+ * path and the manifest were fed different inputs; in practice, an
+ * `astro.config.mjs` that passes the manifest number tables but not
+ * `numbering`, which silently drops the page back to the legacy `##`-section
+ * scheme.
+ */
+function assertManifestNumberParity({
+  file,
+  slug,
+  pageLabels,
+  crossPage,
+  placement,
+  noun,
+  syntax,
+}) {
+  // No entry for this slug at all means the caller supplied no manifest table
+  // (hand-built test trees, non-lesson pages) — nothing to cross-check.
+  const published = crossPage?.[slug];
+  if (!published) return;
+
+  for (const [key, number] of pageLabels) {
+    const expected = published[key];
+    if (expected === undefined) {
+      fail(
+        file,
+        `Stale Explico manifest for ${slug}: this page numbers ${noun} ` +
+          `${syntax(key)} as (${number}), but the manifest lists no such ` +
+          `${noun} for the lesson. Recompile the manifest before rendering.`,
+      );
+    }
+    if (expected !== number) {
+      fail(
+        file,
+        `Inconsistent ${noun} numbering for ${syntax(key)} in ${slug}: this ` +
+          `page renders it as (${number}) while a cross-page reference to it ` +
+          `resolves to (${expected}). ` +
+          (placement === undefined
+            ? 'The remarkNotation options carry the manifest number tables ' +
+              'but no `numbering` entry for this lesson, so the page fell ' +
+              'back to the legacy `##`-section scheme. Pass `manifest` to ' +
+              'remarkNotation so both sides use the part scheme.'
+            : 'The page counters and the manifest disagree; recompile the ' +
+              'manifest from the current content.'),
+      );
+    }
+  }
+}
+
 /**
  * @param {{
  *   definitions?: Map<string, object> | readonly object[] | Record<string, object> | (() => Map<string, object> | readonly object[] | Record<string, object>),
  *   resolve?: (key: string, context: object) => object | undefined,
  *   unknown?: 'error' | 'warn' | 'ignore',
  *   base?: string,
+ *   manifest?: object,
  *   equations?: Record<string, Record<string, string>>,
  *   tables?: Record<string, Record<string, string>>,
  *   figures?: Record<string, Record<string, string>>,
+ *   numbering?: Record<string, { part: number, equations: number, tables: number, figures: number }>,
  *   chapters?: Record<string, number>,
  * }} [options]
  *
- * `chapters` maps a lesson slug to its 1-based course ordinal. When the
- * current page has one, every display equation / `<Table>` / `<Figure>` is
- * numbered `‹chapter›.‹n›` (`##` headings ignored); with no entry the legacy
- * `##`-section scheme applies. It must agree with `manifest.lessons[].chapter`,
- * which is what feeds `equations`/`tables`/`figures` above.
+ * `manifest` is the preferred wiring: pass the compiled manifest and the four
+ * numbering inputs below are read off it together, so they cannot drift apart.
+ * They stay available individually for hand-built trees, and an explicitly
+ * supplied one still wins over the manifest.
+ *
+ * `numbering` maps a lesson slug to its **part** (the number before the dot)
+ * and, per kind of float, how many the earlier lessons of that part already
+ * used. Every display equation / `<Table>` / `<Figure>` on the page is then
+ * numbered `‹part›.‹offset + n›`, with `##` and `###` headings ignored; with no
+ * entry the legacy `##`-section scheme applies. It must agree with
+ * `manifest.lessons[]`, which is what feeds `equations`/`tables`/`figures`
+ * above — supplying the tables without `numbering` numbers the same equation
+ * twice, and `assertManifestNumberParity` turns that into a build error rather
+ * than a page whose references disagree with their targets.
+ *
+ * `chapters` is the superseded per-lesson form (slug → the lesson's course
+ * ordinal, no running offset). Still read when `numbering` has no entry, so a
+ * config written against the old option keeps building.
  */
 export default function remarkNotation(options = {}) {
   const unknown = options.unknown ?? 'error';
+  // The manifest supplies every numbering input at once; an explicit option
+  // still overrides it, so existing per-field wiring keeps working.
+  const numbering = { ...numberingFromManifest(options.manifest), ...options };
 
   return function transform(tree, file) {
     const suppliedDefinitions =
@@ -703,10 +823,10 @@ export default function remarkNotation(options = {}) {
     );
     const localDefinitions = localDefinitionsFromFile(file);
     const lessonId = lessonIdFrom(file);
-    // The lesson's course ordinal (see the `chapters` option). Falsy / missing
-    // ⇒ the legacy `##`-section numbering, so `0` and `undefined` behave alike.
-    const chapter =
-      (lessonId && options.chapters?.[lessonId.replace(/\./g, '/')]) || undefined;
+    const lessonSlug = lessonId ? lessonId.replace(/\./g, '/') : undefined;
+    // `{ prefix, offset }` per kind of float — see the `numbering` option.
+    // Missing ⇒ the legacy `##`-section numbering.
+    const equationNumbering = pageNumbering(numbering, lessonSlug, 'equations');
     const registryFile = isNotationRegistryFile(file);
     const mathScope = pageGlyphScope(
       localDefinitions,
@@ -718,8 +838,9 @@ export default function remarkNotation(options = {}) {
 
     // Equation identity (D7): assign every `\label{eq:…}` its number before any
     // math node is rewritten, so a `[[eq-key]]` earlier in the page still
-    // resolves. `chapter` picks the `‹chapter›.‹n›` vs `##`-section scheme.
-    const equationLabels = collectEquationLabels(tree, chapter);
+    // resolves. `equationNumbering` picks the `‹part›.‹n›` vs `##`-section
+    // scheme.
+    const equationLabels = collectEquationLabels(tree, equationNumbering);
     const pageLabels = new Map();
     for (const label of equationLabels) {
       if (pageLabels.has(label.key)) {
@@ -734,14 +855,25 @@ export default function remarkNotation(options = {}) {
     const eqCtx = {
       base: options.base ?? '',
       pageLabels,
-      crossPage: options.equations ?? {},
+      crossPage: numbering.equations ?? {},
     };
+    // WERN guard: what this page prints next to the equation must be what a
+    // reference from another page prints for it.
+    assertManifestNumberParity({
+      file,
+      slug: lessonSlug,
+      pageLabels,
+      crossPage: eqCtx.crossPage,
+      placement: equationNumbering,
+      noun: 'equation',
+      syntax: (key) => `eq:${key}`,
+    });
 
     // Number and anchor every display equation on a lesson page, keyed or
     // not (F3). Non-lesson pages (notation registry, stray docs) keep the
     // keyed-only behaviour so their body math is left untouched.
     const displayEquations = lessonId
-      ? collectDisplayEquations(tree, chapter)
+      ? collectDisplayEquations(tree, equationNumbering)
       : [];
     const equationByNode = new Map(
       displayEquations.map((equation) => [equation.node, equation]),
@@ -750,9 +882,10 @@ export default function remarkNotation(options = {}) {
     // Keyed floats (F-tables-figures): every `<Table>`/`<Figure>` on a lesson
     // page is numbered and anchored, keyed or not — same rule as equations,
     // via the shared engine in `keyed-jsx-floats.mjs`.
-    const makeFloatCtx = (tagName, crossPage) => {
+    const makeFloatCtx = (tagName, crossPage, kind) => {
+      const floatNumbering = pageNumbering(numbering, lessonSlug, kind);
       const floats = lessonId
-        ? collectKeyedJsxFloats(tree, { tagName, chapter })
+        ? collectKeyedJsxFloats(tree, { tagName, numbering: floatNumbering })
         : [];
       const pageFloatLabels = new Map();
       for (const float of floats) {
@@ -766,6 +899,15 @@ export default function remarkNotation(options = {}) {
         }
         pageFloatLabels.set(float.key, float.number);
       }
+      assertManifestNumberParity({
+        file,
+        slug: lessonSlug,
+        pageLabels: pageFloatLabels,
+        crossPage: crossPage ?? {},
+        placement: floatNumbering,
+        noun: tagName,
+        syntax: (key) => `<${tagName} id="${key}">`,
+      });
       return {
         ctx: {
           base: options.base ?? '',
@@ -777,11 +919,13 @@ export default function remarkNotation(options = {}) {
     };
     const { ctx: tableCtx, byNode: tableByNode } = makeFloatCtx(
       'Table',
-      options.tables,
+      numbering.tables,
+      'tables',
     );
     const { ctx: figureCtx, byNode: figureByNode } = makeFloatCtx(
       'Figure',
-      options.figures,
+      numbering.figures,
+      'figures',
     );
 
     const resolve = (key, kind, node) => {

package/src/styles/global.css

@@ -448,6 +448,135 @@
     min-height: 100%;
   }
 
+  /* A compact chapter remains useful as a row of lesson icons. The
+     link text doubles as a pointer/keyboard tooltip; opening the chapter via
+     its summary restores Starlight's normal, fully labelled list. */
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level) {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.35rem;
+    margin: 0.2rem 0 0.35rem;
+    padding-inline-start: 0.5rem;
+  }
+
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li {
+    position: relative;
+    margin-inline-start: 0;
+    border-inline-start: 0;
+    padding-inline-start: 0;
+  }
+
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li
+    > a {
+    display: grid;
+    position: relative;
+    place-items: center;
+    width: 1.75rem;
+    height: 1.75rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.4rem;
+    padding: 0;
+    color: var(--sl-color-gray-3);
+    background: var(--sl-color-bg-sidebar);
+  }
+
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li
+    > a::before {
+    content: '';
+    width: 0.65rem;
+    height: 0.78rem;
+    border: 1.5px solid currentColor;
+    border-radius: 0.13rem;
+    box-shadow: 0.18rem 0.18rem 0 -0.1rem var(--sl-color-bg-sidebar),
+      0.18rem 0.18rem 0 0 currentColor;
+  }
+
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li
+    > a:hover,
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li
+    > a:focus-visible {
+    border-color: var(--sl-color-accent);
+    color: var(--sl-color-text-accent);
+    background: var(--sl-color-accent-low);
+  }
+
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li
+    > a[aria-current='page'] {
+    color: var(--sl-color-text-invert);
+    background: var(--sl-color-text-accent);
+  }
+
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li
+    > a
+    > span {
+    position: absolute;
+    z-index: 2;
+    inset-block-start: 50%;
+    inset-inline-start: calc(100% + 0.45rem);
+    width: max-content;
+    max-width: 12rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.35rem;
+    padding: 0.3rem 0.5rem;
+    color: var(--sl-color-white);
+    background: var(--sl-color-bg-nav);
+    box-shadow: var(--sl-shadow-md);
+    font-size: var(--sl-text-xs);
+    font-weight: 500;
+    line-height: 1.3;
+    opacity: 0;
+    pointer-events: none;
+    transform: translateY(-50%) translateX(-0.2rem);
+    transition:
+      opacity 100ms ease,
+      transform 100ms ease;
+  }
+
+  .layout-compact-sidebar
+    details[data-compact]
+    > ul:not(.top-level)
+    > li
+    > a:is(:hover, :focus-visible)
+    > span {
+    opacity: 1;
+    transform: translateY(-50%) translateX(0);
+  }
+
+  .layout-compact-sidebar details[data-compact] > summary .caret {
+    transform: rotateZ(0);
+  }
+
+  [dir='rtl']
+    .layout-compact-sidebar
+    details[data-compact]
+    > summary
+    .caret {
+    transform: rotateZ(180deg);
+  }
+
   .layout-navigation-toggle {
     position: fixed;
     z-index: calc(var(--sl-z-index-menu) + 1);