@alikhalilll/a-smart-skeleton 0.0.0-stage → 2.0.0

package/src/core/memory.ts

@@ -0,0 +1,146 @@
+import { ATTR_REVEAL } from './constants';
+import { debugging, reportReveal } from './debug';
+import { isDev, sampleFrom, warnOnce } from './dev';
+import { takeLoadingSize } from './ghost';
+import { rememberShape, trackShape } from './shapes';
+import { autoKey } from './snapshot';
+
+export type MemoryOptions = {
+  id?: string;
+  /** What the content was rendered from, for the `sample` dev hint. */
+  data?: unknown;
+  /** The content is rendered from data by a function, which only `sample` or an `id` can stand in for. */
+  rendered?: boolean;
+  /** A `sample` was passed. */
+  sample?: boolean;
+};
+
+const SAVE_DELAY = 250;
+
+// Synthetic, per-element id for `warnOnce` dedupe when the consumer didn't pass one.
+// Without this every id-less skeleton shares the same `sample:null` / `jump:null` bucket,
+// so only the first warning across the whole app ever fires.
+const anonIds = new WeakMap<HTMLElement, string>();
+let anonSeq = 0;
+const anonId = (element: HTMLElement) => {
+  let id = anonIds.get(element);
+  if (!id) {
+    id = `anon:${++anonSeq}`;
+    anonIds.set(element, id);
+  }
+  return id;
+};
+
+/** Remembers the shape of shown content, so its next skeleton can be drawn from it. */
+export class Memory {
+  private key: string | null;
+  private warnKey: string;
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private mutations: MutationObserver;
+  private resize: ResizeObserver | null;
+  private untrack: () => void;
+
+  constructor(
+    private element: HTMLElement,
+    private options: MemoryOptions = {}
+  ) {
+    this.key = options.id ?? autoKey(element);
+    this.warnKey = this.key ?? anonId(element);
+    this.untrack = this.key ? trackShape(this.key, () => this.save()) : () => {};
+
+    if (isDev || debugging(element)) this.check();
+    this.save();
+
+    this.mutations = new MutationObserver(this.schedule);
+    this.mutations.observe(element, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+    // None in jsdom, which has no layout to follow
+    this.resize = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(this.schedule);
+    this.resize?.observe(element);
+    element.addEventListener('load', this.schedule, true);
+  }
+
+  private schedule = () => {
+    clearTimeout(this.timer);
+    this.timer = setTimeout(() => this.save(), SAVE_DELAY);
+  };
+
+  save() {
+    clearTimeout(this.timer);
+    if (this.key && this.element.isConnected && this.element.offsetHeight) {
+      rememberShape(this.key, this.element);
+    }
+  }
+
+  private check() {
+    const { data, id, rendered, sample } = this.options;
+    const name = id ? `<Skeleton id="${id}">` : '<Skeleton>';
+
+    const reveal = this.element.closest(`[${ATTR_REVEAL}]`);
+    const before = takeLoadingSize(reveal);
+    // Shown without a skeleton first, so nothing was guessed and nothing could move
+    if (!before) return;
+
+    if (before.guessed && rendered && !sample && data != null) {
+      warnOnce(
+        `sample:${this.warnKey}`,
+        `${name} has no \`sample\`, so a first load guesses its shape${id ? '' : " and it can't be remembered"}. Pass this to make it exact:\n  sample={${JSON.stringify(sampleFrom(data))}}`
+      );
+    }
+
+    // Unsized images settle late; compare once they have
+    const images = [...this.element.querySelectorAll('img')].filter((image) => !image.complete);
+    Promise.all(
+      images.map(
+        (image) =>
+          new Promise((resolve) => {
+            image.addEventListener('load', resolve, { once: true });
+            image.addEventListener('error', resolve, { once: true });
+          })
+      )
+    ).then(() => {
+      // Gone before it settled: a detached element measures nothing
+      if (!this.element.isConnected) return;
+      const width = this.element.offsetWidth;
+      const height = this.element.offsetHeight;
+      reportReveal(reveal, {
+        width: width - before.width,
+        height: height - before.height,
+      });
+      if (Math.abs(width - before.width) <= 1 && Math.abs(height - before.height) <= 1) {
+        return;
+      }
+      // Flat in the skeleton, tall now: nothing sized them before they loaded
+      const unsized = [...this.element.querySelectorAll('img')]
+        .filter(
+          (image, i) => (before.images[i] ?? 0) < 1 && image.getBoundingClientRect().height >= 1
+        )
+        .map((image) => image.currentSrc.split('/').pop() || 'an image');
+      if (unsized.length) {
+        warnOnce(
+          `unsized:${this.warnKey}`,
+          `${name}'s skeleton had no room for ${unsized.length === 1 ? 'an image' : `${unsized.length} images`} (${unsized.slice(0, 3).join(', ')}${unsized.length > 3 ? ', …' : ''}), so the layout jumped when they loaded. Give each \`width\` and \`height\` attributes, or an \`aspect-ratio\`, so its space is known before it loads.`
+        );
+        return;
+      }
+      warnOnce(
+        `jump:${this.warnKey}`,
+        before.guessed
+          ? `${name}'s skeleton was ${before.width}×${before.height}px but its content is ${width}×${height}px, so the layout jumped on reveal. ${rendered ? 'Pass `sample` data shaped like the real thing' : 'Pass an `id` so its shape is remembered'}, and give images a size.`
+          : `${name}'s skeleton was drawn from the data on screen (${before.width}×${before.height}px), but the new data is ${width}×${height}px, so the layout jumped on reveal. When new data adds to what's shown — another page of a list — give the addition a reveal of its own.`
+      );
+    });
+  }
+
+  destroy() {
+    this.save();
+    clearTimeout(this.timer);
+    this.mutations.disconnect();
+    this.resize?.disconnect();
+    this.element.removeEventListener('load', this.schedule, true);
+    this.untrack();
+  }
+}

package/src/core/motion.ts

@@ -0,0 +1,12 @@
+const prefers = (query: string) => typeof matchMedia !== 'undefined' && matchMedia(query).matches;
+
+// Not in jsdom, where every fade is instant
+export const canAnimate = () =>
+  typeof Element !== 'undefined' && typeof Element.prototype.animate === 'function';
+
+export const prefersReducedMotion = () =>
+  !canAnimate() || prefers('(prefers-reduced-motion: reduce)');
+
+export const prefersReducedTransparency = () => prefers('(prefers-reduced-transparency: reduce)');
+
+export const animationsOf = (element: Element): Animation[] => element.getAnimations?.() ?? [];

package/src/core/plan.ts

@@ -0,0 +1,368 @@
+import { ATTR_EXITING, CASCADE_SPREAD, FADE_DURATION } from './constants';
+
+/** Where one piece of a reveal sits: a piece of content arriving, or a rect of the skeleton leaving. */
+export type Piece = {
+  rect: DOMRect;
+  /** Its row or card: the nearest ancestor with two or more siblings like it. Null for a rect outside any. */
+  unit: DOMRect | null;
+  /** Smaller text than the largest in its unit. */
+  secondary: boolean;
+  /** The whole reveal. */
+  reveal: DOMRect;
+  /** ms since the first of the reveals landing alongside this one. */
+  late: number;
+};
+
+/** What a reveal knows as its content lands, for `choose`. */
+export type RevealContext = {
+  content: HTMLElement;
+  reveal: HTMLElement;
+  /** ms the skeleton was up; Infinity when it was server-rendered or there was none. */
+  waited: number;
+  /** Someone scrolled or typed in the last 400ms. */
+  input: boolean;
+  /** The skeleton was drawn from the data on screen. */
+  refetch: boolean;
+  height: number;
+  /** How many pieces the content arrives in. */
+  pieces: number;
+};
+
+/** One pane under a wipe: `rect` is its own box, `reveal` the box the front crosses, both in viewport px. */
+export type WipePane = { rect: DOMRect; reveal: DOMRect };
+
+/** A front crossing the whole reveal, as a mask drawn each frame. */
+export type Wipe = {
+  /** The incoming pane's `mask-image` at `progress`, 0 to 1. */
+  mask: (progress: number, pane: WipePane) => string;
+  /** The outgoing pane's; the inverse of `mask` when left out. */
+  out?: (progress: number, pane: WipePane) => string;
+  /** Runs once on the incoming pane; `progress` keeps counting past 1. */
+  effect?: (element: HTMLElement, front: WipePane & { progress: () => number }) => void;
+};
+
+/** How content replaces its skeleton; what `choose` returns as content lands wins over the fields beside it. */
+export type RevealSpec = {
+  order?: 'together' | ((piece: Piece) => number | null);
+  /** Where each piece starts from, on top of the fade: `{ filter: "blur(6px)" }`. */
+  enter?: Keyframe;
+  wipe?: Wipe;
+  delay?: number;
+  /** 0 is instant. */
+  duration?: number;
+  /** ms a skeleton waits before it shows, so data that beats it never shows one. */
+  hold?: number;
+  choose?: (context: RevealContext) => RevealSpec;
+};
+
+/** A built-in reveal by name, or one of your own. */
+export type RevealMode = 'together' | 'sequence' | 'smart' | 'sweep' | 'instant' | RevealSpec;
+
+export const SKELETON_DELAY = 150; // A skeleton up for less than this is a flash — smart holds it back
+const QUICK_FADE = 120; // A refetch, already familiar
+const SMALL_HEIGHT = 72;
+const SMALL_PIECES = 3;
+const SECONDARY_DELAY = 60; // Smaller text follows the text it sits under
+export const BATCH_WINDOW = 150; // Reveals landing this close share one top-to-bottom order
+const ACTIVE_WINDOW = 400; // Input this recent means someone is mid-gesture
+export const MAX_SWEEP_AREA = 1.5; // in screens — a wipe bigger than this crossfades: a front across it is mostly off screen, and costly
+export const MAX_DELAY = 1000; // A custom order's latest piece
+export const MAX_DURATION = 1000;
+
+// What `enter` may set: nothing that changes layout, so no reveal moves the page
+const ENTER = new Set([
+  'filter',
+  'transform',
+  'translate',
+  'scale',
+  'rotate',
+  'clipPath',
+  'easing',
+  'composite',
+]);
+
+export type SequencePlan = {
+  kind: 'sequence';
+  /** When a piece of content appears; null to appear at once. */
+  pieceDelay: (piece: Element) => number | null;
+  /** When a skeleton rect at `rect` goes; null to go at once. */
+  boneDelay: (rect: DOMRect) => number | null;
+  duration: number;
+  enter?: Keyframe;
+};
+
+export type WipePlan = {
+  kind: 'wipe';
+  wipe: Wipe;
+  /** performance.now() at progress 0. */
+  start: number;
+  duration: number;
+  reveal: DOMRect;
+  enter?: Keyframe;
+  /** Set when frames drop mid-wipe: both panes finish as a crossfade instead. */
+  stalled?: boolean;
+};
+
+export type Plan =
+  | { kind: 'instant' }
+  | { kind: 'together'; delay: number; duration: number; enter?: Keyframe }
+  | SequencePlan
+  | WipePlan;
+
+// Input, not scroll: a page restoring its scroll position isn't someone using it. No clicks: a click doesn't move what's being read
+let lastInput = -Infinity;
+let listening = false;
+function listen() {
+  if (listening || typeof addEventListener === 'undefined') return;
+  listening = true;
+  for (const type of ['wheel', 'touchmove', 'keydown']) {
+    addEventListener(type, () => (lastInput = performance.now()), {
+      passive: true,
+      capture: true,
+    });
+  }
+}
+
+const loading = new WeakMap<Element, { since: number; refetch: boolean }>();
+
+/** Notes a skeleton going up in `reveal` — when, and whether it's a refetch over the data on screen. */
+export function noteSkeleton(
+  reveal: Element,
+  { served, refetch }: { served: boolean; refetch: boolean }
+) {
+  listen();
+  const since = loading.get(reveal)?.since ?? performance.now();
+  // Server-rendered: up since the page began, so never a flash
+  loading.set(reveal, { since: served ? -Infinity : since, refetch });
+}
+
+// What a reveal brings in one by one: anything holding text or media of its own
+export function pieces(root: Element): Element[] {
+  const found: Element[] = [];
+  const visit = (element: Element) => {
+    for (const child of element.children) {
+      const ownText = [...child.childNodes].some(
+        (node) => node.nodeType === Node.TEXT_NODE && node.textContent?.trim()
+      );
+      if (!child.firstElementChild || ownText || child.localName === 'svg') {
+        found.push(child);
+      } else {
+        visit(child);
+      }
+    }
+  };
+  visit(root);
+  return found;
+}
+
+// A row of a list or a card of a grid: the piece's nearest ancestor with two or more siblings like it
+function unitOf(piece: Element, root: Element): Element {
+  for (
+    let element: Element | null = piece;
+    element && element !== root;
+    element = element.parentElement
+  ) {
+    const parent = element.parentElement;
+    if (!parent) break;
+    const alike = [...parent.children].filter(
+      (sibling) =>
+        sibling.localName === element!.localName && sibling.className === element!.className
+    );
+    if (alike.length >= 3) return element;
+  }
+  return piece;
+}
+
+const contains = (outer: DOMRect, inner: DOMRect) => {
+  const x = inner.left + inner.width / 2;
+  const y = inner.top + inner.height / 2;
+  return x >= outer.left && x <= outer.right && y >= outer.top && y <= outer.bottom;
+};
+
+/** The box a wipe crosses: the reveal, and any pane leaving it that stands taller or wider. */
+export function revealBox(root: Element): DOMRect {
+  let { left, top, right, bottom } = root.getBoundingClientRect();
+  for (const pane of root.querySelectorAll(`:scope > [${ATTR_EXITING}]`)) {
+    const rect = pane.getBoundingClientRect();
+    left = Math.min(left, rect.left);
+    top = Math.min(top, rect.top);
+    right = Math.max(right, rect.right);
+    bottom = Math.max(bottom, rect.bottom);
+  }
+  return new DOMRect(left, top, right - left, bottom - top);
+}
+
+const clamp = (value: number, max: number) => Math.min(Math.max(value, 0), max);
+
+let batch = -Infinity;
+
+/** Times each piece of `content`, and each skeleton rect it replaces, by `order`. */
+function sequencePlan(
+  content: Element,
+  root: Element,
+  order: (piece: Piece) => number | null,
+  spec: RevealSpec,
+  duration: number
+): SequencePlan {
+  const now = performance.now();
+  if (now - batch > BATCH_WINDOW) batch = now;
+  const late = now - batch;
+  const reveal = root.getBoundingClientRect();
+
+  type Unit = { rect: DOMRect; size: number };
+  const units = new Map<Element, Unit>();
+  const found = new Map<Element, { unit: Unit; size: number }>();
+  const sizeOf = (element: Element) => parseFloat(getComputedStyle(element).fontSize) || 16;
+
+  for (const piece of pieces(content)) {
+    const element = unitOf(piece, content);
+    let unit = units.get(element);
+    if (!unit) {
+      unit = { rect: element.getBoundingClientRect(), size: 0 };
+      units.set(element, unit);
+    }
+    const size = sizeOf(piece);
+    unit.size = Math.max(unit.size, size);
+    found.set(piece, { unit, size });
+  }
+
+  const at = (piece: Piece) => {
+    const delay = order(piece);
+    return delay === null ? null : clamp(delay, MAX_DELAY) + Math.max(spec.delay ?? 0, 0);
+  };
+
+  return {
+    kind: 'sequence',
+    duration,
+    enter: spec.enter,
+    pieceDelay: (element) => {
+      const piece = found.get(element);
+      if (!piece) return null;
+      return at({
+        rect: element.getBoundingClientRect(),
+        unit: piece.unit.rect,
+        secondary: piece.size < piece.unit.size,
+        reveal,
+        late,
+      });
+    },
+    boneDelay: (rect) => {
+      const unit = [...units.values()].find((unit) => contains(unit.rect, rect));
+      return at({
+        rect,
+        unit: unit?.rect ?? null,
+        // A bar shorter than its row's largest type stands for smaller text
+        secondary: !!unit && rect.height < unit.size * 0.8,
+        reveal,
+        late,
+      });
+    },
+  };
+}
+
+/** Keeps `enter` to what paints, warning in development about anything that would move the page. */
+function enterOf(enter: Keyframe | undefined, warn: (key: string) => void) {
+  if (!enter) return undefined;
+  const kept: Keyframe = {};
+  for (const [key, value] of Object.entries(enter)) {
+    if (ENTER.has(key)) kept[key] = value;
+    else if (key !== 'opacity') warn(key);
+  }
+  return kept;
+}
+
+/** Decides how `content` replaces the skeleton in `root`, now that it has arrived. */
+export function planReveal(
+  content: HTMLElement,
+  root: HTMLElement,
+  reveal: RevealSpec,
+  warn: (key: string) => void = () => {}
+): Plan {
+  const info = loading.get(root);
+  loading.delete(root);
+
+  let spec = reveal;
+  while (spec.choose) {
+    const { choose, ...rest } = spec;
+    spec = {
+      ...rest,
+      ...choose({
+        content,
+        reveal: root,
+        waited: info ? performance.now() - info.since : Infinity,
+        input: performance.now() - lastInput < ACTIVE_WINDOW,
+        refetch: !!info?.refetch,
+        height: content.getBoundingClientRect().height,
+        pieces: pieces(content).length,
+      }),
+    };
+  }
+
+  const duration = clamp(spec.duration ?? FADE_DURATION, MAX_DURATION);
+  // No floor: a wipe joining one under way starts partway, before now
+  spec = { ...spec, delay: Math.min(spec.delay ?? 0, MAX_DELAY) };
+  if (!duration) return { kind: 'instant' };
+  const enter = enterOf(spec.enter, warn);
+
+  if (spec.wipe) {
+    const rect = revealBox(root);
+    if (rect.width * rect.height <= innerWidth * innerHeight * MAX_SWEEP_AREA) {
+      return {
+        kind: 'wipe',
+        wipe: spec.wipe,
+        start: performance.now() + (spec.delay ?? 0),
+        duration,
+        reveal: rect,
+        enter,
+      };
+    }
+  } else if (typeof spec.order === 'function') {
+    return sequencePlan(content, root, spec.order, { ...spec, enter }, duration);
+  }
+  return {
+    kind: 'together',
+    delay: Math.max(spec.delay ?? 0, 0),
+    duration,
+    enter,
+  };
+}
+
+/** `sequence`: each piece timed by its place in the reveal, top to bottom, then a little left to right. */
+export const byPosition = ({ rect, reveal }: Piece) => {
+  const down = (rect.top - reveal.top) / Math.max(reveal.height, 1);
+  const across = (rect.left - reveal.left) / Math.max(reveal.width, 1);
+  return clamp(down * 0.8 + across * 0.2, 1) * CASCADE_SPREAD;
+};
+
+const onScreen = (rect: DOMRect) => rect.bottom > 0 && rect.top < innerHeight;
+
+/** `smart`'s order: rows arrive whole, in page order, on screen only, main text first. */
+export const byRow = ({ rect, unit, secondary, late }: Piece) => {
+  if (!unit) return onScreen(rect) ? 0 : null;
+  if (!onScreen(unit)) return null;
+  // Timed against the screen, not the reveal, so reveals landing together read as one page
+  const at = clamp(unit.top / innerHeight, 1) * CASCADE_SPREAD;
+  return Math.max(at - late, 0) + (secondary ? SECONDARY_DELAY : 0);
+};
+
+export const instant: RevealSpec = { duration: 0 };
+export const together: RevealSpec = { order: 'together' };
+export const sequence: RevealSpec = { order: byPosition };
+
+/** The cases `smart` settles before looking at the content: instant, or a quick crossfade. */
+export const quickly = (context: RevealContext): RevealSpec | null =>
+  context.input || context.waited < SKELETON_DELAY
+    ? instant
+    : context.refetch
+      ? { order: 'together', duration: QUICK_FADE }
+      : null;
+
+/** `together` for a small reveal, else `byRow`. */
+export const byContent = (context: RevealContext): RevealSpec =>
+  context.height < SMALL_HEIGHT || context.pieces <= SMALL_PIECES ? together : { order: byRow };
+
+/** Picks for each reveal from how it loaded and what it holds, holding its skeleton back a moment. */
+export const smart: RevealSpec = {
+  hold: SKELETON_DELAY,
+  choose: (context) => quickly(context) ?? byContent(context),
+};

package/src/core/reveal.ts

@@ -0,0 +1,89 @@
+import { ATTR_GHOST, ATTR_PANE, ATTR_REVEAL, ATTR_STATUS } from './constants';
+import { fadeIn, fadeOut } from './fade';
+import type { RevealMode } from './plan';
+import { Ghost } from './ghost';
+import { Memory } from './memory';
+import { addStyles, removeStyles } from './styles';
+
+export type RevealOptions = {
+  /** Remembers the shape under this key; without it, one is derived from the markup. */
+  id?: string;
+  /** How content replaces its skeleton: `smart` (the default), `together`, `sequence`, `sweep`, or a `RevealSpec` of your own. */
+  reveal?: RevealMode;
+  /** Read to screen readers while loading, in place of the skeleton — "Loading profile". */
+  label?: string;
+  /** Called once content has come in over a skeleton. */
+  onReveal?: () => void;
+};
+
+/** Shows a skeleton of content while it loads, then crossfades to the content itself. */
+export class Reveal {
+  private current: HTMLElement | null = null;
+  private ghost: Ghost | null = null;
+  private memory: Memory | null = null;
+  private arrival: Promise<void> = Promise.resolve();
+
+  constructor(
+    private element: HTMLElement,
+    private options: RevealOptions = {}
+  ) {
+    addStyles();
+    element.setAttribute(ATTR_REVEAL, '');
+  }
+
+  /** Shows a skeleton measured from `content`, rendered from sample data, or else the shape last shown. */
+  load(content?: Node | string): HTMLElement {
+    const loading = document.createElement('div');
+    const ghost = document.createElement('div');
+    ghost.setAttribute(ATTR_GHOST, '');
+    if (content) ghost.append(content);
+    loading.append(ghost);
+
+    const pane = this.swap(loading);
+    // Outside the skeleton, which is hidden from screen readers
+    if (this.options.label) {
+      const status = document.createElement('span');
+      status.setAttribute(ATTR_STATUS, '');
+      status.textContent = this.options.label;
+      pane.prepend(status);
+    }
+    this.element.setAttribute('aria-busy', 'true');
+    this.ghost = new Ghost(loading, { id: this.options.id });
+    return pane;
+  }
+
+  show(content: Node | string): HTMLElement {
+    const loading = this.element.getAttribute('aria-busy') === 'true';
+    const pane = this.swap(content);
+    if (loading && this.options.onReveal) this.arrival.then(this.options.onReveal);
+    this.element.removeAttribute('aria-busy');
+    this.memory = new Memory(pane, { id: this.options.id });
+    return pane;
+  }
+
+  private swap(content: Node | string) {
+    this.memory?.destroy();
+    this.ghost?.destroy();
+    this.memory = this.ghost = null;
+
+    const pane = document.createElement('div');
+    pane.setAttribute(ATTR_PANE, '');
+    pane.append(content);
+
+    const previous = this.current;
+    this.current = pane;
+
+    // Popped out before the new pane lands, while it still measures where it stood
+    if (previous) fadeOut(previous).then(() => previous.remove());
+    this.element.append(pane);
+    this.arrival = fadeIn(pane, this.options.reveal, { initial: !previous });
+
+    return pane;
+  }
+
+  destroy() {
+    this.memory?.destroy();
+    this.ghost?.destroy();
+    removeStyles();
+  }
+}

package/src/core/reveals.ts

@@ -0,0 +1,39 @@
+import { CASCADE_SPREAD, FADE_DURATION } from './constants';
+import {
+  instant,
+  MAX_DELAY,
+  MAX_DURATION,
+  sequence,
+  smart,
+  together,
+  type RevealMode,
+  type RevealSpec,
+} from './plan';
+import { sweep, SWEEP_SPREAD } from './sweep';
+
+// `instant` is advertised as a string mode in the README and is exported as a
+// `RevealSpec`, but was previously missing from this map, so passing
+// `reveal="instant"` returned `undefined` and crashed `arrive()` with
+// "Cannot read properties of undefined (reading 'hold')".
+const NAMED = { together, sequence, smart, sweep, instant };
+
+// Unknown strings fall back to `smart` instead of crashing — a stale template
+// or a typo should quietly do the right thing, not blow up the reveal.
+export const revealSpec = (mode: RevealMode = 'smart'): RevealSpec => {
+  if (typeof mode !== 'string') return mode;
+  return (NAMED as Record<string, RevealSpec>)[mode] ?? smart;
+};
+
+/** Longest a pane can take to leave under `mode`, for a framework that has to know up front. */
+export function exitDuration(mode?: RevealMode) {
+  const spec = revealSpec(mode);
+  const hold = spec.hold ?? 0;
+  if (spec === together) return FADE_DURATION;
+  if (spec === sequence) return CASCADE_SPREAD + FADE_DURATION;
+  if (spec === smart) return hold + CASCADE_SPREAD + FADE_DURATION;
+  if (spec === sweep) return hold + SWEEP_SPREAD + FADE_DURATION;
+  if (spec.duration === 0) return 0;
+  // A choice can bring its own delay, as long as the cap allows
+  const delay = spec.choose ? MAX_DELAY : Math.min(Math.max(spec.delay ?? 0, 0), MAX_DELAY);
+  return hold + delay + MAX_DELAY + MAX_DURATION;
+}