explico 0.13.1 → 0.14.0

package/src/components/starlight/LayoutSocialIcons.astro

@@ -14,15 +14,26 @@
  * part and the course as one file each); with `latex`, as PDF and LaTeX
  * source (a part and the course as a book); with `markdown`, as Markdown. A page that is not a chapter has no download of its own (D8):
  * its content is in its part's and the course's files.
+ *
+ * A lesson's deck (docs/authoring/deck.md) adds a row on its own page and on
+ * its chapter's: the slides as standalone HTML (Present mode offline); with
+ * `latex`, as PDF, as a handout (each slide with its speaker notes) and their
+ * LaTeX source; with `markdown`, as Marp's Markdown. A slides-first lesson
+ * has no chapter row: its deck is all of it. A part's deck adds the same row
+ * on its own page and on its part's, above "This part".
  */
 import DefaultSocialIcons from '@astrojs/starlight/components/SocialIcons.astro';
 import { loadManifest } from '../../compiler/manifest';
 import { docsSlugsForRoute } from '../../compiler/lesson-derivation';
 import {
   courseFileStem,
+  deckFileStem,
+  deckOwnerSlug,
+  deckSaveName,
   exportPageSlugs,
   standaloneFilename,
 } from '../../compiler/exports/export-pages';
+import { chapterSlides, deckOfRoute, partDeckOf } from '../deck/deck-context';
 import AboutPanel from './AboutPanel.astro';
 import LessonExportActions, {
   type DownloadCell,
@@ -31,19 +42,63 @@ import LessonExportActions, {
 import TextSizeControl from './TextSizeControl.astro';
 
 const manifest = await loadManifest();
-const routeSlugs = docsSlugsForRoute(Astro.locals.starlightRoute.entry.id);
-const pageSlug = exportPageSlugs(manifest).find((slug) =>
-  routeSlugs.includes(slug),
-);
+const routeId = Astro.locals.starlightRoute.entry.id;
+const routeSlugs = docsSlugsForRoute(routeId);
+// A deck beside its chapter has a route of its own (`<lesson>/slides`); it
+// downloads as its lesson's page does. A part's deck (`<part>/slides`)
+// downloads as its part's page does.
+const pageDeck = deckOfRoute(manifest, routeId);
+const pageSlug =
+  exportPageSlugs(manifest).find((slug) => routeSlugs.includes(slug)) ??
+  (pageDeck?.part !== undefined
+    ? `${pageDeck.part}/index`
+    : pageDeck
+      ? manifest.lessons.find((entry) => entry.id === pageDeck.lessonId)?.slug
+      : undefined);
 const exports = manifest.lessonExports;
 const printEnabled = pageSlug !== undefined && exports.print;
 const lesson = manifest.lessons.find((entry) => entry.slug === pageSlug);
 const part = lesson
   ? manifest.parts.find((entry) => entry.ordinal === lesson.part)
   : manifest.parts.find((entry) => `${entry.dir}/index` === pageSlug);
+// The slides this page lists: its own; its lesson's, or for a chapter with
+// none of its own the part's deck that covers it (`chapterSlides`); or on a
+// part's page the part's.
+const rowDeck =
+  pageDeck ??
+  (lesson
+    ? ((manifest.decks ?? []).find((entry) => entry.lessonId === lesson.id) ??
+      chapterSlides(manifest, lesson.slug)?.deck)
+    : part
+      ? partDeckOf(manifest, part.dir)
+      : undefined);
 
 const downloads: DownloadRow[] = [];
-if (lesson) {
+/** The deck's row: its slides offline, as PDF, as a handout, their source and Marp's Markdown. */
+const deckRow = (): DownloadRow | undefined => {
+  if (!rowDeck) return undefined;
+  const owner = deckOwnerSlug(rowDeck, manifest);
+  const path = deckFileStem(owner);
+  const name = deckSaveName(owner);
+  const handout = manifest.deck.handoutPdf && manifest.deck.notes !== 'off';
+  const cells: DownloadCell[] = [
+    ...(exports.standaloneHtml ? [{ format: 'html' as const, path: `${path}.html`, filename: `${name}.html` }] : []),
+    ...(exports.latex
+      ? [
+          { format: 'pdf' as const, path: `${path}.pdf`, filename: `${name}.pdf` },
+          ...(handout ? [{ format: 'handout' as const, path: `${path}-notes.pdf`, filename: `${name}-notes.pdf` }] : []),
+          { format: 'latex' as const, path: `${path}-latex.zip`, filename: `${name}-latex.zip` },
+        ]
+      : []),
+    ...(exports.markdown ? [{ format: 'markdown' as const, path: `${path}-markdown.zip`, filename: `${name}-markdown.zip` }] : []),
+  ];
+  return cells.length === 0
+    ? undefined
+    : { scope: 'deck', label: pageDeck ? 'These slides' : 'Its slides', title: rowDeck.title, cells };
+};
+const slidesRow = deckRow();
+if (slidesRow && pageDeck) downloads.push(slidesRow);
+if (lesson && lesson.editions.includes('chapter')) {
   const name = lesson.slug.split('/').at(-1) ?? lesson.slug;
   const cells: DownloadCell[] = [];
   if (exports.standaloneHtml) {
@@ -59,9 +114,10 @@ if (lesson) {
     cells.push({ format: 'markdown', path: `${lesson.slug}-markdown.zip`, filename: `${name}-markdown.zip` });
   }
   if (cells.length > 0) {
-    downloads.push({ scope: 'chapter', label: 'This chapter', title: lesson.title, cells });
+    downloads.push({ scope: 'chapter', label: pageDeck ? 'Its chapter' : 'This chapter', title: lesson.title, cells });
   }
 }
+if (slidesRow && !pageDeck) downloads.push(slidesRow);
 if (pageSlug !== undefined) {
   /** A part's or the course's downloads: `stem` names the files a reader saves. */
   const wholeCells = (path: string, stem: string): DownloadCell[] => [

package/src/components/starlight/LessonExportActions.astro

@@ -9,8 +9,8 @@
  * plain link to a file the build wrote. The build lists what it wrote, with
  * sizes, in `downloads/index.json`; the menu reads it the first time it
  * opens, shows each size and hides a cell whose file is not there. During
- * `astro dev` only a chapter's HTML builds on request; the others say they
- * are built when the site is deployed.
+ * `astro dev` only a chapter's and a deck's HTML build on request; the
+ * others say they are built when the site is deployed.
  *
  * **Print.** The button loads every lab that will be on paper before the
  * print dialog opens — the browser's own `beforeprint` cannot wait for that —
@@ -22,7 +22,7 @@
  * page's footer too (`PrintController.astro`), so Ctrl+P prepares a
  * downloaded page the same way.
  */
-export type DownloadFormat = 'html' | 'pdf' | 'latex' | 'markdown';
+export type DownloadFormat = 'html' | 'pdf' | 'handout' | 'latex' | 'markdown';
 
 export interface DownloadCell {
   readonly format: DownloadFormat;
@@ -32,11 +32,11 @@ export interface DownloadCell {
   readonly filename: string;
 }
 
-export type DownloadScope = 'chapter' | 'part' | 'course';
+export type DownloadScope = 'deck' | 'chapter' | 'part' | 'course';
 
 export interface DownloadRow {
   readonly scope: DownloadScope;
-  /** "This chapter", "This part", "Whole course". */
+  /** "These slides", "This chapter", "This part", "Whole course". */
   readonly label: string;
   /** The chapter's title, the part's label or the course's name. */
   readonly title: string;
@@ -61,6 +61,7 @@ const base = siteBaseUrl.replace(/\/$/u, '');
 const development = import.meta.env.DEV;
 /** What a download's accessible name calls each scope. */
 const SCOPE_NAMES: Readonly<Record<DownloadScope, string>> = {
+  deck: 'the slides',
   chapter: 'this chapter',
   part: 'this part',
   course: 'the whole course',
@@ -68,9 +69,25 @@ const SCOPE_NAMES: Readonly<Record<DownloadScope, string>> = {
 const FORMATS: readonly { readonly format: DownloadFormat; readonly label: string; readonly name: string }[] = [
   { format: 'html', label: 'HTML', name: 'as standalone HTML' },
   { format: 'pdf', label: 'PDF', name: 'as PDF' },
+  { format: 'handout', label: 'Handout', name: 'as a handout, each slide with its notes' },
   { format: 'latex', label: 'LaTeX', name: 'as LaTeX source' },
   { format: 'markdown', label: 'Markdown', name: 'as Markdown' },
 ];
+/**
+ * The button's tooltip names the scopes its menu offers on this page, in the
+ * menu's own words ("this chapter", "this part", "the whole course"): a chapter
+ * has all three, a part's page two, any other page only the course. Its
+ * accessible name stays "Download this page": courses select the button by it.
+ */
+const scopeNames = downloads.map((row) => SCOPE_NAMES[row.scope]);
+const downloadTitle =
+  scopeNames.length === 0
+    ? 'Download this page'
+    : `Download ${
+        scopeNames.length === 1
+          ? scopeNames[0]
+          : `${scopeNames.slice(0, -1).join(', ')} or ${scopeNames[scopeNames.length - 1]}`
+      }`;
 const columns = FORMATS.filter(({ format }) =>
   downloads.some((row) => row.cells.some((cell) => cell.format === format)),
 );
@@ -80,6 +97,7 @@ const notes = [
     (columns.some((column) => column.format === 'latex')
       ? 'PDF is typeset for print, and LaTeX is its source.'
       : 'PDF is typeset for print.'),
+  columns.some((column) => column.format === 'handout') && 'Handout is each slide with its speaker notes.',
   columns.some((column) => column.format === 'markdown') && 'Markdown is plain text with images.',
 ].filter(Boolean);
 ---
@@ -96,7 +114,7 @@ const notes = [
         class="lesson-export-actions__download"
         popovertarget={menuId}
         aria-label="Download this page"
-        title="Download this page"
+        title={downloadTitle}
       >
         <svg viewBox="0 0 24 24" aria-hidden="true">
           <path d="M12 3v12m0 0 4-4m-4 4-4-4M5 19h14" />
@@ -148,9 +166,9 @@ const notes = [
                   const cell = row.cells.find((entry) => entry.format === column.format);
                   if (!cell) return <td><span class="explico-downloads__none" aria-hidden="true">—</span></td>;
                   const name = `Download ${SCOPE_NAMES[row.scope]} ${column.name}`;
-                  // `astro dev` builds a chapter's HTML on request; the rest
-                  // exists only once the site is built.
-                  if (development && !(row.scope === 'chapter' && column.format === 'html')) {
+                  // `astro dev` builds a chapter's and a deck's HTML on
+                  // request; the rest exists only once the site is built.
+                  if (development && !((row.scope === 'chapter' || row.scope === 'deck') && column.format === 'html')) {
                     return (
                       <td>
                         <span

package/src/components/starlight/LessonFooter.astro

@@ -19,6 +19,7 @@ import DefaultFooter from '@astrojs/starlight/components/Footer.astro';
 import { assertLocalNotationParity } from '../../compiler/astro';
 import { loadManifest } from '../../compiler/manifest';
 import {
+  DECK_ROW_CLASS,
   isLessonSlug,
   lessonIdFromSlug,
   docsSlugsForRoute,
@@ -36,6 +37,8 @@ import CollapsibleSections from './CollapsibleSections.astro';
 import TableOverflowExpander from '../table/TableOverflowExpander.astro';
 import DiagramEnhancer from './DiagramEnhancer.astro';
 import PrintController from './PrintController.astro';
+import DeckEnhancer from '../deck/DeckEnhancer.astro';
+import { deckNeighbours, deckOfRoute } from '../deck/deck-context';
 import {
   derivedNotationForPage,
   notationDefinitionsForRenderedPage,
@@ -54,7 +57,62 @@ const routeSlugs = docsSlugsForRoute(routeSlug);
 const pageId =
   lessonId ?? manifest.pages.find((page) => routeSlugs.includes(page.slug))?.id;
 
+// Next and Previous step from chapter to chapter: a chapter's slides are a
+// link of their own under it in the sidebar, not a page of the reading order.
+// On a deck's page they step from deck to deck instead, each named
+// "Slides: *title*" (`deckNeighbours`): a reader of the slides reads on in
+// the slides.
+{
+  type SidebarEntry = {
+    type: string;
+    label?: string;
+    href?: string;
+    attrs?: Record<string, unknown>;
+    isCurrent?: boolean;
+    entries?: SidebarEntry[];
+  };
+  const route = Astro.locals.starlightRoute as unknown as {
+    sidebar: SidebarEntry[];
+    pagination: { prev?: SidebarEntry; next?: SidebarEntry };
+  };
+  const links: SidebarEntry[] = [];
+  const flatten = (entries: readonly SidebarEntry[]) => {
+    for (const entry of entries) {
+      if (entry.type === 'group') flatten(entry.entries ?? []);
+      else links.push(entry);
+    }
+  };
+  flatten(route.sidebar ?? []);
+  const isDeckRow = (entry?: SidebarEntry) =>
+    String(entry?.attrs?.class ?? '').split(/\s+/).includes(DECK_ROW_CLASS);
+  const current = links.findIndex((entry) => entry.isCurrent);
+  const beyond = (direction: 1 | -1) => {
+    for (let index = current + direction; index >= 0 && index < links.length; index += direction) {
+      if (!isDeckRow(links[index])) return links[index];
+    }
+    return undefined;
+  };
+  if (current >= 0 && route.pagination) {
+    if (links[current]?.attrs?.['data-edition'] === 'slides') {
+      const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+      const titleByHref = new Map(
+        (manifest.decks ?? []).map((deck) => [`${base}/${deck.slug}`, deck.title]),
+      );
+      const { prev, next } = deckNeighbours(links, current, (link) =>
+        titleByHref.get(String(link.href ?? '').replace(/\/$/, '')),
+      );
+      route.pagination.prev = prev;
+      route.pagination.next = next;
+    } else {
+      if (isDeckRow(route.pagination.next)) route.pagination.next = beyond(1);
+      if (isDeckRow(route.pagination.prev)) route.pagination.prev = beyond(-1);
+    }
+  }
+}
+
 const glossaryBase = `${import.meta.env.BASE_URL.replace(/\/$/, '')}/glossary/`;
+// A lesson's deck: its frames, Present mode and the presenter window.
+const deck = deckOfRoute(manifest, routeSlug);
 
 const definitions: NotationLayerDefinition[] = [];
 let notationDefaultOpen = false;
@@ -164,6 +222,7 @@ if (pageId) {
 {lessonId && <CollapsibleSections />}
 {lessonId && <TableOverflowExpander />}
 <DiagramEnhancer />
+{deck && <DeckEnhancer />}
 {lessonId && <HeadingAnchorEnhancer />}
 {
   pageId && manifest.lessonExports.print && (

package/src/components/starlight/ReadingMemoryNotice.astro

@@ -0,0 +1,114 @@
+---
+/**
+ * The one question explico asks a reader (`session/reading-memory.ts`): may
+ * this course remember their reading in this browser — which chapters they
+ * opened, and the explanation cards they keep or carry, across visits?
+ *
+ * It sits at the bottom of the window, over nothing the reader needs, until
+ * they answer, on every page; the two answers are the same size and weight.
+ * Before an answer nothing of their reading is kept beyond the tab, so
+ * ignoring the question is the same as "Don't remember" for now. The answer
+ * stands for 13 months; the `[?]` panel changes it or forgets everything.
+ *
+ * Rendered once per page by the header, with the course's `readingMemory`
+ * setting and base path on `[data-explico-reading-memory]`, which every
+ * reading-memory reader on the page looks at. A course with the setting
+ * `off` gets the element but never the question. Without JavaScript nothing
+ * is stored at all, so the question stays hidden.
+ */
+import { loadManifest } from '../../compiler/manifest';
+
+const manifest = await loadManifest();
+const mode = manifest.readingMemory ?? 'ask';
+const base = import.meta.env.BASE_URL;
+---
+
+<div
+  data-explico-reading-memory={mode}
+  data-explico-base={base}
+  hidden
+>
+</div>
+{
+  mode === 'ask' && (
+    <section
+      class="explico-reading-notice"
+      aria-label="Remember your reading?"
+      data-explico-reading-notice
+      hidden
+    >
+      <p class="explico-reading-notice__text">
+        <strong>Remember your reading?</strong> This course can keep, in this
+        browser only, which chapters you open, which slides you present and
+        the explanation cards you keep open, so it can mark new and changed
+        chapters and slides and bring your cards back next time. No cookies;
+        nothing is sent anywhere.
+      </p>
+      <div class="explico-reading-notice__actions">
+        <button type="button" data-reading-answer="yes">
+          Remember
+        </button>
+        <button type="button" data-reading-answer="no">
+          Don't remember
+        </button>
+      </div>
+      <p class="explico-reading-notice__note">
+        Your settings, such as the theme and the text size, are kept either
+        way. Change your answer any time with the{' '}
+        <span aria-hidden="true">?</span><span class="sr-only">About</span>{' '}
+        button at the top of the page.
+      </p>
+    </section>
+  )
+}
+
+<script>
+  import {
+    answerReadingMemory,
+    readingAnswer,
+    readingMemoryMode,
+    READING_MEMORY_EVENT,
+  } from '../../session/reading-memory';
+
+  (() => {
+    const config = document.querySelector<HTMLElement>(
+      '[data-explico-reading-memory]',
+    );
+    const notice = document.querySelector<HTMLElement>(
+      '[data-explico-reading-notice]',
+    );
+    if (!config || !notice) return;
+    // A standalone export is one page with no other pages to remember.
+    if (document.documentElement.hasAttribute('data-explico-standalone')) return;
+    const base = config.dataset.explicoBase ?? '/';
+    // Out of the header, whose own positioning would otherwise hold it: a
+    // fixed box at the window's bottom, last in the reading order.
+    document.body.append(notice);
+
+    const sync = () => {
+      notice.hidden =
+        readingMemoryMode() !== 'ask' || readingAnswer(base) !== 'unasked';
+    };
+
+    notice.addEventListener('click', (event) => {
+      const button =
+        event.target instanceof Element
+          ? event.target.closest<HTMLButtonElement>('button[data-reading-answer]')
+          : null;
+      if (!button) return;
+      const hadFocus = notice.contains(document.activeElement);
+      answerReadingMemory(base, button.dataset.readingAnswer === 'yes');
+      // The question goes; focus goes back to the page, not to nowhere.
+      if (hadFocus) {
+        const title = document.querySelector<HTMLElement>('main h1');
+        if (title) {
+          title.tabIndex = -1;
+          title.focus({ preventScroll: true });
+        }
+      }
+    });
+
+    window.addEventListener(READING_MEMORY_EVENT, sync);
+    sync();
+  })();
+</script>

package/src/components/starlight/TextSizeControl.astro

@@ -1,24 +1,32 @@
 ---
 /**
- * The reader's text size on a touch screen: 100%, 90%, 80% or 70% of the
- * site's own. A PC has the browser's zoom for this; a phone's text-size
- * settings are buried in its browser's menus, so the page offers its own.
- * It sits beside the theme switch (in the phone menu, and in the header
- * of a tablet held wide) and shows only where there is no hover.
+ * The reader's text size on a touch screen: 50% to 100% of the site's own, in
+ * five steps of a geometric series (each 2^(1/4), about 1.19, times the one
+ * below: 50, 59, 71, 84, 100). A PC has the browser's zoom for this; a
+ * phone's text-size settings are buried in its browser's menus, so the page
+ * offers its own. It sits beside the theme switch (in the phone menu, and in
+ * the header of a tablet held wide) and shows only where there is no hover.
  *
  * The choice scales the root font size (`data-text-size` on `<html>`,
  * `global.css`), so the text, the math, the spacing and the cards all
- * follow. It is remembered per reader and copied onto the root before the
- * page first paints by the inline script below, so the page never jumps
- * from one size to another. `LayoutSocialIcons.astro` renders this in the
+ * follow, and sets `--explico-text-scale` for what is drawn in px, a
+ * diagram, which `Diagram.astro` scales as a whole. `global.css` has one rule per step: the end-to-end
+ * test holds it to this list. It is remembered per reader and copied onto
+ * the root before the page first paints by the inline script below, so the
+ * page never jumps from one size to another. A size an earlier release
+ * offered and this one does not (90, 80, 70) is ignored: the page shows 100%. `LayoutSocialIcons.astro` renders this in the
  * header and in the phone menu; both copies stay in step.
  */
 import { Icon } from '@astrojs/starlight/components';
 import { inlineRootAttributeScript } from '../../session/PreferenceStore';
 
 const TEXT_SIZE_KEY = 'explico:display:text-size';
-const SIZES = ['100', '90', '80', '70'] as const;
-const boot = inlineRootAttributeScript(TEXT_SIZE_KEY, 'data-text-size', SIZES.slice(1));
+const STEPS = 4;
+/** 50, 59, 71, 84, 100: the series' ratio is 2^(1/STEPS), and its end is 100. */
+const SIZES = Array.from({ length: STEPS + 1 }, (_, step) =>
+  String(Math.round(100 * 2 ** ((step - STEPS) / STEPS))),
+);
+const boot = inlineRootAttributeScript(TEXT_SIZE_KEY, 'data-text-size', SIZES.slice(0, -1));
 ---
 
 <script is:inline set:html={boot} />
@@ -35,15 +43,18 @@ const boot = inlineRootAttributeScript(TEXT_SIZE_KEY, 'data-text-size', SIZES.sl
   import { createBrowserPreferenceStore } from '../../session/PreferenceStore';
 
   const KEY = 'explico:display:text-size';
-  const SIZES = new Set(['100', '90', '80', '70']);
   const preferences = createBrowserPreferenceStore();
   const root = document.documentElement;
   const selects = () =>
     Array.from(document.querySelectorAll<HTMLSelectElement>('[data-text-size-select]'));
 
+  // The steps are the options the page rendered, so the list lives in one place.
+  const sizes = (): Set<string> =>
+    new Set(selects().flatMap((select) => Array.from(select.options, (option) => option.value)));
+
   const current = (): string => {
     const value = root.getAttribute('data-text-size') ?? '100';
-    return SIZES.has(value) ? value : '100';
+    return sizes().has(value) ? value : '100';
   };
 
   const show = (value: string) => {
@@ -51,7 +62,7 @@ const boot = inlineRootAttributeScript(TEXT_SIZE_KEY, 'data-text-size', SIZES.sl
   };
 
   const choose = (value: string) => {
-    if (!SIZES.has(value)) return;
+    if (!sizes().has(value)) return;
     if (value === '100') {
       root.removeAttribute('data-text-size');
       preferences.remove?.(KEY);

package/src/components/starlight/page-marks.ts

@@ -0,0 +1,139 @@
+/**
+ * The sidebar's marks for one reader (`sidebarMarks` in the course settings):
+ * a quiet ring beside every chapter and part page they have not opened yet,
+ * and an accent dot beside every one whose content changed since they last
+ * opened it.
+ *
+ * A page is named by its slug, and its content by the hash rule C5 keeps for
+ * it in `content/versions.json` (the current one, `pending ?? source`), cut to
+ * 12 hex digits. That hash moves with every change to what the page shows —
+ * its text, its checks, the shared notation and sources it uses, its numbers
+ * — and not when a release only stamps a version on it. So "changed" means
+ * "not what this reader saw", which an unreleased change on the live site
+ * already is, and a release of something they had read is not.
+ *
+ * What a reader has seen is view state, the same kind as an unread mark, not
+ * learning progress: it claims nothing about what they learned. It is one
+ * small JSON map per course, `{ "v": 1, "seen": { slug: id } }`, kept through
+ * the `PreferenceStore` under a key scoped by the site's base path, since
+ * several courses can share one origin. It is reading memory
+ * (`../../session/reading-memory.ts`): recorded only after the reader said
+ * yes to the course keeping it, and deleted with a no. Pure: `LayoutSidebar.astro` does the
+ * DOM and the storage, and `tests/unit/page-marks.test.ts` checks this in Node.
+ */
+
+/** One chapter or part page the sidebar can mark. */
+export interface TrackedPage {
+  /** The sidebar link's path, base included: `/course/motion/constant-acceleration/`. */
+  readonly href: string;
+  /** The docs slug: `motion/constant-acceleration`, `motion/index`. */
+  readonly slug: string;
+  /** The content's identity: the first 12 hex digits of its rule C5 hash. */
+  readonly id: string;
+}
+
+export type PageMark = 'unopened' | 'changed';
+
+/** What `LayoutSidebar.astro` hands its script, as JSON. */
+export interface PageMarksPayload {
+  /** The storage key, scoped by the site's base path. */
+  readonly key: string;
+  /** The site's base path, which names the reader's reading-memory answer. */
+  readonly base: string;
+  /** The course's `sidebarMarks` setting. */
+  readonly unopened: boolean;
+  readonly changed: boolean;
+  readonly pages: readonly TrackedPage[];
+  /**
+   * Every deck and its frames' ids now, which the legend's two actions cover
+   * too (D9, `../../session/deck-memory.ts`): `frames[i]` is frame `i + 1`'s id.
+   */
+  readonly decks?: readonly { readonly slug: string; readonly frames: readonly string[] }[];
+}
+
+/** Bumped whenever the stored shape changes; a record of another version is dropped. */
+const VERSION = 1;
+const ID = /^[0-9a-f]{12}$/u;
+
+/** The storage key for a site whose base path is `base` (`/`, `/course/`). */
+export function pageMarksKey(base: string): string {
+  return `explico-page-marks:${base}`;
+}
+
+/** The identity of a page's content: 12 hex digits of its `sha256:…` hash. */
+export function pageMarkId(hash: string): string {
+  return hash.replace(/^sha256:/u, '').slice(0, 12);
+}
+
+/**
+ * The pages the reader has seen, by slug, from the stored text. Anything
+ * that is not a record of this version, and any entry that is not a slug
+ * and an id, is dropped, never trusted.
+ */
+export function decodeSeen(raw: string | null): Map<string, string> {
+  const seen = new Map<string, string>();
+  if (!raw) return seen;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return seen;
+  }
+  if (!parsed || typeof parsed !== 'object') return seen;
+  const { v, seen: entries } = parsed as { v?: unknown; seen?: unknown };
+  if (v !== VERSION || !entries || typeof entries !== 'object' || Array.isArray(entries)) return seen;
+  for (const [slug, id] of Object.entries(entries as Record<string, unknown>)) {
+    if (typeof id === 'string' && ID.test(id) && slug.length > 0) seen.set(slug, id);
+  }
+  return seen;
+}
+
+/** The stored text, slugs sorted so the same state is always the same string. */
+export function encodeSeen(seen: ReadonlyMap<string, string>): string {
+  const entries = [...seen].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return JSON.stringify({ v: VERSION, seen: Object.fromEntries(entries) });
+}
+
+/**
+ * The record after the reader opened `current` (none for a page the sidebar
+ * does not mark), keeping only the pages the course still has.
+ */
+export function withVisit(
+  seen: ReadonlyMap<string, string>,
+  current: TrackedPage | undefined,
+  pages: readonly TrackedPage[],
+): Map<string, string> {
+  const known = new Set(pages.map((page) => page.slug));
+  const next = new Map([...seen].filter(([slug]) => known.has(slug)));
+  if (current) next.set(current.slug, current.id);
+  return next;
+}
+
+/** The record with every page seen as it is now: "Mark all as seen". */
+export function withAllSeen(pages: readonly TrackedPage[]): Map<string, string> {
+  return new Map(pages.map((page) => [page.slug, page.id]));
+}
+
+/**
+ * The record with no page seen: "Mark all as unseen". The page open when the
+ * reader asks is recorded again by {@link withVisit}, since it is open.
+ */
+export function withNoneSeen(): Map<string, string> {
+  return new Map();
+}
+
+/** A page's mark for a reader who has seen `seen`, under the course's setting. */
+export function markOf(
+  page: TrackedPage,
+  seen: ReadonlyMap<string, string>,
+  options: { readonly unopened: boolean; readonly changed: boolean },
+): PageMark | undefined {
+  const id = seen.get(page.slug);
+  if (id === undefined) return options.unopened ? 'unopened' : undefined;
+  return id !== page.id && options.changed ? 'changed' : undefined;
+}
+
+/** A path as the sidebar compares it: no trailing slash, `/` for the root. */
+export function samePath(href: string): string {
+  return href.replace(/\/+$/u, '') || '/';
+}

package/src/components/starlight/section-summary.ts

@@ -13,7 +13,7 @@
  * `hiddenContentParts` / `describeHiddenContent` turn what it found into the
  * reader-facing line.
  */
-import { FLOAT_KIND_WORDS, floatOf, type NamedFloat } from '../float-name';
+import { FLOAT_KIND_WORDS, floatOf, type NamedFloat } from '../../reference/float-name';
 
 export interface HiddenContentCounts {
   readonly subsections: number;