explico 0.13.0 → 0.14.0

package/src/compiler/collections.ts

@@ -51,11 +51,19 @@ import { indexEntryFormula } from '../reference/derived-notation.mjs';
 import { isIndexEntryLatex } from './content-schemas';
 import type { ContentRecord } from '../reference/gate-retired-keys';
 import {
+  deckLessonSlug,
+  deckPageId,
+  deckRouteSlug,
   deriveRequires,
   deriveSources,
+  isDeckSlug,
   isLessonSlug,
+  isPartDeckSlug,
   lessonIdFromSlug,
   parseCheckList,
+  partDeckDir,
+  partDeckPageId,
+  partDeckRouteSlug,
 } from './lesson-derivation';
 
 // Every invocation — the CLI, `astro build`/`check`, and vitest — runs with the
@@ -325,14 +333,166 @@ function docSlug(path: string): string {
   return relative(join(CONTENT_ROOT, 'docs'), path).replace(/\\/g, '/');
 }
 
-/** Assessment ids from a lesson's colocated `<name>.checks.yml`, or `[]`. */
+/**
+ * Assessment ids from a lesson's colocated `<name>.checks.yml`, or `[]`. A
+ * deck file (`<name>.deck.mdx`) reads the same file as its chapter: the checks
+ * belong to the lesson, whichever edition shows them.
+ */
 function lessonCheckIds(lessonPath: string): string[] {
-  const checksPath = lessonPath.replace(/\.mdx?$/, '.checks.yml');
+  const checksPath = lessonPath.replace(/(?:\.deck)?\.mdx?$/, '.checks.yml');
   return existsSync(checksPath)
     ? parseCheckList(readFileSync(checksPath, 'utf8'))
     : [];
 }
 
