crewforth 3.0.4 → 3.1.0-rc.1

package/kit/studio/web/liveness.js

@@ -0,0 +1,66 @@
+// Live, Stale or Offline: when did the panel last hear from its server.
+//
+// "Heard from" is any answer on any channel: the fleet poll, the project poll, an event on the graph stream. The
+// fleet poll alone would be the wrong clock. Each of its answers waits on a `claude agents` spawn, which the server
+// gives ten seconds, so a slow CLI stretches that poll while the rest of the panel is fed as usual.
+//
+// Measured, gaps between answers:
+//   fleet poll, healthy       macOS 2.2 s quiet, 2.5 s under load · Windows 2.1 s quiet, 2.5 s under load
+//   fleet poll, CLI takes 4 s      6.5 s
+//   fleet poll, CLI takes 12 s    12.8 s   (every answer "not measured": the spawn timed out)
+//   project poll, same two servers 5.2 s   (it does not wait on the CLI)
+//
+// So with every channel counted the longest healthy silence is one project poll, 5.2 s, and STALE_AFTER_MS is
+// about twice that. Counting the fleet poll alone, ten seconds would have called a panel with a slow CLI stale
+// while it was answering every five.
+//
+// Offline is not a longer silence. It is the last request failing: a refused connection answers at once, so there
+// is nothing to wait for.
+export const STALE_AFTER_MS = 10000;
+
+/**
+ * @param nowMs        the clock
+ * @param lastOkMs     when an answer last arrived, or null if none has
+ * @param lastFailed   whether the most recent request failed
+ * @returns { state: 'connecting' | 'live' | 'stale' | 'offline', word, detail, tone }
+ */
+export function liveness(nowMs, lastOkMs, lastFailed) {
+  if (lastFailed) {
+    return {
+      state: 'offline',
+      word: 'Offline',
+      tone: 'fail',
+      detail: lastOkMs === null ? 'the server has not answered' : `last update ${clock(lastOkMs)}`,
+    };
+  }
+  if (lastOkMs === null) return { state: 'connecting', word: 'Connecting', tone: null, detail: '' };
+  const silence = Math.max(0, nowMs - lastOkMs);
+  const said = `${Math.round(silence / 1000)}s ago`;
+  if (silence > STALE_AFTER_MS) return { state: 'stale', word: 'Stale', tone: 'waiting', detail: said };
+  return { state: 'live', word: 'Live', tone: 'good', detail: said };
+}
+
+/**
+ * What the stage says while the server is not answering: which picture is on screen, and when the next try is.
+ *
+ * The picture stays — it is the last thing known — and it is named as old. The countdown is to a request this
+ * page is really going to make; "Retry now" makes it at once.
+ *
+ * @param state      liveness().state
+ * @param nextTryMs  when the next poll is due, or null when none is scheduled
+ */
+export function offlineNote(state, lastOkMs, nextTryMs, nowMs) {
+  if (state !== 'offline') return null;
+  const left = nextTryMs == null ? null : Math.max(0, Math.ceil((nextTryMs - nowMs) / 1000));
+  return {
+    text: lastOkMs === null ? 'The server has not answered yet, so there is nothing to show.' : `Showing the last update from ${clock(lastOkMs)}.`,
+    retry: left == null ? 'Reconnecting' : left === 0 ? 'Reconnecting now' : `Reconnecting in ${left}s`,
+    stale: lastOkMs !== null,
+  };
+}
+
+function clock(ms) {
+  const d = new Date(ms);
+  const two = (n) => String(n).padStart(2, '0');
+  return `${two(d.getHours())}:${two(d.getMinutes())}`;
+}

package/kit/studio/web/nav.js

