explico 0.8.0 → 0.11.1

package/src/components/card-memory.ts

@@ -0,0 +1,177 @@
+/**
+ * Remembering a page's open explanation cards. A reader who leaves a lesson
+ * with cards pinned, docked or moved finds them where they were on coming
+ * back to it: through a link, Back or a reload, in another tab, or after the
+ * browser restarts. Closing the last card forgets the page.
+ *
+ * The card manager (`./card-manager.ts`) saves the kept cards as the page is
+ * left (`pagehide`) and restores them as each layer registers. A card is
+ * named by its layer and item, and by which occurrence of the item its
+ * trigger is, counted in document order within the page, or within its
+ * parent card for a card opened from inside another. Its place is saved as
+ * it is kept: its anchor next to the trigger, a moved card's spot, a docked
+ * card's height against its line.
+ *
+ * The stored value is plain JSON, checked field by field on the way back
+ * (`decodeCards`), so a stale or malformed entry is dropped, never trusted.
+ * `decodeCards` and `restorable` are pure, so `tests/unit/card-memory.test.ts`
+ * checks them in Node.
+ */
+import { createBrowserPreferenceStore } from '../session/PreferenceStore';
+import type { MovedSpot } from './card-drag';
+import type { CardAnchor } from './card-placement';
+
+/** A remembered card's mode: a hovered one only when a kept child held it open (C9). */
+export type RememberedMode = 'hover' | 'pinned' | 'side' | 'moved';
+
+export interface RememberedCard {
+  /** The card's layer (`notation`, `citation`, …) and item; its key is `layer:item`. */
+  readonly layer: string;
+  readonly item: string;
+  /** Which occurrence of the item its trigger was, in document order within its scope. */
+  readonly occurrence: number;
+  /** The card it was opened from, restored first; `null` for a card opened from the page. */
+  readonly parentKey: string | null;
+  readonly mode: RememberedMode;
+  /** P1: where it sits next to its trigger (a pinned card's place, every card's home). */
+  readonly anchor: CardAnchor | null;
+  /** D2: a moved card's spot against the article column and its trigger's line. */
+  readonly moved: MovedSpot | null;
+  /** S2, D3: a docked card's top against its trigger's line. */
+  readonly sideDy: number | null;
+}
+
+export interface RememberedPage {
+  /** In the order they were first opened, so Escape closes them in the same order (C10). */
+  readonly cards: readonly RememberedCard[];
+  /** S2: the docked card pointed at last. */
+  readonly pointed: string | null;
+}
+
+/** Bumped whenever the stored shape changes; an entry of another version is dropped. */
+const VERSION = 1;
+
+export const EMPTY_PAGE: RememberedPage = { cards: [], pointed: null };
+
+export const keyOf = (card: Pick<RememberedCard, 'layer' | 'item'>): string =>
+  `${card.layer}:${card.item}`;
+
+export function encodeCards(page: RememberedPage): string {
+  return JSON.stringify({ v: VERSION, cards: page.cards, pointed: page.pointed });
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isNumber = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value);
+
+const MODES: readonly string[] = ['hover', 'pinned', 'side', 'moved'];
+
+function decodeAnchor(value: unknown): CardAnchor | null {
+  if (!isRecord(value)) return null;
+  const { side, dx, dy, column } = value;
+  if ((side !== 'below' && side !== 'above') || !isNumber(dx) || !isNumber(dy)) return null;
+  return column === true ? { side, dx, dy, column: true } : { side, dx, dy };
+}
+
+function decodeMoved(value: unknown): MovedSpot | null {
+  if (!isRecord(value) || !isNumber(value.x) || !isNumber(value.y)) return null;
+  return { x: value.x, y: value.y };
+}
+
+function decodeCard(value: unknown): RememberedCard | null {
+  if (!isRecord(value)) return null;
+  const { layer, item, occurrence, parentKey, mode } = value;
+  if (typeof layer !== 'string' || layer === '' || typeof item !== 'string' || item === '') {
+    return null;
+  }
+  if (!isNumber(occurrence) || occurrence < 0 || !Number.isInteger(occurrence)) return null;
+  if (parentKey !== null && typeof parentKey !== 'string') return null;
+  if (typeof mode !== 'string' || !MODES.includes(mode)) return null;
+  const moved = decodeMoved(value.moved);
+  // A moved card without its spot has nowhere to go.
+  if (mode === 'moved' && !moved) return null;
+  return {
+    layer,
+    item,
+    occurrence,
+    parentKey,
+    mode: mode as RememberedMode,
+    anchor: decodeAnchor(value.anchor),
+    moved: mode === 'moved' ? moved : null,
+    sideDy: mode === 'side' && isNumber(value.sideDy) ? value.sideDy : null,
+  };
+}
+
+/**
+ * The page a stored value remembers, or an empty one for anything else: no
+ * value, other JSON, another version. Malformed cards are dropped one by
+ * one, and so is a card whose parent is not remembered before it.
+ */
+export function decodeCards(text: string | null): RememberedPage {
+  if (!text) return EMPTY_PAGE;
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return EMPTY_PAGE;
+  }
+  if (!isRecord(value) || value.v !== VERSION || !Array.isArray(value.cards)) return EMPTY_PAGE;
+  const cards: RememberedCard[] = [];
+  const seen = new Set<string>();
+  for (const entry of value.cards) {
+    const card = decodeCard(entry);
+    if (!card || seen.has(keyOf(card))) continue;
+    if (card.parentKey !== null && !seen.has(card.parentKey)) continue;
+    seen.add(keyOf(card));
+    cards.push(card);
+  }
+  const pointed =
+    typeof value.pointed === 'string' && seen.has(value.pointed) ? value.pointed : null;
+  return { cards, pointed };
+}
+
+/**
+ * The remembered cards that can be restored now, in their order: their layer
+ * has registered, they are not open already, and the card they were opened
+ * from, if any, is open.
+ */
+export function restorable(
+  cards: readonly RememberedCard[],
+  layers: ReadonlySet<string>,
+  open: ReadonlySet<string>,
+): RememberedCard[] {
+  return cards.filter(
+    (card) =>
+      layers.has(card.layer) &&
+      !open.has(keyOf(card)) &&
+      (card.parentKey === null || open.has(card.parentKey)),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// The DOM layer.
+// ---------------------------------------------------------------------------
+
+// The one seam for browser storage; this module never touches it itself.
+// Local storage, so the cards outlive the tab and a browser restart; tabs
+// open on the same page share one entry, and the last one left wins.
+const store = createBrowserPreferenceStore();
+
+/**
+ * One entry per page, kept only while the page has cards to bring back. The
+ * path includes a course's base, so courses on one origin never share one.
+ */
+const storageKey = () => `explico:cards:${window.location.pathname}`;
+
+/** The cards this page had open when the reader last left it. */
+export const readRememberedCards = (): RememberedPage => decodeCards(store.get(storageKey()));
+
+/** Remember this page's cards; with none, the page is forgotten. */
+export function writeRememberedCards(page: RememberedPage): void {
+  const key = storageKey();
+  if (page.cards.length > 0) store.set(key, encodeCards(page));
+  else if (store.remove) store.remove(key);
+  else store.set(key, '');
+}

package/src/components/card-placement.ts

@@ -0,0 +1,504 @@
+/**
+ * Where an explanation card goes (rules P1–P6 of
+ * `docs/plans/hover-card-consistency.md`).
+ *
+ * P1. Cards live in one body-level layer and are positioned in document
+ * coordinates, so they scroll with the page natively: no scroll listener
+ * moves them, and a pinned card leaves with its trigger. They are placed
+ * once, when they open, and only re-anchored to their trigger when the
+ * layout changes (`watchCardLayout`) or when a scroll container around the
+ * trigger scrolls (`scrollContainersOf`).
+ *
+ * P2. A card takes the first free spot in a fixed order, judged against the
+ * window below the sticky header at open time and against every other open
+ * card (P6). `placeCard` is that decision as a pure function over plain
+ * boxes, so `tests/unit/card-placement.test.ts` runs it in Node; the rest of
+ * this module measures the page and applies the answer.
+ */
+import type { Box } from './card-travel';
+
+export type CardSide = 'below' | 'above';
+export type PlacementStep = 1 | 2 | 3 | 4 | 5 | 6;
+
+/** A spot in the side column, for P2 step 5: its left edge, and level with the trigger's line. */
+export interface SideSpot {
+  readonly left: number;
+  readonly top: number;
+}
+
+export interface PlacementInput {
+  /** The part of the window a card must fit: below the sticky header, inset by the window edge. */
+  readonly band: Box;
+  /** The article column's horizontal extent, or `null` when the page has none. */
+  readonly column: { readonly left: number; readonly right: number } | null;
+  /** The safe region R: the enclosing display equation, else the trigger. */
+  readonly region: Box;
+  readonly trigger: Box;
+  /** The card's natural size. */
+  readonly width: number;
+  readonly height: number;
+  /** Every other open card, oldest first. */
+  readonly others: readonly Box[];
+  /** The gap between a card and R, and between cards placed side by side. */
+  readonly gap: number;
+  /** P2 step 6: how far a card placed over the card in its way is shifted. */
+  readonly overlapOffset: number;
+  /** The shortest a card may be squeezed to fit a side; it scrolls inside. */
+  readonly minHeight: number;
+  /**
+   * P2 step 5: the side column at the trigger's line, for a card of this
+   * size, or `null` when the window has no side column with room for it
+   * (S1, S7). Absent, step 5 is skipped. The spot is free or not like any
+   * other: inside the band (moved up or down into it when it sticks out)
+   * and clear of every other card.
+   */
+  readonly sideColumn?: ((width: number, height: number) => SideSpot | null) | null;
+}
+
+export interface Placement {
+  readonly left: number;
+  readonly top: number;
+  /** The card's height: its natural height, or less when it was squeezed to fit a side. */
+  readonly height: number;
+  readonly side: CardSide;
+  readonly step: PlacementStep;
+}
+
+/** Rounding slack for comparing measured, fractional pixel positions. */
+const EPSILON = 0.5;
+
+const clamp = (value: number, low: number, high: number) =>
+  Math.max(low, Math.min(value, high));
+
+const boxAt = (left: number, top: number, width: number, height: number): Box => ({
+  left,
+  top,
+  right: left + width,
+  bottom: top + height,
+});
+
+/** Whether two boxes share any area; boxes that only touch do not overlap. */
+export function overlaps(a: Box, b: Box): boolean {
+  return (
+    a.left < b.right - EPSILON &&
+    a.right > b.left + EPSILON &&
+    a.top < b.bottom - EPSILON &&
+    a.bottom > b.top + EPSILON
+  );
+}
+
+/**
+ * The horizontal range a card may use: the article column, or the whole
+ * band when the column is narrower than the card.
+ */
+export function horizontalRange(
+  band: Box,
+  column: PlacementInput['column'],
+  width: number,
+): { low: number; high: number } {
+  if (column) {
+    const low = Math.max(band.left, column.left);
+    const high = Math.min(band.right, column.right);
+    if (high - low >= width - EPSILON) return { low, high };
+  }
+  return { low: band.left, high: band.right };
+}
+
+/** P2: the first free spot, in order. Never the top of the window (B11). */
+export function placeCard(input: PlacementInput): Placement {
+  const { band, region, trigger, width, gap, others } = input;
+
+  const spaceBelow = band.bottom - (region.bottom + gap);
+  const spaceAbove = region.top - gap - band.top;
+  const space = (side: CardSide) => (side === 'below' ? spaceBelow : spaceAbove);
+  const fits = (side: CardSide) => input.height <= space(side) + EPSILON;
+
+  // 1: below if the card fits there, else the roomier side.
+  const preferred: CardSide =
+    fits('below') || spaceBelow >= spaceAbove ? 'below' : 'above';
+  const other: CardSide = preferred === 'below' ? 'above' : 'below';
+  // A card taller than its preferred side is squeezed to it and scrolls
+  // inside, down to `minHeight`; below that it keeps its height and overflows.
+  const squeezed = Math.max(
+    Math.min(input.height, space(preferred)),
+    Math.min(input.height, input.minHeight),
+  );
+  const height = fits(preferred) ? input.height : squeezed;
+
+  const { low, high } = horizontalRange(band, input.column, width);
+  const centered = clamp(
+    (trigger.left + trigger.right) / 2 - width / 2,
+    low,
+    Math.max(low, high - width),
+  );
+  const topFor = (side: CardSide, h: number) =>
+    side === 'below' ? region.bottom + gap : region.top - gap - h;
+
+  const fitsBand = (box: Box) =>
+    box.top >= band.top - EPSILON &&
+    box.bottom <= band.bottom + EPSILON &&
+    // A card wider than the whole band cannot fit it; its horizontal
+    // position is already as good as it gets.
+    (width > band.right - band.left ||
+      (box.left >= band.left - EPSILON && box.right <= band.right + EPSILON));
+  const free = (box: Box) => fitsBand(box) && !others.some((o) => overlaps(o, box));
+
+  /** Steps 2 and 3: the free spot on `side` nearest to the centered one. */
+  const slide = (side: CardSide, h: number): Box | null => {
+    const top = topFor(side, h);
+    if (!fitsBand(boxAt(centered, top, width, h))) return null;
+    const inRow = others.filter((o) => o.top < top + h - EPSILON && o.bottom > top + EPSILON);
+    const candidates = new Set<number>([centered, low, high - width]);
+    for (const o of inRow) {
+      candidates.add(o.right + gap);
+      candidates.add(o.left - gap - width);
+    }
+    let best: Box | null = null;
+    for (const left of candidates) {
+      if (left < low - EPSILON || left + width > high + EPSILON) continue;
+      const box = boxAt(left, top, width, h);
+      if (!free(box)) continue;
+      if (!best || Math.abs(left - centered) < Math.abs(best.left - centered)) best = box;
+    }
+    return best;
+  };
+
+  /** Step 4: pushed past the cards in the way, away from R. */
+  const stack = (start: Box, side: CardSide): Box | null => {
+    let box = start;
+    const h = start.bottom - start.top;
+    for (let attempt = 0; attempt <= others.length; attempt++) {
+      const hits = others.filter((o) => overlaps(o, box));
+      if (hits.length === 0) return fitsBand(box) ? box : null;
+      const top =
+        side === 'below'
+          ? Math.max(...hits.map((o) => o.bottom)) + gap
+          : Math.min(...hits.map((o) => o.top)) - gap - h;
+      box = boxAt(box.left, top, width, h);
+      if (!fitsBand(box)) return null;
+    }
+    return null;
+  };
+
+  /** Step 6: over the newest card in the way, shifted down and right. */
+  const cover = (start: Box): Box => {
+    const blocker = [...others].reverse().find((o) => overlaps(o, start));
+    if (!blocker) return start;
+    let left = blocker.left + input.overlapOffset;
+    let top = blocker.top + input.overlapOffset;
+    // Cascade past a card already sitting at that offset.
+    for (let attempt = 0; attempt < others.length; attempt++) {
+      const taken = others.some(
+        (o) => Math.abs(o.left - left) < 1 && Math.abs(o.top - top) < 1,
+      );
+      if (!taken) break;
+      left += input.overlapOffset;
+      top += input.overlapOffset;
+    }
+    left = clamp(left, band.left, Math.max(band.left, band.right - width));
+    return boxAt(left, top, width, start.bottom - start.top);
+  };
+
+  const result = (box: Box, side: CardSide, step: PlacementStep): Placement => ({
+    left: box.left,
+    top: box.top,
+    height: box.bottom - box.top,
+    side,
+    step,
+  });
+
+  const first = boxAt(centered, topFor(preferred, height), width, height);
+  if (free(first)) return result(first, preferred, 1);
+
+  const slid = slide(preferred, height);
+  if (slid) return result(slid, preferred, 2);
+
+  if (fits(other)) {
+    const across = boxAt(centered, topFor(other, input.height), width, input.height);
+    if (free(across)) return result(across, other, 3);
+    const acrossSlid = slide(other, input.height);
+    if (acrossSlid) return result(acrossSlid, other, 3);
+  }
+
+  const stacked = stack(first, preferred);
+  if (stacked) return result(stacked, preferred, 4);
+
+  const spot = input.sideColumn?.(width, height);
+  if (spot) {
+    const top = clamp(spot.top, band.top, Math.max(band.top, band.bottom - height));
+    const beside = boxAt(spot.left, top, width, height);
+    if (free(beside)) return result(beside, preferred, 5);
+  }
+
+  return result(cover(first), preferred, 6);
+}
+
+// ---------------------------------------------------------------------------
+// The DOM layer.
+// ---------------------------------------------------------------------------
+
+/**
+ * How a placed card follows its trigger when the layout changes: the same
+ * horizontal offset from the trigger, and the same distance from the side of
+ * the safe region it was placed on.
+ */
+export interface CardAnchor {
+  readonly side: CardSide;
+  /** The card's left minus the trigger's left. */
+  readonly dx: number;
+  /**
+   * Below: the card's top minus R's bottom. Above: the card's bottom minus
+   * R's top. In the side column: the card's top minus the top of the
+   * trigger's first line.
+   */
+  readonly dy: number;
+  /**
+   * Placed in the side column (P2 step 5): it follows the column's edge and
+   * its trigger's line, not the trigger's left, and the card manager moves
+   * it (`reanchorElement` does not).
+   */
+  readonly column?: boolean;
+}
+
+export interface PlaceOptions {
+  readonly gap: number;
+  readonly edge: number;
+  readonly overlapOffset: number;
+  readonly minHeight: number;
+  readonly sideColumn?: PlacementInput['sideColumn'];
+}
+
+/** The safe region R a card must not cover: the enclosing display equation, else the trigger. */
+export const regionOf = (trigger: HTMLElement): HTMLElement =>
+  trigger.closest<HTMLElement>('.katex-display') ?? trigger;
+
+/** The window below the sticky header, inset by `edge`, in viewport coordinates. */
+export function cardBand(edge: number): Box {
+  const header = document.querySelector<HTMLElement>('.header');
+  const headerBottom = header ? header.getBoundingClientRect().bottom : 0;
+  const root = document.documentElement;
+  return {
+    left: edge,
+    top: Math.max(edge, headerBottom + edge),
+    right: root.clientWidth - edge,
+    bottom: root.clientHeight - edge,
+  };
+}
+
+/**
+ * The article column a trigger's card is kept in. A trigger inside a card
+ * or an expanded diagram (whose `.sl-markdown-content` stand-in has no box
+ * of its own) uses the page's main article.
+ */
+export function articleColumn(
+  trigger: HTMLElement,
+): { left: number; right: number } | null {
+  const candidates = [
+    trigger.closest<HTMLElement>('.sl-markdown-content'),
+    document.querySelector<HTMLElement>('.main-pane .sl-markdown-content'),
+    document.querySelector<HTMLElement>('.sl-markdown-content'),
+  ];
+  for (const article of candidates) {
+    const rect = article?.getBoundingClientRect();
+    if (rect && rect.width > 0) return { left: rect.left, right: rect.right };
+  }
+  return null;
+}
+
+let layer: HTMLElement | null = null;
+
+/**
+ * The one body-level layer every card mounts in (P1). It sits at the
+ * document origin and spans the viewport's width, so a card's `left`/`top`
+ * inside it are document coordinates and the page's own scrolling carries
+ * it. It takes the navbar's stacking level but comes before `.page` in the
+ * document, so cards slide under the header (one level up) and under both
+ * side panels (the same level, later in the document; `global.css`) as the
+ * page scrolls, yet stay above the expanded tables and diagrams one level
+ * below.
+ * Cards must never mount inside the article: an ancestor's stacking context
+ * once let the Starlight sidebar swallow a card's clicks.
+ */
+export function cardLayer(variables: Readonly<Record<string, string>> = {}): HTMLElement {
+  if (layer?.isConnected) return layer;
+  layer = document.createElement('div');
+  layer.className = 'explico-card-layer';
+  layer.dataset.cardLayer = '';
+  layer.style.cssText =
+    'position:absolute;left:0;top:0;width:100%;height:0;z-index:var(--sl-z-index-navbar,10)';
+  for (const [name, value] of Object.entries(variables)) {
+    layer.style.setProperty(name, value);
+  }
+  const page = document.body.querySelector(':scope > .page');
+  if (page) page.before(layer);
+  else document.body.append(layer);
+  return layer;
+}
+
+/** Move `el`, mounted in the card layer, so its viewport position is (`left`, `top`). */
+export function moveTo(el: HTMLElement, left: number, top: number): void {
+  const origin = (el.parentElement ?? document.body).getBoundingClientRect();
+  el.style.left = `${Math.round(left - origin.left)}px`;
+  el.style.top = `${Math.round(top - origin.top)}px`;
+}
+
+/**
+ * Place `el`, already mounted in the card layer, next to `trigger` and clear
+ * of `others` (P2, P6). Returns how it follows the trigger from now on.
+ */
+export function placeElement(
+  el: HTMLElement,
+  trigger: HTMLElement,
+  others: readonly HTMLElement[],
+  options: PlaceOptions,
+): CardAnchor {
+  const band = cardBand(options.edge);
+  const bandHeight = Math.max(band.bottom - band.top, 0);
+  // Measure with all the room the window offers, then keep whatever part of
+  // it the chosen spot allows.
+  el.style.maxHeight = `${bandHeight}px`;
+  moveTo(el, band.left, band.top);
+  const size = el.getBoundingClientRect();
+  const region = regionOf(trigger).getBoundingClientRect();
+  const triggerBox = trigger.getBoundingClientRect();
+
+  const placement = placeCard({
+    band,
+    column: articleColumn(trigger),
+    region,
+    trigger: triggerBox,
+    width: size.width,
+    height: size.height,
+    others: others.map((other) => other.getBoundingClientRect()),
+    gap: options.gap,
+    overlapOffset: options.overlapOffset,
+    minHeight: options.minHeight,
+    sideColumn: options.sideColumn ?? null,
+  });
+
+  const capped =
+    placement.height < size.height - EPSILON || size.height >= bandHeight - EPSILON;
+  el.style.maxHeight = capped ? `${placement.height}px` : '';
+  moveTo(el, placement.left, placement.top);
+
+  if (placement.step === 5) {
+    const line = trigger.getClientRects()[0]?.top ?? triggerBox.top;
+    return {
+      side: placement.side,
+      dx: placement.left - triggerBox.left,
+      dy: placement.top - line,
+      column: true,
+    };
+  }
+  return {
+    side: placement.side,
+    dx: placement.left - triggerBox.left,
+    dy:
+      placement.side === 'below'
+        ? placement.top - region.bottom
+        : placement.top + placement.height - region.top,
+  };
+}
+
+/**
+ * Where `el` sits at its anchor next to `trigger`, in the viewport: its
+ * top-left corner, or `null` when the trigger has no box (inside a closed
+ * disclosure). Not for an anchor in the side column.
+ */
+export function anchoredSpot(
+  el: HTMLElement,
+  trigger: HTMLElement,
+  anchor: CardAnchor,
+  edge: number,
+): { x: number; y: number } | null {
+  if (!trigger.isConnected || trigger.getClientRects().length === 0) return null;
+  const region = regionOf(trigger).getBoundingClientRect();
+  const triggerBox = trigger.getBoundingClientRect();
+  const { width, height } = el.getBoundingClientRect();
+  const band = cardBand(edge);
+  const { low, high } = horizontalRange(band, articleColumn(trigger), width);
+  return {
+    x: clamp(triggerBox.left + anchor.dx, low, Math.max(low, high - width)),
+    y: anchor.side === 'below' ? region.bottom + anchor.dy : region.top + anchor.dy - height,
+  };
+}
+
+/**
+ * Put `el` back at its anchor after the layout moved its trigger (P1). A
+ * trigger with no box (inside a closed disclosure) leaves the card where it
+ * is. Returns whether the trigger could be measured.
+ */
+export function reanchorElement(
+  el: HTMLElement,
+  trigger: HTMLElement,
+  anchor: CardAnchor,
+  edge: number,
+): boolean {
+  const spot = anchoredSpot(el, trigger, anchor, edge);
+  if (!spot) return false;
+  moveTo(el, spot.x, spot.y);
+  return true;
+}
+
+/**
+ * The elements between `trigger` and the page that scroll on their own — a
+ * wide display equation, a wide table, a card's own body — so a card can
+ * follow its trigger when one of them scrolls (P1).
+ */
+export function scrollContainersOf(trigger: HTMLElement): HTMLElement[] {
+  const found: HTMLElement[] = [];
+  for (
+    let node = trigger.parentElement;
+    node && node !== document.body && node !== document.documentElement;
+    node = node.parentElement
+  ) {
+    const style = getComputedStyle(node);
+    if (/auto|scroll/.test(`${style.overflowX} ${style.overflowY}`)) found.push(node);
+  }
+  return found;
+}
+
+/**
+ * Call `onChange` (at most once a frame) whenever the layout may have moved a
+ * trigger: a resize, a font load, a disclosure opening or closing, a panel
+ * toggling, or anything else that changes the size of the page or the
+ * article column. Returns `schedule`, for any other event that may move a
+ * trigger (a scroll container scrolling), and `observe`, which adds one more
+ * element to watch (an open card, whose own size change moves a card placed
+ * above its trigger).
+ */
+export function watchCardLayout(onChange: () => void): {
+  schedule(): void;
+  observe(el: Element): void;
+  unobserve(el: Element): void;
+} {
+  let frame = 0;
+  const schedule = () => {
+    if (frame) return;
+    frame = requestAnimationFrame(() => {
+      frame = 0;
+      onChange();
+    });
+  };
+
+  window.addEventListener('resize', schedule, { passive: true });
+  document.fonts?.addEventListener?.('loadingdone', schedule);
+  // `toggle` does not bubble; capture sees every `<details>`.
+  document.addEventListener('toggle', schedule, true);
+  new MutationObserver(schedule).observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ['data-navigation-hidden', 'data-page-sidebar-hidden'],
+  });
+
+  const resizes = new ResizeObserver(schedule);
+  resizes.observe(document.body);
+  for (const el of document.querySelectorAll('.main-pane, .sl-markdown-content')) {
+    resizes.observe(el);
+  }
+
+  return {
+    schedule,
+    observe: (el) => resizes.observe(el),
+    unobserve: (el) => resizes.unobserve(el),
+  };
+}