+/** Every `.md` / `.mdx` file under `content/docs/`, sorted. */
+function docsFiles(): string[] {
+  const root = join(CONTENT_ROOT, 'docs');
+  return existsSync(root) ? filesBelow(root, ['.md', '.mdx']) : [];
+}
+
+/** What every deck file is, whichever it belongs to ({@link DeckFile}). */
+interface DeckFileBase {
+  /** Absolute path of the deck file. */
+  readonly path: string;
+  /** Repository-relative path, the `file` of its diagnostics. */
+  readonly file: string;
+  /** Docs slug of the deck file, extension included: `motion/range.deck.mdx`. */
+  readonly slug: string;
+  /** Where the deck is served: `motion/range/slides`, `motion/range` alone, or a part's `motion/slides`. */
+  readonly route: string;
+  /** The id of the deck's page: `motion.range.slides`, the lesson's id alone, or a part's `motion.slides`. */
+  readonly pageId: string;
+  /** The part directory the deck sits in: `motion`; empty for a deck outside one. */
+  readonly partDir: string;
+  /** True when the deck sits in a part's directory, as a lesson does. */
+  readonly inPart: boolean;
+  /** The deck file's frontmatter. */
+  readonly data: Record<string, unknown>;
+  readonly body: string;
+  /** 1-based file line {@link body} starts on. */
+  readonly bodyLine: number;
+}
+
+/**
+ * A lesson's deck (`<lesson>.deck.mdx`): its slide edition, beside the
+ * lesson's chapter or, for a lesson that is only slides, alone. See
+ * `docs/authoring/deck.md`.
+ */
+export interface LessonDeckFile extends DeckFileBase {
+  readonly scope: 'lesson';
+  /** The lesson's slug: `motion/range`. */
+  readonly lessonSlug: string;
+  readonly lessonId: string;
+  /** The lesson's chapter file, when it has one. */
+  readonly chapterPath?: string;
+}
+
+/**
+ * A part's deck (`<part>/index.deck.mdx`, beside the part's page): the
+ * slides of the part, whose sections may name the chapters they cover. It
+ * belongs to no lesson.
+ */
+export interface PartDeckFile extends DeckFileBase {
+  readonly scope: 'part';
+}
+
+/** A deck file: a lesson's slide edition, or a part's deck. */
+export type DeckFile = LessonDeckFile | PartDeckFile;
+
+/** A lesson's chapter file, `.mdx` before `.md`, if it has one. */
+function chapterPathOf(lessonSlug: string): string | undefined {
+  for (const extension of ['.mdx', '.md']) {
+    const path = join(CONTENT_ROOT, 'docs', `${lessonSlug}${extension}`);
+    if (existsSync(path)) return path;
+  }
+  return undefined;
+}
+
+/**
+ * Every deck file, by slug: each lesson's, and each part's. A part's deck
+ * (`<part>/index.deck.mdx`) is never read as the deck of a lesson
+ * `<part>/index` whose chapter is the part's page.
+ */
+export function loadDeckFiles(): DeckFile[] {
+  const decks: DeckFile[] = [];
+  for (const path of docsFiles()) {
+    const slug = docSlug(path);
+    if (!isDeckSlug(slug)) continue;
+    const { file, data, body, bodyLine } = parseDocument(path);
+    if (isPartDeckSlug(slug)) {
+      const partDir = partDeckDir(slug);
+      decks.push({
+        scope: 'part',
+        path,
+        file,
+        slug,
+        route: partDeckRouteSlug(partDir),
+        pageId: partDeckPageId(partDir),
+        partDir,
+        inPart: true,
+        data,
+        body,
+        bodyLine,
+      });
+      continue;
+    }
+    const lessonSlug = deckLessonSlug(slug);
+    const lessonId = lessonIdFromSlug(lessonSlug);
+    const chapterPath = chapterPathOf(lessonSlug);
+    const hasChapter = chapterPath !== undefined;
+    decks.push({
+      scope: 'lesson',
+      path,
+      file,
+      slug,
+      lessonSlug,
+      lessonId,
+      ...(chapterPath === undefined ? {} : { chapterPath }),
+      route: deckRouteSlug(lessonSlug, hasChapter),
+      pageId: deckPageId(lessonId, hasChapter),
+      partDir: lessonSlug.includes('/') ? lessonSlug.slice(0, lessonSlug.indexOf('/')) : '',
+      inPart: lessonSlug.includes('/') && !lessonSlug.endsWith('/index'),
+      data,
+      body,
+      bodyLine,
+    });
+  }
+  return decks;
+}
+
+/**
+ * A file that defines a lesson: every chapter, and every deck whose lesson has
+ * no chapter (a slides-first lesson). Its frontmatter is the lesson's —
+ * `teaches`, `assumptions`, `studyMinutes`, `notation` — and its body is what
+ * the lesson's numbering and curriculum passes read.
+ */
+export interface LessonFile {
+  readonly path: string;
+  /** Docs slug of the file, extension included. */
+  readonly slug: string;
+  readonly lessonSlug: string;
+  readonly lessonId: string;
+  readonly edition: 'chapter' | 'deck';
+}
+
+/** Every lesson's defining file, sorted by lesson slug. */
+export function loadLessonFiles(): LessonFile[] {
+  const lessons: LessonFile[] = [];
+  for (const path of docsFiles()) {
+    const slug = docSlug(path);
+    if (isLessonSlug(slug)) {
+      const lessonSlug = slug.replace(/\.(md|mdx)$/, '');
+      lessons.push({ path, slug, lessonSlug, lessonId: lessonIdFromSlug(slug), edition: 'chapter' });
+    } else if (isDeckSlug(slug) && slug.includes('/') && !isPartDeckSlug(slug)) {
+      const lessonSlug = deckLessonSlug(slug);
+      if (chapterPathOf(lessonSlug) !== undefined) continue;
+      lessons.push({ path, slug, lessonSlug, lessonId: lessonIdFromSlug(lessonSlug), edition: 'deck' });
+    }
+  }
+  return lessons.sort((left, right) => left.lessonSlug.localeCompare(right.lessonSlug));
+}
+
 /**
  * One part's **overview page** — `content/docs/<dir>/index.mdx`, the page the
  * part's own directory URL resolves to. `isLessonSlug` already excludes any
@@ -388,17 +548,26 @@ function lessonEntries(
   prerequisitesById: ReadonlyMap<string, readonly string[]>,
 ): LessonDefinition[] {
   const lessons: LessonDefinition[] = [];
-  for (const path of filesBelow(join(CONTENT_ROOT, 'docs'), ['.md', '.mdx'])) {
-    const slug = docSlug(path);
-    if (!isLessonSlug(slug)) continue;
+  // A deck beside its chapter cites what its chapter does not need to: its
+  // sources count for the lesson too.
+  const deckBodies = new Map(
+    loadDeckFiles()
+      .filter((deck): deck is LessonDeckFile => deck.scope === 'lesson' && deck.chapterPath !== undefined)
+      .map((deck) => [deck.lessonId, parseDocument(deck.path).body]),
+  );
+  for (const { path, lessonId } of loadLessonFiles()) {
     const { data, body } = parseDocument(path);
     const teaches = (data.teaches as string[] | undefined) ?? [];
+    const deckBody = deckBodies.get(lessonId);
     lessons.push({
-      id: lessonIdFromSlug(slug),
+      id: lessonId,
       requires: deriveRequires(teaches, prerequisitesById),
       teaches,
       assessments: lessonCheckIds(path),
-      sources: deriveSources(body),
+      sources:
+        deckBody === undefined
+          ? deriveSources(body)
+          : [...new Set([...deriveSources(body), ...deriveSources(deckBody)])].sort(),
       assumptions: (data.assumptions as string[] | undefined) ?? [],
       body,
     });
@@ -538,7 +707,7 @@ function localDefinition(
 function sharedNotationEntries(): SharedNotationDefinitionInput[] {
   const directory = join(CONTENT_ROOT, 'notation');
   return filesBelow(directory, ['.md']).map((path) => {
-    const { file, data, body } = parseDocument(path);
+    const { file, data, body, bodyLine } = parseDocument(path);
     const key = string(data.key, `${file} key`);
     const filenameKey = basename(path, '.md');
     if (key !== filenameKey) {
@@ -566,6 +735,7 @@ function sharedNotationEntries(): SharedNotationDefinitionInput[] {
           ? false
           : boolean(data.aiAssisted, `${file} aiAssisted`),
       body,
+      bodyLine,
       references: extractNotationReferences(body, file, undefined),
       glosses: glossEntries(data.glosses, key, `${file} glosses`),
       source: { file },
@@ -652,21 +822,31 @@ export function notationSuspensions(
   });
 }
 
+/** A lesson file's `notation.local` entries and `notation.suspend` list, parsed. */
+function lessonNotationOf(
+  file: string,
+  data: Record<string, unknown>,
+): { localDefinitions: LocalNotationDefinitionInput[]; suspended: NotationSuspension[] } {
+  const notation = record(data.notation ?? {}, `${file} notation`);
+  const local = Array.isArray(notation.local) ? notation.local : [];
+  const localDefinitions = local.map((entry, index) =>
+    localDefinition(entry, file, index),
+  );
+  return {
+    localDefinitions,
+    suspended: notationSuspensions(notation.suspend, localDefinitions, file),
+  };
+}
+
 function notationLessonEntries(): NotationLessonInput[] {
   const lessons: NotationLessonInput[] = [];
-  for (const path of filesBelow(join(CONTENT_ROOT, 'docs'), ['.md', '.mdx'])) {
-    const slug = docSlug(path);
-    if (!isLessonSlug(slug)) continue;
+  for (const { path, lessonId } of loadLessonFiles()) {
     const { file, data, body, bodyLine } = parseDocument(path);
-    const notation = record(data.notation ?? {}, `${file} notation`);
-    const local = Array.isArray(notation.local) ? notation.local : [];
-    const localDefinitions = local.map((entry, index) =>
-      localDefinition(entry, file, index),
-    );
+    const { localDefinitions, suspended } = lessonNotationOf(file, data);
     lessons.push({
-      lessonId: lessonIdFromSlug(slug),
+      lessonId,
       localDefinitions,
-      suspended: notationSuspensions(notation.suspend, localDefinitions, file),
+      suspended,
       references: extractNotationReferences(body, file, undefined),
       body,
       bodyLine,
@@ -676,6 +856,87 @@ function notationLessonEntries(): NotationLessonInput[] {
   return lessons;
 }
 
+/**
+ * A deck beside its chapter, as a page of the notation registry: its own id
+ * (`<lessonId>.slides`), no entries of its own, and its chapter's scope — the
+ * chapter's `notation.local` entries are the lesson's, so a deck names them
+ * as the chapter does, and it suspends what the chapter suspends. A part's
+ * deck (`<part>.slides`) has its part's scope: every chapter of the part, in
+ * the order the tracks read them, a key one chapter defines locally binding
+ * to the first that does; it suspends what any of them suspends. A deck that
+ * is a lesson's only edition is not here: it is that lesson's page
+ * (`loadNotationRegistryInput`).
+ */
+export interface DeckNotationPage {
+  readonly deck: DeckFile;
+  readonly data: Record<string, unknown>;
+  readonly notation: NotationLessonInput;
+}
+
+export function loadDeckNotationPages(
+  decks: readonly DeckFile[] = loadDeckFiles(),
+  {
+    order = (lessonIds) => lessonIds,
+  }: {
+    /** The lessons of a part in reading order (the tracks'); by slug without it. */
+    readonly order?: (lessonIds: readonly string[]) => readonly string[];
+  } = {},
+): DeckNotationPage[] {
+  const pages: DeckNotationPage[] = [];
+  const chapterFiles = loadLessonFiles().filter((lesson) => lesson.edition === 'chapter');
+  for (const deck of decks) {
+    let chapters: { readonly lessonId: string; readonly path: string }[];
+    if (deck.scope === 'part') {
+      const inPart = chapterFiles.filter((lesson) => lesson.lessonSlug.startsWith(`${deck.partDir}/`));
+      const pathById = new Map(inPart.map((lesson) => [lesson.lessonId, lesson.path]));
+      chapters = order(inPart.map((lesson) => lesson.lessonId)).flatMap((lessonId) => {
+        const path = pathById.get(lessonId);
+        return path === undefined ? [] : [{ lessonId, path }];
+      });
+    } else if (deck.chapterPath !== undefined) {
+      chapters = [{ lessonId: deck.lessonId, path: deck.chapterPath }];
+    } else {
+      continue;
+    }
+    const inheritedLocalDefinitions: LocalNotationDefinitionInput[] = [];
+    const suspended: NotationSuspension[] = [];
+    const inheritedKeys = new Set<string>();
+    for (const { path } of chapters) {
+      const chapter = parseDocument(path);
+      const notation = lessonNotationOf(chapter.file, chapter.data);
+      for (const definition of notation.localDefinitions) {
+        if (!inheritedLocalDefinitions.some((known) => known.key === definition.key)) {
+          inheritedLocalDefinitions.push(definition);
+        }
+      }
+      for (const suspension of notation.suspended) {
+        if (!suspended.some((known) => known.operator === suspension.operator)) suspended.push(suspension);
+      }
+      for (const reference of extractNotationReferences(chapter.body, chapter.file, undefined)) {
+        inheritedKeys.add(reference.key);
+      }
+    }
+    const { file, data, body, bodyLine } = deck;
+    pages.push({
+      deck,
+      data,
+      notation: {
+        lessonId: deck.pageId,
+        localDefinitions: [],
+        suspended,
+        scopeLessonIds: chapters.map((chapter) => chapter.lessonId),
+        inheritedLocalDefinitions,
+        inheritedKeys: [...inheritedKeys].sort(),
+        references: extractNotationReferences(body, file, undefined),
+        body,
+        bodyLine,
+        source: { file },
+      },
+    });
+  }
+  return pages;
+}
+
 /**
  * A docs page that is **not a chapter** (rule S10): the landing page, a part's
  * overview page, and any other page outside a part directory — every slug
@@ -701,9 +962,10 @@ export interface NonChapterPage {
 
 export function loadNonChapterPages(): NonChapterPage[] {
   const pages: NonChapterPage[] = [];
-  for (const path of filesBelow(join(CONTENT_ROOT, 'docs'), ['.md', '.mdx'])) {
+  for (const path of docsFiles()) {
     const slug = docSlug(path);
-    if (isLessonSlug(slug)) continue;
+    // A deck is an edition of a lesson (`loadDeckFiles`), not a page of its own kind.
+    if (isLessonSlug(slug) || isDeckSlug(slug)) continue;
     const { file, data, body, bodyLine } = parseDocument(path);
     const id = lessonIdFromSlug(slug);
     pages.push({
@@ -799,7 +1061,7 @@ export function loadSourceRecords(): Record<string, unknown>[] {
  */
 export function loadLessonChecks(lessonId: string): string[] {
   const slug = lessonId.replace(/\./g, '/');
-  for (const extension of ['.mdx', '.md']) {
+  for (const extension of ['.mdx', '.md', '.deck.mdx', '.deck.md']) {
     const lessonPath = join(CONTENT_ROOT, 'docs', `${slug}${extension}`);
     if (existsSync(lessonPath)) return lessonCheckIds(lessonPath);
   }
@@ -861,11 +1123,8 @@ export function loadNotationSpecs(): NotationSpec[] {
     });
   }
 
-  for (const path of filesBelow(join(CONTENT_ROOT, 'docs'), ['.md', '.mdx'])) {
-    const slug = docSlug(path);
-    if (!isLessonSlug(slug)) continue;
+  for (const { path, lessonId } of loadLessonFiles()) {
     const { file, data } = parseDocument(path);
-    const lessonId = lessonIdFromSlug(slug);
     const local = (data as { notation?: { local?: unknown } }).notation?.local;
     if (!Array.isArray(local)) continue;
     for (const raw of local) {

package/src/compiler/course-config.ts

@@ -386,6 +386,258 @@ export function normalizeCards(config: CourseConfig): NormalizedCards {
   return { carry };
 }
 
+/**
+ * The marks the sidebar puts beside a chapter or part page for one reader
+ * (`sidebarMarks` in the course settings, `page-marks.ts`): a quiet ring
+ * while they have not opened it, an accent dot when its content changed
+ * since they last did. Every field is optional; {@link normalizeSidebarMarks}
+ * fills in the defaults.
+ */
+export interface CourseSidebarMarks {
+  /** Mark a page the reader has not opened yet. Default `true`. */
+  readonly unopened?: boolean;
+  /** Mark a page whose content changed since the reader last opened it. Default `true`. */
+  readonly changed?: boolean;
+}
+
+/** {@link CourseSidebarMarks} with every default applied. */
+export interface NormalizedSidebarMarks {
+  readonly unopened: boolean;
+  readonly changed: boolean;
+}
+
+export const SIDEBAR_MARKS_DEFAULTS: NormalizedSidebarMarks = { unopened: true, changed: true };
+
+/** Validate `CourseConfig.sidebarMarks` and apply its defaults. Throws on a bad value. */
+export function normalizeSidebarMarks(config: CourseConfig): NormalizedSidebarMarks {
+  const marks = config.sidebarMarks ?? {};
+  const read = (field: keyof NormalizedSidebarMarks): boolean => {
+    const value: unknown = marks[field] ?? SIDEBAR_MARKS_DEFAULTS[field];
+    if (typeof value !== 'boolean') {
+      throw new Error(
+        `CourseConfig sidebarMarks.${field} must be true or false; received ${JSON.stringify(value)}.`,
+      );
+    }
+    return value;
+  };
+  return { unopened: read('unopened'), changed: read('changed') };
+}
+
+/**
+ * Which edition of a lesson its sidebar row opens, for a reader who has not
+ * chosen (`sidebarEditions` in the course settings, `sidebar-editions.ts`). A
+ * lesson with a chapter and a deck is one row: the row opens the **lead**
+ * edition, and the **other** is an icon at the row's end, or not listed. A
+ * reader switches both in the sidebar's foot. The plain `string` fields
+ * arrive as JSON; {@link normalizeSidebarEditions} rejects any value it does
+ * not list.
+ */
+export interface CourseSidebarEditions {
+  /** The edition a lesson's row opens: `chapter` (default) or `slides`. */
+  readonly lead?: string;
+  /** Whether the row also lists the other edition: `listed` (default) or `hidden`. */
+  readonly other?: string;
+}
+
+export type SidebarEditionLead = 'chapter' | 'slides';
+export type SidebarEditionOther = 'listed' | 'hidden';
+
+/** {@link CourseSidebarEditions} with every default applied. */
+export interface NormalizedSidebarEditions {
+  readonly lead: SidebarEditionLead;
+  readonly other: SidebarEditionOther;
+}
+
+/** The engine's defaults (decision D10): the chapter leads, the slides are listed. */
+export const SIDEBAR_EDITIONS_DEFAULTS: NormalizedSidebarEditions = { lead: 'chapter', other: 'listed' };
+
+/** Validate `CourseConfig.sidebarEditions` and apply its defaults. Throws on a bad value. */
+export function normalizeSidebarEditions(config: CourseConfig): NormalizedSidebarEditions {
+  const editions = config.sidebarEditions ?? {};
+  const choice = <T extends string>(field: keyof NormalizedSidebarEditions, allowed: readonly T[]): T => {
+    const value: unknown = editions[field] ?? SIDEBAR_EDITIONS_DEFAULTS[field];
+    if (typeof value !== 'string' || !(allowed as readonly string[]).includes(value)) {
+      throw new Error(
+        `CourseConfig sidebarEditions.${field} must be one of ${allowed.map((item) => JSON.stringify(item)).join(', ')}; ` +
+          `received ${JSON.stringify(value)}.`,
+      );
+    }
+    return value as T;
+  };
+  return {
+    lead: choice<SidebarEditionLead>('lead', ['chapter', 'slides']),
+    other: choice<SidebarEditionOther>('other', ['listed', 'hidden']),
+  };
+}
+
+/**
+ * A course's decks: the slide edition of a lesson (`<lesson>.deck.mdx`,
+ * `docs/authoring/deck.md`). Every field is optional; {@link normalizeDeck}
+ * fills in the defaults. The plain `string` fields arrive as JSON, and
+ * {@link normalizeDeck} rejects any value it does not list.
+ */
+export interface CourseDeck {
+  /**
+   * The canvas every deck of the course is laid out on: `16:9` (default),
+   * `16:10` or `4:3`. One setting for the course, because the frame-fit check,
+   * the captured figures and the PDF's page all read it.
+   */
+  readonly aspectRatio?: string;
+  /**
+   * The line on a frame that names the symbols it shows: `first-use`
+   * (default, the symbols the deck has not shown before), `every-frame`
+   * (every symbol on the frame), or `off`.
+   */
+  readonly legend?: string;
+  /**
+   * Who sees a frame's speaker notes: `reader` (default — under each frame in
+   * the scroll view, in the presenter window and in the handout), `presenter`
+   * (the presenter window and the handout only), or `off` (nowhere; the
+   * handout PDF is not built).
+   */
+  readonly notes?: string;
+  /** End each deck on a frame of what its lesson's competencies say a student can now do. Default `true`. */
+  readonly outcomesFrame?: boolean;
+  /** Offer the slides-with-notes PDF beside the slides PDF. Default `true`. */
+  readonly handoutPdf?: boolean;
+}
+
+export type DeckAspectRatio = '16:9' | '16:10' | '4:3';
+export type DeckLegend = 'first-use' | 'every-frame' | 'off';
+export type DeckNotes = 'reader' | 'presenter' | 'off';
+
+/**
+ * The logical canvas a frame is laid out on, in CSS pixels: the width of the
+ * page's reading column, so a figure, a table or a lab lays out on a frame at
+ * the size it was made for, and the frame is scaled to the screen. Every
+ * ratio is 450 px tall, so the type scale and a frame's capacity in lines are
+ * the same in all three. Printed, the canvas is scaled by 1.6 onto a page
+ * 7.5 in tall (13.333 × 7.5 in for 16:9).
+ */
+export const DECK_CANVAS: Readonly<Record<DeckAspectRatio, { readonly width: number; readonly height: number }>> = {
+  '16:9': { width: 800, height: 450 },
+  '16:10': { width: 720, height: 450 },
+  '4:3': { width: 600, height: 450 },
+};
+
+/** {@link CourseDeck} with every default applied, as the manifest publishes it. */
+export interface NormalizedDeck {
+  readonly aspectRatio: DeckAspectRatio;
+  readonly legend: DeckLegend;
+  readonly notes: DeckNotes;
+  readonly outcomesFrame: boolean;
+  readonly handoutPdf: boolean;
+  readonly canvas: { readonly width: number; readonly height: number };
+}
+
+export const DECK_DEFAULTS: Omit<NormalizedDeck, 'canvas'> = {
+  aspectRatio: '16:9',
+  legend: 'first-use',
+  notes: 'reader',
+  outcomesFrame: true,
+  handoutPdf: true,
+};
+
+/** Validate `CourseConfig.deck` and apply its defaults. Throws on a bad value. */
+export function normalizeDeck(config: CourseConfig): NormalizedDeck {
+  const deck = config.deck ?? {};
+  const choice = <T extends string>(field: keyof CourseDeck, allowed: readonly T[]): T => {
+    const value: unknown = deck[field] ?? DECK_DEFAULTS[field as keyof typeof DECK_DEFAULTS];
+    if (typeof value !== 'string' || !(allowed as readonly string[]).includes(value)) {
+      throw new Error(
+        `CourseConfig deck.${field} must be one of ${allowed.map((item) => JSON.stringify(item)).join(', ')}; ` +
+          `received ${JSON.stringify(value)}.`,
+      );
+    }
+    return value as T;
+  };
+  const flag = (field: 'outcomesFrame' | 'handoutPdf'): boolean => {
+    const value: unknown = deck[field] ?? DECK_DEFAULTS[field];
+    if (typeof value !== 'boolean') {
+      throw new Error(`CourseConfig deck.${field} must be true or false; received ${JSON.stringify(value)}.`);
+    }
+    return value;
+  };
+  const aspectRatio = choice<DeckAspectRatio>('aspectRatio', ['16:9', '16:10', '4:3']);
+  return {
+    aspectRatio,
+    legend: choice<DeckLegend>('legend', ['first-use', 'every-frame', 'off']),
+    notes: choice<DeckNotes>('notes', ['reader', 'presenter', 'off']),
+    outcomesFrame: flag('outcomesFrame'),
+    handoutPdf: flag('handoutPdf'),
+    canvas: DECK_CANVAS[aspectRatio],
+  };
+}
+
+/**
+ * Whether the course asks each reader if it may remember their reading in
+ * their browser (`readingMemory` in the course settings,
+ * `session/reading-memory.ts`): which chapters they opened (the sidebar's
+ * marks) and the cards they keep or carry, across visits. `ask` (default)
+ * shows the question until the reader answers; `off` never asks and never
+ * keeps reading memory, so the marks are off and cards last as long as the tab.
+ */
+export type ReadingMemorySetting = 'ask' | 'off';
+
+/** Validate `CourseConfig.readingMemory`. Throws on a bad value. */
+export function normalizeReadingMemory(config: CourseConfig): ReadingMemorySetting {
+  const value: unknown = config.readingMemory ?? 'ask';
+  if (value !== 'ask' && value !== 'off') {
+    throw new Error(`CourseConfig readingMemory must be "ask" or "off"; received ${JSON.stringify(value)}.`);
+  }
+  return value;
+}
+
+/**
+ * How the page tells its zones apart, and how a deck's slides sit on it
+ * (`appearance` in the course settings; `zones.css` and `deck.css` hold the
+ * colours). `zones`: `tonal` (the default) gives both sidebars one step of the
+ * neutral grey and the header a step further; `accent-header` makes the
+ * header a deep band of the course accent; `paper` lays the reading column
+ * on the sidebars' colour as a sheet; `none` keeps Starlight's colours.
+ * `slides`: `lifted` (the default) gives each slide an edge and a drop
+ * shadow, and in the dark theme a sheet a step lighter than the page; `edge`
+ * the edge and shadow on the page's own colour; `sorter` lays the deck on a
+ * tinted well. Every field is optional; {@link normalizeAppearance} fills in
+ * the defaults.
+ */
+export interface CourseAppearance {
+  /** `tonal` (default), `accent-header`, `paper` or `none`. */
+  readonly zones?: string;
+  /** `lifted` (default), `edge` or `sorter`. */
+  readonly slides?: string;
+}
+
+export type AppearanceZones = 'tonal' | 'accent-header' | 'paper' | 'none';
+export type AppearanceSlides = 'lifted' | 'edge' | 'sorter';
+
+/** {@link CourseAppearance} with every default applied. */
+export interface NormalizedAppearance {
+  readonly zones: AppearanceZones;
+  readonly slides: AppearanceSlides;
+}
+
+export const APPEARANCE_DEFAULTS: NormalizedAppearance = { zones: 'tonal', slides: 'lifted' };
+
+const APPEARANCE_ZONES: readonly AppearanceZones[] = ['tonal', 'accent-header', 'paper', 'none'];
+const APPEARANCE_SLIDES: readonly AppearanceSlides[] = ['lifted', 'edge', 'sorter'];
+
+/** Validate `CourseConfig.appearance` and apply its defaults. Throws on a bad value. */
+export function normalizeAppearance(config: CourseConfig): NormalizedAppearance {
+  const appearance = config.appearance ?? {};
+  const choice = <T extends string>(field: keyof NormalizedAppearance, allowed: readonly T[]): T => {
+    const value: unknown = appearance[field] ?? APPEARANCE_DEFAULTS[field];
+    if (!allowed.includes(value as T)) {
+      throw new Error(
+        `CourseConfig appearance.${field} must be one of ${allowed.map((v) => `"${v}"`).join(', ')}; ` +
+          `received ${JSON.stringify(value)}.`,
+      );
+    }
+    return value as T;
+  };
+  return { zones: choice('zones', APPEARANCE_ZONES), slides: choice('slides', APPEARANCE_SLIDES) };
+}
+
 /**
  * Rule S2's word ranges (`rules.S2.bridgeMinWords` … in the course settings),
  * in the shape `gate-part-pages.ts` takes. Built by `partPageLimits` in
@@ -488,6 +740,21 @@ export interface CourseConfig {
   readonly numbering?: CourseNumbering;
   /** How explanation cards start for a reader: "Carry cards" on or off. */
   readonly cards?: CourseCards;
+  /** The sidebar's marks for a page the reader has not opened, or that changed since. */
+  readonly sidebarMarks?: CourseSidebarMarks;
+  /** Which edition a lesson's sidebar row opens, and whether it lists the other. */
+  readonly sidebarEditions?: CourseSidebarEditions;
+  /** How the course's decks look and what they show (`docs/authoring/deck.md`). */
+  readonly deck?: CourseDeck;
+  /**
+   * Ask each reader whether the course may remember their reading in their
+   * browser (`ask`, the default), or never keep it (`off`). A plain `string`
+   * because the settings arrive as JSON; {@link normalizeReadingMemory}
+   * rejects any other value.
+   */
+  readonly readingMemory?: string;
+  /** How the page tells header, sidebars and article apart, and how slides sit on it. */
+  readonly appearance?: CourseAppearance;
   /**
    * How a check's and an example set's heading names its kind: `icon-word`
    * (default) or `icon` ({@link BlockLabels}). A plain `string` because the