@@ -0,0 +1,237 @@
+// What the top bar and the navigator say, kept apart from where they draw it.
+//
+// Everything here is a function of the data the server sent. None of it touches the page, so each rule can be
+// asserted on its own: which word a status gets, what a version badge offers to copy, what a row is called when
+// the transcript carried no title. The drawing is in app.js.
+//
+// One rule runs through it, the panel's own: a value that was not read is never written as if it had been. A
+// status nobody recognises keeps its own word and gets no colour; a branch that could not be read leaves the line
+// without one; a project that cannot be told to update by a command gets a hint instead of a command.
+
+/* ------------------------------------------------------------- status --- */
+
+// The words the design uses, and the token each is drawn in. `tone` names a status-* token; null is the hollow
+// ring of something that is over.
+const AGENT_STATUS = {
+  running: { word: 'running', tone: 'busy' },
+  starting: { word: 'starting', tone: 'busy' },
+  done: { word: 'done', tone: 'good' },
+  failed: { word: 'failed', tone: 'fail' },
+  killed: { word: 'killed', tone: 'fail' },
+  stopped: { word: 'stopped', tone: 'fail' },
+  stale: { word: 'stale', tone: 'idle' },
+  ended: { word: 'ended', tone: null },
+};
+const CHIP_ORDER = ['running', 'starting', 'stale', 'done', 'failed', 'killed', 'stopped', 'ended'];
+
+/** The word and the tone one agent status is drawn in. A status this table does not know keeps its own word. */
+export function agentStatus(status) {
+  const known = AGENT_STATUS[status];
+  return known
+    ? { word: known.word, tone: known.tone, known: true }
+    : { word: String(status ?? 'unknown'), tone: null, known: false };
+}
+
+/**
+ * One chip per status that has at least one agent, so the chips add up to the total. A status this table does
+ * not know is still a chip: its own word, no colour, `known: false`.
+ */
+export function summaryChips(byStatus) {
+  const entries = Object.entries(byStatus ?? {}).filter(([, n]) => n > 0);
+  const rank = (k) => { const i = CHIP_ORDER.indexOf(k); return i === -1 ? CHIP_ORDER.length : i; };
+  entries.sort((a, b) => rank(a[0]) - rank(b[0]) || a[0].localeCompare(b[0]));
+  return entries.map(([status, count]) => {
+    const known = AGENT_STATUS[status];
+    return {
+      status,
+      count,
+      known: Boolean(known),
+      tone: known ? known.tone : null,
+      text: `${count} ${known ? known.word : status}`,
+    };
+  });
+}
+
+// A session, as the machine reports it. `claude agents` knows three states; a session it does not list is not
+// running anywhere on this machine.
+const SESSION_STATUS = {
+  busy: { word: 'Running', tone: 'busy' },
+  waiting: { word: 'Needs you', tone: 'waiting' },
+  idle: { word: 'Idle', tone: 'idle' },
+};
+
+/**
+ * @param fleet the /api/fleet answer, or null before the first one
+ * @returns { key, word, tone, known } — key is 'unmeasured' when the fleet was not read: that is not "ended".
+ */
+export function sessionStatus(sessionId, fleet) {
+  if (!fleet || fleet.measured === false) return { key: 'unmeasured', word: null, tone: null, known: false };
+  const row = (fleet.sessions ?? []).find((s) => s.sessionId === sessionId && s.local !== false);
+  if (!row) return { key: 'ended', word: 'Ended', tone: null, known: true };
+  const known = SESSION_STATUS[row.status];
+  if (!known) return { key: String(row.status), word: String(row.status), tone: null, known: false };
+  return { key: row.status, word: known.word, tone: known.tone, known: true, waitingFor: row.waitingFor ?? null };
+}
+
+/**
+ * Is this the first run: the transcripts were read, and there are none?
+ * An answer that could not be read is not a first run — it is not measured, and the navigator says that.
+ */
+export function isFirstRun(data) {
+  return Boolean(data) && data.measured !== false && Array.isArray(data.projects) && data.projects.length === 0;
+}
+
+/* --------------------------------------------------------------- rows --- */
+
+/** What a session is called: the label given here, the title it carries, and only then its id. */
+export function sessionName(sn, labels) {
+  const own = labels?.[sn.sessionId];
+  if (typeof own === 'string' && own.trim()) return own.trim();
+  if (sn.title) return sn.title;
+  return String(sn.sessionId).slice(0, 8);
+}
+
+/** The line under the name: branch, state, agents. A part that was not read is left out, not filled in. */
+export function sessionSub(sn, status) {
+  const parts = [];
+  if (sn.branch) parts.push(sn.branch);
+  if (status?.key === 'waiting' && status.waitingFor) parts.push(`Needs you · ${status.waitingFor}`);
+  else if (status?.word) parts.push(status.word);
+  if (sn.agentCount > 0) parts.push(`${sn.agentCount} ${sn.agentCount === 1 ? 'agent' : 'agents'}`);
+  return parts.join(' · ');
+}
+
+/** "now", "4m", "2h", "3d" — how long ago, coarse on purpose. */
+export function ago(thenMs, nowMs) {
+  if (typeof thenMs !== 'number' || !Number.isFinite(thenMs)) return '';
+  const s = Math.max(0, Math.round((nowMs - thenMs) / 1000));
+  if (s < 60) return 'now';
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h`;
+  return `${Math.floor(s / 86400)}d`;
+}
+
+/** "seen just now", "seen 3 min ago", "seen 2 h ago" — for a fact recorded earlier, not read now. */
+export function seenAgo(thenMs, nowMs) {
+  if (typeof thenMs !== 'number' || !Number.isFinite(thenMs)) return 'seen at an unrecorded time';
+  const s = Math.max(0, Math.round((nowMs - thenMs) / 1000));
+  if (s < 60) return 'seen just now';
+  if (s < 3600) return `seen ${Math.floor(s / 60)} min ago`;
+  if (s < 86400) return `seen ${Math.floor(s / 3600)} h ago`;
+  return `seen ${Math.floor(s / 86400)} d ago`;
+}
+
+/* ------------------------------------------------------------- search --- */
+
+/** Project name, branch, session id, and the name the row shows. An empty query matches everything. */
+export function matchesSession(query, project, sn, labels) {
+  const q = String(query ?? '').trim().toLowerCase();
+  if (!q) return true;
+  return [project.label, sn.branch, sn.sessionId, sessionName(sn, labels)]
+    .some((v) => typeof v === 'string' && v.toLowerCase().includes(q));
+}
+
+/** `text` cut into parts, the ones that match `query` marked. Case is kept as written. */
+export function highlight(text, query) {
+  const t = String(text ?? '');
+  const q = String(query ?? '').trim().toLowerCase();
+  if (!q) return [{ text: t, hit: false }];
+  const out = [];
+  const low = t.toLowerCase();
+  let i = 0;
+  while (i < t.length) {
+    const at = low.indexOf(q, i);
+    if (at === -1) { out.push({ text: t.slice(i), hit: false }); break; }
+    if (at > i) out.push({ text: t.slice(i, at), hit: false });
+    out.push({ text: t.slice(at, at + q.length), hit: true });
+    i = at + q.length;
+  }
+  return out.length ? out : [{ text: t, hit: false }];
+}
+
+/* -------------------------------------------------------------- badge --- */
+
+/**
+ * The version badge on a project row.
+ *
+ * `copy` is the command a click copies, and it is only ever the one the server sent. Without one — a project
+ * with no Crewforth files, which is also what a plugin install looks like from here — the badge offers the
+ * `/crew-update` hint in its title and copies nothing.
+ */
+export function badgeFor(kit) {
+  if (!kit || !kit.installed) {
+    return {
+      text: 'no Crewforth',
+      tone: 'none',
+      copy: null,
+      title: 'No Crewforth files in this project. A plugin install leaves none, so this cannot tell the two '
+        + 'apart; to update one, run /crew-update in the project.',
+    };
+  }
+  const command = typeof kit.updateCommand === 'string' && kit.updateCommand ? kit.updateCommand : null;
+  const how = command ? `click to copy: ${command}` : 'run /crew-update in this project';
+  if (kit.compared === false) {
+    return {
+      text: `${kit.version} ?`,
+      tone: 'unknown',
+      copy: null,
+      title: `Crewforth ${kit.version} — not compared: ${kit.reason ?? 'no reason given'}`,
+    };
+  }
+  if (kit.outdated) {
+    return {
+      text: `${kit.version} · update`,
+      tone: 'old',
+      copy: command,
+      title: `Crewforth ${kit.version} is behind ${kit.latest} — ${how}`,
+    };
+  }
+  if (kit.ahead) {
+    return {
+      text: kit.version,
+      tone: 'ahead',
+      copy: null,
+      title: `Crewforth ${kit.version} is ahead of the published ${kit.latest}`,
+    };
+  }
+  return { text: kit.version, tone: 'current', copy: null, title: `Crewforth ${kit.version} — current` };
+}
+
+/* --------------------------------------------------------------- live --- */
+
+/** The Live tab: sessions that are working or waiting on someone, the waiting ones first. */
+export function liveSessions(fleet) {
+  if (!fleet || fleet.measured === false) return [];
+  const rank = { waiting: 0, busy: 1 };
+  return (fleet.sessions ?? [])
+    .filter((s) => s.status in rank)
+    .sort((a, b) => rank[a.status] - rank[b.status] || (b.startedAt ?? 0) - (a.startedAt ?? 0));
+}
+
+/**
+ * The Machines tab. Two kinds of other machine, and they are not the same kind of fact: a peer Studio was asked
+ * just now; a Remote Control session is what one session last recorded, at `seenAt`.
+ */
+export function machines(fleet) {
+  const peers = (fleet?.origins ?? []).filter((o) => !o.local).map((o) => ({
+    kind: 'peer',
+    name: o.name,
+    ok: o.ok !== false,
+    reason: o.reason ?? null,
+    sessions: typeof o.sessions === 'number' ? o.sessions : null,
+  }));
+  const roster = fleet?.roster ?? null;
+  const remote = (roster?.peers ?? []).filter((p) => p.remote).map((p) => ({
+    kind: 'snapshot',
+    name: p.name,
+    status: p.status ?? null,
+    note: p.note || p.kind || '',
+    seenAt: roster.seenAt ?? null,
+  }));
+  return {
+    peers,
+    remote,
+    rosterMeasured: Boolean(roster?.measured),
+    rosterReason: roster?.reason ?? null,
+  };
+}

package/kit/studio/web/newsession.js

@@ -0,0 +1,235 @@
+// The New session panel: where a session runs, how much it may do, and what it is asked first.
+//
+// The choices are the server's. The projects are the ones it listed; the modes are the ones it offers, and this
+// file can describe a mode but cannot add one. Starting is guarded by a one-shot: two clicks start one session.
+import { oneShot } from './convo.js';
+
+/**
+ * What each permission mode means for a session started HERE.
+ *
+ * Not the terminal's wording. In a terminal a mode decides what Claude Code asks about. Here every tool call
+ * waits in the approval dock whatever the mode, and an answer given there is the approval: outside plan mode the
+ * gate tells Claude Code so. That leaves two modes that behave alike in Studio, and the panel says that instead
+ * of repeating a difference that only exists in a terminal.
+ */
+export const MODE_TEXT = {
+  plan: { word: 'Plan', says: 'Reads and plans. Cannot change files.' },
+  acceptEdits: { word: 'Accept edits', says: 'Edits files and runs commands, each one after you allow it in the approval dock.' },
+  default: { word: 'Default', says: 'The same in Studio: every call waits for you. It differs from Accept edits only in a terminal.' },
+};
+
+const PREFERRED = 'plan';
+
+/** The modes to offer: exactly the server's list, in its order, each with what is known about it. */
+export function modeChoices(offered) {
+  const list = Array.isArray(offered) ? offered.filter((m) => typeof m === 'string') : [];
+  const initial = list.includes(PREFERRED) ? PREFERRED : (list[0] ?? null);
+  return list.map((mode) => ({
+    mode,
+    // A mode this file has no words for is still the server's to offer: it is shown under its own name.
+    word: MODE_TEXT[mode]?.word ?? mode,
+    says: MODE_TEXT[mode]?.says ?? null,
+    initial: mode === initial,
+  }));
+}
+
+/** The projects a session can be started in: on this machine, with a directory that is still there. */
+export function projectChoices(projects, preferKey = null) {
+  const list = (projects ?? []).filter((p) => p.local !== false && p.exists && p.cwd);
+  const initial = list.find((p) => p.key === preferKey) ?? list.find((p) => p.current) ?? list[0] ?? null;
+  return list.map((p) => ({
+    key: p.key,
+    cwd: p.cwd,
+    label: p.label ?? p.cwd,
+    branch: p.branch ?? null,
+    kit: p.kit?.installed ? (p.kit.version ?? 'installed') : null,
+    initial: p === initial,
+  }));
+}
+
+/** "Runs in <path> on branch <branch>." — the branch only when the server read one. */
+export function runsIn(choice, shorten = (p) => p) {
+  if (!choice) return null;
+  return { path: shorten(choice.cwd), branch: choice.branch };
+}
+
+function mk(tag, cls, text) {
+  const n = document.createElement(tag);
+  if (cls) n.className = cls;
+  if (text != null) n.textContent = text;
+  return n;
+}
+
+export class NewSession {
+  /**
+   * @param onStart  ({ cwd, permissionMode, first }) => Promise<{ ok, reason? }>
+   * @param onClose  () => void
+   * @param shorten  path => the short form the rest of the panel uses
+   */
+  constructor(root, { onStart, onClose, shorten } = {}) {
+    this.root = root;
+    this.onClose = onClose ?? (() => {});
+    this.shorten = shorten ?? ((p) => p);
+    this.projects = [];
+    this.modes = [];
+    this.mode = null;
+    // Spent by the first click and re-armed only by opening the panel again, or by a start that was refused.
+    this.start = oneShot((args) => (onStart ?? (() => ({ ok: false, reason: 'nothing to start' })))(args));
+    this.#build();
+  }
+
+  #build() {
+    const head = mk('div', 'np-head');
+    const close = mk('button', 'btn icon sm ghost');
+    close.type = 'button';
+    close.setAttribute('aria-label', 'Close');
+    close.innerHTML = '<svg class="ic" viewBox="0 0 16 16" aria-hidden="true"><path d="M4 4l8 8M12 4l-8 8"/></svg>';
+    close.addEventListener('click', () => this.close());
+    head.append(mk('h2', 'np-title', 'New session'), mk('span', 'row-fill'), close);
+
+    const form = mk('form', 'np-body');
+    form.addEventListener('submit', (e) => { e.preventDefault(); this.submit(); });
+
+    const projWrap = mk('div', 'np-field');
+    const projLabel = mk('label', 'np-label', 'Project');
+    projLabel.htmlFor = 'np-project';
+    this.projectEl = mk('select', 'np-select');
+    this.projectEl.id = 'np-project';
+    this.projectEl.addEventListener('change', () => this.paintRunsIn());
+    this.runsEl = mk('span', 'sub np-runs');
+    projWrap.append(projLabel, this.projectEl, this.runsEl);
+
+    this.modesEl = mk('fieldset', 'np-modes');
+
+    const firstWrap = mk('div', 'np-field');
+    const firstLabel = mk('label', 'np-label', 'First message');
+    firstLabel.htmlFor = 'np-first';
+    this.firstEl = mk('textarea', 'np-first');
+    this.firstEl.id = 'np-first';
+    this.firstEl.rows = 5;
+    this.firstEl.placeholder = 'What should this session do?';
+    firstWrap.append(firstLabel, this.firstEl,
+      mk('span', 'sub', 'Optional. You can also start empty and write in the conversation panel.'));
+
+    // What starting here means, said before the button: a closed panel is a refusal.
+    const note = mk('div', 'np-note');
+    note.innerHTML = '<svg class="ic" viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="8" r="6"/><path d="M8 7.5v3.5M8 5h.01"/></svg>';
+    note.append(mk('span', 'sub',
+      'Every tool call in this session waits for your approval here in Studio. If Studio is closed, the request is denied.'));
+
+    this.errorEl = mk('div', 'np-error');
+    this.errorEl.setAttribute('role', 'alert');
+    this.errorEl.hidden = true;
+
+    form.append(projWrap, this.modesEl, firstWrap, note, this.errorEl);
+
+    const foot = mk('div', 'np-foot');
+    const cancel = mk('button', 'btn', 'Cancel');
+    cancel.type = 'button';
+    cancel.addEventListener('click', () => this.close());
+    this.startEl = mk('button', 'btn primary', 'Start session');
+    this.startEl.type = 'button';
+    this.startEl.addEventListener('click', () => this.submit());
+    foot.append(cancel, this.startEl);
+
+    this.root.replaceChildren(head, form, foot);
+  }
+
+  get isOpen() { return !this.root.hidden; }
+
+  /**
+   * Show the panel. Opening one that is already open changes nothing — in particular it does not arm a second
+   * start, so a second click on the bar's button cannot become a second session.
+   */
+  open({ projects, modes, preferKey } = {}) {
+    if (this.isOpen) return false;
+    this.projects = projectChoices(projects, preferKey);
+    this.modes = modeChoices(modes);
+    this.mode = this.modes.find((m) => m.initial)?.mode ?? null;
+    this.firstEl.value = '';
+    this.errorEl.hidden = true;
+    this.start.arm();
+    this.paint();
+    this.root.hidden = false;
+    return true;
+  }
+
+  close() {
+    if (!this.isOpen) return;
+    this.root.hidden = true;
+    this.onClose();
+  }
+
+  get project() { return this.projects.find((p) => p.key === this.projectEl.value) ?? null; }
+
+  paint() {
+    this.projectEl.replaceChildren(...this.projects.map((p) => {
+      const o = mk('option', null, p.kit ? `${p.label} · Crewforth ${p.kit}` : `${p.label} · no Crewforth`);
+      o.value = p.key;
+      o.selected = p.initial;
+      return o;
+    }));
+    const initial = this.projects.find((p) => p.initial);
+    if (initial) this.projectEl.value = initial.key;
+    this.paintRunsIn();
+    this.paintModes();
+    this.paintStart();
+  }
+
+  paintRunsIn() {
+    const r = runsIn(this.project, this.shorten);
+    if (!r) {
+      this.runsEl.textContent = 'No project on this machine to start a session in.';
+      return;
+    }
+    const parts = ['Runs in ', mk('code', null, r.path)];
+    if (r.branch) parts.push(' on branch ', mk('code', null, r.branch));
+    parts.push('.');
+    this.runsEl.replaceChildren(...parts);
+  }
+
+  paintModes() {
+    const legend = mk('legend', 'np-label', 'Permission mode');
+    const rows = this.modes.map((m) => {
+      const row = mk('label', 'np-mode');
+      const radio = mk('input');
+      radio.type = 'radio';
+      radio.name = 'np-mode';
+      radio.value = m.mode;
+      radio.checked = m.mode === this.mode;
+      radio.addEventListener('change', () => { this.mode = m.mode; this.paintModes(); });
+      row.classList.toggle('on', m.mode === this.mode);
+      const text = mk('span', 'np-mode-text');
+      const word = mk('span', 'np-mode-word', m.word);
+      if (m.initial) word.append(mk('span', 'sub', ' · default'));
+      text.append(word);
+      if (m.says) text.append(mk('span', 'sub', m.says));
+      row.append(radio, text);
+      return row;
+    });
+    this.modesEl.replaceChildren(legend, ...rows, mk('span', 'sub', 'Modes that skip Crewforth\'s gates are not offered.'));
+  }
+
+  paintStart() {
+    const busy = this.start.spent();
+    this.startEl.disabled = busy || !this.project || !this.mode;
+    this.startEl.textContent = busy ? 'Starting…' : 'Start session';
+  }
+
+  async submit() {
+    const project = this.project;
+    if (!project || !this.mode) return null;
+    const pending = this.start({ cwd: project.cwd, permissionMode: this.mode, first: this.firstEl.value.trim() });
+    this.paintStart();
+    let out;
+    try { out = await pending; } catch (e) { out = { ok: false, reason: e?.message ?? String(e) }; }
+    if (out?.ok) {
+      this.close();
+    } else {
+      this.errorEl.textContent = `Could not start a session — ${out?.reason ?? 'no reason given'}`;
+      this.errorEl.hidden = false;
+      this.paintStart();
+    }
+    return out;
+  }
+}

package/kit/studio/web/press.js

@@ -0,0 +1,65 @@
+// A view that redraws itself does not redraw while a button is down on it.
+//
+// The Timeline and the List put their rows in again about once a second while something in them moves. A browser
+// sends a click only when the element that took the press is still in the page at the release. A redraw between
+// the two took that element out, and the press chose nothing: measured, 3 presses of 20 at an ordinary 90 ms, and
+// 20 of 20 when the button was held longer than a redraw. Keeping the row's own element and refilling it does not
+// help: what takes the press is the text inside it, and a press whose target is gone gets no click at all.
+//
+// So the redraw waits. While a press is down the view says "later", and when the press is over, and the click it
+// made has been delivered, the view draws what it put off. A press that is held and held is not a click: after
+// HOLD_MS the view stops waiting for it.
+
+export const HOLD_MS = 3000;
+
+export class Press {
+  /**
+   * @param redraw  called once after a press, if a redraw was put off during it
+   * @param timers  { set(fn, ms) => id, clear(id) } — the page's setTimeout and clearTimeout, or a test's
+   */
+  constructor(redraw, timers = { set: (fn, ms) => setTimeout(fn, ms), clear: (id) => clearTimeout(id) }) {
+    this.redraw = redraw;
+    this.timers = timers;
+    this.down = false;
+    this.owed = false;
+    this.cap = null;
+  }
+
+  /** A button went down on the view. */
+  press() {
+    this.down = true;
+    this.timers.clear(this.cap);
+    this.cap = this.timers.set(() => this.release(), HOLD_MS);
+  }
+
+  /** It came up, or was taken away. What was put off is drawn after the click has been delivered. */
+  release() {
+    if (!this.down) return;
+    this.down = false;
+    this.timers.clear(this.cap);
+    this.cap = null;
+    this.timers.set(() => { if (this.owed && !this.down) { this.owed = false; this.redraw(); } }, 0);
+  }
+
+  /**
+   * Asked by the view at the top of its redraw: true means "not now". A redraw that does run settles the debt.
+   */
+  defer() {
+    if (this.down) { this.owed = true; return true; }
+    this.owed = false;
+    return false;
+  }
+
+  /**
+   * Watch a view. The press is seen on the view; the release is seen on the window, because a press that began
+   * on a row can end anywhere. The space bar is a press too: a button answers it at the key's release.
+   */
+  watch(root, win) {
+    root.addEventListener('pointerdown', () => this.press(), true);
+    root.addEventListener('keydown', (e) => { if (e.key === ' ') this.press(); }, true);
+    for (const type of ['pointerup', 'pointercancel', 'keyup']) win.addEventListener(type, () => this.release(), true);
+    // The window losing the keyboard, not an element in it: a press moves the focus, and that blur is not a release.
+    win.addEventListener('blur', (e) => { if (e.target === win) this.release(); });
+    return this;
+  }
+}