explico 0.3.0 → 0.4.0

package/src/compiler/course-config.ts

@@ -7,13 +7,25 @@
  * supplies its own value of this shape.
  */
 
-export interface CourseSection {
+/**
+ * One **part** — a sidebar group, holding the chapters (lessons) whose slugs
+ * start with `dir`. A part's 1-based position in `CourseConfig.parts` is the
+ * number before the dot in every equation, table, and figure number inside it.
+ * See `docs/authoring/structure.md` for the full level taxonomy.
+ */
+export interface CoursePart {
   /** Lesson-slug prefix, e.g. `bonds` for `bonds/yield-to-maturity`. */
   readonly dir: string;
   /** Sidebar group heading. */
   readonly label: string;
 }
 
+/**
+ * @deprecated Renamed to {@link CoursePart}. "Section" now only ever means an
+ * `##` heading inside a lesson. Removed in the next MINOR release.
+ */
+export type CourseSection = CoursePart;
+
 export interface CourseConventions {
   /** Notation key a lesson's stated sign convention must resolve to. */
   readonly signConventionKey: string;
@@ -74,8 +86,16 @@ export interface CourseAbout {
 export interface CourseConfig {
   readonly title: string;
   readonly description: string;
-  /** Sidebar section groups, in order. */
-  readonly sections: readonly CourseSection[];
+  /**
+   * The course's parts (sidebar groups), in order. Exactly one of `parts` or
+   * the deprecated `sections` must be given.
+   */
+  readonly parts?: readonly CoursePart[];
+  /**
+   * @deprecated Renamed to {@link CourseConfig.parts}. Still honoured, so a
+   * course on the old name keeps building; removed in the next MINOR release.
+   */
+  readonly sections?: readonly CoursePart[];
   /** Namespaces used by competency / notation `domain` fields. */
   readonly domains: readonly string[];
   readonly conventions: CourseConventions;
@@ -84,3 +104,19 @@ export interface CourseConfig {
   /** Edits to the shipped named-operator baseline (rule N8). Optional. */
   readonly operators?: CourseOperators;
 }
+
+/**
+ * The course's parts, from whichever field the config uses. Throws rather than
+ * silently producing a course with no sidebar groups — a config with neither
+ * field would otherwise number every float by the `##`-section fallback.
+ */
+export function coursePartsOf(config: CourseConfig): readonly CoursePart[] {
+  const parts = config.parts ?? config.sections;
+  if (!parts || parts.length === 0) {
+    throw new Error(
+      'CourseConfig needs at least one entry in `parts` (a sidebar group: ' +
+        '{ dir, label }). The old name `sections` is still accepted.',
+    );
+  }
+  return parts;
+}

package/src/compiler/lesson-derivation.ts

@@ -156,7 +156,7 @@ export type SidebarGroup =
 export function buildSidebar(
   tracks: readonly TrackLike[],
   lessonSlugs: readonly string[],
-  sections: readonly SidebarSection[],
+  parts: readonly SidebarSection[],
 ): SidebarGroup[] {
   const rank = new Map(
     mergeTrackOrder(tracks).map((lessonId, index) => [lessonId, index]),
@@ -164,7 +164,7 @@ export function buildSidebar(
   const positionOf = (slug: string) =>
     rank.get(lessonIdFromSlug(slug)) ?? Number.POSITIVE_INFINITY;
 
-  const groups: SidebarGroup[] = sections.map(({ dir, label }) => ({
+  const groups: SidebarGroup[] = parts.map(({ dir, label }) => ({
     label,
     items: lessonSlugs
       .filter((slug) => slug.startsWith(`${dir}/`))

package/src/compiler/manifest.ts

@@ -47,6 +47,8 @@ import {
   type ConsistencyDiagnostic,
 } from '../reference/consistency';
 import { validateNotationAlignment } from '../reference/curriculum-alignment';
+import { countDisplayEquations } from '../reference/equations.mjs';
+import { countKeyedJsxFloats } from '../reference/keyed-jsx-floats.mjs';
 import {
   validateEquations,
   type EquationDiagnostic,
@@ -80,7 +82,7 @@ import type {
   NotationLessonInput,
   NotationPageBundle,
 } from '../reference/types';
-import type { CourseConfig } from './course-config';
+import { coursePartsOf, type CourseConfig } from './course-config';
 import {
   resolveKnowledgeVersion,
   type KnowledgeVersionDiagnostic,
@@ -116,8 +118,12 @@ import {
  * against `content/CHANGELOG.md`) and `diagnostics.knowledge`.
  * v6 (chapter numbering): `lessons[].chapter` — the lesson's 1-based course
  * ordinal, the chapter in every equation/table/figure number (`(2.1)`).
+ * v7 (part numbering): `lessons[].part` (the sidebar group's 1-based ordinal,
+ * now the number before the dot), `lessons[].chapter` redefined as the
+ * lesson's ordinal *within its part*, and `lessons[].numbering` — the
+ * per-kind offsets that make `n` run continuously across a part.
  */
-export const MANIFEST_SCHEMA_VERSION = 6;
+export const MANIFEST_SCHEMA_VERSION = 7;
 
 const REPOSITORY_ROOT = process.cwd();
 // Content is the top-level `content/` folder; the build output is `build/`
@@ -206,11 +212,28 @@ export interface ManifestLesson {
   /** Docs-loader slug, e.g. `bonds/price-yield-relationship`. */
   readonly slug: string;
   /**
-   * The lesson's 1-based ordinal in the course (merged track order, then any
-   * unranked lessons by slug). It is the chapter in every equation, table, and
-   * figure number on the page — `(2.1)` is the first equation of chapter 2.
+   * The 1-based ordinal of the **part** this lesson sits in — its sidebar
+   * group's position in `courseConfig.parts`. It is the number before the dot
+   * in every equation, table, and figure number on the page: `(2.1)` is the
+   * first equation of part 2. See `docs/authoring/structure.md`.
+   */
+  readonly part: number;
+  /**
+   * The lesson's 1-based ordinal **within its part** (merged track order, then
+   * any unranked lessons by slug) — its chapter number. This orders the
+   * sidebar and the reading path; it does not appear in a float's number.
    */
   readonly chapter: number;
+  /**
+   * How many floats of each kind the earlier lessons of this part already
+   * used. The lesson's own floats continue from here, so a part's sequence
+   * runs unbroken across its chapters instead of restarting on every page.
+   */
+  readonly numbering: {
+    readonly equations: number;
+    readonly tables: number;
+    readonly figures: number;
+  };
   readonly file: string;
   readonly title: string;
   readonly description: string;
@@ -586,45 +609,84 @@ export async function compileManifest(
   const sidebar = buildSidebar(
     catalog.tracks.map((track) => ({ id: track.id, lessons: track.lessons })),
     lessonSlugs,
-    courseConfig.sections,
+    coursePartsOf(courseConfig),
   );
 
-  // A lesson's chapter is its position when the sidebar is read top to bottom
-  // (sections in config order, lessons within a section by merged track order
-  // then slug). It prefixes every equation / table / figure number on the page
-  // (`(2.1)` = first equation of chapter 2). Derived from `sidebar` so there is
-  // one lesson-ordering source, not two.
-  const chapterByLessonId = new Map<string, number>();
-  let chapterCursor = 0;
+  // Part and chapter, read straight off the sidebar so there is one
+  // lesson-ordering source and not two: a part is a sidebar group (parts in
+  // config order), a chapter is a lesson's position inside its part (merged
+  // track order, then slug). The part is what prefixes every equation / table
+  // / figure number — `(2.1)` is the first equation of part 2 — while `n`
+  // continues across the part's chapters rather than restarting on each page,
+  // so every lesson also needs the running count that precedes it.
+  // See `docs/authoring/structure.md`.
+  const bodyByLessonId = new Map(
+    notationInput.lessons.map((lesson) => [lesson.lessonId, lesson.body]),
+  );
+  const placementByLessonId = new Map<
+    string,
+    {
+      part: number;
+      chapter: number;
+      numbering: { equations: number; tables: number; figures: number };
+    }
+  >();
+  let partCursor = 0;
   for (const group of sidebar) {
-    for (const item of group.items) {
-      if (typeof item !== 'string') continue; // the static Reference group
-      chapterByLessonId.set(lessonIdFromSlug(item), ++chapterCursor);
+    const lessonIds = group.items
+      .filter((item): item is string => typeof item === 'string')
+      .map(lessonIdFromSlug);
+    if (lessonIds.length === 0) continue; // the static Reference group
+    partCursor += 1;
+    // Running totals for this part, advanced one chapter at a time.
+    const used = { equations: 0, tables: 0, figures: 0 };
+    let chapterCursor = 0;
+    for (const lessonId of lessonIds) {
+      const body = bodyByLessonId.get(lessonId) ?? '';
+      placementByLessonId.set(lessonId, {
+        part: partCursor,
+        chapter: ++chapterCursor,
+        numbering: { ...used },
+      });
+      used.equations += countDisplayEquations(body);
+      used.tables += countKeyedJsxFloats(body, { tagName: 'Table' });
+      used.figures += countKeyedJsxFloats(body, { tagName: 'Figure' });
     }
   }
 
-  const keyedFloatLessonInputs = notationInput.lessons.map((lesson) => ({
-    lessonId: lesson.lessonId,
-    slug: lesson.lessonId.replace(/\./g, '/'),
-    file: lesson.source.file,
-    body: lesson.body,
-    chapter: chapterByLessonId.get(lesson.lessonId),
-  }));
-  const equationValidation = validateEquations(keyedFloatLessonInputs);
+  const floatInputs = (kind: 'equations' | 'tables' | 'figures') =>
+    notationInput.lessons.map((lesson) => {
+      const placement = placementByLessonId.get(lesson.lessonId);
+      return {
+        lessonId: lesson.lessonId,
+        slug: lesson.lessonId.replace(/\./g, '/'),
+        file: lesson.source.file,
+        body: lesson.body,
+        ...(placement
+          ? {
+              numbering: {
+                prefix: placement.part,
+                offset: placement.numbering[kind],
+              },
+            }
+          : {}),
+      };
+    });
+  const equationValidation = validateEquations(floatInputs('equations'));
   const equationsBySlug = new Map(
     Object.entries(equationValidation.numbersBySlug).map(([slug, table]) => [
       slug,
       Object.entries(table).map(([key, number]) => ({ key, number })),
     ]),
   );
-  const tableValidation = validateTables(keyedFloatLessonInputs);
+  const tableValidation = validateTables(floatInputs('tables'));
   const tablesBySlug = new Map(
     Object.entries(tableValidation.numbersBySlug).map(([slug, table]) => [
       slug,
       Object.entries(table).map(([key, number]) => ({ key, number })),
     ]),
   );
-  const figureValidation = validateFigures(keyedFloatLessonInputs);
+  const figureValidation = validateFigures(floatInputs('figures'));
   const figuresBySlug = new Map(
     Object.entries(figureValidation.numbersBySlug).map(([slug, table]) => [
       slug,
@@ -645,10 +707,16 @@ export async function compileManifest(
     lessons.push({
       id,
       slug: id.replace(/\./g, '/'),
-      // 0 = the lesson is not placed in any configured section; a curriculum
+      // 0 = the lesson is not placed in any configured part; a curriculum
       // diagnostic covers that separately, and both numbering paths then fall
       // back to the legacy `##`-section scheme.
-      chapter: chapterByLessonId.get(id) ?? 0,
+      part: placementByLessonId.get(id)?.part ?? 0,
+      chapter: placementByLessonId.get(id)?.chapter ?? 0,
+      numbering: placementByLessonId.get(id)?.numbering ?? {
+        equations: 0,
+        tables: 0,
+        figures: 0,
+      },
       file: notationLesson.source.file,
       title: frontmatter.title,
       description: frontmatter.description,
@@ -842,13 +910,17 @@ export function readManifestSync(): Manifest {
 export async function loadManifest(
   courseConfig?: CourseConfig,
 ): Promise<Manifest> {
-  if (existsSync(MANIFEST_PATH)) return readManifestSync();
-  if (!courseConfig) {
-    throw new Error(
-      `${relative(REPOSITORY_ROOT, MANIFEST_PATH)} not found. Run \`pnpm validate:content\` first.`,
-    );
+  // A caller that has the course config is an authoring/build entry point. It
+  // must compile the current content tree even when a persisted manifest is
+  // present: using that file here can split the page in two, with remark
+  // seeing current frontmatter while Astro components render stale cards.
+  if (courseConfig) {
+    const manifest = await compileManifest(courseConfig);
+    writeManifest(manifest);
+    return manifest;
   }
-  const manifest = await compileManifest(courseConfig);
-  writeManifest(manifest);
-  return manifest;
+  if (existsSync(MANIFEST_PATH)) return readManifestSync();
+  throw new Error(
+    `${relative(REPOSITORY_ROOT, MANIFEST_PATH)} not found. Run \`pnpm validate:content\` first.`,
+  );
 }

package/src/components/notation/NotationLayer.astro

@@ -711,6 +711,17 @@ for (const gloss of glossItems) {
     pointer-events: none;
   }
 
+  /* KaTeX draws a radical sign, an extensible arrow (`\xrightarrow`), and
+     other stretchy glyphs as an absolutely-positioned SVG layer that is
+     painted after — and on top of — the content it decorates. Without this,
+     a pointer over a symbol inside `\sqrt{…}` or under an arrow hits that
+     overlay instead of the notation marker beneath it. The radicand lives in
+     the sibling `.svg-align` layer, which stays interactive. */
+  :global(.katex-html .sqrt .vlist > span:not(.svg-align)),
+  :global(.katex-html .hide-tail) {
+    pointer-events: none;
+  }
+
   :global(.katex-html [data-notation-key]) {
     cursor: help;
   }

package/src/components/starlight/LayoutSidebar.astro

@@ -23,7 +23,68 @@ import DefaultSidebar from '@astrojs/starlight/components/Sidebar.astro';
       size="1rem"
     />
   </button>
-  <div id="starlight__navigation-content" class="layout-navigation-content">
+  <div
+    id="starlight__navigation-content"
+    class="layout-navigation-content layout-compact-sidebar"
+  >
     <DefaultSidebar />
+    <script>
+      import { createBrowserPreferenceStore } from '../../session/PreferenceStore';
+
+      (() => {
+        if (!matchMedia('(min-width: 50rem)').matches) return;
+        const root = document.querySelector('#starlight__navigation-content');
+        const stateRoot = root?.querySelector('sl-sidebar-state-persist');
+        if (!stateRoot) return;
+
+        const groups = [
+          ...stateRoot.querySelectorAll(':scope > ul > li > details'),
+        ];
+        const storageKey = 'explico-sidebar-groups';
+        const preferences = createBrowserPreferenceStore();
+        let compact = groups.map(() => true);
+        try {
+          const saved = JSON.parse(preferences.get(storageKey) || 'null');
+          if (
+            saved?.hash === stateRoot.dataset.hash &&
+            Array.isArray(saved.compact)
+          ) {
+            compact = groups.map((_, index) => saved.compact[index] !== false);
+          }
+        } catch {}
+
+        const save = () => {
+          try {
+            preferences.set(
+              storageKey,
+              JSON.stringify({
+                hash: stateRoot.dataset.hash,
+                compact: groups.map((group) => group.hasAttribute('data-compact')),
+              }),
+            );
+          } catch {}
+        };
+
+        groups.forEach((group, index) => {
+          // The links remain rendered and operable in compact mode; only their
+          // labels collapse. Keep <details> open so this stays true for assistive
+          // technology as well as pointer users.
+          group.setAttribute('open', '');
+          group.toggleAttribute('data-compact', compact[index]);
+          const summary = group.querySelector(':scope > summary');
+          summary?.setAttribute('aria-expanded', String(!compact[index]));
+          summary?.addEventListener('click', (event) => {
+            event.preventDefault();
+            group.toggleAttribute('data-compact');
+            group.setAttribute('open', '');
+            summary.setAttribute(
+              'aria-expanded',
+              String(!group.hasAttribute('data-compact')),
+            );
+            save();
+          });
+        });
+      })();
+    </script>
   </div>
 </div>

package/src/components/starlight/LessonFooter.astro

@@ -9,6 +9,7 @@
  * D5); this component never rebuilds the registry.
  */
 import DefaultFooter from '@astrojs/starlight/components/Footer.astro';
+import { assertLocalNotationParity } from '../../compiler/astro';
 import { loadManifest } from '../../compiler/manifest';
 import {
   isLessonSlug,
@@ -34,6 +35,16 @@ const definitions: NotationLayerDefinition[] = [];
 if (lessonId) {
   const manifest = await loadManifest();
   const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
+  const routeData = Astro.locals.starlightRoute.entry.data as {
+    notation?: { local?: readonly { key?: unknown }[] };
+  };
+  const authoredLocalKeys = (routeData.notation?.local ?? [])
+    .map((entry) => entry.key)
+    .filter((key): key is string => typeof key === 'string');
+  const renderedLocalKeys = (lesson?.notation.definitions ?? [])
+    .filter((definition) => definition.scope === 'local')
+    .map((definition) => definition.key);
+  assertLocalNotationParity(lessonId, authoredLocalKeys, renderedLocalKeys);
   for (const definition of lesson?.notation.definitions ?? []) {
     definitions.push({
       key: definition.key,

package/src/components/table/Table.astro

@@ -2,8 +2,9 @@
 /**
  * A referenceable table (F-tables-figures) — the table equivalent of a
  * keyed display equation. `remark-notation.mjs` numbers every `<Table>` on a
- * lesson page `‹chapter›.‹n›` (chapter = the lesson's course ordinal, `n`
- * sequential over the lesson), keyed or not, and injects the resulting
+ * lesson page `‹part›.‹n›` (the part is the sidebar group's ordinal, `n`
+ * sequential over every `<Table>` in that part — see
+ * `docs/authoring/structure.md`), keyed or not, and injects the resulting
  * `number`/`anchorId` as props; this component only renders what it's given
  * — it never computes its own number, same as `equationNode()`'s output for
  * equations.

package/src/reference/equations-validate.ts

@@ -54,10 +54,12 @@ export interface EquationLessonInput {
   readonly file: string;
   readonly body: string;
   /**
-   * The lesson's 1-based ordinal in the course. When set, equations are
-   * numbered `‹chapter›.‹n›`; when omitted, the legacy `##`-section scheme.
+   * `{ prefix, offset }` — the part's 1-based ordinal among the sidebar groups,
+   * and how many display equations earlier lessons of that part already used.
+   * When set, equations are numbered `‹part›.‹offset + n›`; when omitted, the
+   * legacy `##`-section scheme. See `docs/authoring/structure.md`.
    */
-  readonly chapter?: number;
+  readonly numbering?: { readonly prefix: number; readonly offset: number };
 }
 
 const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
@@ -95,7 +97,7 @@ export function validateEquations(
   )) {
     const seen = new Set<string>();
     const table: Record<string, string> = {};
-    for (const raw of scanEquationLabels(lesson.body, lesson.chapter) as {
+    for (const raw of scanEquationLabels(lesson.body, lesson.numbering) as {
       key: string;
       number: string;
       section: number;

package/src/reference/equations.mjs

@@ -2,12 +2,17 @@
  * Equation identity (Step D7, extended F3) — shared, framework-free helpers.
  *
  * Every display equation (`$$…$$`) in a lesson is numbered and given an `id`
- * from appearance order. When the caller supplies a `chapter` (the lesson's
- * ordinal position in the course), the number is `‹chapter›.‹n›` — `n` counts
- * every display equation in the lesson and `##` headings do not affect it
- * (`(2.4)` = fourth display equation of the second lesson). With no `chapter`
- * the number falls back to the `##`-section scheme `‹section›.‹indexInSection›`
- * (used by hand-built test trees and non-lesson pages). An author additionally
+ * from appearance order. When the caller supplies `numbering`
+ * (`{ prefix, offset }` — see `resolveNumbering`), the number is
+ * `‹part›.‹offset + n›`: the prefix is the **part**'s ordinal among the sidebar
+ * groups, `n` counts every display equation in the lesson, and `offset` carries
+ * the count from earlier lessons of the same part so the sequence runs
+ * continuously across a part rather than restarting on every page. `##` and
+ * `###` headings never affect it — `(2.4)` is the fourth display equation of
+ * part 2, wherever in that part it sits. See `docs/authoring/structure.md` for
+ * the level names. With no `numbering` the number falls back to the
+ * `##`-section scheme `‹section›.‹indexInSection›` (used by hand-built test
+ * trees and non-lesson pages). An author additionally
  * marks an equation with a trailing `\label{eq:<key>}` inside its `$$…$$`
  * block (inside math, so the `:` is safe and the form matches amsmath) when
  * they want a *stable* anchor that survives edits and cross-page references:
@@ -63,19 +68,42 @@ function equationNumber(section, index) {
 }
 
 /**
- * The visible number for one display equation. With `chapter` (the lesson's
- * course ordinal) the scheme is `‹chapter›.‹indexInLesson›` and `##` headings
+ * Normalise the numbering input to `{ prefix, offset }`.
+ *
+ * `prefix` is the number before the dot — the **part**'s ordinal (its position
+ * among the sidebar groups). `offset` is how many display equations already
+ * appeared in earlier lessons of that same part, so `n` runs continuously
+ * across a part instead of restarting on every page. A bare number is the
+ * legacy per-lesson form (`prefix = n`, `offset = 0`) and is still accepted so
+ * hand-built trees and unit tests keep working. `undefined`/`null`/`0` ⇒ the
+ * `##`-section fallback for non-lesson pages.
+ */
+export function resolveNumbering(input) {
+  if (input == null) return { prefix: undefined, offset: 0 };
+  if (typeof input === 'number') {
+    return { prefix: input || undefined, offset: 0 };
+  }
+  return {
+    prefix: input.prefix || undefined,
+    offset: Number(input.offset) || 0,
+  };
+}
+
+/**
+ * The visible number for one display equation. With a `prefix` (the part's
+ * ordinal) the scheme is `‹part›.‹offset + indexInLesson›` and `##` headings
  * are ignored; without it, the legacy `##`-section scheme.
  */
 export function displayEquationNumber({
-  chapter,
+  prefix,
+  offset = 0,
   section,
   indexInSection,
   indexInLesson,
 }) {
-  return chapter == null
+  return prefix == null
     ? equationNumber(section, indexInSection)
-    : `${chapter}.${indexInLesson}`;
+    : `${prefix}.${offset + indexInLesson}`;
 }
 
 /** The positional anchor id for an unkeyed equation, e.g. `2.4` → `eq-2-4`. */
@@ -109,15 +137,18 @@ export function stripJsxComponents(markdown, keep) {
 }
 
 /**
- * Every keyed display equation in a Markdown body, in appearance order, with
- * its assigned number. `$$…$$` blocks only. With `chapter` (the lesson's
- * course ordinal) the number is `‹chapter›.‹n›`, `n` sequential over every
- * display block in the lesson; without it, `##` headings advance a section
- * counter and the number is `‹section›.‹indexInSection›`. Either way every
- * display block advances the index, so a keyed equation's number reflects its
- * position among *all* display equations, not only the keyed ones.
+ * Every display equation in a Markdown body, keyed or not, in appearance order
+ * with its assigned number. `$$…$$` blocks only. With `numbering`
+ * (`{ prefix, offset }`, the part's ordinal and the count of display equations
+ * in earlier lessons of that part) the number is `‹part›.‹offset + n›`, `n`
+ * sequential over every display block in the lesson; without it, `##` headings
+ * advance a section counter and the number is `‹section›.‹indexInSection›`.
+ * Either way every display block advances the index, so a keyed equation's
+ * number reflects its position among *all* display equations, not only the
+ * keyed ones.
  */
-export function scanEquationLabels(markdown, chapter) {
+export function scanDisplayEquations(markdown, numbering) {
+  const { prefix, offset } = resolveNumbering(numbering);
   const text = stripJsxComponents(stripFencedCode(markdown));
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
@@ -148,11 +179,11 @@ export function scanEquationLabels(markdown, chapter) {
     }
     indexInSection += 1;
     indexInLesson += 1;
-    if (token.key == null) continue;
     labels.push({
       key: token.key,
       number: displayEquationNumber({
-        chapter,
+        prefix,
+        offset,
         section,
         indexInSection,
         indexInLesson,
@@ -164,14 +195,31 @@ export function scanEquationLabels(markdown, chapter) {
   return labels;
 }
 
+/** The keyed subset of `scanDisplayEquations` — the manifest builder's view. */
+export function scanEquationLabels(markdown, numbering) {
+  return scanDisplayEquations(markdown, numbering).filter(
+    (equation) => equation.key != null,
+  );
+}
+
+/**
+ * How many display equations a lesson body holds. This is what makes `n` run
+ * continuously across a part: a lesson's `offset` is the sum of this over every
+ * earlier lesson in the same part.
+ */
+export function countDisplayEquations(markdown) {
+  return scanDisplayEquations(markdown).length;
+}
+
 /**
  * The mdast equivalent of `scanEquationLabels` for *every* display equation:
  * walk the tree in document order, advancing the section counter on every
  * depth-2 heading and emitting a record for every `math` node. `key` is the
- * `\label{eq:…}` payload when present, else `null`. `chapter` is threaded the
+ * `\label{eq:…}` payload when present, else `null`. `numbering` is threaded the
  * same way as in `scanEquationLabels`.
  */
-export function collectDisplayEquations(tree, chapter) {
+export function collectDisplayEquations(tree, numbering) {
+  const { prefix, offset } = resolveNumbering(numbering);
   const equations = [];
   let section = 0;
   let indexInSection = 0;
@@ -196,7 +244,8 @@ export function collectDisplayEquations(tree, chapter) {
       equations.push({
         key: label ? label[1] : null,
         number: displayEquationNumber({
-          chapter,
+          prefix,
+          offset,
           section,
           indexInSection,
           indexInLesson,
@@ -214,8 +263,8 @@ export function collectDisplayEquations(tree, chapter) {
  * The keyed subset of `collectDisplayEquations` — the tree-walk counterpart of
  * `scanEquationLabels`. Numbers reflect position among all display equations.
  */
-export function collectEquationLabels(tree, chapter) {
-  return collectDisplayEquations(tree, chapter).filter(
+export function collectEquationLabels(tree, numbering) {
+  return collectDisplayEquations(tree, numbering).filter(
     (equation) => equation.key != null,
   );
 }

package/src/reference/keyed-float-validate.ts

@@ -69,10 +69,13 @@ export interface KeyedFloatLessonInput {
   readonly file: string;
   readonly body: string;
   /**
-   * The lesson's 1-based ordinal in the course. When set, floats are numbered
-   * `‹chapter›.‹n›`; when omitted, the legacy `##`-section scheme.
+   * `{ prefix, offset }` — the part's 1-based ordinal among the sidebar groups,
+   * and how many floats of this kind earlier lessons of that part already used.
+   * When set, floats are numbered `‹part›.‹offset + n›`; when omitted, the
+   * legacy `##`-section scheme. Each kind counts on its own, so the caller
+   * passes a different `offset` for `<Table>` than for `<Figure>`.
    */
-  readonly chapter?: number;
+  readonly numbering?: { readonly prefix: number; readonly offset: number };
 }
 
 const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
@@ -117,7 +120,7 @@ export function validateKeyedFloats(
     const table: Record<string, string> = {};
     for (const raw of scanKeyedJsxFloats(lesson.body, {
       tagName,
-      chapter: lesson.chapter,
+      numbering: lesson.numbering,
     }) as {
       key: string | null;
       number: string;