Front-end kits

{% extends "tables/play.html" %}{% load static %}
{% comment %}
Contract Rummy's page: the game's files under games/static/games/contract-rummy/,
in the room (games/static/games/room/) and the card room (games/static/games/cards/;
docs/adr/0009, 0015). Its styles load in that order: the table style's tokens,
the room's structure, the cards, the game's own, then the house kit's sheets,
toasts and Options (games/static/games/house/, ADR 0025), drawn from them.
{% endcomment %}
{% block html_attrs %} data-theme="clubhouse"{% endblock %}
{% block theme_color %}#1d4a3c{% endblock %}
{% block head %}
  {# Put on the player's table style before anything paints. #}
  <script>try { var t = JSON.parse(localStorage.getItem('uo:cards:theme')); if (t) document.documentElement.dataset.theme = t; } catch (e) {}</script>
  <link rel="stylesheet" href="{% static 'games/cards/themes.css' %}">
  <link rel="stylesheet" href="{% static 'games/room/room.css' %}">
  <link rel="stylesheet" href="{% static 'games/cards/cards.css' %}">
  <link rel="stylesheet" href="{% static 'games/contract-rummy/rummy.css' %}">
  <link rel="stylesheet" href="{% static 'games/house/house.css' %}">
{% endblock %}

// The house kit: the one implementation of what every UO game shares
// (docs/design-language.md, "Using the house kit"; ADR 0025). A game imports
// from here and loads house.css after its own tokens; the look stays the
// game's, drawn from the tokens its root declares.
//
//   import { configure, sheet, toast, openOptions, result } from '../../house/ui.js';

export { h, keep, copy, plural, clockText, configure, button, link, tabStops, handFocus } from './dom.js';
export { sheet, actionRow, sheetsOpen, topSheet, onSheets, setSheetClock, closeTop, closeSheets, hideBoard, escapeOverSheets } from './sheet.js';
export { toast, clearToasts, banner, bannerQueued, skipBanner, clearBanners, catchingUp, splash } from './toast.js';
export { announce, skipAnnouncement, clearAnnouncements, ANNOUNCE_MS } from './announce.js';
export { celebrate, stopCelebration, CHEERS } from './celebrate.js';
export { prompt, beckon, cueOn, cueOption } from './cue.js';
export { prefs, seg, setting, onOff, optionRows, openOptions, feedbackRow, ROW, SECTIONS, HELPERS_NOTE, ON_OFF } from './options.js';
export { shortcuts, typing, isSingleKey, kbd, keyCap, showKeyCaps, finePointer, shortcutsDefault } from './keys.js';
export { MOTION, EASE, reducedMotion, motionMs, play, wait, sweepTiming, dealDelays } from './motion.js';
export { backArrow, backArrowHTML, BACK_PATH, closeIcon, CLOSE_PATH, guideHref, guideLink, guideLinkHTML } from './nav.js';
export { result, shareResult, rateLine, ratingLine, record, STATES, celebrateResults } from './end.js';
export { brag, facts, placeLine, roundRow, podium, medal, bar, EMOJI } from './brag.js';
export { feedbackLink, footFeedback, footFeedbackHTML, openFeedback, feedbackUrl } from './feedback.js';
export { openInstall, homeScreenButton, shouldOffer, detect, environment, isStandalone } from './install.js';

/** configure({ buttons: { primary, secondary, quiet, danger }, app }):
 * the class names each button weight wears, and the selector of what goes
 * inert behind a sheet. Call it once before anything opens. */
export function configure({ buttons, app } = {}) {
  if (buttons) Object.assign(settings.buttons, buttons);
  if (app) settings.app = app;
  return { buttons: { ...settings.buttons }, app: settings.app };
}

const show = () => {
  handle.waiting = false;
  handle.open = true;
  opener = document.activeElement;
  opened = performance.now();
  if (!stack.length) lockPage();
  else stack.at(-1).el.inert = true;
  stack.push(handle);
  if (sheetClock) {
    const draw = () => {
      const left = sheetClock?.();
      clock.hidden = left === null || left === undefined;
      if (!clock.hidden) clock.textContent = left > 0 ? `${Math.ceil(left)}s left` : 'Time’s up';
    };
    draw();
    ticking = setInterval(draw, 250);
  }
  document.body.append(handle.el);
  const wanted = typeof opts.focus === 'function' ? opts.focus(handle) : opts.focus;
  (wanted || firstFocus(handle.foot) || x || handle.box).focus({ preventScroll: true });
  changed();
  opts.onopen?.(handle);
};

function lockPage() {
  const root = document.documentElement;
  const gutter = (globalThis.innerWidth || 0) - (root.clientWidth || 0);
  // The scrollbar's space is kept, so nothing behind shifts sideways.
  if (gutter > 0) root.style.scrollbarGutter = 'stable';
  root.classList.add('house-locked');
  const app = appRoot();
  appWasInert = !!app?.inert;
  if (app) app.inert = true;
  document.addEventListener('keydown', onkey, true);
}

function onkey(e) {
  const top = topSheet();
  if (!top) return;
  if (e.key === 'Escape') {
    // Escape undoes the last layer, only that: what's over the sheets
    // first (an announcement), else the top sheet.
    e.preventDefault();
    e.stopImmediatePropagation();
    if ([...overSheets].reverse().some(fn => fn())) return;
    if (top.dismissable) top.close('escape');
    return;
  }
  if (e.key !== 'Tab') return;
  const stops = tabStops(top.box);
  if (!stops.length) { e.preventDefault(); top.box.focus(); return; }
  const first = stops[0], last = stops.at(-1), at = document.activeElement;
  if (!top.box.contains(at)) { e.preventDefault(); first.focus(); }
  else if (e.shiftKey && (at === first || at === top.box)) { e.preventDefault(); last.focus(); }
  else if (!e.shiftKey && at === last) { e.preventDefault(); first.focus(); }
}

/**
 * One row of actions, in the house order: quiet ones at the far left, then
 * the secondaries, then the primary at the right end. Each action is
 * { label, weight: 'primary' | 'secondary' | 'quiet', onclick(handle, e),
 * href, danger, keepOpen, key, disabled, name }; secondaries are listed
 * nearest the primary first. A sheet's action closes it after its onclick,
 * unless it's `keepOpen` (Share result) or a link. Returns the row's
 * element, with each button on `.buttons[name || label]`.
 */
export function actionRow(actions, handle = null, cls = 'house-foot') {
  const list = actions.filter(Boolean).map((a, i) => ({ weight: 'secondary', ...a, i }));
  // Primary last; secondaries reversed (the first named sits by the primary); quiet first, in order.
  list.sort((a, b) => (RANK[a.weight] - RANK[b.weight]) || (a.weight === 'secondary' ? b.i - a.i : a.i - b.i));
  const row = h(`div.${cls}`);
  row.buttons = {};
  for (const a of list) {
    const weight = a.danger ? 'danger' : a.weight;
    const el = a.href
      ? link(weight, a.label, a.href)
      : button(weight, a.label, e => {
        const keepOpen = a.onclick?.(handle, e) === false || a.keepOpen;
        if (!keepOpen) handle?.close(a.name || 'action');
      }, { disabled: !!a.disabled });
    el.dataset.weight = a.weight;
    if (a.danger) el.dataset.danger = '';
    if (a.key) el.setAttribute('aria-keyshortcuts', a.key);
    row.buttons[a.name || a.label] = el;
    row.append(el);
  }
  return row;
}

/** Where focus starts in a row: the primary, or the safe button beside it
 * when the primary is a danger (a stray Enter mustn't do it). */
function firstFocus(row) {
  const kids = [...(row?.children || [])].filter(b => !b.disabled);
  const primary = kids.find(b => b.dataset.weight === 'primary');
  if (primary && !('danger' in primary.dataset)) return primary;
  return kids.filter(b => b.dataset.weight === 'secondary' && !('danger' in b.dataset)).at(-1) || null;
}

/**
 * result(options) opens the result sheet (waiting, like any sheet that
 * opens by itself, for the player's own sheets to close) and returns its
 * handle, with post(text) to change the post line and `actions` (the row,
 * without See the board, for the game's dock).
 *
 * options:
 * - state: 'won' | 'lost' | 'stuck' | 'gaveup' | 'hand' | 'over'.
 * - kicker, heading (the game's voice; a plain default by state).
 * - emblem: the game's picture or celebration (a node, or a function).
 * - celebrate: 'win' (a table game won), 'best' (a personal best), 'daily'
 *   (a daily solved), or null (celebrate.js). It plays behind the sheet as
 *   it opens; handle.celebrate(kind) plays one later (a rating high, once
 *   the post comes back). A table's game over that names none gets the
 *   room's (celebrateResults).
 * - news: a game's own milestone in a word or two ("New best", "First
 *   solve"), a tag over the facts that pops in as the sheet opens; null
 *   for none. The compare lines still say it in full.
 * - facts: [[label, value]] or nodes ("1:09" time, "84" moves).
 * - compare: lines (strings or nodes): your best, your streak, rateLine().
 * - body: anything else the game shows (a score chart), after compare.
 * - post: the post line ("#3 of 20 today."), changed later with post().
 * - primary: { label, onclick } (the default label: New {noun}, Next hand
 *   or Play again); null for none ("The host can start another game.").
 * - noun: 'deal', 'puzzle', 'chart', 'case' …
 * - share: a function (the game's own) or { text, url, title }.
 * - leaderboard: its address, or a function.
 * - restart, undo: functions, for lost and stuck.
 * - back: { label, href } for a table's game over ("Back to Euchre").
 * - extra: more secondaries, after the standard ones.
 * - see: 'board' or 'table' (the quiet button's noun).
 * - onsee(actions): put away (See the board, Escape, ✕ or the scrim); the
 *   game shows these actions in its dock.
 * - onclose(how): after any close.
 */
export function result(opts = {}) {
  const {
    state = 'won', kicker = null, heading = HEADINGS[state] || HEADINGS.won, emblem = null, news = null, facts = [], compare = [], body = null,
    post = '', noun = 'game', share = null, leaderboard = null, restart = null, undo = null, back = null, extra = [], see = 'board',
    onsee = null, onclose = null,
  } = opts;
  if (!STATES.includes(state)) throw new Error(`No result state called ${state}`);

  const defaultPrimary = state === 'hand' ? 'Next hand' : state === 'over' ? 'Play again' : `New ${noun}`;
  const primary = opts.primary === null ? null : { label: defaultPrimary, ...(opts.primary || {}) };
  const actions = [];
  if (primary) actions.push({ ...primary, weight: 'primary', name: 'primary' });

  // Secondaries, nearest the primary first.
  const shareAction = share && {
    label: 'Share result', name: 'share', keepOpen: true,
    onclick: typeof share === 'function' ? share : () => { shareResult(share); },
  };
  if (state === 'won') {
    if (shareAction) actions.push(shareAction);
    // (#you: the board brings your row into view and lights it once, static/js/board.js)
    if (leaderboard) actions.push(typeof leaderboard === 'string' ? { label: 'Leaderboard', href: leaderboard.includes('#') ? leaderboard : `${leaderboard}#you`, name: 'leaderboard' } : { label: 'Leaderboard', onclick: leaderboard, name: 'leaderboard' });
  } else if (state === 'lost' || state === 'stuck') {
    if (restart && primary?.label !== 'Restart') actions.push({ label: 'Restart', onclick: restart, name: 'restart' });
    if (undo) actions.push({ label: 'Undo', onclick: undo, name: 'undo', key: 'Z' });
  } else if (state === 'over') {
    if (shareAction) actions.push(shareAction);
  }
  for (const a of extra) actions.push({ ...a, weight: 'secondary' });

  // The quiet one, at the far left.
  const seeLabel = `See the ${see}`;
  if (state === 'over' && back) actions.push({ label: back.label, href: back.href, weight: 'quiet', name: 'back' });
  else actions.push({ label: seeLabel, weight: 'quiet', name: 'see' });

  const postLine = h('p.house-post', { role: 'status' }, post);
  const content = h('div.house-result-body',
    emblem ? h('div.house-emblem', typeof emblem === 'function' ? emblem() : emblem) : null,
    // (a tag the eye lands on; the compare line under it is what's read out)
    news ? h('p.house-news', { 'aria-hidden': 'true' }, h('span', news)) : null,
    facts.length ? h('div.house-facts', facts.map(f => (f instanceof Node ? f : h('div.house-fact', h('b', f[1]), h('span', f[0]))))) : null,
    compare.filter(Boolean).length ? h('div.house-compare', compare.filter(Boolean).map(c => (c instanceof Node ? c : h('p', c)))) : null,
    body,
    postLine);

  const forDock = actions.filter(a => a.name !== 'see');
  const said = 'celebrate' in opts ? opts.celebrate : overCheer(state);
  let opening = said && typeof said === 'object' ? said.kind : said;
  const onplay = said && typeof said === 'object' ? said.onplay : null;
  let party = null;
  const played = new Set(); // each kind plays once on a sheet (a best, then a rating high: once)
  let deferred = null, onseen = null;
  // (the sheet's own handle: onopen runs before sheet() has returned)
  const play = (which, at, rising = false) => {
    if (!CHEERS[which] || !at?.open || played.has(which)) return;
    if (document.hidden) {
      // A game over in a hidden tab: it plays when the tab's seen again, if
      // the sheet's still open (the newest asked for, if several).
      deferred = { which, rising };
      if (!onseen) {
        onseen = () => {
          if (document.hidden) return;
          document.removeEventListener('visibilitychange', onseen);
          onseen = null;
          const d = deferred;
          deferred = null;
          if (d && at.open) play(d.which, at, true);
        };
        document.addEventListener('visibilitychange', onseen);
      }
      return;
    }
    const c = cheer(which, { over: at.el, from: at.box, rising });
    if (!c.live) return;
    party = c;
    played.add(which);
    if (which === opening) onplay?.();
  };
  const handle = sheet(heading, content, {
    kicker, actions, auto: opts.auto ?? true, kind: 'result',
    onopen: at => play(opening, at, true),
    className: `house-result house-${state}`,
    onclose: how => {
      party?.stop();
      if (onseen) document.removeEventListener('visibilitychange', onseen);
      onseen = null;
      const putAway = !['primary', 'restart', 'undo', 'leaderboard', 'back', 'all'].includes(how) && !extra.some(a => (a.name || a.label) === how);
      if (putAway) onsee?.(forDock);
      // A finished game or puzzle, put away: the one moment it's polite to
      // mention the Home Screen (install.js decides whether it's time).
      if (putAway && (state === 'won' || state === 'over')) offerAfterResult();
      onclose?.(how);
    },
  });
  handle.post = text => { postLine.replaceChildren(...[text].flat().filter(x => x !== null && x !== undefined)); };
  handle.actions = forDock;
  handle.state = state;
  // Later (a rating high, once the post comes back): a sheet still waiting
  // its turn opens with it instead; a kind already played isn't played again.
  handle.celebrate = which => {
    if (handle.waiting) { if (CHEERS[which]) opening = which; return; }
    play(which, handle);
  };
  return handle;
}

/** The message: "{emoji} {title} · {head}", then each line (empty ones
 * dropped), then the link. */
export function brag({ game, title, head = '', lines = [], url = '' }) {
  const top = `${EMOJI[game] ? `${EMOJI[game]} ` : ''}${title}${head ? ` · ${head}` : ''}`;
  return [top, ...lines.flat().filter(Boolean), url].filter(Boolean).join('\n');
}

/** Share result: the game's few lines (brag.js) with the link last. On a
 * phone with a share sheet it shares; elsewhere it copies and says so. The
 * link goes inside the text, never as the share's own url: a text thread
 * given both often sends one and drops the other, and a copy has only the
 * text. Called straight from the tap, with nothing awaited first, so the
 * share sheet (and the clipboard) still count it as the player's. */
export async function shareResult({ text, url = '', title = '' }) {
  const said = url && !text.includes(url) ? `${text}\n${url}` : text;
  const coarse = (() => { try { return matchMedia('(pointer: coarse)').matches; } catch { return false; } })();
  if (coarse && navigator.share) {
    try { await navigator.share({ title, text: said }); return 'shared'; } catch (err) { if (err?.name === 'AbortError') return 'cancelled'; }
  }
  const ok = await copy(said);
  toast(ok ? 'Copied — paste it anywhere.' : 'Couldn’t copy it. Try again.');
  return ok ? 'copied' : 'failed';
}

/** How long each plays, in to out, how long its still picture stays, and
 * (on a phone) how long it's seen before the sheet covers it: the first
 * volley, the burst, the ring, the first two shells bursting. */
export const CHEERS = Object.freeze({
  win: { ms: 3000, still: 1800, lead: 900 },
  best: { ms: 2300, still: 1600, lead: 800 },
  sweep: { ms: 5200, still: 2600, lead: 1500 },
  daily: { ms: 1100, still: 1000, lead: 700 },
});

/** Whether a sheet (its box `r`) covers what's behind it in `box` (its
 * scrim): a phone's, about as wide as the window, or one leaving under a
 * third of a short window above it (a phone on its side). */
export function covers(r, box) {
  if (!r?.width || !box?.width || !box?.height) return false;
  return r.width >= box.width * 0.85 || (box.height < 520 && r.top - box.top < box.height * 0.3);
}

/** What a table's game over celebrates for this browser (house/end.js
 * celebrateResults): `win` when your place is first, else `best` for a
 * rating high, as { kind, onplay }; null for a hand over, a loss, a
 * spectator, or a game already celebrated here. Once a game: onplay marks
 * it, once it has played, so a reload doesn't replay it and a second game
 * at the same table gets its own. */
export function gameOverCheer(state, t, { spectating = false, store = keep } = {}) {
  if (state !== 'over' || spectating || !t || t.you === null || t.you === undefined) return null;
  const kind = t.standings?.places?.[t.you] === 1 ? 'win' : t.rating?.high ? 'best' : null;
  const once = `${t.code}:${t.game_no}`;
  if (!kind || store.get(CHEERED, []).includes(once)) return null;
  return {
    kind,
    onplay: () => {
      const seen = store.get(CHEERED, []);
      if (!seen.includes(once)) store.set(CHEERED, [...seen, once].slice(-20));
    },
  };
}

/**
 * toast(text, { action, onaction, ms }) shows a short message and returns
 * { dismiss }. `action` is one quiet button's label; pressing it runs
 * onaction and puts the toast away. The same text already showing or
 * waiting isn't said twice.
 */
export function toast(text, { action = null, onaction = null, ms = action ? MOTION.toastAction : MOTION.toast } = {}) {
  const same = [showing, ...queue].find(t => t && t.text === text && !t.gone);
  if (same) return same.handle;
  const t = { text, action, onaction, ms, gone: false };
  t.handle = { dismiss: () => end(t) };
  queue.push(t);
  if (!showing) next();
  else hurry();
  return t.handle;
}

/** catchingUp(true) as older moves start going to their end at once (the
 * room's Cues: catchUp(), a queue too far behind), catchingUp(false) once
 * the queue's idle again; calls nest. */
export function catchingUp(on) {
  if (on) catching++;
  else if (catching > 0 && --catching === 0) catchTail = performance.now() + CATCH_TAIL_MS;
}

/**
 * announce({ kicker, title, sub, art }, { over, ms, read, say, replace,
 * className, onend }) and returns { skip, done } (done resolves with
 * 'played', 'skipped' or 'dropped').
 * - title: the news in a few words, the verb first where there is one; a
 *   *phrase in asterisks* (a painting's name) is set in italics
 *   ("Ana stole your card", "Basil bought Water Lilies"). kicker: a word over it
 *   ("Sold", "Streak"). sub: at most one short line under it.
 *   art: a node shown beside the title (a card, a seat's token).
 * - over: the element it's centered on (the table); the window by default.
 * - ms: how long, in to out (ANNOUNCE_MS; 3200 at most).
 * - read: whether it's read out (true); say: the words read, if not these.
 */
export function announce({ kicker = '', title = '', sub = '', art = null } = {}, opts = {}) {
  const { over = null, ms = ANNOUNCE_MS, read = true, say = null, replace = false, className = '', onend = null } = opts;
  if (replace) clearAnnouncements();
  let resolveDone;
  const a = { kicker, title, sub, art, over, ms: Math.min(Math.max(ms, HURRY_MS), 3200), read, say, className, onend, gone: false };
  a.done = new Promise(r => { resolveDone = r; });
  a.resolve = how => { if (a.how) return; a.how = how; a.onend?.(how); resolveDone(how); };
  a.handle = { skip: () => (showing === a ? a.skip?.() : drop(a)), done: a.done };
  queue.push(a);
  while (queue.length > MOST) drop(queue[0]);
  if (!showing) next();
  else hurry();
  return a.handle;
}

/**
 * beckon(targets, { after }) rings each target (an element, a list or a
 * NodeList) after `after` ms (MOTION.beckonIdle, a few seconds, by default;
 * 0 at once), until stop() or a press on any of them. Returns { stop }.
 * Beckoning the same targets again restarts the wait.
 */
export function beckon(targets, { after = MOTION.beckonIdle, untilPress = true } = {}) {
  const els = list(targets);
  if (!els.length || !cueOn()) return { stop() {} };
  let timer = null, stopped = false;
  const stop = () => {
    if (stopped) return;
    stopped = true;
    clearTimeout(timer);
    for (const el of els) {
      el.classList.remove('house-beckon');
      el.removeEventListener('pointerdown', stop);
    }
  };
  const ring = () => { if (!stopped) for (const el of els) el.classList.add('house-beckon'); };
  for (const el of els) {
    el.classList.remove('house-beckon');
    if (untilPress) el.addEventListener('pointerdown', stop, { once: true });
  }
  if (after > 0) timer = setTimeout(ring, after); else ring();
  return { stop };
}

/**
 * openOptions(spec, { slug, store, onchange, onclose }) opens the Options
 * sheet: the sections in order, closed with Done. Without a store, choices
 * are kept under `uo:<slug>:options`. Returns the sheet's handle.
 */
export function openOptions(spec, { slug = null, store = null, onchange = null, onclose = null } = {}) {
  store ||= slug ? prefs(`uo:${slug}:options`) : null;
  const rows = optionRows(spec, { store, onchange });
  const home = homeScreenRow();
  if (home) rows.push(home);
  const feedback = feedbackRow();
  if (feedback) rows.push(feedback);
  return sheet('Options', h('div.house-options', rows), { onclose, className: 'house-options-sheet' });
}

/**
 * prefs(key, defaults): a game's choices, kept together under one key in
 * this browser ({ get(id), set(id, value), all() }). What isn't kept yet
 * reads as its default; a browser that can't keep things just forgets.
 */
export function prefs(key, defaults = {}) {
  const read = () => {
    const kept = keep.get(key, {});
    return kept && typeof kept === 'object' && !Array.isArray(kept) ? kept : {};
  };
  return {
    key,
    defaults,
    get: id => { const kept = read(); return id in kept ? kept[id] : defaults[id]; },
    set: (id, value) => keep.set(key, { ...read(), [id]: value }),
    all: () => ({ ...defaults, ...read() }),
  };
}

/**
 * shortcuts({ z: undo, '?': howTo, ... }, { on, dragging, target, mod })
 * listens for single keys and returns a function that stops listening.
 * - on(): whether Shortcut keys is on (single keys are dropped when it's off;
 *   the keys in `always` still work).
 * - dragging(): true mid-drag (nothing fires).
 * - mod: { z: undo, y: redo } for Ctrl/⌘ variants, which fire whatever the
 *   Shortcut keys option says (they're the browser's own habit).
 * - always: { ArrowLeft: …, Enter: … } for keys that always work.
 * Keys are matched case-insensitively for letters; a handler that returns
 * false lets the key go on to the page.
 */
export function shortcuts(keys = {}, { on = () => true, dragging = () => false, target = document, mod = {}, always = {} } = {}) {
  const lower = o => Object.fromEntries(Object.entries(o).map(([k, v]) => [k.length === 1 ? k.toLowerCase() : k, v]));
  const single = lower(keys), withMod = lower(mod), fixed = lower(always);
  const listener = e => {
    if (e.defaultPrevented || e.repeat || typing(e) || sheetsOpen() || dragging()) return;
    const key = e.key.length === 1 ? e.key.toLowerCase() : e.key;
    let fn;
    if (e.ctrlKey || e.metaKey) {
      if (e.altKey) return;
      fn = withMod[key];
    } else if (e.altKey) {
      return;
    } else if (fixed[key]) {
      fn = fixed[key];
    } else if (isSingleKey(e.key) && on()) {
      fn = single[key];
    }
    if (!fn) return;
    if (fn(e) === false) return;
    e.preventDefault();
  };
  target.addEventListener('keydown', listener);
  return () => target.removeEventListener('keydown', listener);
}

/** Milliseconds, by name. */
export const MOTION = Object.freeze({
  press: 120,      // a button going down
  lift: 150,       // hover or focus on a box or card
  quick: 150,      // the most a hover or press may take (house rule 11)
  glide: 250,      // your own move, place to place (ease-out)
  stagger: 22,     // between the cards of a run that glide together
  reflow: 220,     // the hand closing up
  flight: 380,     // someone else's (or a helper's) move across the table
  flightLong: 580, // a long one
  deal: 250,       // each card from the dealer
  dealGap: 40,     // between dealt cards (1.5s in all at most)
  flip: 240,       // a card turning over, through its edge
  sweepHold: 900,  // a finished trick, its winner ringed
  sweepHoldRelaxed: 1350,
  sweep: 350,      // then the trick slides to the winner
  arrive: 350,     // a card joining your hand
  pop: 200,        // a mark placed
  nope: 360,       // a refused move's shake
  pulse: 1200,     // a place that just changed, once
  sheetIn: 150,    // a sheet or toast appearing
  sheetOut: 150,   // and going
  banner: 2000,    // a game moment, fades included
  announce: 2000,  // a strong announcement (announce.js), in to out
  toast: 4500,     // how long a toast stays
  toastAction: 6000, // one with an action
  splash: 3400,    // a new hand's splash, at most
  prompt: 2600,    // a "your move" card (cue.js), in to out
  beckon: 1600,    // one breath of the ring round what to press
  beckonIdle: 3000, // how long a routine turn waits before the ring
  celebrate: 1000, // a puzzle's settle when solved
  hold: 1200,      // someone else's move, held before the next one's motion starts
  holdKey: 2000,   // a deciding one (a sale, a ruling, a guess, a call)
  catchUp: 1500,   // your turn with more than this still to play: older moves jump to their end
  emote: 3200,     // someone's emote rising up the screen, fading as it goes (room/kit/talk.js)
});

/* Reduced motion: nothing travels, every change lands at once; fades of
   150ms or less stay; a celebration is a still picture (celebrate.js). A game that times its motion
   with these tokens gets this for nothing. */
@media (prefers-reduced-motion: reduce) {
  :where(:root) {
    --m-glide: 0ms; --m-stagger: 0ms; --m-reflow: 0ms; --m-flight: 0ms; --m-flight-long: 0ms;
    --m-deal: 0ms; --m-deal-gap: 0ms; --m-flip: 0ms; --m-sweep: 0ms; --m-arrive: 0ms;
    --m-pop: 0ms; --m-nope: 0ms; --m-celebrate: 0ms;
  }
}

/** How long a named motion takes here: its time, or 0 under reduced motion
 * (except a fade short enough to keep). */
export function motionMs(name, { fade = false } = {}) {
  const ms = typeof name === 'number' ? name : MOTION[name];
  if (ms === undefined) throw new Error(`No motion called ${name}`);
  if (!reducedMotion()) return ms;
  return fade ? Math.min(ms, FADE_OK) : 0;
}

/** backArrow({ href, label, onclick }): the arrow. With an `href` it's a
 * link (so a middle-click or a long-press works, and the address shows);
 * an `onclick` runs first and may stop the link (preventDefault) when a
 * game has something to save or confirm before it leaves. Without an
 * `href` it's a button. `label` is its name and its tooltip, "More games"
 * on a home. */
export function backArrow({ href, label = 'More games', onclick, extra = {} } = {}) {
  const attrs = { class: 'house-back', 'aria-label': label, title: label, ...extra };
  const el = href === undefined ? h('button', { type: 'button', ...attrs }) : h('a', { href, ...attrs });
  el.append(icon());
  if (onclick) el.addEventListener('click', onclick);
  return el;
}

/** Whether it's time to offer it by itself: a pure answer from the
 * environment, what's kept and the clock, so it can be tested. */
export function shouldOffer(env, state, { now = Date.now(), prompt = !!deferred, shown = shownHere } = {}) {
  if (env.standalone || env.os === 'other' || shown) return false;
  if (state.never || state.installed || state.asked >= MAX_ASKS) return false;
  if (state.visits < MIN_VISITS) return false;
  // Android's Install button is the whole offer: with no prompt to wire it to, there's nothing to ask for.
  if (env.os === 'android' && env.canAdd && !prompt) return false;
  if (state.asked > 0 && (now - state.askedAt < SNOOZE_DAYS * DAY || state.visits - state.askedVisits < SNOOZE_VISITS)) return false;
  return true;
}

/**
 * The very last section of every game's Options, for a signed-in player
 * only: Feedback, which opens the house kit's Feedback sheet over Options
 * (feedback.js, docs/adr/0038). Like the Home Screen row, an action rather
 * than a preference, and the kit's alone: a game adds nothing.
 */
export function feedbackRow() {
  if (!feedbackUrl()) return null;
  return h('section', { class: 'house-section', dataset: { section: 'feedback' } },
    h('h3', 'Feedback'),
    setting('Send feedback', 'To David, who makes these games. Only when you press Submit.',
      button('secondary', 'Write', () => openFeedback(), { class: 'house-action', 'aria-haspopup': 'dialog' }), { id: 'feedback' }));
}

/** What's in the window now, without any sheet or toast, as a JPEG Blob
 * under SHOT_BYTES; throws if it can't be drawn. */
export async function capture() {
  const html2canvas = await loadCapture();
  // A board hidden only because a sheet is up (sheet.js hideBoard) is drawn
  // as it is behind it: shown for the moment its picture's styles are read,
  // in the same task, so it's never painted.
  const behind = [...document.querySelectorAll('[data-house-sheet-hides]')];
  behind.forEach(el => el.classList.remove('hidden'));
  let pictures;
  try {
    pictures = svgPictures();
  } finally {
    behind.forEach(el => el.classList.add('hidden'));
  }
  tagClipped();
  let page;
  try {
    page = await html2canvas(document.body, {
      x: globalThis.scrollX, y: globalThis.scrollY, width: globalThis.innerWidth, height: globalThis.innerHeight,
      windowWidth: document.documentElement.clientWidth, windowHeight: document.documentElement.clientHeight,
      scale: Math.min(globalThis.devicePixelRatio || 1, 2),
      backgroundColor: getComputedStyle(document.body).backgroundColor || '#ffffff',
      logging: false, useCORS: true,
      // (the sheet and its scrim, and toasts: the picture is of the page behind)
      // (and what only shows without script: the copy runs none)
      ignoreElements: el => el.tagName === 'NOSCRIPT' || (!!el.classList && (el.classList.contains('house-scrim') || el.classList.contains('house-toasts'))),
      onclone: async doc => {
        // (the copy fetches the page's stylesheets again: drawn before they
        // arrive, it's unstyled, so wait for each, a few seconds at most)
        await Promise.all([...doc.querySelectorAll('link[rel="stylesheet"]')].filter(l => !l.sheet).map(l => new Promise(done => {
          l.addEventListener('load', done, { once: true });
          l.addEventListener('error', done, { once: true });
          setTimeout(done, 4000);
        })));
        await Promise.race([doc.fonts?.ready, new Promise(done => setTimeout(done, 1500))]);
        for (const el of doc.querySelectorAll('[data-uo-shot-hide]')) el.style.visibility = 'hidden';
        for (const el of doc.querySelectorAll('[data-house-sheet-hides]')) el.classList.remove('hidden');
        for (const svg of doc.querySelectorAll('svg[data-uo-shot]')) {
          const p = pictures.get(svg.dataset.uoShot);
          if (!p) continue;
          const img = doc.createElement('img');
          img.src = p.url;
          img.className = svg.getAttribute('class') || '';
          img.style.cssText = `display:${p.display === 'inline' ? 'inline-block' : p.display};width:${p.w}px;height:${p.h}px;max-width:none`;
          svg.replaceWith(img);
        }
      },
    });
  } finally {
    for (const svg of document.querySelectorAll('svg[data-uo-shot]')) delete svg.dataset.uoShot;
    for (const el of document.querySelectorAll('[data-uo-shot-hide]')) delete el.dataset.uoShotHide;
  }
  let side = SHOT_SIDE;
  for (let tries = 0; tries < 3; tries++, side = Math.round(side * 0.7)) {
    const size = fit(page.width, page.height, side);
    const out = document.createElement('canvas');
    out.width = size.w;
    out.height = size.h;
    const g = out.getContext('2d');
    g.imageSmoothingQuality = 'high';
    g.drawImage(page, 0, 0, size.w, size.h);
    for (const q of QUALITIES) {
      const blob = await toBlob(out, q);
      if (blob && blob.size <= SHOT_BYTES) return blob;
    }
  }
  throw new Error('screenshot too big');
}