explico 0.8.0 → 0.11.1

package/src/components/card-manager.ts

@@ -0,0 +1,1589 @@
+/**
+ * One interaction model for every explanation card (rules C1–C15 of
+ * `docs/plans/hover-card-consistency.md`): notation symbols and terms,
+ * citations, abbreviations, and references to equations, tables, figures,
+ * diagrams and sections.
+ *
+ * Each layer registers a `CardSource` — how to find its triggers, how to
+ * name the item a trigger points at, how to build a card — and this module
+ * runs the rest once, for all of them:
+ *
+ * - one card per key (`notation:motion.velocity`, `citation:3`), several at
+ *   once in every layer;
+ * - hover or keyboard focus opens a card; a click on any trigger toggles its
+ *   pin and never navigates; a click inside a card or elsewhere never closes
+ *   a pinned one;
+ * - the travel zone (`./card-travel.ts`) keeps a hovered card reachable;
+ * - opening a card closes the hovered cards outside its hover chain, and a
+ *   card opened from inside another is its child, across layers;
+ * - Escape closes one card per press, newest first;
+ * - placement (`./card-placement.ts`) puts every card against every other;
+ * - a kept card can move to the side column, level with its trigger's line,
+ *   and the article slides left to make room for it (`./card-side.ts`);
+ * - an arrow runs from a kept card to the occurrence of its item the reader
+ *   points at (`./card-arrow.ts`);
+ * - a card's grip drags it anywhere between the sidebars, or into the side
+ *   column, and its arrow keys move it (`./card-drag.ts`);
+ * - the kept cards are remembered when the page is left and come back when
+ *   the reader does, even after a browser restart (`./card-memory.ts`).
+ *
+ * The registry's rules are pure functions over plain `CardState` records
+ * (`escapeTarget`, `chainOf`, `closedByOpening`, …) so `tests/unit/` can check
+ * them in Node. Nothing here touches the DOM until a source registers.
+ */
+import { createArrowOverlay, type ArrowOverlay } from './card-arrow';
+import {
+  dragBounds,
+  installCardDrag,
+  keepBetween,
+  movedAt,
+  movedSpot,
+  nudgeSpot,
+  sidebarsBetween,
+  type CardDrag,
+  type DragHost,
+  type MovedSpot,
+} from './card-drag';
+import {
+  keyOf,
+  readRememberedCards,
+  restorable,
+  writeRememberedCards,
+  type RememberedCard,
+} from './card-memory';
+import {
+  anchoredSpot,
+  articleColumn,
+  cardLayer,
+  moveTo,
+  placeElement,
+  reanchorElement,
+  scrollContainersOf,
+  watchCardLayout,
+  type CardAnchor,
+  type SideSpot,
+} from './card-placement';
+import {
+  articleContainers,
+  articleLeft,
+  columnLeft,
+  createKeepLeftToggle,
+  headerBottom,
+  layoutColumn,
+  lineTopOf,
+  measureSide,
+  readKeepLeft,
+  remToPx,
+  roomAt,
+  sideColumn,
+  slideArticle,
+  writeKeepLeft,
+  type ColumnEntry,
+  type KeepLeftToggle,
+  type SideColumn,
+  type SideMeasure,
+  type SideOptions,
+} from './card-side';
+import { startTrip, type Box, type Point, type Trip } from './card-travel';
+
+/**
+ * Every tunable number of the card system, in one place (the Constants
+ * table of the plan, which records the values tuned in Part 3).
+ */
+export const CARD_CONSTANTS = {
+  /** P2: the gap between a card and its safe region, and between cards side by side (px). */
+  gap: 10,
+  /** P2: the room a card keeps from the window edge (px). */
+  edge: 12,
+  /** P2: a card squeezed to fit its side is never shorter than this (px). */
+  cardMinHeight: 120,
+  /** P2 step 6: the offset of a card placed over the card in its way (px). */
+  overlapOffset: 24,
+  /** P5: notation, citation and abbreviation cards. */
+  cardWidth: '23rem',
+  /** P5: the widest a reference card grows before its content scrolls. */
+  referenceMaxWidth: '80ch',
+  /** C2: how long the pointer may stay outside the travel zone (ms). */
+  travelGraceMs: 250,
+  /** C2: resting this long on a held-back trigger switches to it (ms). */
+  travelRestMs: 450,
+  /** C2: the longest one trip may last (ms). */
+  travelTripMaxMs: 2500,
+  /** C8: how long a kept card flashes (ms). */
+  flashMs: 500,
+  /** S1: the side column's gaps to the article and to the rail (px). */
+  sideGap: 16,
+  /** S1: the side card's narrowest and widest. */
+  sideWidthMin: '18rem',
+  sideWidthMax: '23rem',
+  /** S2: a side card's top sits this far above its trigger's line (px). */
+  sideLineOffset: 14,
+  /** S8: a side card is at most the window height, less the header and this (px). */
+  sideHeightMargin: 24,
+  /** S4: moving into or out of the side, and the article's slide (ms). */
+  animationMs: 100,
+  /** S5: how long the arrow stays after the pointer leaves (ms). */
+  arrowFadeMs: 1500,
+  /** D1: movement before a drag starts (px). */
+  dragThreshold: 4,
+  /** D3, D4: snapping into the side column, and letting go again (px). */
+  snapDistance: 32,
+  snapRelease: 48,
+  /** D5: a drop this close to the anchored spot returns the card (px). */
+  snapHome: 32,
+  /** D6: one arrow-key move, and one with Shift (px). */
+  keyboardStep: 8,
+  keyboardStepLarge: 48,
+} as const;
+
+// ---------------------------------------------------------------------------
+// The registry, as pure state.
+// ---------------------------------------------------------------------------
+
+/**
+ * Hover: follows the pointer. Pinned: kept next to its trigger. Side: kept in
+ * the side column, level with its trigger's line. Moved: kept where the
+ * reader dragged it, against the article column and its trigger's line.
+ */
+export type CardMode = 'hover' | 'pinned' | 'side' | 'moved';
+
+/** A kept card stays open on its own; only a hovered one depends on the pointer. */
+export const isKept = (mode: CardMode): boolean => mode !== 'hover';
+
+export interface CardState {
+  readonly key: string;
+  /** The card whose content holds this card's trigger (C9), if any. */
+  readonly parentKey: string | null;
+  readonly mode: CardMode;
+  /** When the card first opened. Pinning never changes it (C10). */
+  readonly order: number;
+}
+
+export type CardStates = ReadonlyMap<string, CardState>;
+
+const byOrder = (a: CardState, b: CardState) => a.order - b.order;
+
+/** The card Escape closes: the newest, whatever its layer or mode (C10). */
+export function escapeTarget(cards: CardStates): string | null {
+  let newest: CardState | null = null;
+  for (const card of cards.values()) {
+    if (!newest || card.order > newest.order) newest = card;
+  }
+  return newest?.key ?? null;
+}
+
+/** A card and its ancestors: the hover chain a card opened from inside `key` belongs to (C7). */
+export function chainOf(cards: CardStates, key: string | null): Set<string> {
+  const chain = new Set<string>();
+  for (let at = key; at && cards.has(at) && !chain.has(at); ) {
+    chain.add(at);
+    at = cards.get(at)?.parentKey ?? null;
+  }
+  return chain;
+}
+
+/** The cards opened from inside `key`, directly or further down, parents before children. */
+export function descendantsOf(cards: CardStates, key: string): string[] {
+  const found: string[] = [];
+  const seen = new Set<string>([key]);
+  for (let index = -1; index < found.length; index++) {
+    const parent = index === -1 ? key : found[index];
+    for (const card of [...cards.values()].sort(byOrder)) {
+      if (card.parentKey === parent && !seen.has(card.key)) {
+        seen.add(card.key);
+        found.push(card.key);
+      }
+    }
+  }
+  return found;
+}
+
+/** A card and everything opened from inside it, in the order they close: children first (C9). */
+export function closingOrder(cards: CardStates, key: string): string[] {
+  if (!cards.has(key)) return [];
+  return [...descendantsOf(cards, key).reverse(), key];
+}
+
+/** Whether a card has a child, which keeps it open (C9). */
+export function hasChild(cards: CardStates, key: string): boolean {
+  for (const card of cards.values()) if (card.parentKey === key) return true;
+  return false;
+}
+
+/**
+ * Whether only the pointer keeps a card open: it is hovered, and no card
+ * opened from inside it is kept — a pinned child keeps its parent (C9).
+ */
+export function isTransient(cards: CardStates, key: string): boolean {
+  const card = cards.get(key);
+  if (!card || isKept(card.mode)) return false;
+  return descendantsOf(cards, key).every((child) => {
+    const mode = cards.get(child)?.mode;
+    return !mode || !isKept(mode);
+  });
+}
+
+/**
+ * The cards that close when a card opens from inside `hostKey` (`null`: from
+ * the page): every transient card outside the host's chain, newest first
+ * (C7). A kept card never closes because another opened.
+ */
+export function closedByOpening(cards: CardStates, hostKey: string | null): string[] {
+  const chain = chainOf(cards, hostKey);
+  return [...cards.values()]
+    .filter((card) => !chain.has(card.key) && isTransient(cards, card.key))
+    .sort((a, b) => b.order - a.order)
+    .map((card) => card.key);
+}
+
+// ---------------------------------------------------------------------------
+// Sources: what a layer tells the manager.
+// ---------------------------------------------------------------------------
+
+export interface CardSource {
+  /** The first half of every card key: `notation`, `citation`, … */
+  readonly layer: string;
+  /** The trigger an event target belongs to, including triggers inside open cards. */
+  triggerFrom(node: EventTarget | null): HTMLElement | null;
+  /** The item a trigger names (`motion.velocity`, `3`), or `null` to leave the trigger alone. */
+  itemFor(trigger: HTMLElement): string | null;
+  /**
+   * Whether a card may open for this trigger right now (default: yes). A
+   * trigger the source does not claim stays a plain link: the reference
+   * layer's highlight mode, and cross-page references in a standalone export.
+   */
+  claims?(trigger: HTMLElement): boolean;
+  /**
+   * A fresh, unattached card for `item` (see `cloneCardShell`), or `null`
+   * for an unknown item. A promise opens the card once it resolves, if the
+   * reader still wants it.
+   */
+  render(item: string, trigger: HTMLElement): HTMLElement | null | Promise<HTMLElement | null>;
+  /** After any of this layer's cards opens, closes or changes mode: the open items. */
+  onChange?(open: ReadonlyMap<string, CardMode>): void;
+}
+
+let shellSerial = 0;
+
+/**
+ * A fresh card element from a `HoverPanel.astro` template, with an id of its
+ * own. The header's Side, Pin and × buttons (`data-card-side`,
+ * `data-card-pin`, `data-card-close`) and its note (`data-card-note`) are the
+ * manager's; the layer fills everything else.
+ */
+export function cloneCardShell(template: HTMLTemplateElement): HTMLElement | null {
+  const shell = template.content.firstElementChild;
+  if (!(shell instanceof HTMLElement)) return null;
+  const el = document.importNode(shell, true);
+  if (template.id) el.id = `${template.id}-${++shellSerial}`;
+  return el;
+}
+
+// ---------------------------------------------------------------------------
+// The manager.
+// ---------------------------------------------------------------------------
+
+interface CardRecord extends CardState {
+  readonly key: string;
+  readonly item: string;
+  readonly source: CardSource;
+  readonly el: HTMLElement;
+  /** The occurrence the card is anchored to; a hovered card follows the pointer to another (C8). */
+  trigger: HTMLElement;
+  parentKey: string | null;
+  mode: CardMode;
+  readonly order: number;
+  /** Where the card goes next to its trigger (P2): its home, for Home and D5. */
+  anchor: CardAnchor | null;
+  /** D2: a Moved card's place, against the article column and its trigger's line. */
+  moved: MovedSpot | null;
+  /** D2: where a Moved card was just dropped (viewport); stored once the article has moved. */
+  dropAt: Point | null;
+  /** S2, D3: a docked card's top minus its trigger's line top; a drop sets its own. */
+  sideDy: number;
+  graceTimer: ReturnType<typeof setTimeout> | null;
+  flashTimer: ReturnType<typeof setTimeout> | null;
+  unwatch: () => void;
+}
+
+interface Hit {
+  readonly source: CardSource;
+  readonly trigger: HTMLElement;
+  readonly item: string;
+  readonly key: string;
+}
+
+/** A card waiting for its content (a fetched page). */
+interface PendingOpen {
+  hit: Hit;
+  mode: CardMode;
+  readonly token: number;
+}
+
+const LAYER_VARIABLES = {
+  '--explico-card-width': CARD_CONSTANTS.cardWidth,
+  '--explico-card-reference-max-width': CARD_CONSTANTS.referenceMaxWidth,
+  '--explico-card-flash': `${CARD_CONSTANTS.flashMs}ms`,
+  '--explico-card-motion': `${CARD_CONSTANTS.animationMs}ms`,
+};
+
+/** S7: the Side button's answer when the window has no side column. */
+const NO_ROOM_MESSAGE = 'Collapse a side panel to make room';
+
+const sources: CardSource[] = [];
+const cards = new Map<string, CardRecord>();
+const pending = new Map<string, PendingOpen>();
+let travel: { readonly card: CardRecord; readonly trip: Trip } | null = null;
+let layout: ReturnType<typeof watchCardLayout> | null = null;
+let opened = 0;
+let raised = 0;
+let pendingSerial = 0;
+/**
+ * The pointer's last position. A `pointerout` reports where the pointer has
+ * already arrived — often on the next trigger — so the trip's apex, the
+ * point where it left its trigger, is the last position before that.
+ */
+let lastPointer: Point | null = null;
+/** A trigger being given focus back as its card closes: focusing it must not reopen the card. */
+let refocusing: HTMLElement | null = null;
+/** S3: how far the article is slid left of where it rests now (px). */
+let slid = 0;
+/**
+ * S2: the docked card the reader pointed at last — docked, or re-aligned by
+ * a click on another occurrence. It keeps its ideal spot in every later
+ * layout, so a resize does not reshuffle the column.
+ */
+let pointedKey: string | null = null;
+/** S9: "Keep the article left", as the reader last set it. */
+let keepLeft = false;
+let keepLeftToggle: KeepLeftToggle | null = null;
+/** S5: the one arrow, from a kept card to an occurrence of its item. */
+let arrow: ArrowOverlay | null = null;
+/** S4: the animations moving cards and the article now. */
+const motion = new Set<Animation>();
+/** D1–D7: the grip's gesture, and the card being dragged with what it was before. */
+let drag: CardDrag | null = null;
+let dragged: {
+  readonly card: CardRecord;
+  readonly mode: CardMode;
+  readonly measure: SideMeasure | null;
+  readonly column: SideColumn | null;
+} | null = null;
+/** Cards this page had open when the reader last left it, not restored yet. */
+let remembered: RememberedCard[] = [];
+let rememberedPointed: string | null = null;
+/** A layout change that arrived while things were moving; handled once they stop. */
+let arrangeWhenStill = false;
+let arranging = false;
+let arrangeAgain = false;
+
+const noop = () => {};
+
+const isOpen = (card: CardRecord) => cards.get(card.key) === card;
+
+const ordered = () => [...cards.values()].sort(byOrder);
+
+function cardContaining(node: EventTarget | null): CardRecord | null {
+  const start =
+    node instanceof Element ? node : node instanceof Node ? node.parentElement : null;
+  const el = start?.closest<HTMLElement>('[data-card-key]');
+  const card = el?.dataset.cardKey ? cards.get(el.dataset.cardKey) : undefined;
+  return card && card.el === el ? card : null;
+}
+
+/** Whether `node` is inside `card` or inside a card opened from it. */
+function insideSubtree(card: CardRecord, node: Node): boolean {
+  if (card.el.contains(node)) return true;
+  return descendantsOf(cards, card.key).some((key) => cards.get(key)?.el.contains(node));
+}
+
+/** The innermost trigger of any layer at `node`. */
+function findTrigger(node: EventTarget | null): Hit | null {
+  let best: Hit | null = null;
+  for (const source of sources) {
+    const trigger = source.triggerFrom(node);
+    if (!trigger || (best && trigger.contains(best.trigger))) continue;
+    const item = source.itemFor(trigger);
+    if (item === null) continue;
+    const key = `${source.layer}:${item}`;
+    // A card's own item, pointed at from inside that card, is not a trigger.
+    if (cardContaining(trigger)?.key === key) continue;
+    best = { source, trigger, item, key };
+  }
+  return best;
+}
+
+/**
+ * Hovered, keyboard-focused, or kept open by a child (C9). Focus counts only
+ * as `:focus-visible`: the focus a mouse click leaves behind is not a reason
+ * to keep a card.
+ */
+function wanted(card: CardRecord): boolean {
+  const { trigger, el } = card;
+  return (
+    (trigger.isConnected &&
+      (trigger.matches(':hover') || trigger.matches(':focus-visible'))) ||
+    el.matches(':hover') ||
+    el.matches(':focus-visible') ||
+    el.querySelector(':focus-visible') !== null ||
+    hasChild(cards, card.key)
+  );
+}
+
+function notify(source: CardSource): void {
+  if (!source.onChange) return;
+  const open = new Map<string, CardMode>();
+  for (const card of ordered()) if (card.source === source) open.set(card.item, card.mode);
+  source.onChange(open);
+}
+
+function syncMode(card: CardRecord): void {
+  card.el.dataset.cardMode = card.mode;
+  for (const pin of card.el.querySelectorAll<HTMLElement>('[data-card-pin]')) {
+    pin.setAttribute('aria-pressed', String(card.mode === 'pinned'));
+  }
+  for (const side of card.el.querySelectorAll<HTMLElement>('[data-card-side]')) {
+    side.setAttribute('aria-pressed', String(card.mode === 'side'));
+  }
+  if (card.mode === 'side') showNote(card, null);
+}
+
+/** S7: a short message in the card's header, or none. */
+function showNote(card: CardRecord, text: string | null): void {
+  const note = card.el.querySelector<HTMLElement>('[data-card-note]');
+  if (!note) return;
+  note.textContent = text ?? '';
+  note.hidden = text === null;
+}
+
+function setMode(card: CardRecord, mode: CardMode): void {
+  if (card.mode === mode) return;
+  card.mode = mode;
+  if (mode !== 'moved') {
+    card.moved = null;
+    card.dropAt = null;
+  }
+  if (mode !== 'side') card.sideDy = -CARD_CONSTANTS.sideLineOffset;
+  if (isKept(mode)) {
+    cancelGrace(card);
+    if (travel?.card === card) endTravel();
+  } else if (arrow?.card === card.el) {
+    arrow.hide(); // S5: only a kept card has an arrow
+  }
+  syncMode(card);
+  notify(card.source);
+}
+
+/** P4: the card clicked, focused or opened last is on top. */
+function raise(card: CardRecord): void {
+  card.el.style.zIndex = String(++raised);
+}
+
+/** C8: an accent ring for a moment, to show where a kept card is. */
+function flash(card: CardRecord): void {
+  const { el } = card;
+  el.classList.remove('is-card-flashing');
+  void el.offsetWidth; // restart the animation
+  el.classList.add('is-card-flashing');
+  if (card.flashTimer !== null) clearTimeout(card.flashTimer);
+  card.flashTimer = setTimeout(() => {
+    card.flashTimer = null;
+    el.classList.remove('is-card-flashing');
+  }, CARD_CONSTANTS.flashMs);
+}
+
+function cancelGrace(card: CardRecord): void {
+  if (card.graceTimer !== null) clearTimeout(card.graceTimer);
+  card.graceTimer = null;
+}
+
+function closeUnlessWanted(card: CardRecord): void {
+  if (!isOpen(card) || card.mode !== 'hover' || travel?.card === card || wanted(card)) return;
+  close(card);
+}
+
+/** C2: close a hovered card after the grace, unless something wants it by then. */
+function graceCheck(card: CardRecord): void {
+  cancelGrace(card);
+  card.graceTimer = setTimeout(() => {
+    card.graceTimer = null;
+    closeUnlessWanted(card);
+  }, CARD_CONSTANTS.travelGraceMs);
+}
+
+function endTravel(): void {
+  travel?.trip.end();
+  travel = null;
+}
+
+/** C2: the pointer left `card`'s trigger at `apex`, heading somewhere. */
+function startTravel(card: CardRecord, apex: Point): void {
+  endTravel();
+  cancelGrace(card);
+  let handle: Trip | null = null;
+  const release = () => {
+    if (travel && travel.trip === handle) travel = null;
+  };
+  handle = startTrip(apex, {
+    graceMs: CARD_CONSTANTS.travelGraceMs,
+    restMs: CARD_CONSTANTS.travelRestMs,
+    tripMaxMs: CARD_CONSTANTS.travelTripMaxMs,
+    cardBox: () => (isOpen(card) ? card.el.getBoundingClientRect() : null),
+    triggerBox: () =>
+      card.trigger.isConnected ? card.trigger.getBoundingClientRect() : null,
+    onExit: () => {
+      release();
+      closeUnlessWanted(card);
+    },
+    onLand: () => {
+      release();
+      // Landing on the card's box normally means hovering it; the check
+      // only catches a card covered by another where it landed.
+      graceCheck(card);
+    },
+    onRest: (point) => restOn(card, point),
+  });
+  travel = handle.active ? { card, trip: handle } : null;
+}
+
+/** C2: the pointer rested in the zone; a held-back trigger under it takes over. */
+function restOn(card: CardRecord, point: Point): void {
+  const under = findTrigger(document.elementFromPoint(point.x, point.y));
+  if (!under || under.trigger === card.trigger || card.el.contains(under.trigger)) return;
+  endTravel();
+  if (isOpen(card) && card.mode === 'hover') close(card);
+  hoverOpen(under);
+}
+
+/** C2: a scroll or resize moves the zone out from under the pointer. */
+function interruptTravel(): void {
+  if (!travel) return;
+  const { card } = travel;
+  endTravel();
+  graceCheck(card);
+}
+
+function watch(card: CardRecord): void {
+  card.unwatch();
+  if (!layout) return;
+  const { schedule, observe, unobserve } = layout;
+  const containers = scrollContainersOf(card.trigger);
+  for (const container of containers) {
+    container.addEventListener('scroll', schedule, { passive: true });
+  }
+  observe(card.el);
+  card.unwatch = () => {
+    for (const container of containers) container.removeEventListener('scroll', schedule);
+    unobserve(card.el);
+  };
+}
+
+/** P2, P6: place `card` next to its trigger, clear of every other open card. */
+function place(card: CardRecord): void {
+  const others = ordered()
+    .filter((other) => other !== card)
+    .map((other) => other.el);
+  card.anchor = placeElement(card.el, card.trigger, others, {
+    gap: CARD_CONSTANTS.gap,
+    edge: CARD_CONSTANTS.edge,
+    overlapOffset: CARD_CONSTANTS.overlapOffset,
+    minHeight: CARD_CONSTANTS.cardMinHeight,
+    sideColumn: (width) => columnSpot(card, width),
+  });
+  watch(card);
+}
+
+const sideOptions = (): SideOptions => ({
+  gap: CARD_CONSTANTS.sideGap,
+  minWidth: remToPx(CARD_CONSTANTS.sideWidthMin),
+  maxWidth: remToPx(CARD_CONSTANTS.sideWidthMax),
+});
+
+/**
+ * P2 step 5: the side column at the trigger's line, when the window has one
+ * (S1, S7) with room for `width` where the article is now. A card placed
+ * here never slides the article: that would move its trigger out from under
+ * the pointer that opened it.
+ */
+function columnSpot(card: CardRecord, width: number): SideSpot | null {
+  const measure = measureSide();
+  if (!measure || !sideColumn(measure, sideOptions())) return null;
+  const line = lineTopOf(card.trigger);
+  const gap = CARD_CONSTANTS.sideGap;
+  if (line === null || roomAt(measure, slid, gap) < width - 0.5) return null;
+  return { left: columnLeft(measure, slid, gap), top: line - CARD_CONSTANTS.sideLineOffset };
+}
+
+/**
+ * D2: a Moved card at its place against the article column and its
+ * trigger's line, kept between the sidebars. A card just dropped is stored
+ * against where they are now, so a slide of the article that the drop set
+ * off leaves the card where the reader let go of it.
+ */
+function placeMoved(card: CardRecord): void {
+  const line = lineTopOf(card.trigger);
+  const column = articleColumn(card.trigger);
+  const { dropAt } = card;
+  card.dropAt = null;
+  if (line === null || !column) {
+    // The trigger has no box (a disclosure closed around it): the card stays.
+    if (dropAt && !card.moved) moveTo(card.el, dropAt.x, dropAt.y);
+    return;
+  }
+  if (dropAt) card.moved = movedSpot(dropAt, column.left, line);
+  if (!card.moved) return;
+  const at = movedAt(card.moved, column.left, line);
+  const { width } = card.el.getBoundingClientRect();
+  moveTo(card.el, keepBetween(at.x, width, sidebarsBetween(CARD_CONSTANTS.edge)), at.y);
+}
+
+/** P1: a card that is not docked goes back to its place after a layout change. */
+function reanchor(card: CardRecord, measure: SideMeasure | null): void {
+  if (card.mode === 'moved') {
+    placeMoved(card);
+    return;
+  }
+  const { anchor } = card;
+  if (!anchor) return;
+  if (anchor.column) {
+    // Placed in the side column (P2 step 5): it follows the column's edge and
+    // its trigger's line while the column has room for it.
+    const line = lineTopOf(card.trigger);
+    const gap = CARD_CONSTANTS.sideGap;
+    const { width } = card.el.getBoundingClientRect();
+    if (measure && line !== null && roomAt(measure, slid, gap) >= width - 0.5) {
+      moveTo(card.el, columnLeft(measure, slid, gap), line + anchor.dy);
+    } else if (line !== null) {
+      place(card);
+    } else if (!card.trigger.isConnected && card.mode === 'hover') {
+      close(card);
+    }
+    return;
+  }
+  const placed = reanchorElement(card.el, card.trigger, anchor, CARD_CONSTANTS.edge);
+  if (!placed && !card.trigger.isConnected && card.mode === 'hover') close(card);
+}
+
+/** S8: the tallest a docked card gets. */
+const sideMaxHeight = () =>
+  Math.max(
+    CARD_CONSTANTS.cardMinHeight,
+    window.innerHeight - headerBottom() - CARD_CONSTANTS.sideHeightMargin,
+  );
+
+/**
+ * S2: where each docked card goes, in page coordinates, with the article slid
+ * `slide` px; the card `first` gets its ideal spot first. `extra` is a card
+ * about to dock at a height of its own (D3's landing spot). The card being
+ * dragged is left out.
+ */
+function columnTops(
+  column: SideColumn,
+  slide: number,
+  first: string | null,
+  extra: ColumnEntry | null = null,
+): { left: number; docked: CardRecord[]; tops: Map<string, number>; origin: DOMRect } {
+  const skip = (card: CardRecord) => card === dragged?.card || card.key === extra?.key;
+  const docked = ordered().filter((card) => card.mode === 'side' && !skip(card));
+  const left = columnLeft(column, slide, CARD_CONSTANTS.sideGap);
+  const right = left + column.width;
+  // Page coordinates, so the layout does not depend on the scroll position.
+  const origin = cardLayer(LAYER_VARIABLES).getBoundingClientRect();
+  const entries: ColumnEntry[] = docked.map((card) => {
+    const rect = card.el.getBoundingClientRect();
+    const line = lineTopOf(card.trigger);
+    return {
+      key: card.key,
+      ideal: line === null ? null : line - origin.top + card.sideDy,
+      top: rect.top - origin.top,
+      height: rect.height,
+    };
+  });
+  if (extra) entries.push(extra);
+  // Any other card in the column's way stays where it is.
+  const obstacles = ordered()
+    .filter((card) => card.mode !== 'side' && !skip(card))
+    .map((card) => card.el.getBoundingClientRect())
+    .filter((rect) => rect.left < right && rect.right > left)
+    .map((rect) => ({ top: rect.top - origin.top, bottom: rect.bottom - origin.top }));
+  const tops = layoutColumn(entries, {
+    first,
+    gap: CARD_CONSTANTS.gap,
+    // Not under the fixed header at the top of the page.
+    minTop: headerBottom() + CARD_CONSTANTS.edge,
+    obstacles,
+  });
+  return { left, docked, tops, origin };
+}
+
+/**
+ * S1, S2, S8: the docked cards, at the column's edge and width, each level
+ * with its trigger's line (or at the height it was dropped at, D3); the card
+ * being pointed at first.
+ */
+function layoutDocked(column: SideColumn, first: CardRecord | null): void {
+  const docking = ordered().filter((card) => card.mode === 'side' && card !== dragged?.card);
+  if (docking.length === 0) return;
+  const maxHeight = sideMaxHeight();
+  for (const card of docking) card.el.style.maxHeight = `${maxHeight}px`;
+  if (first) pointedKey = first.key;
+  const { left, docked, tops, origin } = columnTops(column, slid, pointedKey);
+  for (const card of docked) {
+    moveTo(card.el, left, (tops.get(card.key) ?? 0) + origin.top);
+  }
+}
+
+interface Motion {
+  readonly cards: ReadonlyMap<CardRecord, DOMRect>;
+  readonly article: number | null;
+}
+
+/** S4: where everything is before a change that should animate; `null` under reduced motion. */
+function motionFrom(): Motion | null {
+  if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return null;
+  return {
+    cards: new Map(ordered().map((card) => [card, card.el.getBoundingClientRect()])),
+    article: articleLeft(),
+  };
+}
+
+function stopMotion(): void {
+  for (const animation of [...motion]) animation.cancel();
+  motion.clear();
+}
+
+/**
+ * S4: everything that moved slides from where it was to where it is now, in
+ * 100 ms. The layout is already final; only the picture catches up with it.
+ */
+function play(from: Motion): void {
+  const timing: KeyframeAnimationOptions = {
+    duration: CARD_CONSTANTS.animationMs,
+    easing: 'ease-out',
+  };
+  const run = (el: HTMLElement, transform: string) => {
+    const animation = el.animate([{ transform }, { transform: 'none' }], timing);
+    motion.add(animation);
+    const done = () => {
+      motion.delete(animation);
+      if (motion.size > 0) return;
+      if (arrangeWhenStill) {
+        arrangeWhenStill = false;
+        arrange();
+      } else {
+        arrow?.redraw();
+      }
+    };
+    animation.finished.then(done, done);
+  };
+  for (const [card, before] of from.cards) {
+    if (!isOpen(card)) continue;
+    const after = card.el.getBoundingClientRect();
+    const dx = before.left - after.left;
+    const dy = before.top - after.top;
+    if (Math.abs(dx) >= 0.5 || Math.abs(dy) >= 0.5) {
+      run(card.el, `translate(${dx}px, ${dy}px)`);
+    }
+  }
+  const now = articleLeft();
+  if (from.article !== null && now !== null && Math.abs(from.article - now) >= 0.5) {
+    for (const el of articleContainers()) run(el, `translateX(${from.article - now}px)`);
+  }
+}
+
+interface ArrangeOptions {
+  /** Where everything was before the change, when it should animate (S4). */
+  readonly from?: Motion | null;
+  /** The card being pointed at: in the side column it gets its ideal spot first (S2). */
+  readonly first?: CardRecord | null;
+  /** Cards to place afresh next to their triggers (P2), once the article has moved. */
+  readonly place?: readonly CardRecord[];
+}
+
+/**
+ * P1, S1–S3, S7, S9: after anything that moves cards — a card docking,
+ * leaving the side or closing, the reader's "Keep the article left", a
+ * layout change — slide the article as far as the side column needs, lay the
+ * docked cards out, and put every other card back beside its trigger.
+ */
+function arrange(options: ArrangeOptions = {}): void {
+  if (arranging) {
+    arrangeAgain = true;
+    return;
+  }
+  arranging = true;
+  try {
+    stopMotion();
+    const docked = ordered().filter((card) => card.mode === 'side');
+    const needed =
+      docked.length > 0 || keepLeft || ordered().some((card) => card.anchor?.column);
+    const measure = needed ? measureSide() : null;
+    const column = measure ? sideColumn(measure, sideOptions()) : null;
+    const fresh = new Set(options.place ?? []);
+    if (!column) {
+      // S7: the side column is gone — the window narrowed, a panel opened.
+      // Its cards go back next to their triggers, still kept.
+      for (const card of docked) {
+        if (card === dragged?.card) continue;
+        fresh.add(card);
+        setMode(card, 'pinned');
+      }
+    }
+    const docking = column ? docked.length : 0;
+    // S3, S9: only as far as the side cards need, or all the way while the
+    // reader keeps the article left.
+    slid = !column ? 0 : keepLeft ? column.maxSlide : docking > 0 ? column.slide : 0;
+    slideArticle(slid, column?.maxSlide ?? 0);
+    if (column) {
+      cardLayer(LAYER_VARIABLES).style.setProperty(
+        '--explico-card-side-width',
+        `${column.width}px`,
+      );
+    }
+    // The card being dragged goes where the pointer takes it, nowhere else.
+    for (const card of ordered()) {
+      if (card.mode !== 'side' && !fresh.has(card) && card !== dragged?.card) {
+        reanchor(card, measure);
+      }
+    }
+    if (column) layoutDocked(column, options.first ?? null);
+    for (const card of fresh) if (isOpen(card) && card !== dragged?.card) place(card);
+    keepLeftToggle?.update({
+      visible: !!column && (keepLeft || docking > 0),
+      on: keepLeft,
+      left: column ? columnLeft(column, slid, CARD_CONSTANTS.sideGap) : 0,
+    });
+    arrow?.redraw();
+    if (options.from) play(options.from);
+  } finally {
+    arranging = false;
+  }
+  if (arrangeAgain) {
+    arrangeAgain = false;
+    arrange();
+  }
+}
+
+/** P1: the layout changed. While cards or the article are moving, wait until they stop. */
+function reanchorAll(): void {
+  if (motion.size > 0) {
+    arrangeWhenStill = true;
+    return;
+  }
+  arrange();
+}
+
+/** S6, S7: the Side button — into the side column, or back next to the trigger. */
+function toggleSide(card: CardRecord): void {
+  const from = motionFrom();
+  if (card.mode === 'side') {
+    setMode(card, 'pinned');
+    arrange({ from, place: [card] });
+    return;
+  }
+  const measure = measureSide();
+  if (!measure || !sideColumn(measure, sideOptions())) {
+    showNote(card, NO_ROOM_MESSAGE);
+    return;
+  }
+  setMode(card, 'side');
+  raise(card);
+  arrange({ from, first: card });
+}
+
+/** S5: a docked or moved card can sit far from its trigger; pointing at it shows where it is. */
+const awayFromTrigger = (mode: CardMode | undefined): boolean =>
+  mode === 'side' || mode === 'moved';
+
+/** S5: the arrow from a kept card to an occurrence of its item. Not while the card is dragged. */
+function pointAt(card: CardRecord, target: HTMLElement): void {
+  if (!arrow || !isKept(card.mode) || dragged?.card === card) return;
+  arrow.show(card.el, target);
+}
+
+/** C8: move a card to another occurrence of its item. A docked card re-aligns to its line. */
+function reattach(card: CardRecord, trigger: HTMLElement): void {
+  card.trigger = trigger;
+  card.parentKey = cardContaining(trigger)?.key ?? null;
+  if (card.mode !== 'side') {
+    place(card);
+    return;
+  }
+  const from = motionFrom();
+  card.sideDy = -CARD_CONSTANTS.sideLineOffset;
+  watch(card);
+  arrange({ from, first: card });
+}
+
+/** D5, D6: back next to its trigger, Pinned, at the spot it was placed at. */
+function goHome(card: CardRecord): void {
+  const from = motionFrom();
+  setMode(card, 'pinned');
+  arrange({ from, place: card.anchor ? [] : [card] });
+}
+
+/** D5: where a card's anchor puts it next to its trigger (its top-left corner), or `null`. */
+function homeSpot(card: CardRecord, measure: SideMeasure | null): Point | null {
+  const { anchor } = card;
+  if (!anchor) return null;
+  if (!anchor.column) return anchoredSpot(card.el, card.trigger, anchor, CARD_CONSTANTS.edge);
+  const line = lineTopOf(card.trigger);
+  if (!measure || line === null) return null;
+  return { x: columnLeft(measure, slid, CARD_CONSTANTS.sideGap), y: line + anchor.dy };
+}
+
+/** D3: where a card dropped in the snap zone with its top at `top` lands, in the viewport. */
+function landingOf(card: CardRecord, top: number): Box | null {
+  const column = dragged?.card === card ? dragged.column : null;
+  if (!column) return null;
+  // S3, S9: the article slides as the card docks, as far as it will then be.
+  const slide = keepLeft ? column.maxSlide : column.slide;
+  const origin = cardLayer(LAYER_VARIABLES).getBoundingClientRect();
+  const height = Math.min(card.el.getBoundingClientRect().height, sideMaxHeight());
+  const want = top - origin.top;
+  const { left, tops } = columnTops(column, slide, card.key, {
+    key: card.key,
+    ideal: want,
+    top: want,
+    height,
+  });
+  const at = (tops.get(card.key) ?? want) + origin.top;
+  return { left, top: at, right: left + column.width, bottom: at + height };
+}
+
+/** D1–D7: the manager's side of a drag from a card's grip (`./card-drag.ts`). */
+const dragHost: DragHost = {
+  cardOf(grip) {
+    const card = cardContaining(grip);
+    return card && card.el.contains(grip) ? card.el : null;
+  },
+  begin(el) {
+    const card = cardContaining(el);
+    if (!card || card.el !== el) return null;
+    const measure = measureSide();
+    const column = measure ? sideColumn(measure, sideOptions()) : null;
+    const home = homeSpot(card, measure);
+    stopMotion();
+    dragged = { card, mode: card.mode, measure, column };
+    // D2: dragging pins the card.
+    if (card.mode === 'hover') setMode(card, 'pinned');
+    raise(card);
+    if (arrow?.card === card.el) arrow.hide();
+    const gap = CARD_CONSTANTS.sideGap;
+    // D3, S7: without a side column the zone shows nothing and never snaps.
+    const edge = column && measure ? columnLeft(measure, slid, 0) : null;
+    return {
+      bounds: dragBounds(CARD_CONSTANTS.edge),
+      edge,
+      area: edge !== null && measure ? { left: edge + gap, right: measure.railLeft - gap } : null,
+      home,
+    };
+  },
+  landing(el, top) {
+    const card = cardContaining(el);
+    return card ? landingOf(card, top) : null;
+  },
+  drop(el, outcome) {
+    const card = dragged?.card;
+    dragged = null;
+    if (!card || card.el !== el || !isOpen(card)) return;
+    if (outcome.kind === 'home') {
+      goHome(card);
+      return;
+    }
+    const from = motionFrom();
+    if (outcome.kind === 'side') {
+      // D3: at the drop height; S2 resolves overlaps, the article slides (S3).
+      setMode(card, 'side');
+      const line = lineTopOf(card.trigger);
+      card.sideDy = line === null ? -CARD_CONSTANTS.sideLineOffset : outcome.top - line;
+      arrange({ from, first: card });
+      return;
+    }
+    // D2: where it was dropped.
+    setMode(card, 'moved');
+    card.dropAt = { x: outcome.left, y: outcome.top };
+    arrange({ from });
+  },
+  cancel(el) {
+    const state = dragged;
+    dragged = null;
+    if (!state || state.card.el !== el || !isOpen(state.card)) return;
+    // D7: back where it started, as it was: a hovered card closes again
+    // once the pointer is elsewhere.
+    setMode(state.card, state.mode);
+    arrange();
+    if (state.mode === 'hover') graceCheck(state.card);
+  },
+  nudge(el, by) {
+    const card = cardContaining(el);
+    if (!card || card.el !== el) return;
+    const rect = el.getBoundingClientRect();
+    const grip = el.querySelector<HTMLElement>('[data-card-grip]');
+    const grab = grip ? Math.max(grip.getBoundingClientRect().bottom - rect.top, 1) : rect.height;
+    const at = nudgeSpot(
+      { x: rect.left, y: rect.top },
+      by,
+      rect.width,
+      dragBounds(CARD_CONSTANTS.edge),
+      grab,
+    );
+    const from = motionFrom();
+    setMode(card, 'moved');
+    card.dropAt = at;
+    raise(card);
+    arrange({ from });
+  },
+  home(el) {
+    const card = cardContaining(el);
+    if (!card || card.el !== el || card.mode === 'hover') return;
+    goHome(card);
+  },
+};
+
+/** C10: focus goes back to the trigger when it can take focus, else to the article. */
+function returnFocus(card: CardRecord): void {
+  const { trigger } = card;
+  if (trigger.isConnected && trigger.tabIndex >= 0 && trigger.getClientRects().length > 0) {
+    refocusing = trigger;
+    try {
+      trigger.focus({ preventScroll: true });
+    } finally {
+      refocusing = null;
+    }
+    return;
+  }
+  const article = document.querySelector<HTMLElement>('main');
+  if (!article) return;
+  if (!article.hasAttribute('tabindex')) {
+    article.setAttribute('tabindex', '-1');
+    article.dataset.cardFocusReturn = '';
+  }
+  article.focus({ preventScroll: true });
+}
+
+function teardown(card: CardRecord): void {
+  const focusInside = card.el.contains(document.activeElement);
+  if (dragged?.card === card) {
+    dragged = null;
+    drag?.abort();
+  }
+  if (travel?.card === card) endTravel();
+  if (arrow?.card === card.el) arrow.hide();
+  cancelGrace(card);
+  if (card.flashTimer !== null) clearTimeout(card.flashTimer);
+  card.unwatch();
+  cards.delete(card.key);
+  card.el.remove();
+  if (focusInside) returnFocus(card);
+  notify(card.source);
+}
+
+/** Close a card and every card opened from inside it (C9). */
+function close(card: CardRecord): void {
+  if (!isOpen(card)) return;
+  const parent = card.parentKey ? cards.get(card.parentKey) : undefined;
+  const closing = closingOrder(cards, card.key);
+  const undocking = closing.some((key) => cards.get(key)?.mode === 'side');
+  const from = undocking ? motionFrom() : null;
+  for (const key of closing) {
+    const target = cards.get(key);
+    if (target) teardown(target);
+  }
+  // S2, S3: the column closes up, and the article slides back once the last
+  // side card is gone.
+  if (undocking) arrange({ from });
+  // C9: the parent was kept open by this child; check it again.
+  if (parent && isOpen(parent) && parent.mode === 'hover') graceCheck(parent);
+}
+
+/** C7: close the transient cards outside the chain of `hostKey`. */
+function closeOutside(hostKey: string | null): void {
+  for (const key of closedByOpening(cards, hostKey)) {
+    const card = cards.get(key);
+    if (card) close(card);
+  }
+}
+
+function mount(hit: Hit, el: HTMLElement, mode: CardMode): void {
+  el.dataset.cardKey = hit.key;
+  el.hidden = false;
+  el.style.visibility = 'hidden';
+  cardLayer(LAYER_VARIABLES).append(el);
+  const card: CardRecord = {
+    key: hit.key,
+    item: hit.item,
+    source: hit.source,
+    el,
+    trigger: hit.trigger,
+    parentKey: cardContaining(hit.trigger)?.key ?? null,
+    mode,
+    order: ++opened,
+    anchor: null,
+    moved: null,
+    dropAt: null,
+    sideDy: -CARD_CONSTANTS.sideLineOffset,
+    graceTimer: null,
+    flashTimer: null,
+    unwatch: noop,
+  };
+  cards.set(card.key, card);
+  syncMode(card);
+  place(card);
+  el.style.visibility = '';
+  raise(card);
+  el.addEventListener('pointerleave', (event) => {
+    if (event.pointerType === 'touch' || !isOpen(card) || card.mode !== 'hover') return;
+    // Straight back onto the trigger is the trigger's own business.
+    if (event.relatedTarget instanceof Node && card.trigger.contains(event.relatedTarget)) {
+      return;
+    }
+    graceCheck(card);
+  });
+  el.addEventListener('focusout', () => {
+    if (isOpen(card) && card.mode === 'hover') graceCheck(card);
+  });
+  notify(card.source);
+}
+
+function settle(key: string, token: number, el: HTMLElement | null): void {
+  const waiting = pending.get(key);
+  if (!waiting || waiting.token !== token) return;
+  pending.delete(key);
+  const { hit, mode } = waiting;
+  if (!el || cards.has(key) || !hit.trigger.isConnected) return;
+  if (
+    mode === 'hover' &&
+    !hit.trigger.matches(':hover') &&
+    !hit.trigger.matches(':focus-visible')
+  ) {
+    return;
+  }
+  closeOutside(cardContaining(hit.trigger)?.key ?? null);
+  mount(hit, el, mode);
+}
+
+/** Open a card for `hit` (C7: first closing the transient cards outside its chain). */
+function request(hit: Hit, mode: CardMode): void {
+  closeOutside(cardContaining(hit.trigger)?.key ?? null);
+  for (const [key, waiting] of pending) {
+    if (key !== hit.key && waiting.mode === 'hover') pending.delete(key);
+  }
+  const rendered = hit.source.render(hit.item, hit.trigger);
+  if (rendered instanceof Promise) {
+    const token = ++pendingSerial;
+    pending.set(hit.key, { hit, mode, token });
+    rendered.then(
+      (el) => settle(hit.key, token, el),
+      () => settle(hit.key, token, null),
+    );
+    return;
+  }
+  if (rendered) mount(hit, rendered, mode);
+}
+
+/** C1, C7, C8: the pointer or keyboard focus reached a trigger. */
+function hoverOpen(hit: Hit): void {
+  const card = cards.get(hit.key);
+  if (card) {
+    cancelGrace(card);
+    if (travel?.card === card) endTravel();
+    if (hit.trigger !== card.trigger) {
+      // C8: a hovered card follows the pointer to another occurrence; a kept
+      // one stays and shows where it is, with an arrow to this one (S5).
+      const inside = insideSubtree(card, hit.trigger);
+      if (card.mode === 'hover' && !inside) {
+        reattach(card, hit.trigger);
+      } else {
+        flash(card);
+        if (!inside) pointAt(card, hit.trigger);
+      }
+    } else if (awayFromTrigger(card.mode)) {
+      pointAt(card, card.trigger); // S5: a docked or moved card's own line
+    }
+    closeOutside(card.key);
+    return;
+  }
+  if (hit.source.claims && !hit.source.claims(hit.trigger)) return;
+  const waiting = pending.get(hit.key);
+  if (waiting) {
+    waiting.hit = hit;
+    return;
+  }
+  request(hit, 'hover');
+}
+
+function onPointerOver(event: PointerEvent): void {
+  if (event.pointerType === 'touch') return;
+  arrow?.follow(event.target);
+  // S5: pointing at a docked or moved card shows where its line is.
+  const host = cardContaining(event.target);
+  if (
+    host &&
+    awayFromTrigger(host.mode) &&
+    arrow?.card !== host.el &&
+    !(event.relatedTarget instanceof Node && host.el.contains(event.relatedTarget))
+  ) {
+    pointAt(host, host.trigger);
+  }
+  const hit = findTrigger(event.target);
+  if (!hit) return;
+  if (event.relatedTarget instanceof Node && hit.trigger.contains(event.relatedTarget)) return;
+  if (travel) {
+    const { card, trip } = travel;
+    if (hit.trigger === card.trigger) {
+      endTravel(); // back on the trigger
+    } else if (
+      !card.el.contains(hit.trigger) &&
+      trip.holds({ x: event.clientX, y: event.clientY })
+    ) {
+      return; // C2: held back while the pointer travels to the card
+    }
+  }
+  hoverOpen(hit);
+}
+
+function onPointerOut(event: PointerEvent): void {
+  if (event.pointerType === 'touch') return;
+  if (!event.relatedTarget) arrow?.release(); // out of the window
+  const hit = findTrigger(event.target);
+  if (!hit) return;
+  const to = event.relatedTarget instanceof Node ? event.relatedTarget : null;
+  if (to && hit.trigger.contains(to)) return;
+  const card = cards.get(hit.key);
+  if (!card || card.trigger !== hit.trigger || card.mode !== 'hover') return;
+  if (to && card.el.contains(to)) return; // straight onto its card
+  startTravel(card, lastPointer ?? { x: event.clientX, y: event.clientY });
+}
+
+function onPointerMove(event: PointerEvent): void {
+  if (event.pointerType === 'touch') return;
+  lastPointer = { x: event.clientX, y: event.clientY };
+  travel?.trip.move(lastPointer);
+}
+
+function onPointerDown(event: PointerEvent): void {
+  const card = cardContaining(event.target);
+  if (card) raise(card);
+}
+
+function onFocusIn(event: FocusEvent): void {
+  arrow?.follow(event.target);
+  const card = cardContaining(event.target);
+  if (card) raise(card);
+  const visible = event.target instanceof Element && event.target.matches(':focus-visible');
+  if (card && awayFromTrigger(card.mode) && visible && arrow?.card !== card.el) {
+    pointAt(card, card.trigger);
+  }
+  const hit = findTrigger(event.target);
+  if (!hit || hit.trigger === refocusing) return;
+  // C1: keyboard focus opens a card; the focus a click leaves behind does not.
+  if (!visible) return;
+  hoverOpen(hit);
+}
+
+function onFocusOut(event: FocusEvent): void {
+  if (!event.relatedTarget) arrow?.release();
+  const hit = findTrigger(event.target);
+  if (!hit) return;
+  const card = cards.get(hit.key);
+  if (card && card.trigger === hit.trigger && card.mode === 'hover') graceCheck(card);
+}
+
+/** C3, C4, C6, C8, S6, D5: clicks on a card's controls and on triggers. */
+function onClick(event: MouseEvent): void {
+  const host = cardContaining(event.target);
+  const control =
+    host && event.target instanceof Element
+      ? event.target.closest<HTMLElement>('[data-card-pin], [data-card-close], [data-card-side]')
+      : null;
+  if (host && control && host.el.contains(control)) {
+    if (control.hasAttribute('data-card-close')) {
+      close(host);
+    } else if (control.hasAttribute('data-card-side') || host.mode === 'side') {
+      toggleSide(host);
+    } else if (host.mode === 'moved') {
+      goHome(host); // its Pin is hidden, like a docked card's (S6)
+    } else if (host.mode === 'pinned') {
+      setMode(host, 'hover');
+      graceCheck(host);
+    } else {
+      setMode(host, 'pinned');
+    }
+    return;
+  }
+
+  const hit = findTrigger(event.target);
+  if (!hit) return;
+  const link = hit.trigger.closest('a[href]');
+  // A modified click on a link keeps its native meaning (a new tab, …).
+  if (
+    link &&
+    (event.button !== 0 || event.ctrlKey || event.metaKey || event.shiftKey || event.altKey)
+  ) {
+    return;
+  }
+  const card = cards.get(hit.key);
+  const waiting = pending.get(hit.key);
+  if (!card && !waiting && hit.source.claims && !hit.source.claims(hit.trigger)) return;
+
+  event.preventDefault();
+  // C3: the click toggles a pin and is nothing else. The anchor scroller and
+  // the float enhancer must not read it as a jump to the target.
+  if (link) event.stopPropagation();
+
+  if (card) {
+    if (hit.trigger === card.trigger) {
+      if (card.mode === 'hover') setMode(card, 'pinned');
+      else close(card); // C4: its trigger, clicked again
+    } else if (insideSubtree(card, hit.trigger)) {
+      if (card.mode === 'hover') setMode(card, 'pinned');
+      else flash(card);
+    } else if (card.mode === 'moved') {
+      // C8: a moved card stays where the reader put it, and shows where it is.
+      flash(card);
+      pointAt(card, hit.trigger);
+      closeOutside(card.key);
+    } else {
+      // C8: the card moves to this occurrence, and stays: a pinned card
+      // beside it, a docked one level with its line.
+      reattach(card, hit.trigger);
+      if (card.mode === 'hover') setMode(card, 'pinned');
+      closeOutside(card.key);
+    }
+    return;
+  }
+  if (waiting) {
+    waiting.hit = hit;
+    waiting.mode = 'pinned';
+    return;
+  }
+  request(hit, 'pinned');
+}
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (event.key !== 'Escape') return;
+  const key = escapeTarget(cards);
+  const card = key ? cards.get(key) : undefined;
+  if (card) {
+    close(card); // C10: one card per press, newest first
+    return;
+  }
+  pending.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Remembering the open cards (`./card-memory.ts`).
+// ---------------------------------------------------------------------------
+
+/**
+ * Every trigger of `source` for one of `items`, in document order: on the
+ * page (outside every card) when `scope` is `null`, else inside that card.
+ */
+function occurrencesOf(
+  source: CardSource,
+  items: ReadonlySet<string>,
+  scope: HTMLElement | null,
+): Map<string, HTMLElement[]> {
+  const found = new Map<string, HTMLElement[]>();
+  const layer = cardLayer(LAYER_VARIABLES);
+  for (const el of (scope ?? document.body).querySelectorAll<HTMLElement>('*')) {
+    if (!scope && layer.contains(el)) continue;
+    if (source.triggerFrom(el) !== el) continue;
+    const item = source.itemFor(el);
+    if (item === null || !items.has(item)) continue;
+    const list = found.get(item);
+    if (list) list.push(el);
+    else found.set(item, [el]);
+  }
+  return found;
+}
+
+/** Remember the cards the reader keeps, and what keeps them there, as the page is left. */
+function rememberCards(): void {
+  const saved: RememberedCard[] = [];
+  const keys = new Set<string>();
+  // One walk of the page, or of a parent card, per layer.
+  const lookups = new Map<string, Map<string, HTMLElement[]>>();
+  const kept = ordered().filter((card) => !isTransient(cards, card.key));
+  for (const card of kept) {
+    if (!card.trigger.isConnected) continue;
+    // A card opened from inside another comes back only with it.
+    if (card.parentKey !== null && !keys.has(card.parentKey)) continue;
+    const scope = card.parentKey ? (cards.get(card.parentKey)?.el ?? null) : null;
+    const lookup = `${card.source.layer}|${card.parentKey ?? ''}`;
+    let triggers = lookups.get(lookup);
+    if (!triggers) {
+      const items = new Set(
+        kept
+          .filter((other) => other.source === card.source && other.parentKey === card.parentKey)
+          .map((other) => other.item),
+      );
+      triggers = occurrencesOf(card.source, items, scope);
+      lookups.set(lookup, triggers);
+    }
+    const occurrence = triggers.get(card.item)?.indexOf(card.trigger) ?? -1;
+    if (occurrence < 0) continue;
+    keys.add(card.key);
+    saved.push({
+      layer: card.source.layer,
+      item: card.item,
+      occurrence,
+      parentKey: card.parentKey,
+      mode: card.mode,
+      anchor: card.anchor,
+      moved: card.mode === 'moved' ? card.moved : null,
+      sideDy: card.mode === 'side' ? card.sideDy : null,
+    });
+  }
+  writeRememberedCards({
+    cards: saved,
+    pointed: pointedKey !== null && keys.has(pointedKey) ? pointedKey : null,
+  });
+}
+
+/** Open a remembered card as it was: in its mode, at its place. */
+function revive(hit: Hit, el: HTMLElement, saved: RememberedCard): void {
+  mount(hit, el, saved.mode === 'hover' ? 'hover' : 'pinned');
+  const card = cards.get(hit.key);
+  if (!card || card.el !== el) return;
+  if (saved.anchor) card.anchor = saved.anchor;
+  if (saved.mode === 'side') {
+    setMode(card, 'side');
+    if (saved.sideDy !== null) card.sideDy = saved.sideDy;
+  } else if (saved.mode === 'moved' && saved.moved) {
+    setMode(card, 'moved');
+    card.moved = saved.moved;
+  }
+  if (rememberedPointed === card.key) pointedKey = card.key;
+}
+
+/**
+ * Restore every remembered card that can open now: its layer registered and
+ * the card it was opened from open. A card whose content is fetched (a
+ * cross-page reference) opens when it arrives; its children follow it.
+ */
+function restoreRemembered(): void {
+  let revived = false;
+  for (;;) {
+    const ready = restorable(
+      remembered,
+      new Set(sources.map((source) => source.layer)),
+      new Set(cards.keys()),
+    );
+    if (ready.length === 0) break;
+    for (const saved of ready) {
+      remembered = remembered.filter((other) => other !== saved);
+      const source = sources.find((candidate) => candidate.layer === saved.layer);
+      if (!source) continue;
+      const parent = saved.parentKey ? cards.get(saved.parentKey) : undefined;
+      if (saved.parentKey && !parent) continue;
+      const triggers = occurrencesOf(source, new Set([saved.item]), parent?.el ?? null).get(
+        saved.item,
+      );
+      // The same occurrence, or the first one if the page changed since.
+      const trigger = triggers?.[saved.occurrence] ?? triggers?.[0];
+      if (!trigger) continue;
+      const hit: Hit = { source, trigger, item: saved.item, key: keyOf(saved) };
+      const rendered = source.render(saved.item, trigger);
+      if (rendered instanceof Promise) {
+        rendered.then(
+          (el) => {
+            if (!el || cards.has(hit.key) || !trigger.isConnected) return;
+            revive(hit, el, saved);
+            arrange();
+            restoreRemembered();
+          },
+          noop,
+        );
+      } else if (rendered) {
+        revive(hit, rendered, saved);
+        revived = true;
+      }
+    }
+  }
+  if (!revived) return;
+  arrange();
+  // A hovered card came back only for a kept child (C9); without one it
+  // closes like any hovered card.
+  for (const card of cards.values()) {
+    if (card.mode === 'hover' && !hasChild(cards, card.key)) graceCheck(card);
+  }
+}
+
+function install(): void {
+  if (layout) return;
+  layout = watchCardLayout(reanchorAll);
+  const layer = () => cardLayer(LAYER_VARIABLES);
+  arrow = createArrowOverlay({
+    layer,
+    holdMs: CARD_CONSTANTS.arrowFadeMs,
+    fadeMs: CARD_CONSTANTS.animationMs,
+  });
+  drag = installCardDrag(dragHost, {
+    threshold: CARD_CONSTANTS.dragThreshold,
+    snapDistance: CARD_CONSTANTS.snapDistance,
+    snapRelease: CARD_CONSTANTS.snapRelease,
+    snapHome: CARD_CONSTANTS.snapHome,
+    step: CARD_CONSTANTS.keyboardStep,
+    stepLarge: CARD_CONSTANTS.keyboardStepLarge,
+    layer,
+  });
+  keepLeftToggle = createKeepLeftToggle(layer, (on) => {
+    keepLeft = on;
+    writeKeepLeft(on);
+    arrange({ from: motionFrom() });
+  });
+  // S9: a reader who keeps the article left finds it there on every page.
+  keepLeft = readKeepLeft();
+  if (keepLeft) arrange();
+  // The cards the reader left this page with, restored as each layer registers.
+  const page = readRememberedCards();
+  remembered = [...page.cards];
+  rememberedPointed = page.pointed;
+  window.addEventListener('pagehide', rememberCards);
+  document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState === 'hidden') rememberCards();
+  });
+  document.addEventListener('pointerover', onPointerOver);
+  document.addEventListener('pointerout', onPointerOut);
+  document.addEventListener('pointermove', onPointerMove, { passive: true });
+  document.addEventListener('pointerdown', onPointerDown, true);
+  document.addEventListener('focusin', onFocusIn);
+  document.addEventListener('focusout', onFocusOut);
+  // Capture, so a trigger's click is claimed before any other listener sees it.
+  document.addEventListener('click', onClick, true);
+  document.addEventListener('keydown', onKeyDown);
+  window.addEventListener('scroll', interruptTravel, { capture: true, passive: true });
+  window.addEventListener('resize', interruptTravel, { passive: true });
+}
+
+/**
+ * Hand a layer's triggers to the manager. A source registered again under
+ * the same `layer` replaces the old one and closes its cards.
+ */
+export function registerCardSource(source: CardSource): void {
+  install();
+  const at = sources.findIndex((existing) => existing.layer === source.layer);
+  if (at === -1) {
+    sources.push(source);
+  } else {
+    const previous = sources[at];
+    for (const card of ordered().reverse()) if (card.source === previous) close(card);
+    sources.splice(at, 1, source);
+  }
+  restoreRemembered();
+}
+
+/**
+ * Close every card only the pointer keeps open, leaving kept ones. A diagram
+ * or table expanding over the page calls this, so a card it would cover
+ * does not linger.
+ */
+export function closeTransientCards(): void {
+  endTravel();
+  for (const [key, waiting] of pending) {
+    if (waiting.mode === 'hover') pending.delete(key);
+  }
+  closeOutside(null);
+}