explico 0.13.1 → 0.15.0

package/dist/compiler/exports/static-tree.d.ts

@@ -132,12 +132,16 @@ type Block = {
     readonly ordered: boolean;
     readonly start?: number;
     readonly items: readonly (readonly Block[])[];
+    /** On a deck, the step each item appears at (1 for the first), when an item is a step of its own. */
+    readonly itemSteps?: readonly number[];
 } | {
     readonly kind: 'equation';
     readonly anchor: string;
     readonly number: string;
     readonly key?: string;
     readonly tex: string;
+    /** On a deck, a recalled equation's place in its chapter. */
+    readonly recall?: string;
 } | {
     readonly kind: 'displayMath';
     readonly tex: string;
@@ -249,5 +253,38 @@ declare function readDiagramGeometry(figure: HtmlElement): DiagramGeometry | und
 declare function readInlineFragment(html: string, route: string, base?: string): Inline[];
 /** Read the static reading tree of one built page. */
 declare function readStaticPage(html: string, slug: string, route: string): StaticPage;
+/** One frame of a deck page (docs/authoring/deck.md), as print exports read it. */
+interface DeckFrame {
+    readonly number: number;
+    readonly kind: 'title' | 'section' | 'frame' | 'outcomes' | 'references';
+    /** The frame heading's anchor. */
+    readonly anchor?: string;
+    readonly title: readonly Inline[];
+    /** The frame's content, a run of blocks per step, in reading order: step 1 is what shows first. */
+    readonly segments: readonly {
+        readonly step: number;
+        readonly blocks: readonly Block[];
+    }[];
+    readonly steps: number;
+    readonly notes: readonly Block[];
+    /** The legend line: each symbol's TeX and its name. */
+    readonly legend: readonly {
+        readonly tex: string;
+        readonly label: readonly Inline[];
+    }[];
+}
+interface StaticDeck {
+    readonly slug: string;
+    readonly route: string;
+    readonly title: string;
+    readonly frames: readonly DeckFrame[];
+    /**
+     * The page's notation list: its lesson's symbols, its chapter's included.
+     * The PDF's appendix keeps the ones its frames use.
+     */
+    readonly notation: readonly NotationEntry[];
+}
+/** Read the frames of one built deck page. */
+declare function readStaticDeck(html: string, slug: string, route: string): StaticDeck;
 
-export { type Block, type CourseTarget, type DiagramGeometry, type DiagramNodeShape, type FigurePicture, type Inline, type NotationEntry, type RefKind, type StaticPage, type TableCell, courseTarget, readDiagramGeometry, readInlineFragment, readStaticPage, readableText };
+export { type Block, type CourseTarget, type DeckFrame, type DiagramGeometry, type DiagramNodeShape, type FigurePicture, type Inline, type NotationEntry, type RefKind, type StaticDeck, type StaticPage, type TableCell, courseTarget, readDiagramGeometry, readInlineFragment, readStaticDeck, readStaticPage, readableText };

package/dist/compiler/exports/static-tree.js

@@ -386,7 +386,8 @@ function readBlock(node, context) {
         anchor: attribute(node, "id") ?? "",
         number: attribute(node, "data-eq-number") ?? "",
         ...key ? { key } : {},
-        tex: (katex && texOf(katex)) ?? ""
+        tex: (katex && texOf(katex)) ?? "",
+        ...attribute(node, "data-eq-recall") ? { recall: attribute(node, "data-eq-recall") } : {}
       }
     ];
   }
