explico 0.13.0 → 0.14.0

package/dist/compiler/lesson-derivation.js

@@ -1,10 +1,35 @@
 import { citedIds, withoutLinkCitations } from "../reference/citation-format.mjs";
 function lessonIdFromSlug(slug) {
-  return slug.replace(/\.(md|mdx)$/, "").replace(/\//g, ".");
+  return slug.replace(/\.(md|mdx)$/, "").replace(/\.deck$/, "").replace(/\//g, ".");
 }
 function isLessonSlug(slug) {
   const clean = slug.replace(/\.(md|mdx)$/, "");
-  return clean.includes("/") && !clean.endsWith("/index");
+  return clean.includes("/") && !clean.endsWith("/index") && !isDeckSlug(clean);
+}
+const DECK_ROUTE_SEGMENT = "slides";
+function isDeckSlug(slug) {
+  return /\.deck(?:\.mdx?)?$/.test(slug);
+}
+function deckLessonSlug(slug) {
+  return slug.replace(/\.(md|mdx)$/, "").replace(/\.deck$/, "");
+}
+function isPartDeckSlug(slug) {
+  return /^[^/]+\/index\.deck(?:\.mdx?)?$/.test(slug);
+}
+function partDeckDir(slug) {
+  return slug.replace(/\/index\.deck(?:\.mdx?)?$/, "");
+}
+function partDeckRouteSlug(partDir) {
+  return `${partDir}/${DECK_ROUTE_SEGMENT}`;
+}
+function partDeckPageId(partDir) {
+  return `${partDir}.${DECK_ROUTE_SEGMENT}`;
+}
+function deckRouteSlug(lessonSlug, hasChapter) {
+  return hasChapter ? `${lessonSlug}/${DECK_ROUTE_SEGMENT}` : lessonSlug;
+}
+function deckPageId(lessonId, hasChapter) {
+  return hasChapter ? `${lessonId}.${DECK_ROUTE_SEGMENT}` : lessonId;
 }
 function docsSlugsForRoute(routeSlug) {
   return routeSlug === "" ? ["index"] : [routeSlug, `${routeSlug}/index`];
@@ -58,27 +83,95 @@ function mergeTrackOrder(tracks) {
   return ordered;
 }
 const PART_OVERVIEW_CLASS = "explico-part-overview";
-function buildSidebar(tracks, lessonSlugs, parts, { floatIndex = false } = {}) {
+const DECK_ROW_CLASS = "explico-deck-row";
+const DECK_LESSON_CLASS = "explico-deck-lesson";
+const PART_DECK_CLASS = "explico-part-deck";
+function numberList(numbers) {
+  const sorted = [...new Set(numbers)].sort((left, right) => left - right);
+  const runs = [];
+  for (let start = 0; start < sorted.length; ) {
+    let end = start;
+    while (end + 1 < sorted.length && sorted[end + 1] === sorted[end] + 1) end += 1;
+    runs.push(end === start ? String(sorted[start]) : `${sorted[start]}\u2013${sorted[end]}`);
+    start = end + 1;
+  }
+  return runs.join(", ");
+}
+function sidebarLessonSlug(item) {
+  if (typeof item === "string") return item;
+  if (!("slug" in item)) return void 0;
+  return item.attrs?.["data-lesson"] === item.slug ? item.slug : void 0;
+}
+function buildSidebar(tracks, lessonSlugs, parts, {
+  floatIndex = false,
+  decks = /* @__PURE__ */ new Map(),
+  slidesFirst = /* @__PURE__ */ new Set(),
+  partDecks = /* @__PURE__ */ new Map(),
+  titleOf = () => void 0
+} = {}) {
   const rank = new Map(
     mergeTrackOrder(tracks).map((lessonId, index) => [lessonId, index])
   );
   const positionOf = (slug) => rank.get(lessonIdFromSlug(slug)) ?? Number.POSITIVE_INFINITY;
+  const edition = (lesson, name) => {
+    const title = titleOf(lesson);
+    return {
+      "data-edition": name,
+      "data-lesson": lesson,
+      ...title === void 0 ? {} : { "data-title": title }
+    };
+  };
   const groups = parts.map(
     ({ dir, label, overviewLabel, overviewLink }) => {
-      const chapters = lessonSlugs.filter((slug) => slug.startsWith(`${dir}/`)).sort(
+      const partDeck = partDecks.get(dir);
+      const ordered = lessonSlugs.filter((slug) => slug.startsWith(`${dir}/`)).sort(
         (left, right) => positionOf(left) - positionOf(right) || left.localeCompare(right)
       );
-      return {
-        label,
-        items: overviewLink ? [
+      const chapters = ordered.flatMap((slug) => {
+        if (slidesFirst.has(slug)) {
+          return [{ slug, attrs: { class: DECK_LESSON_CLASS, ...edition(slug, "slides") } }];
+        }
+        const deck = decks.get(slug);
+        const frame = deck === void 0 ? partDeck?.covers.get(slug) : void 0;
+        const chapter = {
+          slug,
+          attrs: {
+            ...edition(slug, "chapter"),
+            ...frame === void 0 || partDeck === void 0 ? {} : { "data-deck-href": `/${partDeck.route}/#slide-${frame}` }
+          }
+        };
+        return deck === void 0 ? [chapter] : [chapter, { slug: deck, label: "Slides", attrs: { class: DECK_ROW_CLASS, ...edition(slug, "slides") } }];
+      });
+      const own = [
+        ...overviewLink ? [
           {
             label: overviewLabel ?? "Overview",
             link: overviewLink,
-            attrs: { class: PART_OVERVIEW_CLASS }
-          },
-          ...chapters
-        ] : chapters
-      };
+            attrs: { class: PART_OVERVIEW_CLASS, "data-part": dir, "data-part-edition": "overview" }
+          }
+        ] : [],
+        ...partDeck === void 0 ? [] : [
+          {
+            slug: partDeck.route,
+            label: "Slides",
+            attrs: {
+              class: `${DECK_ROW_CLASS} ${PART_DECK_CLASS}`,
+              "data-edition": "slides",
+              "data-part": dir,
+              "data-part-edition": "slides",
+              "data-title": label,
+              // A chapter's ordinal is its place in the part, as `lessons[].chapter` numbers it.
+              "data-chapters": numberList(
+                [...partDeck.covers.keys()].flatMap((slug) => {
+                  const at = ordered.indexOf(slug);
+                  return at === -1 ? [] : [at + 1];
+                })
+              )
+            }
+          }
+        ]
+      ];
+      return { label, items: [...own, ...chapters] };
     }
   );
   groups.push({
@@ -91,15 +184,54 @@ function buildSidebar(tracks, lessonSlugs, parts, { floatIndex = false } = {}) {
   });
   return groups;
 }
+function withPartDeckFrames(groups, decks) {
+  const byPart = new Map(decks.flatMap((deck) => deck.part === void 0 ? [] : [[deck.part, deck]]));
+  const rangeOf = (chapter) => {
+    const numbers = decks.flatMap(
+      (deck) => deck.part === void 0 ? [] : deck.frames.filter((frame) => frame.chapter === chapter).map((frame) => frame.number)
+    );
+    if (numbers.length === 0) return void 0;
+    const first = Math.min(...numbers);
+    const last = Math.max(...numbers);
+    return first === last ? String(first) : `${first}\u2013${last}`;
+  };
+  return groups.map((group) => ({
+    ...group,
+    items: group.items.map((item) => {
+      if (typeof item === "string" || item.attrs === void 0) return item;
+      const attrs = item.attrs;
+      const deck = attrs["data-part-edition"] === "slides" ? byPart.get(attrs["data-part"] ?? "") : void 0;
+      if (deck) return { ...item, attrs: { ...attrs, "data-frames": String(deck.frames.length) } };
+      const lesson = attrs["data-lesson"];
+      const range = attrs["data-deck-href"] === void 0 || lesson === void 0 ? void 0 : rangeOf(lesson);
+      return range === void 0 ? item : { ...item, attrs: { ...attrs, "data-deck-range": range } };
+    })
+  }));
+}
 export {
+  DECK_LESSON_CLASS,
+  DECK_ROUTE_SEGMENT,
+  DECK_ROW_CLASS,
+  PART_DECK_CLASS,
   PART_OVERVIEW_CLASS,
   buildSidebar,
   citedSourceIds,
+  deckLessonSlug,
+  deckPageId,
+  deckRouteSlug,
   deriveRequires,
   deriveSources,
   docsSlugsForRoute,
+  isDeckSlug,
   isLessonSlug,
+  isPartDeckSlug,
   lessonIdFromSlug,
   mergeTrackOrder,
-  parseCheckList
+  numberList,
+  parseCheckList,
+  partDeckDir,
+  partDeckPageId,
+  partDeckRouteSlug,
+  sidebarLessonSlug,
+  withPartDeckFrames
 };

package/dist/compiler/manifest.d.ts

@@ -12,10 +12,12 @@ import { LabKatexDiagnostic } from '../reference/lab-katex-validate.js';
 import { MathGateDiagnostic } from '../reference/gate-math.js';
 import { ContentSegment } from '../reference/mixed-content.js';
 import { GlyphScopeEntry } from '../reference/gloss.js';
-import { NotationDefinitionRecord, NotationPageBundle, NotationBacklink, NotationDiagnostic, NotationGlossEntry } from '../reference/types.js';
-import { N as NormalizedLessonExports, a as NormalizedDisclosure, b as NormalizedNumbering, B as BlockLabels, c as NormalizedCards, M as ManifestRules, d as ConfigDiagnostic, C as CourseConfig } from '../course-config-rRtME5UV.js';
+import { NotationGlossEntry, NotationDefinitionRecord, NotationPageBundle, NotationBacklink, NotationDiagnostic } from '../reference/types.js';
+import { N as NormalizedLessonExports, a as NormalizedDisclosure, b as NormalizedNumbering, B as BlockLabels, c as NormalizedCards, d as NormalizedSidebarMarks, e as NormalizedSidebarEditions, R as ReadingMemorySetting, f as NormalizedAppearance, g as NormalizedDeck, M as ManifestRules, h as ConfigDiagnostic, C as CourseConfig } from '../course-config-BLtIdkei.js';
 import { WaiverDiagnostic } from '../rules/waivers.js';
 import { KnowledgeVersionDiagnostic } from './knowledge-version.js';
+import { ManifestPageVersions } from './page-versions.js';
+import { BuiltDeck } from './decks.js';
 import { SidebarGroup } from './lesson-derivation.js';
 import './collections.js';
 import '../reference/gate-retired-keys.js';
@@ -23,6 +25,8 @@ import '../reference/lint-ignore.js';
 import '../reference/keyed-float-validate.js';
 import '../rules/catalog.js';
 import '../rules/course-rules.js';
+import '../reference/decks-validate.js';
+import '../reference/deck-source.js';
 
 /**
  * The one compiler manifest (Phase D5).
@@ -209,8 +213,65 @@ import '../rules/course-rules.js';
  * `formulaTemplate` when its entry sets them, and a bundle definition its
  * `range`. `diagnostics.math` carries `index-explained`, `index-swallowed`,
  * `index-range` and `derived-key-taken`.
+ *
+ * v32 (a page's own version, rule C5): `lessons[].since` and
+ * `parts[].overview.since` carry the knowledge version each chapter's and
+ * part page's content last changed in (`null` for a change not yet
+ * released), read from the committed `content/versions.json` through
+ * `pageVersions` — the record as `validate:content` writes it.
+ * `about.knowledge` gains `releases` (every released entry with its date)
+ * and `unreleased` (whether `## [Unreleased]` holds bullets).
+ * `diagnostics.knowledge` can carry `page-versions-invalid`.
+ * `sidebarMarks` carries the course's `sidebarMarks` setting, defaults
+ * applied: whether the sidebar marks a page the reader has not opened yet,
+ * and one whose content changed since they last did. `readingMemory` says
+ * whether the course asks the reader to keep that memory (`ask`) or never
+ * keeps it (`off`).
+ * v33 (decks, additive): `decks` lists each lesson's slide edition
+ * (`<lesson>.deck.mdx`) with its frames, numbered as the deck shows them;
+ * `deck` carries the course's `deck` settings, defaults applied, and the
+ * canvas; `lessons[].editions` says which editions a lesson has
+ * (`chapter`, `deck`). A slides-first lesson (a deck with no chapter) is a
+ * lesson like any other, with `editions: ["deck"]`. `decks[].since` is the
+ * version a deck's page last changed in (rule C5), as a chapter's `since`.
+ * In `sidebar`, a deck beside its chapter follows the chapter's slug as
+ * `{ slug, label: "Slides", attrs: { class: "explico-deck-row" } }`, and a
+ * slides-first lesson is `{ slug, attrs: { class: "explico-deck-lesson" } }`
+ * in place of its slug (`sidebarLessonSlug` reads either kind of lesson).
+ *
+ * v34 (editions in the sidebar): `sidebarEditions` carries the course's
+ * `sidebarEditions` setting, defaults applied: the edition a lesson's row
+ * opens (`lead`: `chapter` or `slides`) and whether the row lists the other
+ * (`other`: `listed` or `hidden`). In `sidebar`, every item of a lesson
+ * carries `data-edition` (`chapter` or `slides`), `data-lesson` (the
+ * lesson's slug) and `data-title` (its title) in `attrs`, so a chapter is
+ * `{ slug, attrs }` where it was a bare slug. An item lists its lesson when
+ * it is served at the lesson's own URL, `data-lesson` equal to its `slug`:
+ * a chapter, or a slides-first lesson's deck; a chapter's slides row
+ * follows it as before.
+ *
+ * v35 (the slides a reader has seen): every frame of `decks[].frames`
+ * carries `id`, 12 hex digits of a SHA-256 over what it shows, which a
+ * reader's record of the frames shown in Present mode keeps
+ * (`ManifestDeckFrame.id`).
+ *
+ * v36 (a part's deck): `decks` lists each part's deck
+ * (`<part>/index.deck.mdx`, at `<part>/slides`) too, with `part` (its
+ * directory) and no `lessonId`, which is now optional. Every deck carries
+ * `covers`, the chapters a part's deck covers with the frame each one's
+ * section opens on (empty on a lesson's deck); a part's deck carries
+ * `recalledFrom`, the chapter of each float it recalls, and each frame of
+ * a covered section `chapter`. In `sidebar`, a part's deck follows the
+ * part's Overview as `{ slug, label: "Slides", attrs: { class:
+ * "explico-deck-row explico-part-deck", "data-edition": "slides",
+ * "data-part" } }`, and a chapter it covers that has no deck of its own
+ * carries `data-deck-href`, the address of its section.
+ *
+ * v37 (the page's zones and slide edges): `appearance` carries the course's
+ * `appearance` setting, defaults applied: `zones` (`tonal`, `accent-header`,
+ * `paper` or `none`) and `slides` (`lifted`, `edge` or `sorter`).
  */
-declare const MANIFEST_SCHEMA_VERSION = 31;
+declare const MANIFEST_SCHEMA_VERSION = 37;
 declare const MANIFEST_PATH: string;
 interface ManifestCitation {
     readonly id: string;
@@ -276,6 +337,16 @@ interface ManifestDerivedNotation {
     readonly glosses: readonly NotationGlossEntry[];
     readonly formulaScope: readonly GlyphScopeEntry[];
 }
+/**
+ * One lesson's deck (v33), or a part's (v36): its frames as `decks.ts` reads
+ * them, and the notation its page shows — its own bundle, which holds its
+ * chapters'.
+ */
+interface ManifestDeck extends BuiltDeck {
+    readonly notation: ManifestLesson['notation'];
+    /** The version the deck's page last changed in (rule C5), as a chapter's `since`. */
+    readonly since: string | null;
+}
 /**
  * One keyed float of a lesson (v21): its key and number, and its caption pair
  * — `short` (an equation's `\caption{…}`, or the `short` prop) and, for a
@@ -305,6 +376,12 @@ interface ManifestLesson {
     readonly id: string;
     /** Docs-loader slug, e.g. `bonds/price-yield-relationship`. */
     readonly slug: string;
+    /**
+     * The lesson's editions (v33): `chapter` (its `.mdx`), `deck` (its
+     * `.deck.mdx`, listed in `manifest.decks`), or both. A slides-first lesson
+     * is `["deck"]`: its slug is its deck's route and its floats are unnumbered.
+     */
+    readonly editions: readonly ('chapter' | 'deck')[];
     /**
      * The 1-based ordinal of the **part** this lesson sits in — its sidebar
      * group's position in `courseConfig.parts`. It is the first number of every
@@ -353,6 +430,15 @@ interface ManifestLesson {
     readonly file: string;
     readonly title: string;
     readonly description: string;
+    /**
+     * The knowledge version this chapter's content last changed in (v32, rule
+     * C5): its file, its checks and assessments, the shared notation it uses,
+     * the sources it cites and its numbers, against `content/versions.json`.
+     * `null` while it has a change `## [Unreleased]` has not released. What
+     * the exports and the `[?]` panel print for the page; with rule C5 off,
+     * the course's own version.
+     */
+    readonly since: string | null;
     /** Authored reader-facing estimate; `40` and `[30, 40]` both land here. */
     readonly studyMinutes?: {
         readonly min: number;
@@ -439,6 +525,16 @@ interface ManifestAbout {
         readonly date?: string;
         /** Bullet notes from that entry. */
         readonly notes: readonly string[];
+        /**
+         * Every released entry, newest first, with its date (v32): what dates a
+         * document whose content last changed in an earlier release (rule C5).
+         */
+        readonly releases: readonly {
+            readonly version: string;
+            readonly date?: string;
+        }[];
+        /** `## [Unreleased]` holds bullets: a change is waiting for a release (v32). */
+        readonly unreleased: boolean;
         /** Content fingerprint at compile time — ties the shown version to a build. */
         readonly contentTree: string;
     };
@@ -506,6 +602,8 @@ interface ManifestPart {
         readonly title: string;
         readonly file: string;
         readonly description?: string;
+        /** The version the page's content last changed in (v32, rule C5), as a chapter's `since`. */
+        readonly since: string | null;
     };
 }
 interface Manifest {
@@ -520,6 +618,30 @@ interface Manifest {
     readonly blockLabels: BlockLabels;
     /** How the explanation cards start for a reader, defaults applied (`CourseConfig.cards`). */
     readonly cards: NormalizedCards;
+    /**
+     * Which marks the sidebar shows a reader beside a chapter or part page
+     * (v32, `CourseConfig.sidebarMarks`): not opened yet, changed since opened.
+     */
+    readonly sidebarMarks: NormalizedSidebarMarks;
+    /**
+     * Which edition a lesson's sidebar row opens for a reader who has not
+     * chosen, and whether it lists the other (v34, `CourseConfig.sidebarEditions`).
+     */
+    readonly sidebarEditions: NormalizedSidebarEditions;
+    /**
+     * Whether the course asks the reader to keep their reading memory (v32,
+     * `CourseConfig.readingMemory`): `ask` or `off`.
+     */
+    readonly readingMemory: ReadingMemorySetting;
+    /**
+     * How the page tells its zones apart and how slides sit on it, defaults
+     * applied (v37, `CourseConfig.appearance`).
+     */
+    readonly appearance: NormalizedAppearance;
+    /** The course's `deck` settings, defaults applied, and its canvas (v33). */
+    readonly deck: NormalizedDeck;
+    /** Each lesson's deck, by route (v33). */
+    readonly decks: readonly ManifestDeck[];
     /** Reader-facing identity + versions (the `[?]` About panel). */
     readonly about: ManifestAbout;
     readonly notation: {
@@ -539,6 +661,13 @@ interface Manifest {
     /** The course's parts in config order, with their chapters and overview pages. */
     readonly parts: readonly ManifestPart[];
     readonly lessons: readonly ManifestLesson[];
+    /**
+     * The record of every chapter's and part page's own version (v32, rule
+     * C5), as `validate:content` writes it to `content/versions.json`
+     * (`syncPageVersions`); `lessons[].since` and `parts[].overview.since`
+     * are read from it.
+     */
+    readonly pageVersions: ManifestPageVersions;
     /** Every docs page that is not a chapter, by id (v25). */
     readonly pages: readonly ManifestPage[];
     /** Full competency prerequisite graph. */
@@ -656,4 +785,4 @@ declare function readManifestSync(): Manifest;
  */
 declare function loadManifest(courseConfig?: CourseConfig): Promise<Manifest>;
 
-export { MANIFEST_PATH, MANIFEST_SCHEMA_VERSION, type Manifest, type ManifestAbout, type ManifestAssessmentItemContent, type ManifestCitation, type ManifestDerivedNotation, type ManifestLesson, type ManifestLessonFloat, type ManifestLessonNotation, type ManifestNotationResolution, type ManifestPage, type ManifestPart, type ManifestTitledBlock, type PrereqEdge, compileManifest, loadManifest, readManifestSync, serializeManifest, writeManifest };
+export { MANIFEST_PATH, MANIFEST_SCHEMA_VERSION, type Manifest, type ManifestAbout, type ManifestAssessmentItemContent, type ManifestCitation, type ManifestDeck, type ManifestDerivedNotation, type ManifestLesson, type ManifestLessonFloat, type ManifestLessonNotation, type ManifestNotationResolution, type ManifestPage, type ManifestPart, type ManifestTitledBlock, type PrereqEdge, compileManifest, loadManifest, readManifestSync, serializeManifest, writeManifest };