explico 0.13.1 → 0.15.0

package/src/components/deck/deck-controller.ts

@@ -0,0 +1,1287 @@
+/**
+ * A deck page in the browser (docs/authoring/deck.md).
+ *
+ * - **The study page.** Every frame's canvas is laid out at the course's canvas
+ *   size and scaled to its stage (`--deck-scale`), every step shown.
+ * - **Present mode.** One frame on the whole screen; keys, a swipe or the
+ *   controls step through it. → ↓ Space PageDown step forward; ← ↑ PageUp
+ *   Backspace step back; Home and End; a number and Enter jump; F full screen;
+ *   N the notes beside the frame; P the presenter window; B blacks the screen
+ *   out; Esc leaves. A lab's slider keeps its arrow keys; PageUp and PageDown
+ *   (what a clicker sends) always move the deck.
+ * - **The presenter window** (`?presenter`): this frame, the next, the notes and
+ *   a clock, kept in step with the room's window by a `BroadcastChannel`.
+ * - **A step's effects.** `data-step-control` moves a lab's control along to a
+ *   value; `data-step-highlight` lights every occurrence of a symbol; a frame
+ *   with `data-morph` morphs from the frame before it with the browser's View
+ *   Transitions, each bound symbol keeping its identity. Reduced motion jumps
+ *   to each effect's end.
+ * - **Where the reader stopped**, the frame and its step, kept with the
+ *   course's reading memory and offered back as a button that presents from
+ *   there — or from the frame after it, once its every step was shown — on
+ *   the next visit and whenever Present mode ends.
+ * - **The slides a reader has seen** (`session/deck-memory.ts`): each frame Present
+ *   mode shows them is kept as it was, for the tab before they answer the
+ *   reading-memory question and across visits with their yes. A line above
+ *   each frame says whether it was shown, not yet, or changed since, and holds
+ *   "Continue here" on the frame to continue at and "Present from here" on
+ *   every other; the slide map under the title shows every frame the same
+ *   way (`deck-map.ts`), pinned under the header while the deck scrolls; a
+ *   line under Present counts them and offers "Mark all as seen" and "Mark all
+ *   as unseen".
+ * - **The chapter on screen**, on a part's deck: the chapter of the frame in
+ *   view on the study page, or shown in Present mode and the presenter, is
+ *   told to the sidebar, which lights its section (`sidebar-editions.ts`).
+ */
+import {
+  answerKey,
+  deckPositionsKey,
+  READING_MEMORY_EVENT,
+  readingAnswer,
+  readingMemoryStore,
+} from '../../session/reading-memory';
+import { slideMap, type SlideMapItem } from './deck-map';
+import {
+  DECK_MEMORY_EVENT,
+  decodeDeckMemory,
+  encodeDeckMemory,
+  frameMark,
+  resumeAt,
+  withAllSeen,
+  withNoneSeen,
+  withPosition,
+  withShown,
+  type DeckFrameId,
+  type DeckFrameSteps,
+  type DeckMemory,
+  type FrameMark,
+  type Resume,
+} from '../../session/deck-memory';
+import {
+  DECK_CHAPTER_ATTRIBUTE,
+  DECK_FRAME_EVENT,
+  type DeckFrameDetail,
+} from '../starlight/sidebar-editions';
+
+interface Frame {
+  readonly element: HTMLElement;
+  readonly number: number;
+  /** What it shows (`data-frame-id`, `ManifestDeckFrame.id`); empty on a page built without one. */
+  readonly id: string;
+  /** On a part's deck, the chapter its section covers (`data-chapter`, a lesson slug); empty otherwise. */
+  readonly chapter: string;
+  readonly steps: number;
+  readonly stage: HTMLElement | null;
+}
+
+interface Deck {
+  readonly root: HTMLElement;
+  readonly slug: string;
+  readonly frames: readonly Frame[];
+  readonly canvasWidth: number;
+  readonly canvasHeight: number;
+  /** The marks the course shows (`sidebarMarks`, `data-deck-marks` on the actions row): none when it keeps no reading memory. */
+  readonly marks: ReadonlySet<FrameMark>;
+  /**
+   * The reader's own controls: the resume button, the marks and their line,
+   * each frame's line, the slide map. Not in the presenter window, and not in
+   * a downloaded deck (`data-explico-export-chrome`).
+   */
+  readonly chrome: boolean;
+  /** Each frame's line on the study page (`installLines`), by index. */
+  readonly lines: FrameLine[];
+  /** The slide map (`installMap`). */
+  map?: SlideMap;
+  /** The reader's record as the study page last showed it (`readReading`). */
+  reading?: Reading;
+  index: number;
+  step: number;
+  presenting: boolean;
+  presenter: boolean;
+  channel?: BroadcastChannel;
+  /** The chapter on screen as last told (`showChapter`). */
+  chapter?: string;
+}
+
+/** A frame's line above it on the study page: its state, and the button that presents from it. */
+interface FrameLine {
+  readonly state: HTMLElement;
+  readonly button: HTMLButtonElement;
+  readonly label: HTMLElement;
+}
+
+/** The slide map under the deck's title. */
+interface SlideMap {
+  readonly nav: HTMLElement;
+  readonly list: HTMLOListElement;
+  /** Its places by key (`slide-3`, `gap-4-55`), kept from one drawing to the next. */
+  readonly places: Map<string, HTMLLIElement>;
+  /** The frame in view, by index. */
+  current: number;
+}
+
+const reducedMotion = (): boolean =>
+  typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+function pixels(value: string, fallback: number): number {
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+// --- scaling ------------------------------------------------------------------
+
+function scaleStage(deck: Deck, stage: HTMLElement): void {
+  const width = stage.clientWidth;
+  if (width > 0) stage.style.setProperty('--deck-scale', String(width / deck.canvasWidth));
+}
+
+/** The least a figure's tools or picture is scaled to fit its frame; past it, the frame does not fit. */
+const LEAST_FIT = 0.6;
+
+/**
+ * A figure on a frame takes the room the frame has (rule D7): its tools are
+ * scaled down, and its picture narrowed, to the height left below the
+ * figure's top — as far as {@link LEAST_FIT}, past which the frame does not
+ * fit (rule D2). A picture is narrowed rather than zoomed, because most take
+ * their width from their column (an inline SVG, a lab's chart box) and keep
+ * their shape: zoomed, they would fill the same column again.
+ */
+function fitFigures(frame: HTMLElement): void {
+  const body = frame.querySelector<HTMLElement>('.deck-frame__body');
+  if (!body) return;
+  const canvas = frame.querySelector<HTMLElement>('.deck-canvas');
+  // Screen pixels per canvas pixel: the canvas lays out at its own size, then scales.
+  const scale = canvas && canvas.offsetWidth > 0 ? canvas.getBoundingClientRect().width / canvas.offsetWidth : 1;
+  const roomBelow = (element: HTMLElement) => body.getBoundingClientRect().bottom - element.getBoundingClientRect().top;
+  for (const figure of body.querySelectorAll<HTMLElement>('.keyed-figure')) {
+    const tools = figure.querySelector<HTMLElement>(':scope > .keyed-figure__tools-fold');
+    const picture = figure.querySelector<HTMLElement>(':scope > .keyed-figure__body');
+    tools?.style.removeProperty('zoom');
+    picture?.style.removeProperty('zoom');
+    picture?.style.removeProperty('max-width');
+    picture?.style.removeProperty('margin-inline');
+    if (tools) {
+      // Both in screen pixels, so the canvas's own scale cancels out.
+      const height = tools.getBoundingClientRect().height;
+      const room = roomBelow(tools);
+      if (height > room + 1) tools.style.setProperty('zoom', String(Math.max(LEAST_FIT, (room / height) * 0.98)));
+    }
+    if (!picture) continue;
+    if (picture.scrollWidth > picture.clientWidth + 1) {
+      // Content of a fixed width, wider than its column (a long formula, a
+      // plot drawn at its size): zoomed, for its width and its height alike.
+      const height = picture.getBoundingClientRect().height + figureCaptionHeight(figure);
+      const room = roomBelow(picture);
+      const tall = height > room + 1 ? (room / height) * 0.98 : 1;
+      picture.style.setProperty('zoom', String(Math.max(LEAST_FIT, Math.min(picture.clientWidth / picture.scrollWidth, tall))));
+      continue;
+    }
+    // What runs past the frame's body, in canvas pixels, comes off the
+    // picture's height, unless the tools' column is the taller one.
+    const over = body.scrollHeight - body.clientHeight;
+    const column = Math.max(picture.getBoundingClientRect().bottom, figure.querySelector(':scope > figcaption')?.getBoundingClientRect().bottom ?? 0);
+    if (over > 1 && !(tools && tools.getBoundingClientRect().bottom > column + 1)) {
+      const height = picture.getBoundingClientRect().height / scale;
+      const fit = Math.max(LEAST_FIT, (Math.max(height - over, 0) / height) * 0.98);
+      picture.style.setProperty('max-width', `${(picture.getBoundingClientRect().width / scale) * fit}px`);
+      picture.style.setProperty('margin-inline', 'auto');
+    }
+  }
+}
+
+/** The caption line under a figure's picture, in its column beside the tools or under the picture alone. */
+function figureCaptionHeight(figure: HTMLElement): number {
+  const caption = figure.querySelector<HTMLElement>(':scope > figcaption');
+  return caption ? caption.getBoundingClientRect().height : 0;
+}
+
+/**
+ * The frames whose content runs past their canvas (rule D2), by number. The
+ * canvas is laid out at its own size whatever the scale, so the measure is
+ * the same on every screen; the build calls it in a browser to fail on one.
+ */
+export function overflowingFrames(root: ParentNode = document): number[] {
+  const numbers: number[] = [];
+  for (const frame of root.querySelectorAll<HTMLElement>('.deck .deck-frame')) {
+    fitFigures(frame);
+    const body = frame.querySelector<HTMLElement>('.deck-frame__body');
+    const canvas = frame.querySelector<HTMLElement>('.deck-canvas');
+    const over =
+      (body !== null && body.scrollHeight > body.clientHeight + 1) ||
+      (body !== null && body.scrollWidth > body.clientWidth + 1) ||
+      (canvas !== null && canvas.scrollHeight > canvas.clientHeight + 1);
+    frame.toggleAttribute('data-deck-overflow', over);
+    if (over) numbers.push(Number(frame.dataset.frame));
+  }
+  return numbers;
+}
+
+function installScaling(deck: Deck): void {
+  deck.root.style.setProperty('--deck-ratio', String(deck.canvasWidth / deck.canvasHeight));
+  deck.root.dataset.deckReady = '';
+  const stages = deck.frames.flatMap((frame) => (frame.stage ? [frame.stage] : []));
+  for (const stage of stages) scaleStage(deck, stage);
+  if (typeof ResizeObserver === 'function') {
+    const observer = new ResizeObserver((entries) => {
+      for (const entry of entries) scaleStage(deck, entry.target as HTMLElement);
+    });
+    for (const stage of stages) observer.observe(stage);
+  }
+}
+
+// --- steps and their effects -----------------------------------------------------
+
+const prior = new WeakMap<HTMLElement, string>();
+
+function stepElements(frame: Frame): HTMLElement[] {
+  return [...frame.element.querySelectorAll<HTMLElement>('.deck-step[data-step]')];
+}
+
+function showSteps(frame: Frame, step: number | 'all'): void {
+  for (const element of stepElements(frame)) {
+    const at = Number(element.dataset.step);
+    element.classList.toggle('is-future', step !== 'all' && at > step);
+  }
+}
+
+/** The text a control is known by: its label, its `aria-label`, or what `aria-labelledby` names. */
+function controlName(control: HTMLElement): string {
+  const parts: string[] = [];
+  const aria = control.getAttribute('aria-label');
+  if (aria) parts.push(aria);
+  const labelledBy = control.getAttribute('aria-labelledby');
+  if (labelledBy) {
+    for (const id of labelledBy.split(/\s+/)) parts.push(document.getElementById(id)?.textContent ?? '');
+  }
+  const labels = (control as HTMLInputElement).labels;
+  if (labels) for (const label of labels) parts.push(label.textContent ?? '');
+  const title = control.getAttribute('title');
+  if (title) parts.push(title);
+  return parts.join(' ').replace(/\s+/g, ' ').trim().toLowerCase();
+}
+
+function findControl(frame: Frame, name: string): HTMLInputElement | HTMLSelectElement | undefined {
+  const wanted = name.trim().toLowerCase();
+  const controls = [...frame.element.querySelectorAll<HTMLInputElement | HTMLSelectElement>('.deck-canvas input, .deck-canvas select')];
+  return (
+    controls.find((control) => controlName(control) === wanted) ??
+    controls.find((control) => controlName(control).includes(wanted))
+  );
+}
+
+/** Set a control's value as a reader's hand would: the value, then the events a lab listens to. */
+function setControl(control: HTMLInputElement | HTMLSelectElement, value: string, final: boolean): void {
+  const prototype = control instanceof HTMLSelectElement ? HTMLSelectElement.prototype : HTMLInputElement.prototype;
+  const setter = Object.getOwnPropertyDescriptor(prototype, 'value')?.set;
+  if (setter) setter.call(control, value);
+  else control.value = value;
+  control.dispatchEvent(new Event('input', { bubbles: true }));
+  if (final) control.dispatchEvent(new Event('change', { bubbles: true }));
+}
+
+const running = new WeakMap<HTMLElement, number>();
+
+function driveControl(step: HTMLElement, frame: Frame): void {
+  const name = step.dataset.stepControl;
+  const to = Number(step.dataset.stepTo);
+  if (!name || !Number.isFinite(to)) return;
+  const control = findControl(frame, name);
+  if (!control) {
+    console.warn(`[explico deck] slide ${frame.number}: no control labelled “${name}” to drive.`);
+    return;
+  }
+  if (!prior.has(step)) prior.set(step, control.value);
+  const fromValue = step.dataset.stepFrom !== undefined ? Number(step.dataset.stepFrom) : Number(control.value);
+  const seconds = Number(step.dataset.stepSeconds ?? '1.5');
+  const previous = running.get(step);
+  if (previous !== undefined) cancelAnimationFrame(previous);
+  if (reducedMotion() || !Number.isFinite(fromValue) || !(seconds > 0) || control instanceof HTMLSelectElement) {
+    setControl(control, String(to), true);
+    return;
+  }
+  const start = performance.now();
+  const duration = seconds * 1000;
+  const stepSize = Number((control as HTMLInputElement).step) || 0;
+  const tick = (now: number) => {
+    const t = Math.min(1, (now - start) / duration);
+    const eased = t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2;
+    let value = fromValue + (to - fromValue) * eased;
+    if (stepSize > 0) value = Math.round(value / stepSize) * stepSize;
+    setControl(control, String(t === 1 ? to : value), t === 1);
+    if (t < 1) running.set(step, requestAnimationFrame(tick));
+    else running.delete(step);
+  };
+  running.set(step, requestAnimationFrame(tick));
+}
+
+function undriveControl(step: HTMLElement, frame: Frame): void {
+  const name = step.dataset.stepControl;
+  const before = prior.get(step);
+  const previous = running.get(step);
+  if (previous !== undefined) cancelAnimationFrame(previous);
+  if (!name || before === undefined) return;
+  const control = findControl(frame, name);
+  if (control) setControl(control, before, true);
+  prior.delete(step);
+}
+
+function spotlight(frame: Frame, key: string | undefined, on: boolean, source = 'step'): void {
+  if (!key) return;
+  for (const element of frame.element.querySelectorAll<HTMLElement>(`.deck-canvas [data-notation-key="${CSS.escape(key)}"]`)) {
+    const holders = new Set((element.dataset.deckSpotlight ?? '').split(' ').filter(Boolean));
+    if (on) holders.add(source);
+    else holders.delete(source);
+    element.dataset.deckSpotlight = [...holders].join(' ');
+    element.classList.toggle('deck-spotlight', holders.size > 0);
+  }
+}
+
+/** Run what steps `from`+1 … `to` do, forward, or undo them, backward. */
+function stepEffects(frame: Frame, from: number, to: number): void {
+  const steps = stepElements(frame);
+  if (to > from) {
+    for (const element of steps) {
+      const at = Number(element.dataset.step);
+      if (at <= from || at > to) continue;
+      if (element.dataset.stepControl) driveControl(element, frame);
+      if (element.dataset.stepHighlight) spotlight(frame, element.dataset.stepHighlight, true);
+    }
+  } else if (to < from) {
+    for (const element of [...steps].reverse()) {
+      const at = Number(element.dataset.step);
+      if (at <= to || at > from) continue;
+      if (element.dataset.stepControl) undriveControl(element, frame);
+      if (element.dataset.stepHighlight) spotlight(frame, element.dataset.stepHighlight, false);
+    }
+  }
+}
+
+// --- morph ----------------------------------------------------------------------
+
+function nameShared(frame: Frame): void {
+  const counts = new Map<string, number>();
+  const title = frame.element.querySelector<HTMLElement>('.deck-frame__title');
+  if (title) title.style.setProperty('view-transition-name', 'deck-title');
+  for (const element of frame.element.querySelectorAll<HTMLElement>('.deck-frame__body [data-notation-key]')) {
+    if (element.closest('.deck-step.is-future')) continue;
+    const key = element.dataset.notationKey ?? '';
+    const count = (counts.get(key) ?? 0) + 1;
+    counts.set(key, count);
+    element.style.setProperty('view-transition-name', `deck-${key.replace(/[^a-z0-9-]/gi, '-')}-${count}`);
+  }
+  for (const element of frame.element.querySelectorAll<HTMLElement>('.deck-frame__body .keyed-equation[data-eq-key]')) {
+    element.style.setProperty('view-transition-name', `deck-eq-${element.dataset.eqKey}`);
+  }
+}
+
+function clearNames(frame: Frame): void {
+  for (const element of frame.element.querySelectorAll<HTMLElement>('[style*="view-transition-name"]')) {
+    element.style.removeProperty('view-transition-name');
+  }
+}
+
+// --- moving ---------------------------------------------------------------------
+
+function markCurrent(deck: Deck): void {
+  deck.frames.forEach((frame, index) => {
+    frame.element.classList.toggle('is-current', index === deck.index);
+    frame.element.classList.toggle('is-next', index === deck.index + 1);
+  });
+}
+
+function announce(deck: Deck): void {
+  const frame = deck.frames[deck.index];
+  const live = deck.root.querySelector<HTMLElement>('.deck-live');
+  if (!frame || !live) return;
+  const title = frame.element.querySelector('.deck-frame__title, .deck-title__title')?.textContent?.trim() ?? '';
+  live.textContent = `Slide ${frame.number} of ${deck.frames.length}${title ? `: ${title}` : ''}`;
+  const counter = deck.root.querySelector<HTMLElement>('.deck-hud__count');
+  if (counter) counter.textContent = `${frame.number} / ${deck.frames.length}`;
+}
+
+/**
+ * Tell the sidebar the chapter of the frame at `index`, when it changed: on
+ * `<html>` (`DECK_CHAPTER_ATTRIBUTE`, empty for a frame of no chapter), for
+ * a sidebar script that runs later, and as `DECK_FRAME_EVENT`.
+ */
+function showChapter(deck: Deck, index: number): void {
+  const chapter = deck.frames[index]?.chapter ?? '';
+  if (chapter === deck.chapter) return;
+  deck.chapter = chapter;
+  document.documentElement.setAttribute(DECK_CHAPTER_ATTRIBUTE, chapter);
+  window.dispatchEvent(
+    new CustomEvent<DeckFrameDetail>(DECK_FRAME_EVENT, { detail: { deck: deck.slug, chapter } }),
+  );
+}
+
+// --- what the reader has seen ------------------------------------------------------
+
+const idOf = (frame: Frame): DeckFrameId => ({ number: frame.number, id: frame.id });
+const stepsOf = (frame: Frame): DeckFrameSteps => ({ ...idOf(frame), steps: frame.steps });
+
+/** Every deck's record, as the course's reading memory holds it (`deck-memory.ts`). */
+function readMemory(): DeckMemory {
+  try {
+    return decodeDeckMemory(readingMemoryStore(baseOf()).get(deckPositionsKey(baseOf())));
+  } catch {
+    return new Map();
+  }
+}
+
+/** Write a change to the record; `tell` the page, which reads it again (`DECK_MEMORY_EVENT`). */
+function changeMemory(change: (memory: DeckMemory) => DeckMemory, { tell = true } = {}): void {
+  try {
+    const store = readingMemoryStore(baseOf());
+    const key = deckPositionsKey(baseOf());
+    store.set(key, encodeDeckMemory(change(decodeDeckMemory(store.get(key)))));
+  } catch {
+    // Reading memory is a convenience; a blocked store keeps nothing.
+  }
+  if (tell) window.dispatchEvent(new CustomEvent(DECK_MEMORY_EVENT));
+}
+
+/**
+ * Whether the frames Present mode shows are kept and marked: the course marks
+ * them, and the reader has not said no to reading memory. With their yes they
+ * are kept across visits; before an answer, for the tab (`readingMemoryStore`),
+ * as kept cards are.
+ */
+function keepsShown(deck: Deck): boolean {
+  return deck.marks.size > 0 && readingAnswer(baseOf()) !== 'no';
+}
+
+/**
+ * Where Present mode stands, the step too, and, while the frames shown are
+ * kept, the frame it shows as it is (D8: the current frame, in the room's
+ * window or the presenter's, at any step). Otherwise the place alone, for the
+ * tab. The page reads it again when Present mode ends.
+ */
+function remember(deck: Deck): void {
+  const frame = deck.frames[deck.index];
+  if (!frame || (!deck.presenting && !deck.presenter)) return;
+  const shown = frame.id !== '' && keepsShown(deck);
+  changeMemory(
+    (memory) =>
+      shown
+        ? withShown(memory, deck.slug, idOf(frame), deck.step)
+        : withPosition(memory, deck.slug, frame.number, deck.step),
+    { tell: false },
+  );
+}
+
+function go(deck: Deck, index: number, step: number, { broadcast = true, effects = true } = {}): void {
+  const target = Math.max(0, Math.min(deck.frames.length - 1, index));
+  const frame = deck.frames[target];
+  if (!frame) return;
+  const nextStep = Math.max(1, Math.min(frame.steps, step));
+  const old = deck.frames[deck.index];
+  const changing = target !== deck.index;
+  const morph =
+    changing &&
+    old !== undefined &&
+    ((target === deck.index + 1 && frame.element.hasAttribute('data-morph')) ||
+      (target === deck.index - 1 && old.element.hasAttribute('data-morph')));
+
+  const apply = () => {
+    if (changing && old) {
+      stepEffects(old, deck.step, 0);
+      spotlight(old, undefined, false);
+    }
+    const fromStep = changing ? 0 : deck.step;
+    deck.index = target;
+    deck.step = nextStep;
+    if (deck.presenting || deck.presenter) showSteps(frame, nextStep);
+    markCurrent(deck);
+    if (effects) stepEffects(frame, fromStep, nextStep);
+    // Once the frame is the current one: a morph applies it a frame later.
+    if (deck.presenting || deck.presenter) {
+      announce(deck);
+      showChapter(deck, target);
+    }
+    remember(deck);
+  };
+
+  const transition = (document as Document & { startViewTransition?: (update: () => void) => { finished: Promise<void> } })
+    .startViewTransition;
+  if (morph && deck.presenting && transition && !reducedMotion()) {
+    nameShared(old!);
+    const view = transition.call(document, () => {
+      clearNames(old!);
+      apply();
+      nameShared(frame);
+    });
+    void view.finished.finally(() => clearNames(frame));
+  } else {
+    apply();
+  }
+
+  if (deck.presenting || deck.presenter) {
+    history.replaceState(history.state, '', `${location.pathname}${location.search}#slide-${frame.number}`);
+  }
+  if (broadcast) deck.channel?.postMessage({ type: 'go', index: target, step: nextStep });
+}
+
+function next(deck: Deck): void {
+  const frame = deck.frames[deck.index];
+  if (frame && deck.step < frame.steps) go(deck, deck.index, deck.step + 1);
+  else if (deck.index < deck.frames.length - 1) go(deck, deck.index + 1, 1);
+}
+
+function previous(deck: Deck): void {
+  if (deck.step > 1) go(deck, deck.index, deck.step - 1);
+  else if (deck.index > 0) {
+    // Back to the frame before, whole: as beamer goes back.
+    const before = deck.frames[deck.index - 1];
+    go(deck, deck.index - 1, before?.steps ?? 1);
+  }
+}
+
+// --- Present mode ----------------------------------------------------------------
+
+function frameInView(deck: Deck): number {
+  const middle = window.innerHeight / 3;
+  let best = 0;
+  let distance = Number.POSITIVE_INFINITY;
+  deck.frames.forEach((frame, index) => {
+    const box = frame.element.getBoundingClientRect();
+    const d = Math.abs(box.top - middle);
+    if (box.bottom > 0 && d < distance) {
+      distance = d;
+      best = index;
+    }
+  });
+  return best;
+}
+
+function rescaleCurrent(deck: Deck): void {
+  requestAnimationFrame(() => {
+    for (const frame of deck.frames) if (frame.stage) scaleStage(deck, frame.stage);
+  });
+}
+
+function present(deck: Deck, index = frameInView(deck)): void {
+  deck.presenting = true;
+  document.documentElement.classList.add('deck-presenting');
+  deck.index = -1;
+  go(deck, index, 1);
+  for (const frame of deck.frames) if (deck.frames.indexOf(frame) !== deck.index) showSteps(frame, 1);
+  rescaleCurrent(deck);
+  const root = document.documentElement;
+  if (root.requestFullscreen && !document.fullscreenElement) {
+    root.requestFullscreen().catch(() => undefined);
+  }
+  deck.frames[deck.index]?.element.focus({ preventScroll: true });
+}
+
+function leave(deck: Deck): void {
+  if (!deck.presenting) return;
+  const frame = deck.frames[deck.index];
+  deck.presenting = false;
+  document.documentElement.classList.remove('deck-presenting', 'deck-notes-open', 'deck-blackout', 'deck-hud-visible');
+  for (const each of deck.frames) {
+    showSteps(each, 'all');
+    each.element.classList.remove('is-current', 'is-next');
+  }
+  if (document.fullscreenElement && document.exitFullscreen) document.exitFullscreen().catch(() => undefined);
+  rescaleCurrent(deck);
+  frame?.element.scrollIntoView({ block: 'start' });
+  // Focus is where the reader is now, not on the frame Present mode started at.
+  frame?.element.focus({ preventScroll: true });
+  // What Present mode recorded: the resume button, the marks, the sidebar's line read it again.
+  window.dispatchEvent(new CustomEvent(DECK_MEMORY_EVENT));
+}
+
+function openPresenter(deck: Deck): void {
+  const frame = deck.frames[deck.index];
+  const url = `${location.pathname}?presenter#slide-${frame?.number ?? 1}`;
+  window.open(url, `explico-presenter-${deck.slug}`, 'popup,width=1280,height=800');
+}
+
+function isEditable(target: EventTarget | null): boolean {
+  const element = target as HTMLElement | null;
+  if (!element || !element.closest) return false;
+  return Boolean(element.closest('input, select, textarea, [contenteditable=""], [contenteditable="true"], [role="slider"]'));
+}
+
+function installKeys(deck: Deck): void {
+  let digits = '';
+  document.addEventListener('keydown', (event) => {
+    if (!deck.presenting && !deck.presenter) return;
+    if (event.altKey || event.ctrlKey || event.metaKey) return;
+    const key = event.key;
+    // A clicker's PageDown/PageUp always move the deck; the rest yield to a control.
+    if (isEditable(event.target) && key !== 'PageDown' && key !== 'PageUp' && key !== 'Escape') return;
+    let handled = true;
+    if (/^[0-9]$/.test(key)) {
+      digits += key;
+    } else if (key === 'Enter' && digits) {
+      const number = Number(digits);
+      digits = '';
+      const index = deck.frames.findIndex((frame) => frame.number === number);
+      if (index >= 0) go(deck, index, 1);
+    } else if (['ArrowRight', 'ArrowDown', ' ', 'PageDown', 'Enter'].includes(key)) {
+      next(deck);
+    } else if (['ArrowLeft', 'ArrowUp', 'PageUp', 'Backspace'].includes(key)) {
+      previous(deck);
+    } else if (key === 'Home') {
+      go(deck, 0, 1);
+    } else if (key === 'End') {
+      go(deck, deck.frames.length - 1, deck.frames.at(-1)?.steps ?? 1);
+    } else if (key === 'f' || key === 'F') {
+      if (document.fullscreenElement) document.exitFullscreen?.().catch(() => undefined);
+      else document.documentElement.requestFullscreen?.().catch(() => undefined);
+    } else if (key === 'n' || key === 'N') {
+      document.documentElement.classList.toggle('deck-notes-open');
+      rescaleCurrent(deck);
+    } else if ((key === 'p' || key === 'P') && deck.presenting) {
+      openPresenter(deck);
+    } else if (key === 'b' || key === 'B' || key === '.') {
+      document.documentElement.classList.toggle('deck-blackout');
+    } else if (key === 'Escape' && deck.presenting) {
+      leave(deck);
+    } else {
+      handled = false;
+    }
+    if (handled) {
+      event.preventDefault();
+      if (!/^[0-9]$/.test(key)) digits = key === 'Enter' ? '' : digits;
+    }
+  });
+}
+
+function installTouch(deck: Deck): void {
+  let startX = 0;
+  let startY = 0;
+  deck.root.addEventListener('pointerdown', (event) => {
+    startX = event.clientX;
+    startY = event.clientY;
+  });
+  deck.root.addEventListener('pointerup', (event) => {
+    if (!deck.presenting || event.pointerType === 'mouse' || isEditable(event.target)) return;
+    const dx = event.clientX - startX;
+    const dy = event.clientY - startY;
+    if (Math.abs(dx) > 60 && Math.abs(dx) > 2 * Math.abs(dy)) {
+      if (dx < 0) next(deck);
+      else previous(deck);
+    }
+  });
+}
+
+function installHud(deck: Deck): void {
+  const hud = document.createElement('div');
+  hud.className = 'deck-hud';
+  hud.innerHTML =
+    '<button type="button" data-deck-hud="previous" aria-label="Previous step">◀</button>' +
+    '<span class="deck-hud__count" aria-hidden="true"></span>' +
+    '<button type="button" data-deck-hud="next" aria-label="Next step">▶</button>' +
+    '<button type="button" data-deck-hud="notes">Notes</button>' +
+    '<button type="button" data-deck-hud="presenter">Presenter</button>' +
+    '<button type="button" data-deck-hud="leave">Exit</button>';
+  deck.root.append(hud);
+  const live = document.createElement('div');
+  live.className = 'deck-live sr-only';
+  live.setAttribute('aria-live', 'polite');
+  deck.root.append(live);
+  hud.addEventListener('click', (event) => {
+    const action = (event.target as HTMLElement).closest<HTMLElement>('[data-deck-hud]')?.dataset.deckHud;
+    if (action === 'previous') previous(deck);
+    else if (action === 'next') next(deck);
+    else if (action === 'notes') {
+      document.documentElement.classList.toggle('deck-notes-open');
+      rescaleCurrent(deck);
+    } else if (action === 'presenter') openPresenter(deck);
+    else if (action === 'leave') leave(deck);
+  });
+  let timer: number | undefined;
+  document.addEventListener('pointermove', () => {
+    if (!deck.presenting) return;
+    document.documentElement.classList.add('deck-hud-visible');
+    window.clearTimeout(timer);
+    timer = window.setTimeout(() => document.documentElement.classList.remove('deck-hud-visible'), 2200);
+  });
+}
+
+/** A symbol under the pointer lights every place it shows on the frame. */
+function installHoverSpotlight(deck: Deck): void {
+  deck.root.addEventListener('pointerover', (event) => {
+    if (!deck.presenting) return;
+    const element = (event.target as HTMLElement).closest<HTMLElement>('.deck-canvas [data-notation-key]');
+    const frame = deck.frames[deck.index];
+    if (element && frame) spotlight(frame, element.dataset.notationKey, true, 'pointer');
+  });
+  deck.root.addEventListener('pointerout', (event) => {
+    const element = (event.target as HTMLElement).closest<HTMLElement>('.deck-canvas [data-notation-key]');
+    const frame = deck.frames[deck.index];
+    if (element && frame) spotlight(frame, element.dataset.notationKey, false, 'pointer');
+  });
+}
+
+function installPresenterWindow(deck: Deck): void {
+  deck.presenter = true;
+  document.documentElement.classList.add('deck-presenter-window');
+  const clock = document.createElement('div');
+  clock.className = 'deck-clock';
+  document.body.append(clock);
+  const started = Date.now();
+  const tick = () => {
+    const seconds = Math.floor((Date.now() - started) / 1000);
+    clock.textContent = `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`;
+  };
+  tick();
+  window.setInterval(tick, 1000);
+  const hash = /^#slide-(\d+)$/.exec(location.hash);
+  const index = hash ? deck.frames.findIndex((frame) => frame.number === Number(hash[1])) : 0;
+  deck.index = -1;
+  go(deck, Math.max(0, index), 1, { broadcast: false });
+  rescaleCurrent(deck);
+}
+
+function baseOf(): string {
+  return document.querySelector<HTMLElement>('[data-explico-card-config]')?.dataset.base ?? '/';
+}
+
+// --- the study page: the reader's record ------------------------------------------
+
+/** A frame's state on the study page: shown as it is now, not shown yet, or changed since it was. */
+type FrameState = 'shown' | FrameMark;
+
+/** What a frame's line says for its state; the frame is described by it. */
+const STATE_TEXT: Record<FrameState, string> = {
+  shown: 'Shown',
+  unseen: 'Not shown yet',
+  changed: 'Changed since shown',
+};
+
+/** The reader's record of this deck, as the study page shows it. */
+interface Reading {
+  /** Each frame's state, by index: none while the frames shown are not kept, nor where the course marks nothing. */
+  readonly states: readonly (FrameState | undefined)[];
+  readonly kept: boolean;
+  /** How many frames the record holds as shown. */
+  readonly seen: number;
+  readonly resume?: Resume;
+  /** The frame "Continue here" is on, by index: -1 for none, at the first frame and for "Present again". */
+  readonly continueAt: number;
+}
+
+/**
+ * The record as the study page shows it. A frame is "Shown" once Present
+ * mode showed it as it is now, while the course marks a frame not shown yet;
+ * "Not shown yet" and "Changed since shown" are the sidebar's two marks
+ * (`sidebarMarks`), each only while the course has it on. Nothing is marked
+ * while the frames shown are not kept (`keepsShown`). Where to continue
+ * (`resumeAt`) is kept in either case.
+ */
+function readReading(deck: Deck): Reading {
+  const kept = keepsShown(deck);
+  const record = readMemory().get(deck.slug);
+  const states = deck.frames.map((frame): FrameState | undefined => {
+    if (!kept || frame.id === '') return undefined;
+    const mark = frameMark(idOf(frame), record);
+    if (mark === undefined) return deck.marks.has('unseen') ? 'shown' : undefined;
+    return deck.marks.has(mark) ? mark : undefined;
+  });
+  const resume = resumeAt(record, deck.frames.map(stepsOf));
+  const index = resume && !resume.again ? deck.frames.findIndex((frame) => frame.number === resume.number) : -1;
+  return {
+    states,
+    kept,
+    seen: kept ? (record?.seen.size ?? 0) : 0,
+    ...(resume ? { resume } : {}),
+    continueAt: index > 0 ? index : -1,
+  };
+}
+
+/**
+ * "Continue at slide 7": a button beside Present that presents from the frame
+ * to continue at (`resumeAt`), or "Present again", from the first frame, once
+ * the reader was shown all of the last. Run as the page opens and again
+ * whenever Present mode ends, so it names the latest place, whatever slide the
+ * address names. None before a reader has presented, while the place is the
+ * first frame, nor for a frame the deck no longer has. It is the reader's own
+ * (`data-explico-export-chrome`): a downloaded deck never carries it.
+ */
+function refreshResume(deck: Deck, reading: Reading): void {
+  const actions = document.querySelector<HTMLElement>('[data-deck-actions]');
+  if (!actions) return;
+  const { resume, continueAt } = reading;
+  let button = actions.querySelector<HTMLButtonElement>('[data-deck-resume]');
+  if (!resume || (!resume.again && continueAt < 0)) {
+    button?.remove();
+    return;
+  }
+  if (!button) {
+    const created = document.createElement('button');
+    created.type = 'button';
+    created.className = 'deck-actions__resume';
+    created.dataset.deckResume = '';
+    created.dataset.explicoExportChrome = 'deck-resume';
+    created.addEventListener('click', () => present(deck, Number(created.dataset.deckResume) || 0));
+    const presentButton = actions.querySelector('[data-deck-present]');
+    if (presentButton) presentButton.after(created);
+    else actions.prepend(created);
+    button = created;
+  }
+  button.dataset.deckResume = String(resume.again ? 0 : continueAt);
+  button.textContent = resume.again ? 'Present again' : `Continue at slide ${resume.number}`;
+}
+
+const MARKS: readonly FrameMark[] = ['unseen', 'changed'];
+
+function countText(mark: FrameMark, count: number): string {
+  const slides = `${count} ${count === 1 ? 'slide' : 'slides'}`;
+  return mark === 'unseen' ? `${slides} not shown yet` : `${slides} changed since shown`;
+}
+
+/** A button out of use keeps its place and its focus, so it is `aria-disabled`, not `disabled`, as the sidebar's are. */
+function setUsable(button: HTMLButtonElement | null, usable: boolean): void {
+  if (usable) button?.removeAttribute('aria-disabled');
+  else button?.setAttribute('aria-disabled', 'true');
+}
+
+/**
+ * The marks' line, last in the actions row: how many frames carry each mark,
+ * "Mark all as seen" and "Mark all as unseen" for this deck, and a status
+ * line that says what a button did. The buttons keep their place, so focus
+ * stays where it was.
+ */
+function buildMarksLine(deck: Deck, actions: HTMLElement): HTMLElement {
+  const line = document.createElement('div');
+  line.className = 'deck-actions__marks';
+  line.dataset.deckMarksLine = '';
+  line.dataset.explicoExportChrome = 'deck-marks';
+  for (const mark of MARKS) {
+    const count = document.createElement('span');
+    count.className = 'deck-actions__mark';
+    count.dataset.frameMark = mark;
+    count.hidden = true;
+    line.append(count);
+  }
+  const buttons = document.createElement('span');
+  buttons.className = 'deck-actions__mark-buttons';
+  // There from the start, empty, so a screen reader hears what it gains.
+  const status = document.createElement('p');
+  status.className = 'deck-actions__marks-status';
+  status.setAttribute('role', 'status');
+  for (const [action, label, done] of [
+    ['seen', 'Mark all as seen', 'Every slide is marked as seen.'],
+    ['unseen', 'Mark all as unseen', 'Every slide is marked as not shown yet.'],
+  ] as const) {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'deck-actions__mark-button';
+    button.dataset.deckMarksAction = action;
+    button.textContent = label;
+    button.addEventListener('click', () => {
+      if (button.getAttribute('aria-disabled') === 'true') return;
+      changeMemory((memory) =>
+        action === 'seen'
+          ? withAllSeen(memory, deck.slug, deck.frames.flatMap((frame) => (frame.id === '' ? [] : [idOf(frame)])))
+          : withNoneSeen(memory, deck.slug),
+      );
+      status.textContent = done;
+    });
+    buttons.append(button);
+  }
+  line.append(buttons, status);
+  actions.append(line);
+  return line;
+}
+
+/**
+ * The marks' summary under the title (D8): each frame's mark on the frame
+ * itself (`data-frame-mark`), and the line that counts them, while the
+ * frames shown are kept (`keepsShown`). After a no, and in a course that
+ * marks nothing, no mark and no line.
+ */
+function showMarks(deck: Deck, reading: Reading): void {
+  const counts: Record<FrameMark, number> = { unseen: 0, changed: 0 };
+  deck.frames.forEach((frame, index) => {
+    const state = reading.states[index];
+    if (state === 'unseen' || state === 'changed') {
+      frame.element.dataset.frameMark = state;
+      counts[state] += 1;
+    } else if (frame.element.dataset.frameMark !== undefined) {
+      delete frame.element.dataset.frameMark;
+    }
+  });
+  const actions = document.querySelector<HTMLElement>('[data-deck-actions]');
+  if (!actions) return;
+  let line = actions.querySelector<HTMLElement>('[data-deck-marks-line]');
+  if (!reading.kept) {
+    line?.remove();
+    return;
+  }
+  line ??= buildMarksLine(deck, actions);
+  for (const mark of MARKS) {
+    const count = line.querySelector<HTMLElement>(`.deck-actions__mark[data-frame-mark="${mark}"]`);
+    if (!count) continue;
+    count.hidden = counts[mark] === 0;
+    count.textContent = countText(mark, counts[mark]);
+  }
+  setUsable(line.querySelector('[data-deck-marks-action="seen"]'), counts.unseen + counts.changed > 0);
+  setUsable(line.querySelector('[data-deck-marks-action="unseen"]'), reading.seen > 0);
+}
+
+// --- the study page: each frame's line ---------------------------------------------
+
+const PLAY_GLYPH =
+  '<svg viewBox="0 0 24 24" width="12" height="12" aria-hidden="true"><path d="M7 4l13 8-13 8z" fill="currentColor"/></svg>';
+
+/**
+ * A line above each frame (Q1), outside its canvas, in the page's own type
+ * whatever the frame's scale: "Slide 5", the frame's state, and a button
+ * that presents from the frame (Q2) — "Continue here", filled and always
+ * shown, on the frame to continue at; "Present from here" on every other,
+ * shown while the pointer is on the frame or focus is in it, the frame
+ * ringed then, and always where there is no hover, as its glyph alone
+ * (`deck.css`). A real button in the tab order, whose name says which frame.
+ * Present mode never shows the line, and print and a downloaded deck never
+ * carry it.
+ */
+function installLines(deck: Deck): void {
+  deck.root.dataset.deckLines = '';
+  deck.frames.forEach((frame, index) => {
+    const line = document.createElement('div');
+    line.className = 'deck-frame__line not-content';
+    line.dataset.explicoExportChrome = 'deck-frame-line';
+    const name = document.createElement('span');
+    name.className = 'deck-frame__name';
+    name.textContent = `Slide ${frame.number}`;
+    const state = document.createElement('span');
+    state.className = 'deck-frame__state';
+    state.id = `explico-deck-state-${frame.number}`;
+    state.hidden = true;
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'deck-frame__present';
+    button.dataset.deckPresentFrom = String(frame.number);
+    button.innerHTML = PLAY_GLYPH;
+    const label = document.createElement('span');
+    label.className = 'deck-frame__present-label';
+    button.append(label);
+    button.addEventListener('click', () => present(deck, index));
+    line.append(name, state, button);
+    frame.element.prepend(line);
+    deck.lines.push({ state, button, label });
+  });
+}
+
+/** Each frame's line for `reading`: its state, which also describes the frame, and its button. */
+function showLines(deck: Deck, reading: Reading): void {
+  deck.frames.forEach((frame, index) => {
+    const line = deck.lines[index];
+    if (!line) return;
+    const state = reading.states[index];
+    line.state.hidden = state === undefined;
+    line.state.textContent = state === undefined ? '' : STATE_TEXT[state];
+    if (state === undefined) {
+      delete line.state.dataset.frameState;
+      frame.element.removeAttribute('aria-describedby');
+    } else {
+      line.state.dataset.frameState = state;
+      frame.element.setAttribute('aria-describedby', line.state.id);
+    }
+    const here = index === reading.continueAt;
+    frame.element.toggleAttribute('data-deck-continue', here);
+    const text = here ? 'Continue here' : 'Present from here';
+    line.label.textContent = text;
+    // Its name starts with what it shows (WCAG 2.5.3), then says which frame.
+    line.button.setAttribute('aria-label', `${text}, slide ${frame.number}`);
+  });
+}
+
+// --- the study page: the slide map ------------------------------------------------
+
+/**
+ * The slide map (Q1): every frame as a numbered square under the deck's
+ * title, a link to it on the page, pinned under the header while the deck
+ * scrolls. A square is filled once its frame was shown, outlined before, and
+ * dotted when it changed since; the frame to continue at is ringed and the
+ * one in view underlined. A deck too long for the map's line keeps its ends,
+ * the frames around the one to continue at and around the one in view
+ * (`deck-map.ts`); each gap is a link to the frame in its middle.
+ */
+function installMap(deck: Deck): void {
+  if (deck.frames.length < 2) return;
+  const nav = document.createElement('nav');
+  nav.className = 'deck-map not-content';
+  nav.dataset.explicoExportChrome = 'deck-map';
+  const label = document.createElement('span');
+  label.className = 'deck-map__label';
+  label.id = `explico-deck-map-${deck.slug.replace(/[^a-z0-9-]/giu, '-')}`;
+  label.textContent = 'Slides';
+  nav.setAttribute('aria-labelledby', label.id);
+  const list = document.createElement('ol');
+  list.className = 'deck-map__list';
+  nav.append(label, list);
+  deck.root.prepend(nav);
+  deck.root.dataset.deckMap = '';
+  const map: SlideMap = { nav, list, places: new Map(), current: 0 };
+  deck.map = map;
+  let pending = 0;
+  const follow = () => {
+    pending = 0;
+    if (deck.presenting) return;
+    // Pinned: the deck's top has gone up under the header, and the map stays.
+    nav.toggleAttribute('data-stuck', deck.root.getBoundingClientRect().top < nav.getBoundingClientRect().top - 1);
+    const current = frameAtLine(deck, nav);
+    showChapter(deck, current);
+    if (current === map.current) return;
+    map.current = current;
+    drawMap(deck);
+  };
+  map.current = frameAtLine(deck, nav);
+  showChapter(deck, map.current);
+  window.addEventListener('scroll', () => (pending ||= window.requestAnimationFrame(follow)), { passive: true });
+  if (typeof ResizeObserver === 'function') {
+    let width = 0;
+    new ResizeObserver(() => {
+      if (deck.root.clientWidth === width) return;
+      width = deck.root.clientWidth;
+      drawMap(deck);
+    }).observe(deck.root);
+  }
+}
+
+/**
+ * The frame in view, by index: the last whose top is above the reading line,
+ * a third of the way down the window below the map.
+ */
+function frameAtLine(deck: Deck, nav: HTMLElement): number {
+  const top = Math.max(0, nav.getBoundingClientRect().bottom);
+  const line = top + (window.innerHeight - top) / 3;
+  let at = 0;
+  for (const [index, frame] of deck.frames.entries()) {
+    if (frame.element.getBoundingClientRect().top > line) break;
+    at = index;
+  }
+  return at;
+}
+
+function slidePlace(number: number): HTMLLIElement {
+  const place = document.createElement('li');
+  const link = document.createElement('a');
+  link.className = 'deck-map__slide';
+  link.href = `#slide-${number}`;
+  link.textContent = String(number);
+  place.append(link);
+  return place;
+}
+
+function gapPlace(from: number, to: number): HTMLLIElement {
+  const place = document.createElement('li');
+  place.className = 'deck-map__gap';
+  const link = document.createElement('a');
+  link.href = `#slide-${Math.round((from + to) / 2)}`;
+  link.textContent = '…';
+  link.title = `Slides ${from}–${to}`;
+  link.setAttribute('aria-label', `Slides ${from} to ${to}`);
+  place.append(link);
+  return place;
+}
+
+/** Put `items` in the map's list, each place kept from the drawing before when it was there, and mark each square. */
+function placeItems(map: SlideMap, items: readonly SlideMapItem[], reading: Reading): void {
+  const keys = items.map((item) => (item.kind === 'slide' ? `slide-${item.number}` : `gap-${item.from}-${item.to}`));
+  const nodes = items.map((item, index) => {
+    const key = keys[index]!;
+    let place = map.places.get(key);
+    if (!place) {
+      place = item.kind === 'slide' ? slidePlace(item.number) : gapPlace(item.from, item.to);
+      map.places.set(key, place);
+    }
+    return place;
+  });
+  const children = map.list.children;
+  if (children.length !== nodes.length || nodes.some((node, index) => children[index] !== node)) {
+    map.list.replaceChildren(...nodes);
+  }
+  const wanted = new Set(keys);
+  for (const key of [...map.places.keys()]) if (!wanted.has(key)) map.places.delete(key);
+  items.forEach((item, position) => {
+    if (item.kind !== 'slide') return;
+    const link = nodes[position]!.firstElementChild as HTMLAnchorElement;
+    const index = item.number - 1;
+    const state = reading.states[index];
+    const here = index === reading.continueAt;
+    if (state === undefined) delete link.dataset.frameState;
+    else link.dataset.frameState = state;
+    link.toggleAttribute('data-deck-continue', here);
+    if (index === map.current) link.setAttribute('aria-current', 'true');
+    else link.removeAttribute('aria-current');
+    const name = [`Slide ${item.number}`, state === undefined ? '' : STATE_TEXT[state].toLowerCase(), here ? 'continue here' : '']
+      .filter(Boolean)
+      .join(', ');
+    link.setAttribute('aria-label', name);
+  });
+}
+
+/**
+ * How many squares the map's line has room for: the deck's width, less the
+ * map's padding and its label, in squares as wide as the widest number's.
+ * A gap is narrower than a square, so the count errs short.
+ */
+function mapRoom(deck: Deck, map: SlideMap): number {
+  const navStyle = getComputedStyle(map.nav);
+  const label = map.nav.querySelector<HTMLElement>('.deck-map__label');
+  const beside = label && getComputedStyle(label).position !== 'absolute' ? label.offsetWidth + (Number.parseFloat(navStyle.columnGap) || 0) : 0;
+  const width = deck.root.clientWidth - (Number.parseFloat(navStyle.paddingInlineStart) || 0) - (Number.parseFloat(navStyle.paddingInlineEnd) || 0) - beside;
+  const probe = slidePlace(deck.frames.length);
+  probe.style.position = 'absolute';
+  probe.style.visibility = 'hidden';
+  map.list.append(probe);
+  const square = probe.getBoundingClientRect().width;
+  probe.remove();
+  const gap = Number.parseFloat(getComputedStyle(map.list).columnGap) || 0;
+  return square > 0 ? Math.floor((width + gap) / (square + gap)) : deck.frames.length;
+}
+
+/**
+ * Draw the map for the record as the page shows it and the frame in view:
+ * as much of the deck as its line has room for (`slideMap`), one place fewer
+ * while it still runs over, and wrapped past the least a shortened map
+ * keeps. Focus stays on the square it was on; the frames keep their tops
+ * clear of the pinned map (`--deck-map-height`, `deck.css`).
+ */
+function drawMap(deck: Deck): void {
+  const map = deck.map;
+  const reading = deck.reading;
+  if (!map || !reading) return;
+  const unseen = reading.states.indexOf('unseen');
+  const anchor = reading.continueAt >= 0 ? reading.continueAt : unseen;
+  const focus = { ...(anchor >= 0 ? { anchor: anchor + 1 } : {}), current: map.current + 1 };
+  const active = document.activeElement;
+  map.list.removeAttribute('data-wrap');
+  let room = mapRoom(deck, map);
+  for (;;) {
+    const items = slideMap(deck.frames.length, focus, room);
+    placeItems(map, items, reading);
+    if (map.list.scrollWidth <= map.list.clientWidth + 1) break;
+    // Fewer places, until the least a shortened map keeps.
+    if (room >= items.length && items.length > 1) {
+      room = items.length - 1;
+      continue;
+    }
+    map.list.setAttribute('data-wrap', '');
+    break;
+  }
+  if (active instanceof HTMLElement && active !== document.activeElement && map.list.contains(active)) {
+    active.focus({ preventScroll: true });
+  }
+  deck.root.style.setProperty('--deck-map-height', `${map.nav.offsetHeight}px`);
+}
+
+export function installDeck(root: HTMLElement): void {
+  const style = getComputedStyle(root);
+  const frames = [...root.querySelectorAll<HTMLElement>(':scope > .deck-frame')].map((element) => ({
+    element,
+    number: Number(element.dataset.frame) || 0,
+    id: /^[0-9a-f]{12}$/u.test(element.dataset.frameId ?? '') ? (element.dataset.frameId as string) : '',
+    chapter: element.dataset.chapter ?? '',
+    steps: Math.max(1, Number(element.dataset.steps) || 1),
+    stage: element.querySelector<HTMLElement>(':scope > .deck-stage'),
+  }));
+  for (const frame of frames) {
+    frame.element.tabIndex = -1;
+    // A lab's tools are the frame's: always open beside its picture (rule D7).
+    for (const fold of frame.element.querySelectorAll<HTMLDetailsElement>('details.keyed-figure__tools-fold')) {
+      fold.open = true;
+    }
+  }
+  const presenterWindow = new URLSearchParams(location.search).has('presenter');
+  const marks = document.querySelector<HTMLElement>('[data-deck-actions]')?.dataset.deckMarks ?? '';
+  const deck: Deck = {
+    root,
+    slug: root.dataset.deck ?? location.pathname,
+    frames,
+    canvasWidth: pixels(style.getPropertyValue('--deck-canvas-width'), 1280),
+    canvasHeight: pixels(style.getPropertyValue('--deck-canvas-height'), 720),
+    marks: new Set(MARKS.filter((mark) => marks.split(/\s+/u).includes(mark))),
+    chrome: !presenterWindow && !document.documentElement.hasAttribute('data-explico-standalone'),
+    lines: [],
+    index: 0,
+    step: 1,
+    presenting: false,
+    presenter: false,
+  };
+  installScaling(deck);
+  // Measured once the fonts are in, and again whenever a figure changes size
+  // (a lab hydrating, a plot redrawn): the build's own check calls the same
+  // measure (`compiler/exports/deck-fit.ts`).
+  let refit: number | undefined;
+  const measure = () => {
+    window.cancelAnimationFrame(refit ?? 0);
+    if (root.dataset.deckStatic !== undefined) return;
+    refit = window.requestAnimationFrame(() => overflowingFrames(root));
+  };
+  // The export's figure capture (`markdown` mode) draws each figure at its own
+  // size: no canvas scale and no fitting zoom (`data-deck-static`, deck.css).
+  // Print keeps the slides as they are.
+  window.addEventListener('explico:prepare-static-export', (event) => {
+    if ((event as CustomEvent<{ mode?: unknown }>).detail?.mode !== 'markdown') return;
+    if (deck.presenting) leave(deck);
+    root.dataset.deckStatic = '';
+    for (const part of root.querySelectorAll<HTMLElement>('.keyed-figure > *')) {
+      for (const property of ['zoom', 'max-width', 'margin-inline']) part.style.removeProperty(property);
+    }
+  });
+  window.addEventListener('explico:restore-static-export', () => {
+    if (root.dataset.deckStatic === undefined) return;
+    delete root.dataset.deckStatic;
+    measure();
+  });
+  void (document.fonts?.ready ?? Promise.resolve()).then(measure);
+  if (typeof ResizeObserver === 'function') {
+    const figures = new ResizeObserver(measure);
+    for (const figure of root.querySelectorAll('.deck-frame__body .keyed-figure, .deck-frame__body .keyed-table, .deck-frame__body .diagram')) {
+      figures.observe(figure);
+    }
+  }
+  (window as Window & { explicoDeckOverflow?: () => number[] }).explicoDeckOverflow = () => overflowingFrames(root);
+  installHud(deck);
+  installKeys(deck);
+  installTouch(deck);
+  installHoverSpotlight(deck);
+  if (typeof BroadcastChannel === 'function') {
+    deck.channel = new BroadcastChannel(`explico-deck:${deck.slug}`);
+    deck.channel.addEventListener('message', (event: MessageEvent<{ type?: string; index?: number; step?: number }>) => {
+      if (event.data?.type !== 'go' || (!deck.presenting && !deck.presenter)) return;
+      go(deck, Number(event.data.index), Number(event.data.step), { broadcast: false });
+    });
+  }
+  for (const button of document.querySelectorAll<HTMLElement>('[data-deck-present]')) {
+    button.addEventListener('click', () => present(deck));
+  }
+  document.addEventListener('fullscreenchange', () => rescaleCurrent(deck));
+  if (presenterWindow) {
+    installPresenterWindow(deck);
+    return;
+  }
+  if (!deck.chrome) return;
+  installLines(deck);
+  installMap(deck);
+  // A deck too short for a map: its first frame, the title, has no chapter.
+  if (!deck.map) showChapter(deck, 0);
+  // The record and the answer, read again whenever either changes: on this
+  // page (Present mode ended, a mark action here or in the sidebar, the
+  // reading-memory question answered) or in another tab.
+  const refresh = () => {
+    const reading = readReading(deck);
+    deck.reading = reading;
+    refreshResume(deck, reading);
+    showMarks(deck, reading);
+    showLines(deck, reading);
+    drawMap(deck);
+  };
+  window.addEventListener(DECK_MEMORY_EVENT, refresh);
+  window.addEventListener(READING_MEMORY_EVENT, refresh);
+  window.addEventListener('storage', (event) => {
+    if (event.key === null || event.key === deckPositionsKey(baseOf()) || event.key === answerKey(baseOf())) refresh();
+  });
+  refresh();
+}
+
+export function installDecks(): void {
+  for (const root of document.querySelectorAll<HTMLElement>('.deck[data-deck]')) installDeck(root);
+}