@@ -480,6 +481,18 @@ function readBlock(node, context) {
   if (node.tagName === "compact-examples" || hasClass(node, "compact-examples")) {
     return [readExamples(node, context)];
   }
+  if (hasClass(node, "deck-check__label") && attribute(node, "data-block-kind") === "check") {
+    const anchor = attribute(node, "id") ?? "";
+    return [
+      {
+        kind: "check",
+        anchor,
+        number: attribute(node, "data-check-number") ?? "",
+        assessmentId: anchor.replace(/^check-/u, ""),
+        title: [{ kind: "text", value: attribute(node, "data-check-title") ?? "" }]
+      }
+    ];
+  }
   if (hasClass(node, "sl-heading-wrapper")) {
     const heading = headingOf(node);
     if (!heading) return readBlocks(node, context);
@@ -599,6 +612,17 @@ function readStaticPage(html, slug, route) {
   const title = elements(main, (node) => node.tagName === "h1")[0];
   const content = elements(main, (node) => hasClass(node, "sl-markdown-content"))[0];
   if (!content) throw new Error(`Built page ${slug} has no .sl-markdown-content element.`);
+  const { notation, notationRemarks } = readPageNotation(main, context);
+  return {
+    slug,
+    route,
+    title: title ? collapse(readableText(title)).trim() : slug,
+    blocks: readBlocks(content, context),
+    notation,
+    notationRemarks
+  };
+}
+function readPageNotation(main, context) {
   const layer = elements(
     main,
     (node) => hasClass(node, "notation-layer") && attribute(node, "data-notation-layer-id") === "page-notation"
@@ -607,19 +631,111 @@ function readStaticPage(html, slug, route) {
   const remarks = layer ? elements(layer, (node) => node.tagName === "ul" && hasClass(node, "notation-suspended")).flatMap(
     (list) => childrenOf(list).filter((item) => isElement(item) && item.tagName === "li").map((item) => inlineContent(item, context))
   ) : [];
+  return { notation: entries.map((entry) => readNotationEntry(entry, context)), notationRemarks: remarks };
+}
+function listItemSteps(list) {
+  const items = childrenOf(list).filter((child) => isElement(child) && child.tagName === "li");
+  let step = 1;
+  let any = false;
+  const steps = items.map((item) => {
+    const at = attribute(item, "data-step");
+    if (at !== void 0) {
+      step = Number(at) || step;
+      any = true;
+    }
+    return step;
+  });
+  return any ? steps : void 0;
+}
+function readSegments(body, context) {
+  const segments = [];
+  const add = (step, blocks) => {
+    if (blocks.length === 0) return;
+    const last = segments.at(-1);
+    if (last && last.step === step) last.blocks.push(...blocks);
+    else segments.push({ step, blocks: [...blocks] });
+  };
+  let pending = [];
+  const flush = () => {
+    if (pending.length === 0) return;
+    const holder = { nodeName: "div", tagName: "div", attrs: [], childNodes: pending };
+    add(1, withItemSteps(holder, readBlocks(holder, context)));
+    pending = [];
+  };
+  for (const child of childrenOf(body)) {
+    if (isElement(child) && hasClass(child, "deck-step") && attribute(child, "data-step") !== void 0) {
+      flush();
+      add(Number(attribute(child, "data-step")) || 1, withItemSteps(child, readBlocks(child, context)));
+      continue;
+    }
+    pending.push(child);
+  }
+  flush();
+  return segments;
+}
+function withItemSteps(node, blocks) {
+  const lists = childrenOf(node).filter(
+    (child) => isElement(child) && (child.tagName === "ul" || child.tagName === "ol")
+  );
+  let index = 0;
+  return blocks.map((block) => {
+    if (block.kind !== "list") return block;
+    const list = lists[index++];
+    const itemSteps = list ? listItemSteps(list) : void 0;
+    return itemSteps ? { ...block, itemSteps } : block;
+  });
+}
+function readStaticDeck(html, slug, route) {
+  const document = parse(html);
+  const base = inferBasePrefix(document);
+  const context = { route, base };
+  const main = elements(document, (node) => node.tagName === "main")[0];
+  if (!main) throw new Error(`Built page ${slug} has no <main> element.`);
+  const deck = elements(main, (node) => hasClass(node, "deck") && attribute(node, "data-deck") !== void 0)[0];
+  if (!deck) throw new Error(`Built page ${slug} has no deck (.deck[data-deck]).`);
+  const title = elements(main, (node) => node.tagName === "h1")[0];
+  const frames = childrenOf(deck).filter((child) => isElement(child) && hasClass(child, "deck-frame")).map((frame) => {
+    const canvas = firstByClass(frame, "deck-canvas");
+    const heading = canvas ? firstByClass(canvas, "deck-frame__title") ?? firstByClass(canvas, "deck-title__title") : void 0;
+    const body = canvas ? firstByClass(canvas, "deck-frame__body") : void 0;
+    const notes = childrenOf(frame).find(
+      (child) => isElement(child) && hasClass(child, "deck-notes")
+    );
+    const legend = canvas ? firstByClass(canvas, "deck-legend") : void 0;
+    const kind = attribute(frame, "data-kind") ?? "frame";
+    const generatedContent = !body && canvas ? readBlocks(
+      canvas,
+      context,
+      (child) => !(isElement(child) && (hasClass(child, "deck-frame__title") || hasClass(child, "deck-frame__foot") || hasClass(child, "deck-title__title")))
+    ) : [];
+    return {
+      number: Number(attribute(frame, "data-frame")) || 0,
+      kind,
+      ...heading && attribute(heading, "id") ? { anchor: attribute(heading, "id") } : {},
+      title: heading ? inlineContent(heading, context) : [],
+      segments: body ? readSegments(body, context) : generatedContent.length > 0 ? [{ step: 1, blocks: generatedContent }] : [],
+      steps: Number(attribute(frame, "data-steps")) || 1,
+      notes: notes ? readBlocks(notes, context) : [],
+      legend: legend ? elements(legend, (node) => hasClass(node, "deck-legend__item")).map((item) => {
+        const katex = elements(item, (node) => hasClass(node, "katex"))[0];
+        const label = firstByClass(item, "deck-legend__label");
+        return { tex: (katex && texOf(katex)) ?? "", label: label ? inlineContent(label, context) : [] };
+      }) : []
+    };
+  });
   return {
     slug,
     route,
     title: title ? collapse(readableText(title)).trim() : slug,
-    blocks: readBlocks(content, context),
-    notation: entries.map((entry) => readNotationEntry(entry, context)),
-    notationRemarks: remarks
+    frames,
+    notation: readPageNotation(main, context).notation
   };
 }
 export {
   courseTarget,
   readDiagramGeometry,
   readInlineFragment,
+  readStaticDeck,
   readStaticPage,
   readableText
 };

package/dist/compiler/knowledge-version.d.ts

@@ -21,7 +21,13 @@ interface KnowledgeChangelogEntry {
     /** Bullet lines under the heading, marker stripped, in file order. */
     readonly notes: readonly string[];
 }
-type KnowledgeVersionCode = 'knowledge-changelog-missing' | 'knowledge-version-invalid' | 'knowledge-version-mismatch';
+/** The released entries and, apart from them, the bullets `## [Unreleased]` holds. */
+interface KnowledgeChangelog {
+    readonly entries: readonly KnowledgeChangelogEntry[];
+    /** Bullet lines under `## [Unreleased]`, any `###` group included, marker stripped. */
+    readonly unreleased: readonly string[];
+}
+type KnowledgeVersionCode = 'knowledge-changelog-missing' | 'knowledge-version-invalid' | 'knowledge-version-mismatch' | 'page-versions-invalid';
 interface KnowledgeVersionDiagnostic {
     readonly code: KnowledgeVersionCode;
     /** Tier 3 — a knowledge-version drift never fails the build. */
@@ -34,9 +40,27 @@ interface KnowledgeVersion {
     readonly version: string;
     /** The newest released `## [x.y.z]` entry, when the changelog has one. */
     readonly latest?: KnowledgeChangelogEntry;
+    /** Every released entry, newest first; empty without a changelog. */
+    readonly entries: readonly KnowledgeChangelogEntry[];
+    /**
+     * The bullets `## [Unreleased]` holds: a content change not yet released
+     * (rule C1). A page changed while there are any is "not yet released"
+     * (rule C5); with none, a change is the release's own, or one rule C1 lets
+     * go unlisted.
+     */
+    readonly unreleased: readonly string[];
     readonly diagnostics: readonly KnowledgeVersionDiagnostic[];
 }
 declare function isKnowledgeSemver(value: string): boolean;
+/**
+ * A `content/CHANGELOG.md` body: every released entry in file order (newest
+ * first, by Keep a Changelog convention), and the bullets of
+ * `## [Unreleased]`. A released entry's notes end at a `###` group heading,
+ * as the About panel has always shown them; the unreleased bullets are
+ * counted through every group, since what they answer is whether anything
+ * is waiting for a release.
+ */
+declare function scanKnowledgeChangelog(text: string): KnowledgeChangelog;
 /**
  * Every released entry in a `content/CHANGELOG.md` body, in file order (newest
  * first, by Keep a Changelog convention). `## [Unreleased]` is skipped.
@@ -55,4 +79,4 @@ declare function resolveKnowledgeVersion(options: {
     readonly file?: string;
 }): KnowledgeVersion;
 
-export { type KnowledgeChangelogEntry, type KnowledgeVersion, type KnowledgeVersionCode, type KnowledgeVersionDiagnostic, isKnowledgeSemver, parseKnowledgeChangelog, resolveKnowledgeVersion };
+export { type KnowledgeChangelog, type KnowledgeChangelogEntry, type KnowledgeVersion, type KnowledgeVersionCode, type KnowledgeVersionDiagnostic, isKnowledgeSemver, parseKnowledgeChangelog, resolveKnowledgeVersion, scanKnowledgeChangelog };

package/dist/compiler/knowledge-version.js

@@ -4,18 +4,19 @@ const BULLET_RE = /^[-*]\s+(.*\S)\s*$/;
 function isKnowledgeSemver(value) {
   return SEMVER_RE.test(value.trim());
 }
-function parseKnowledgeChangelog(text) {
+function scanKnowledgeChangelog(text) {
   const lines = text.split(/\r?\n/);
   const entries = [];
+  const unreleased = [];
   let current = null;
+  let inUnreleased = false;
   for (const line of lines) {
     const heading = HEADING_RE.exec(line);
     if (heading) {
       const token = (heading[1] ?? "").trim();
-      if (/^unreleased$/i.test(token)) {
-        current = null;
-        continue;
-      }
+      current = null;
+      inUnreleased = /^unreleased$/i.test(token);
+      if (inUnreleased) continue;
       current = { version: token, notes: [] };
       const date = (heading[2] ?? "").trim();
       if (date) current.date = date;
@@ -24,17 +25,25 @@ function parseKnowledgeChangelog(text) {
     }
     if (/^#{1,3}\s/.test(line) && !line.startsWith("## [")) {
       current = null;
+      if (/^#{1,2}\s/.test(line)) inUnreleased = false;
       continue;
     }
-    if (!current) continue;
     const bullet = BULLET_RE.exec(line);
-    if (bullet) current.notes.push(bullet[1] ?? "");
+    if (!bullet) continue;
+    if (current) current.notes.push(bullet[1] ?? "");
+    else if (inUnreleased) unreleased.push(bullet[1] ?? "");
   }
-  return entries.map((entry) => ({
-    version: entry.version,
-    ...entry.date === void 0 ? {} : { date: entry.date },
-    notes: [...entry.notes]
-  }));
+  return {
+    entries: entries.map((entry) => ({
+      version: entry.version,
+      ...entry.date === void 0 ? {} : { date: entry.date },
+      notes: [...entry.notes]
+    })),
+    unreleased
+  };
+}
+function parseKnowledgeChangelog(text) {
+  return [...scanKnowledgeChangelog(text).entries];
 }
 function resolveKnowledgeVersion(options) {
   const { changelogText, declaredVersion } = options;
@@ -54,16 +63,16 @@ function resolveKnowledgeVersion(options) {
       "knowledge-changelog-missing",
       `No ${file}. Add a Keep a Changelog file whose newest \`## [x.y.z]\` heading is ${JSON.stringify(declaredVersion)} (rule C1).`
     );
-    return { version: declaredVersion, diagnostics };
+    return { version: declaredVersion, entries: [], unreleased: [], diagnostics };
   }
-  const entries = parseKnowledgeChangelog(changelogText);
+  const { entries, unreleased } = scanKnowledgeChangelog(changelogText);
   const latest = entries[0];
   if (!latest) {
     warn(
       "knowledge-changelog-missing",
       `${file} has no released \`## [x.y.z]\` entry \u2014 only \`## [Unreleased]\`. Cut a release: move it to \`## [${declaredVersion}] - <date>\` (rule C3).`
     );
-    return { version: declaredVersion, diagnostics };
+    return { version: declaredVersion, entries, unreleased, diagnostics };
   }
   if (isKnowledgeSemver(declaredVersion) && latest.version !== declaredVersion) {
     warn(
@@ -71,10 +80,11 @@ function resolveKnowledgeVersion(options) {
       `about.version is ${JSON.stringify(declaredVersion)} but the newest ${file} entry is ${JSON.stringify(latest.version)}. Bump one to match the other (rule C3).`
     );
   }
-  return { version: declaredVersion, latest, diagnostics };
+  return { version: declaredVersion, latest, entries, unreleased, diagnostics };
 }
 export {
   isKnowledgeSemver,
   parseKnowledgeChangelog,
-  resolveKnowledgeVersion
+  resolveKnowledgeVersion,
+  scanKnowledgeChangelog
 };

package/dist/compiler/lesson-derivation.d.ts

@@ -23,14 +23,62 @@
  * shared keys the body names with `[[key]]` / `\explain` — so an import list
  * is redundant.
  */
-/** `foundations/discount-factors` → `foundations.discount-factors`. */
+/**
+ * `foundations/discount-factors` → `foundations.discount-factors`. A deck
+ * file's slug (`foundations/discount-factors.deck.mdx`) gives its lesson's id;
+ * a deck's route (`foundations/discount-factors/slides`) gives the deck's page
+ * id, `foundations.discount-factors.slides` ({@link deckPageId}).
+ */
 declare function lessonIdFromSlug(slug: string): string;
 /**
- * A docs entry is a lesson when it lives in a section directory. The three
+ * A docs entry is a chapter when it lives in a section directory. The three
  * top-level pages (`index`, `curriculum-map`, `glossary`) are not lessons; a
- * future `<section>/index` page would not be one either.
+ * future `<section>/index` page would not be one either, and neither is a
+ * lesson's deck file (`<lesson>.deck.mdx`, {@link isDeckSlug}), which is an
+ * edition of a lesson rather than a lesson.
  */
 declare function isLessonSlug(slug: string): boolean;
+/**
+ * The last segment of a deck's route when the deck stands beside its chapter:
+ * `projectiles/projectile-range` is the chapter, `projectiles/projectile-range/slides`
+ * the deck.
+ */
+declare const DECK_ROUTE_SEGMENT = "slides";
+/**
+ * A deck file — a lesson's slide edition, `content/docs/<part>/<lesson>.deck.mdx`
+ * beside the chapter `<lesson>.mdx` or alone for a lesson that is only slides,
+ * or a part's deck ({@link isPartDeckSlug}). True for the docs slug with or
+ * without its extension; a caller that needs the lesson asks
+ * {@link isPartDeckSlug} first.
+ */
+declare function isDeckSlug(slug: string): boolean;
+/** The lesson a lesson's deck file belongs to: `motion/range.deck.mdx` → `motion/range`. */
+declare function deckLessonSlug(slug: string): string;
+/**
+ * A part's deck, `content/docs/<part>/index.deck.mdx` beside the part's page
+ * `index.mdx`: the slides of the part, served at `/<part>/slides/`
+ * ({@link partDeckRouteSlug}), whose `##` sections may each name the chapter
+ * they cover (`docs/authoring/deck.md`). It is no lesson's edition.
+ */
+declare function isPartDeckSlug(slug: string): boolean;
+/** The part a part's deck belongs to: `motion/index.deck.mdx` → `motion`. */
+declare function partDeckDir(slug: string): string;
+/** Where a part's deck is served: `<part>/slides`, as a chapter's deck is `<lesson>/slides`. */
+declare function partDeckRouteSlug(partDir: string): string;
+/** The page id of a part's deck, the id of its route: `<part>.slides`. */
+declare function partDeckPageId(partDir: string): string;
+/**
+ * Where a lesson's deck is served: `<lesson>/slides` beside its chapter, or
+ * the lesson's own route when the lesson has no chapter (a slides-first
+ * lesson, whose deck is its only edition).
+ */
+declare function deckRouteSlug(lessonSlug: string, hasChapter: boolean): string;
+/**
+ * The page id a deck's notation bundle, gates and diagnostics use — the id of
+ * its route ({@link lessonIdFromSlug}): `<lessonId>.slides` beside a chapter,
+ * the lesson's own id for a slides-first lesson.
+ */
+declare function deckPageId(lessonId: string, hasChapter: boolean): string;
 /**
  * The docs slugs a Starlight route id can stand for. The glob loader shortens
  * `<dir>/index.mdx` to the id `<dir>`, and may give the landing page an empty
@@ -85,12 +133,21 @@ interface SidebarSection {
 /**
  * One sidebar entry: a lesson slug, or an explicit link. `attrs` is Starlight's
  * own passthrough onto the rendered `<a>` — the engine uses it to mark a part's
- * overview row so CSS can give it its own icon.
+ * overview row so CSS can give it its own icon, and to name each edition of a
+ * lesson for the sidebar's script ({@link buildSidebar}).
  */
 type SidebarItem = string | {
     readonly label: string;
     readonly link: string;
     readonly attrs?: Readonly<Record<string, string>>;
+} | {
+    /**
+     * A docs entry by its id (Starlight's `slug` item), with its own label,
+     * or the entry's title without one.
+     */
+    readonly slug: string;
+    readonly label?: string;
+    readonly attrs?: Readonly<Record<string, string>>;
 };
 interface SidebarGroup {
     readonly label: string;
@@ -98,15 +155,95 @@ interface SidebarGroup {
 }
 /** Marks the overview row so `global.css` can give it its own icon. */
 declare const PART_OVERVIEW_CLASS = "explico-part-overview";
+/**
+ * Marks a deck's row, listed under its chapter, so `deck.css` can set it
+ * apart. That is the sidebar without its script; with it, the deck is its
+ * chapter row's trailing icon, or leads the row (`sidebar-editions.ts`).
+ */
+declare const DECK_ROW_CLASS = "explico-deck-row";
+/**
+ * Marks a slides-first lesson's row, whose deck is the lesson, so `deck.css`
+ * gives it the deck's glyph where a chapter has none (a row) or a sheet (a
+ * compact tile). It is a lesson of the reading order, unlike {@link DECK_ROW_CLASS}.
+ */
+declare const DECK_LESSON_CLASS = "explico-deck-lesson";
+/**
+ * Marks a part's deck, listed right after the part's Overview (with
+ * {@link DECK_ROW_CLASS}, so Next and Previous step past it as past any
+ * deck): the part's own, as Overview is, with the part's deck glyph. The
+ * sidebar's script makes the two one row, the part's, as a lesson's chapter
+ * and deck are one (`sidebar-editions.ts`).
+ */
+declare const PART_DECK_CLASS = "explico-part-deck";
+/**
+ * Numbers as a reader reads a run of them: `1–2`, `1, 3`, `2–4, 6`. A run of
+ * two or more is its ends with an en dash.
+ */
+declare function numberList(numbers: readonly number[]): string;
+/**
+ * The lesson a sidebar item lists, by its slug: an item served at its
+ * lesson's own URL (its `data-lesson` is its `slug`), a chapter or a
+ * slides-first lesson's deck. A part's overview, a chapter's slides row
+ * (served under the chapter) and a link list no lesson. A bare slug is a
+ * lesson too.
+ */
+declare function sidebarLessonSlug(item: SidebarItem): string | undefined;
 /**
  * The Starlight `sidebar` config: one group per section, lessons ordered by the
  * merged track order (ties broken by slug), then the static Reference group.
  * Replaces seven `autogenerate` blocks that read an authored `sidebar.order`.
  * `floatIndex`: the course has a top-level "Figures and tables" page
  * (`figures-and-tables.mdx`, `FloatIndex.astro`), listed in Reference.
+ *
+ * Each edition of a lesson is an item of its own, its chapter first, and
+ * names its edition, lesson and title (`data-edition`, `data-lesson`,
+ * `data-title` on the link): the HTML lists both, and the sidebar's script
+ * (`LayoutSidebar.astro`, `sidebar-editions.ts`) makes the two one row.
+ *
+ * A part's deck is an item of the part right after its Overview. Both name
+ * their part and which of its two editions they are (`data-part`,
+ * `data-part-edition`), and the deck its part's label and the ordinals of
+ * the chapters it covers (`data-title`, `data-chapters`: `1–2`), so the
+ * script makes them the part's one row. A chapter it covers that has no deck
+ * of its own carries the address of its section in the part's deck
+ * (`data-deck-href`, `/<part>/slides/#slide-N`, without the site's base),
+ * which the script makes the chapter's other edition: a lesson's own deck
+ * wins over its part's. The frames the deck and each section hold are
+ * `buildDecks`'s, added once it has run ({@link withPartDeckFrames}).
  */
-declare function buildSidebar(tracks: readonly TrackLike[], lessonSlugs: readonly string[], parts: readonly SidebarSection[], { floatIndex }?: {
+declare function buildSidebar(tracks: readonly TrackLike[], lessonSlugs: readonly string[], parts: readonly SidebarSection[], { floatIndex, decks, slidesFirst, partDecks, titleOf, }?: {
     readonly floatIndex?: boolean;
+    /** A deck beside its chapter: chapter slug → the deck's route, listed under the chapter. */
+    readonly decks?: ReadonlyMap<string, string>;
+    /** The lessons whose only edition is a deck, by slug: listed with the deck's glyph. */
+    readonly slidesFirst?: ReadonlySet<string>;
+    /**
+     * A part's deck, by the part's directory: its route, and the frame each
+     * chapter it covers opens on (its section's divider), by chapter slug.
+     */
+    readonly partDecks?: ReadonlyMap<string, {
+        readonly route: string;
+        readonly covers: ReadonlyMap<string, number>;
+    }>;
+    /** A lesson's title, by its slug: `data-title` on each of its items, left out when unknown. */
+    readonly titleOf?: (slug: string) => string | undefined;
 }): SidebarGroup[];
+/** A part's deck as {@link withPartDeckFrames} reads it: its part and its frames, each with the chapter it covers. */
+interface PartDeckFrames {
+    readonly part?: string;
+    readonly frames: readonly {
+        readonly number: number;
+        readonly chapter?: string;
+    }[];
+}
+/**
+ * The sidebar with each part's deck's frames, as `buildDecks` numbers them:
+ * the deck's count on its item (`data-frames`), and on each chapter that
+ * links into its section the frames that section holds (`data-deck-range`,
+ * `2–16`, or `5` for one), its first to its last when it runs over several
+ * sections. `buildDecks` runs after the sidebar is built, since the chapters
+ * it numbers are ordered by the sidebar.
+ */
+declare function withPartDeckFrames(groups: readonly SidebarGroup[], decks: readonly PartDeckFrames[]): SidebarGroup[];
 
-export { PART_OVERVIEW_CLASS, type SidebarGroup, type SidebarItem, type SidebarSection, buildSidebar, citedSourceIds, deriveRequires, deriveSources, docsSlugsForRoute, isLessonSlug, lessonIdFromSlug, mergeTrackOrder, parseCheckList };
+export { DECK_LESSON_CLASS, DECK_ROUTE_SEGMENT, DECK_ROW_CLASS, PART_DECK_CLASS, PART_OVERVIEW_CLASS, type PartDeckFrames, type SidebarGroup, type SidebarItem, type SidebarSection, buildSidebar, citedSourceIds, deckLessonSlug, deckPageId, deckRouteSlug, deriveRequires, deriveSources, docsSlugsForRoute, isDeckSlug, isLessonSlug, isPartDeckSlug, lessonIdFromSlug, mergeTrackOrder, numberList, parseCheckList, partDeckDir, partDeckPageId, partDeckRouteSlug, sidebarLessonSlug, withPartDeckFrames };