@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/web/pages/syncs.js

@@ -0,0 +1,155 @@
+/**
+ * THE SYNCS VIEW (#observability/syncs, a view of the Observability group; `#observability/logs`, `#logs` and `#syncs`
+ * land here;
+ * docs/OBSERVABILITY.md "Pages"): the sync's events (`mason logs --events`) over the time range the Observability views
+ * share, as a timeline table NEWEST FIRST (When sorts it the other way) — narrowed in the page alone by "Failures only",
+ * a kind and a table (every kind, and every added table from `/api/state`, events or not), at most EVENTS_SHOWN rows written with
+ * "Show more" — and, behind a closed details "The run's raw log (for debugging)", the run's last log entries, newest
+ * first (`mason logs`: they carry internal tags and absolute paths, so they are not the page's content). Reads
+ * `/api/events` every 10 s while the range is Now, and `/api/logs` every 5 s ONLY WHILE the details is open (the page's own state: nothing is
+ * read when it is closed); the events once when a range other than Now is chosen. A page module (src/web/app.js has the contract). Never the engine's name.
+ */
+import { esc, agoText, utcText, badge, empty, panel, n, sortTh, nextSort, moreRows, readPart, eventCells, RANGES, DEFAULT_RANGE, rangeOf, rangeEvery } from "../shared.js";
+
+/** How many of the range's events are read (the newest), and how many of those the page writes at once. */
+const EVENTS_LIMIT = 500;
+const EVENTS_SHOWN = 100;
+/** The events of a range: the newest EVENTS_LIMIT since its start. */
+const eventsPath = (range = DEFAULT_RANGE) => `/api/events?limit=${EVENTS_LIMIT}&since=${RANGES[rangeOf(range)].since}`;
+const LOGS = "/api/logs?lines=200";
+const STATE = "/api/state";
+
+const th = (cols) => cols.map((c) => `<th scope="col">${esc(c)}</th>`).join("");
+
+/** An event's kind as a badge: a failure red (with its ✗), a copy made or a failure recovered green, any other gray. */
+const kindBadge = (e) => badge(e.failed ? `✗ ${e.kind}` : e.kind, e.failed ? "bad" : /^(copied|recovered|synced)$/.test(e.kind) ? "ok" : "");
+
+/** The events read that pass the page's filters: failures only, a kind, a table ("" any; the sync's own is "(the sync)"). */
+const eventsShown = (events, { failuresOnly = false, kind = "", table = "" } = {}) =>
+  events.filter((e) => (!failuresOnly || e.failed) && (!kind || e.kind === kind) && (!table || (e.table ?? "(the sync)") === table));
+
+/**
+ * The sync's events as a timeline, NEWEST FIRST (`sort.dir` "asc": oldest first, as the command lists them): when (how
+ * long ago; the UTC time, as the command prints it, is the title), the kind as a badge, the table, the reason's first line
+ * and, under it, its further lines. `failuresOnly`, `kind` and `table` (the page's filters) keep the events of what was
+ * read that pass (`eventsShown`); at most `limit` rows are written. `span` the range's words; `now` the page's clock.
+ */
+export function renderEvents(b, { failuresOnly = false, kind = "", table = "", now = Date.now(), sort = { key: "time", dir: "desc" }, limit = EVENTS_SHOWN, span = "" } = {}) {
+  const days = `${b.keptDays} day${b.keptDays === 1 ? "" : "s"}`;
+  const within = span ? `in ${span} (the events are kept ${days}: MASON_HISTORY_DAYS)` : `in the last ${days} (MASON_HISTORY_DAYS)`;
+  const passing = eventsShown(b.events, { failuresOnly, kind, table });
+  const narrowed = failuresOnly || kind || table;
+  // a table chosen that had none (every added table is a choice, events or not): said by its name
+  if (!passing.length && table && !kind) return empty(`No ${failuresOnly ? "failure" : "event"}s for ${table} ${within}.`);
+  if (!b.events.length) return empty(`No sync event ${within}.`);
+  if (!passing.length) {
+    return empty(failuresOnly && !kind && !table ? `None of the ${b.events.length} sync event${b.events.length === 1 ? "" : "s"} shown failed.` : `None of the ${n(b.events.length)} sync event${b.events.length === 1 ? "" : "s"} read passes the filters.`);
+  }
+  const ordered = sort.dir === "asc" ? passing : [...passing].reverse();
+  const rows = ordered.slice(0, limit).map((e) => {
+    const c = eventCells(e);
+    const more = e.message.includes("\n") ? `<pre>${esc(e.message.split("\n").slice(1).join("\n"))}</pre>` : "";
+    return `<tr${e.failed ? ` class="t-failed"` : ""}><th scope="row"><time data-tick datetime="${esc(e.at)}" title="${esc(c.time)} UTC">${esc(agoText(e.at, now))}</time></th><td>${kindBadge(e)}</td>` +
+      `<td>${c.table.startsWith("(") ? `<span class="dim">${esc(c.table)}</span>` : `<code class="name" title="${esc(c.table)}">${esc(c.table)}</code>`}</td><td>${esc(c.message)}${more}</td></tr>`;
+  }).join("");
+  const count = narrowed ? `<p class="dim">${n(passing.length)} of the ${n(b.events.length)} events read.</p>` : "";
+  return count + panel(`<table class="events"><thead><tr>${sortTh("events", "time", "When", sort)}${th(["Kind", "Table", "Message"])}</tr></thead><tbody>${rows}</tbody></table>`) +
+    moreRows("events", Math.min(limit, passing.length), passing.length, EVENTS_SHOWN);
+}
+
+/** EVERY KIND OF SYNC EVENT, in its order (src/duck/events.ts `EVENT_KINDS`, held equal by the tests): the Kind filter
+ *  offers each, whether the range has one or not. */
+export const EVENT_KINDS = ["copy_failed", "poll_failed", "catch_up_failed", "stream_failed", "source_unreachable", "generated_failed", "restart", "copied", "recovered", "synced", "sync_changed"];
+
+/** The kind and table filters' controls: EVERY kind (EVENT_KINDS), and EVERY added table (`/api/state` `tables`, `s`) —
+ *  the sync's own "(the sync)" first — whether the range has an event of it or not, so the choices never depend on what
+ *  happened to be read; a table only the events name (removed since) and the one chosen are kept too. Written into
+ *  their part: the tables follow the state. */
+export function renderEventFilters(b, { kind = "", table = "" } = {}, s = null) {
+  const events = b?.events ?? [];
+  const added = (s?.tables ?? []).filter((t) => t.added).map((t) => t.table);
+  const others = [...new Set([...events.map((e) => e.table).filter((t) => t !== null && t !== undefined && !added.includes(t)), ...(table && table !== "(the sync)" && !added.includes(table) ? [table] : [])])].sort();
+  const tables = ["(the sync)", ...[...added].sort(), ...others];
+  const kinds = [...EVENT_KINDS, ...[...new Set([...events.map((e) => e.kind), ...(kind ? [kind] : [])])].filter((k) => !EVENT_KINDS.includes(k)).sort()];
+  const select = (id, label, all, values, chosen) => `<div class="field"><label for="${id}">${esc(label)}</label><select id="${id}">` +
+    `<option value="">${esc(all)}</option>${values.map((v) => `<option value="${esc(v)}"${v === chosen ? " selected" : ""}>${esc(v)}</option>`).join("")}</select></div>`;
+  return select("syncs-kind", "Kind", "Every kind", kinds, kind) + select("syncs-table", "Table", "Every table", tables, table);
+}
+
+/** The run's last log entries as a terminal's lines, NEWEST FIRST (the debugging reader wants what just happened); an entry of several lines is one, as written. */
+export function renderLogs(b) {
+  if (!b.lines.length) return empty("The run has logged nothing yet.");
+  return `<div class="terminal" role="log">` +
+    [...b.lines].reverse().map((l) => `<div class="log-line"><time>${esc(l.at === null || l.at === undefined ? "" : utcText(l.at))}</time><pre>${esc(l.text)}</pre></div>`).join("") + `</div>` +
+    `<p class="dim">The last ${b.lines.length} of at most ${b.kept} entries the run keeps, newest first; <code>mason logs</code> reads the log file.</p>`;
+}
+
+/** The raw log's details: its summary closed or open, and, open, the entries (or that they are being asked). */
+export function renderRawLog(open, inner) {
+  return `<details id="syncs-raw"${open ? " open" : ""}><summary>The run's raw log (for debugging)</summary>${open ? inner : ""}</details>`;
+}
+
+export const page = {
+  id: "syncs",
+  hash: "observability/syncs",
+  parent: "observability",
+  title: "Sync events",
+  create(ctx) {
+    const m = { rawOpen: false, failuresOnly: false, kind: "", table: "", sort: { key: "time", dir: "desc" }, limit: EVENTS_SHOWN };
+    const events = () => eventsPath(ctx.range());
+    const part = (path, render, says) => readPart(ctx, path, render, says);
+    const actions = {
+      /** The details opened or closed: the log is read from then on, or no longer. */
+      async showRawLog(open) {
+        m.rawOpen = open === true;
+        if (m.rawOpen) await ctx.refresh([LOGS]);
+      },
+      sortEvents() { m.sort = nextSort(m.sort, "time"); },
+      showMoreEvents() { m.limit += EVENTS_SHOWN; },
+      showAllEvents() { m.limit = Infinity; },
+    };
+    return {
+      model: m,
+      // the state for the Table filter's choices (every added table), as often as tables are added
+      reads: () => [{ path: events(), everyMs: rangeEvery(ctx.range(), 10_000) }, { path: STATE, everyMs: 30_000 }, ...(m.rawOpen ? [{ path: LOGS, everyMs: 5000 }] : [])],
+      actions,
+      view: () => ({
+        "syncs-filters": renderEventFilters(ctx.read(events())?.body, m, ctx.read(STATE)?.body ?? null),
+        "syncs-events": part(events(), (b) => renderEvents(b, { failuresOnly: m.failuresOnly, kind: m.kind, table: m.table, now: ctx.now().getTime(), sort: m.sort, limit: m.limit,
+          span: RANGES[ctx.range()]?.span ?? "" }), false),
+        "syncs-run": renderRawLog(m.rawOpen, m.rawOpen ? part(LOGS, renderLogs, true) : ""),
+      }),
+      /** The "Failures only" box, the kind or the table chosen: the events read are filtered in the page alone. */
+      input(target) {
+        if (target?.id === "syncs-failures-only") { m.failuresOnly = target.checked === true; m.limit = EVENTS_SHOWN; return true; }
+        if (target?.id === "syncs-kind") { m.kind = target.value ?? ""; m.limit = EVENTS_SHOWN; return true; }
+        if (target?.id === "syncs-table") { m.table = target.value ?? ""; m.limit = EVENTS_SHOWN; return true; }
+        return null;
+      },
+      /** `#observability/syncs?failures=1` (where the Overview's sync errors lead): the failures only, the box ticked;
+       *  `?table=<name>` (a table's View events) its events only, the Table filter showing it. */
+      route(params, { doc } = {}) {
+        if (params.failures === undefined && params.table === undefined) return null;
+        m.failuresOnly = params.failures === "1";
+        m.table = params.table ?? "";
+        m.limit = EVENTS_SHOWN;
+        const box = doc?.getElementById?.("syncs-failures-only");
+        if (box) box.checked = m.failuresOnly;
+        return true;
+      },
+      click(d) {
+        if (d.sortTable === "events") return actions.sortEvents() ?? true;
+        if (d.showMore === "events") return actions.showMoreEvents() ?? true;
+        if (d.showAll === "events") return actions.showAllEvents() ?? true;
+        return null;
+      },
+      /** A details of this section opened or closed (the shell listens to `toggle`): null when it is not the raw log's. */
+      toggle(target) {
+        if (target.id !== "syncs-raw") return null;
+        const open = target.open === true;
+        if (open === m.rawOpen) return target.clicked === true ? true : null;   // a click: the element disagrees, written again
+        return actions.showRawLog(open);
+      },
+    };
+  },
+};

package/dist/src/web/pages/tables.js

@@ -0,0 +1,439 @@
+/**
+ * THE TABLES PAGE (#tables): the database's tables in ONE table, as `mason tables` lists them. An added table shows its
+ * copy's sync — state, rows, last sync and its age, how long it took, the copy's own size, and in replication mode its
+ * stream state — and its error, with Sync (POST /api/sync, `mason sync`) and Remove (POST /api/remove, `mason remove`);
+ * one not added shows its rows and key and why it cannot be added as it is, with Add, Columns… and Name its key…
+ * (POST /api/pick, `mason add`). A search box filters by name, and All / Added / Failed / Not added by state
+ * (`#tables?show=failed`, where the Overview's card leads). With hundreds of tables the page writes the first
+ * TABLE_ROWS that pass and "Show N more" / "Show all" (the search is over all of them, at once); a long name is cut with
+ * an ellipsis, its whole the title. Reads `/api/state` every poll (lean: no table's columns) and `/api/usage`'s
+ * `copySizes` every minute; a table's columns once, when its Columns… or Name its key… form opens
+ * (`GET /api/tables/<table>/columns`, `columnsPath`).
+ */
+import { msText, bytesText, button, card, cards, code, createOpenSet, moreRows, details, empty, entryName, esc, fileSize, firstLine, json, n, panel, renderFailure, rowsHtml, spanText, duration, status, streamRows, utcText, pop, fresh, actId, ROOMS, POLL_MS } from "../shared.js";
+import { copyBar, copyingCount, createMonotone, tableLine } from "./status.js";
+
+/** `/api/usage` asked for the copies' own sizes alone: the last minute's samples (none needed), and `copySizes`. */
+const SIZES_PATH = "/api/usage?since=1m";
+
+/** Where one table's columns are read, when its form opens (src/cli/run-server.ts tableColumns): never with the state,
+ *  which is polled every 2 s and would carry every table's (3.4 MB at 800 tables of 50 columns). */
+/** A table's sync events: Observability › Sync events narrowed to it (src/web/pages/syncs.js `route`), over the week (its
+ *  copy and failures are rarely in the last 15 minutes, Now's). */
+export const syncsHref = (table) => `#observability/syncs?table=${encodeURIComponent(table)}&range=7d`;
+export const columnsPath = (table) => `/api/tables/${encodeURIComponent(table)}/columns`;
+
+/** A table's sync in one word (`/api/state` `tables[].sync.state`, src/cli/readiness.ts `syncStateOf`). */
+const SYNC_WORDS = { synced: "Synced", syncing: "Syncing", behind: "Behind", failed: "Failed", waiting: "Waiting" };
+
+/** Whether a table's name has the search box's text (any case; nothing typed: every table). */
+const nameMatches = (table, filter) => !filter || table.toLowerCase().includes(filter.trim().toLowerCase());
+
+/**
+ * WHAT A SYNC DID, as `mason sync` prints it from `POST /api/sync`'s answer (src/cli/sync.ts `syncedReport`, held equal
+ * by the tests): the rows written and deleted, a line per table, and what happens next to each table synced (`syncedTips`:
+ * an `off` one stays as of this sync). A table whose sync is replication was not polled: its line says where the stream
+ * is (`streamed`), and a sync of those alone has nothing to sync.
+ */
+export function syncedReport(b, picked, tables) {
+  const streamed = b.streamed ?? [];
+  const streamedRows = streamed.map((t) => [t.table, `${t.state}${t.why ? `: ${t.why}` : ""} · the stream has applied the database's changes through ${t.position}`]);
+  if (b.tables.length === 0 && streamed.length > 0) {
+    return { headline: `Nothing to sync: logical replication keeps ${picked.join(", ")} current.`, details: streamedRows, tips: [] };
+  }
+  const changed = b.tables.reduce((a, t) => a + t.changed, 0), deleted = b.tables.reduce((a, t) => a + t.deleted, 0);
+  const streamedNames = new Set(streamed.map((t) => t.table));
+  const polled = picked.filter((t) => !streamedNames.has(t));
+  return {
+    headline: `Synced ${polled.join(", ")}: ${n(changed)} row(s) written, ${n(deleted)} deleted${streamedRows.length ? `; logical replication keeps ${streamedRows.map((r) => r[0]).join(", ")} current` : ""}.`,
+    details: [...b.tables.map((t) => [t.table, `${n(t.changed)} changed, ${n(t.deleted)} deleted, ${n(t.rows)} rows now · ${msText(t.ms)}`]), ...streamedRows],
+    tips: syncedTips(tables),
+  };
+}
+
+/** What happens to each table synced after now, by its sync (src/cli/sync.ts `syncedTips`): an `off` table stays as of
+ *  this sync until the next one, a polled one is polled again after its interval. */
+function syncedTips(tables) {
+  return tables.flatMap((t) => {
+    const k = t.kept;
+    if (k?.by !== "poll") return [];
+    return [k.sync.mode === "off" ? `${t.table}'s sync is off: it stays as of this sync until the next mason sync ${entryName(t.table)}`
+      : `${t.table} is polled every ${k.sync.every}: its next poll is an interval from this one`];
+  });
+}
+
+/** A sync's answer said as `mason sync` says it, with Dismiss. `s`: the state, for the tables not kept current. */
+function renderSynced(b, table, s) {
+  const r = syncedReport(b, [table], s.tables.filter((t) => t.table === table));
+  return `<div class="done"><p class="headline">${esc(r.headline)}</p>${rowsHtml(r.details)}${r.tips.map((x) => `<p class="tip">Tip: ${esc(x)}</p>`).join("")}` +
+    `${button("Dismiss", { dismissSynced: "", popClose: "" }, "small")}</div>`;
+}
+
+/** The filter beside the search box: which of the database's tables are listed. */
+export const SHOWS = { all: "All", added: "Added", failed: "Failed", "not-added": "Not added" };
+
+/** How many of the tables that pass the filters the page writes at once; "Show N more" writes as many again. */
+const TABLE_ROWS = 100;
+
+/** Whether an added table's copy or sync failed (the Failed filter, the Overview's failed card). */
+const failedTable = (t) => t.added && (t.sync?.state === "failed" || Boolean(t.error));
+
+/** What brought a copy current, in a web developer's words (`/api/state` `tables[].sync.syncedBy` keeps the mechanism's
+ *  name for an operator: copy, poll, catch-up, stream). */
+export const SYNCED_BY = { copy: "read whole", poll: "changes checked", "catch-up": "changes checked", stream: "streamed" };
+/** How long a sync took, as the commands say it (`spanText`) but for one under a tenth of a second, which is not worth a
+ *  digit: `<0.1 s`; what did it is the cell's title (`tookTitle`: the column stays narrow enough for Sync and Remove). */
+export const tookText = (y) => y.syncSeconds < 0.1 ? "<0.1 s" : spanText(y.syncSeconds);
+export const tookTitle = (y) => SYNCED_BY[y.syncedBy] ?? String(y.syncedBy);
+
+/** A table's facts as `mason tables` says them on its line (src/cli/commands.ts `tableFacts`): its size, its key, and
+ *  added or why it cannot be added as it is (null: neither). */
+export function tableFacts(t) {
+  return { size: t.rows === null ? "rows unknown" : `~${n(t.rows)} rows`, key: t.key.length ? `key ${t.key.join(", ")}` : "no key",
+    state: t.added ? "added" : t.reason ? `cannot be added as it is: ${t.reason}` : null };
+}
+
+/** What `mason add` prints for a table added, from `/api/pick`'s answer (src/cli/commands.ts `addedLines`): its line,
+ *  then its notes — the key added to the columns asked, the secret-looking columns left out. */
+export function addedLines(b, file) {
+  const copies = b.columns === null ? (b.exclude.length ? `every column but ${b.exclude.join(", ")}` : "every column") : b.columns.join(", ");
+  const s = b.skippedSecrets;
+  const name = entryName(b.table);
+  const sync = b.bigOff ? `sync: off written on its entry: it has more than 1,000,000 rows, and each poll scans it whole on your database — ` +
+      `mason add ${name} --sync "poll 1h" polls it hourly; mason sync ${name} syncs it once, now; mason add ${name} --sync replication keeps it current from the change log`
+    : b.notReplicated ? `sync: poll 5m written on its entry, not the file's replication: ${b.notReplicated} — ` +
+      `mason add ${name} --sync "poll 1h" polls it hourly; mason add ${name} --sync off reads it only by mason sync ${name}`
+    : b.sync.value === "off" ? `sync: off (${b.sync.from === "entry" ? "its entry's" : b.sync.from === "file" ? "the file's" : "the default"}): after its first sync it is read again only by mason sync ${name} — ` +
+      `mason add ${name} --sync "poll 5m" polls it every 5 minutes`
+    : b.sync.value === "replication" ? `sync: replication (${b.sync.from === "entry" ? "its entry's" : "the file's"}): kept current from the database's change log after its first sync — ` +
+      `mason add ${name} --sync "poll 5m" polls it instead`
+    : `sync: ${b.sync.value} (${b.sync.from === "entry" ? "its entry's" : "the file's"}): polled every ${b.sync.value.slice("poll ".length)} after its first sync — mason add ${name} --sync off stops that`;
+  return { line: `Added ${b.table} to ${file}: ${copies}${b.key ? `, keyed by ${b.key.join(", ")}` : ""}${b.already ? " (already so)" : ""}`, notes: [
+    sync,
+    ...(b.pollCost !== null ? [b.pollCost] : []),
+    ...(b.addedKey.length ? [`key added: ${b.addedKey.join(", ")} (a synced table always has its key)`] : []),
+    ...(s.length ? [`left out ${s.join(", ")}: ${s.length === 1 ? "it looks" : "they look"} like ${s.length === 1 ? "a secret" : "secrets"}, ` +
+      `which anyone with a user's password could read (--include ${s[0]} adds it)`] : []),
+  ] };
+}
+
+/** What `mason remove` prints for the tables removed (src/cli/commands.ts `removedReport`). */
+export function removedReport(removed, file) {
+  return { headline: `Removed ${removed.join(", ")}`, details: [["from", file]],
+    tips: [`Mason stops syncing ${removed.length === 1 ? "it" : "them"} and drops ${removed.length === 1 ? "its synced data" : "their synced data"}`] };
+}
+
+/**
+ * `POST /api/pick`'s body for a table added: the columns ticked as `--columns`, the key's as `--key`, each left out when
+ * none is ticked (none: every column, as `mason add <table>` copies; no key: its primary key). What the lists may hold
+ * is the server's to judge (src/cli/run-server.ts `pick`), never the page's.
+ */
+export const pickBody = (table, columns = [], key = []) => ({ table, picked: true, ...(columns.length ? { columns } : {}), ...(key.length ? { key } : {}) });
+
+/** The sources file as the commands name it, from the project's root (`/api/state` `source.shownFile`), when it is the
+ *  one the state names: the page never shows an absolute path. */
+const shownFileOf = (s, file) => s?.source?.file === file && typeof s.source.shownFile === "string" ? s.source.shownFile : file;
+
+/** A table just added (`/api/pick`'s answer, `mason add --json`'s `added` entry): the line and notes `mason add` prints,
+ *  the sources file named as `file` (as `mason add` names it: from the project's root). */
+export function renderTableAdded(b, file = b.file) {
+  const l = addedLines(b, file);
+  return `<div class="done"><p class="headline">${esc(l.line)}</p>${l.notes.map((x) => `<p class="note">${esc(x)}</p>`).join("")}` +
+    `${button("Dismiss", { dismissOutcome: "", popClose: "" }, "small")}</div>`;
+}
+
+/** Tables just removed (`/api/remove`'s answer, `mason remove --json`'s shape): what `mason remove` prints, the file named
+ *  as `file`. */
+export function renderTablesRemoved(b, file = b.file) {
+  const r = removedReport(b.removed, file);
+  return `<div class="done"><p class="headline">${esc(r.headline)}</p>${rowsHtml(r.details)}${r.tips.map((x) => `<p class="tip">Tip: ${esc(x)}</p>`).join("")}` +
+    `${button("Dismiss", { dismissOutcome: "", popClose: "" }, "small")}</div>`;
+}
+
+const tick = (name, c, on) => `<label class="tick"><input type="checkbox" name="${name}" value="${esc(c.name)}"${on ? " checked" : ""}> ${code(c.name)} <span class="dim">${esc(c.type)}</span></label>`;
+
+/** The form that adds a table with the columns ticked (`--columns`) and, for one with no primary key, its key (`--key`).
+ *  The ticks live in the document while the person ticks (the tables part is held still meanwhile: the page's `held`);
+ *  `ticked`, what a refused submit sent, writes them back when the refusal is said over the form, in its popover. `cols` is what
+ *  `GET /api/tables/<table>/columns` answered for it — { table, columns } or { table, failure } — or null while it is read. */
+function pickForm(t, cols, ticked = null) {
+  const name = entryName(t.table);
+  if (cols?.table !== t.table) return `<p class="dim">Reading ${esc(name)}'s columns…</p>${button("Cancel", { cancelChoose: "", popClose: "" }, "small")}`;
+  if ("failure" in cols) return `${renderFailure(cols.failure)}${button("Cancel", { cancelChoose: "", popClose: "" }, "small")}`;
+  const boxes = (field) => cols.columns.map((c) => tick(field, c, ticked?.[field]?.includes(c.name) ?? false)).join("");
+  return `<form class="pick" data-pick-form="${esc(t.table)}" autocomplete="off">` +
+    (t.key.length ? "" : `<fieldset><legend>Its key: the columns that tell its rows apart, as ${code(`mason add ${name} --key`)}</legend>${boxes("key")}</fieldset>`) +
+    `<fieldset><legend>Its columns, as ${code(`mason add ${name} --columns`)} (none ticked: as ${code(`mason add ${name}`)}, every column)</legend>${boxes("columns")}</fieldset>` +
+    `<button type="submit" class="primary small">Add ${esc(name)}</button> ${button("Cancel", { cancelChoose: "", popClose: "" }, "small")}</form>`;
+}
+
+/** The cards over the list: the tables added of all, those synced, those failed and the copies' rows (`/api/state`
+ *  `totals`, which `mason status --json` also carries); none before the state, or with no table to count. */
+export function renderTablesCards(s) {
+  const t = s.totals;
+  if (!t || !s.tables.length) return "";
+  const added = s.tables.filter((x) => x.added).length;
+  return cards([
+    card("Tables added", `${n(added)} of ${n(s.tables.length)}`, "in the database"),
+    card("Synced", n(t.copied), `of ${n(added)} added${copyingCount(s) ? `, ${n(copyingCount(s))} syncing` : ""}`),
+    card("Failed", n(t.failed), `of ${n(added)} added`, "", t.failed ? "bad" : ""),
+    card("Rows", n(t.rows), "in the synced tables"),
+  ]);
+}
+
+/**
+ * THE DATABASE'S TABLES from `/api/state` `tables` (`mason tables --json`'s list), ONE table in a card: a row each — its
+ * name in mono, its state as a dot and the word (an added table's sync: Synced / Syncing / Failed / Waiting, else Not
+ * added), its rows, its key, an added table's last sync as its age (the UTC time in a title), how long it took and the
+ * copy's own size (`ui.sizes`: `/api/usage`'s body or `{ failure }`), its stream state in replication mode, and a note —
+ * its error as a red line (the whole error in a details, `ui.open(key)` whether it is open), or why it cannot be added as
+ * it is (`tableFacts`, as `mason tables` prints it). What can be done: Sync and Remove (asking first, `ui.removing`) for an
+ * added table; Add (every column, as `mason add <table>`) and Columns… (the form) for one not added; Name its key… for
+ * one with no primary key. `ui.choosing` is the table whose form is open (`ui.ticked` its boxes ticked: { columns, key };
+ * `ui.columns` its columns as read when it opened: { table, columns } | { table, failure }, null while read);
+ * `ui.outcome` what the last add or remove answered ({ table, added } | { table, removed } | { table, failure }) and
+ * `ui.synced` what the last sync did, each a popover beside its table's actions (`at`: when, gone after OUTCOME_MS at `ui.now`); `ui.syncing` the tables whose sync is asked; `ui.filter` the
+ * search box's text and `ui.show` the state filter (a key of SHOWS).
+ */
+export function renderTables(s, ui = {}) {
+  const { removing = null, choosing = null, columns = null, outcome = null, ticked = null, filter = "", show = "all", sizes, syncing = [], adding = [], shares = new Map(), before = new Map(), synced = null, open = () => false, limit = TABLE_ROWS } = ui;
+  const now = ui.now ?? Date.now();
+  if (!s.tables.length) return empty(`${s.source.database} has no table this user can read.`);
+  // why no table can be added or removed from here (a server's sources file this run cannot write), or null
+  const readOnly = s.sourcesReadOnly ?? null;
+  const stream = s.stream ? new Map(streamRows(s.stream, now).tables) : null;
+  // SEVEN NARROW COLUMNS OF FIXED WIDTHS, NOTHING LONG IN A CELL, AND NOTHING A CLICK INSERTS: a table's state is its word
+  // over its copy's bar (a line kept for it when it has none); its last sync an age over how long it took; whatever is
+  // said at length — the words `mason wait` prints, an error, why it cannot be added, its stream state — is ITS NOTE, a
+  // line of its own under the row, across every column, written for every row (empty when it says nothing), so a note
+  // that comes or goes moves no row. A question (Remove), a form (Columns…) and what an action answered are POPOVERS
+  // beside the row's actions (`pop`), written after the table: a click moves no other row and no column
+  // (`table-layout: fixed`, the stylesheet's widths by the header's classes; a button whose label changes keeps its room).
+  const head = [["Table", "name"], ["State", "state"], ["Rows", "num rows"], ["Key", "key"], ["Last sync", "num last"], ["Size", "num size"], ["", "act"]];
+  const sizeOf = new Map(sizes && !("failure" in sizes) ? sizes.copySizes.map((c) => [c.table, c.bytes]) : []);
+  const under = (html, cls = "") => `<tr class="under${cls ? ` ${cls}` : ""}"><td colspan="${head.length}"><div class="under-body">${html}</div></td></tr>`;
+  const cell = (v, cls = "", title = "") => `<td${cls ? ` class="${cls}"` : ""}${title ? ` title="${esc(title)}"` : ""}>${esc(v)}</td>`;
+  // the popovers of the rows written, in their order: after the table, each anchored to its row's actions
+  const pops = [];
+  const line = (t) => {
+    const f = tableFacts(t);
+    const name = entryName(t.table);
+    const y = t.sync;
+    const adding_ = adding.includes(t.table);
+    const asking = removing === t.table;
+    const anchor = actId("tables", t.table);
+    const syncedNow = synced?.table === t.table && !("failure" in synced) && fresh(synced, now);
+    const act = adding_ ? button("Adding…", {}, "primary small", { disabled: true }) : t.added
+      // Sync now → Syncing… → Synced ✓ in the one room (ROOMS.sync), so the actions never move
+      // View events: its sync events, on Observability › Sync events (a link: it goes to another page)
+      ? `<a class="btn small" href="${esc(syncsHref(t.table))}">View events</a> ` +
+        (syncing.includes(t.table) ? button("Syncing…", {}, "small", { room: ROOMS.sync, disabled: true }) : button(syncedNow ? "Synced ✓" : "Sync now", { syncTable: t.table }, "small", { room: ROOMS.sync })) + " " +
+        // while it asks, Remove stays where it was, held down: the question beside it answers it
+        (readOnly ? "" : asking ? button("Remove", {}, "danger small", { disabled: true, expanded: true }) : button("Remove", { removeTable: t.table }, "danger small"))
+      // a sources file this run cannot write (`s.sourcesReadOnly`, a server's): no control that could only fail
+      : readOnly ? ""
+      : t.reason === null
+        ? `${button("Add", { addTable: t.table }, "primary small")} ${choosing === t.table ? button("Columns…", {}, "small", { disabled: true, expanded: true }) : button("Columns…", { choose: t.table }, "small")}`
+        : t.key.length ? "" : choosing === t.table ? button("Name its key…", {}, "small", { disabled: true, expanded: true }) : button("Name its key…", { choose: t.table }, "small");
+    // a failed copy's rows so far are none: the copy it serves meanwhile is said by its error and mason status
+    const rows = t.added && t.copy && t.copy.phase !== "failed" ? n(t.copy.rowsCopied) : f.size;
+    // EVERY ADDED TABLE HAS ITS BAR, as `mason status` and `mason wait` print one for each (src/cli/commands.ts
+    // `tableLines`): full at 100% once copied, red when its copy failed, amber when it is not kept current, moving while
+    // it copies, the indeterminate shimmer while it waits — the Overview's renderer (`copyBar`), its words the line's;
+    // a table with none keeps its line, empty, so the row is as tall either way
+    const l = t.added && !adding_ ? tableLine(t) : null;
+    const bar = l ? `<span class="copyline t-${l.state}">${copyBar(t.table, l, shares.get(t.table) ?? l.fraction, before.get(t.table))}</span>` : `<span class="copyline none" aria-hidden="true"></span>`;
+    const state = adding_ ? status("warn", "Adding…") : t.added ? (y ? status(undefined, SYNC_WORDS[y.state]) : "") : status("unknown", "Not added");
+    const took = t.added && y?.syncSeconds != null ? `<span class="took" title="${esc(tookTitle(y))}">took ${esc(tookText(y))}</span>` : "";
+    const last = t.added && y?.syncedAt && y?.ageSeconds != null
+      ? `<td class="num"><span title="${esc(`${utcText(y.syncedAt)} UTC`)}">${esc(`${duration(y.ageSeconds)} ago`)}</span>${took}</td>` : `<td class="num">${took}</td>`;
+    // what is said at length, its note under the row: the words the CLI prints after a bar that is not full and current,
+    // an error (its first line; the whole in a details), why it cannot be added as it is, its stream state (replication mode)
+    const said_ = adding_ ? `<span class="dim">adding it to the sources file…</span>`
+      : t.added ? [
+        l && l.state !== "done" && !t.error ? `<span class="what-copy t-${l.state}">${esc(l.what)}</span>` : "",
+        t.error ? `<span class="err">${esc(firstLine(t.error))}</span>${t.error.includes("\n") ? details(`error:${t.table}`, "the whole error", `<pre>${esc(t.error)}</pre>`, open(`error:${t.table}`)) : ""}` : "",
+        stream && stream.get(t.table) ? `<span class="stream dim">Stream: ${esc(stream.get(t.table))}</span>` : "",
+      ].filter(Boolean).join("")
+      : f.state ? `<span class="dim">${esc(f.state)}</span>` : "";
+    const note = under(said_, "note");
+    if (asking) {
+      pops.push(pop(anchor, `<p class="confirm">Remove ${esc(name)}? ${esc(removedReport([t.table], "").tips[0])}.</p>` +
+        `<p class="pop-actions">${button(`Remove ${name}`, { confirmRemoveTable: t.table }, "danger small")} ${button("Cancel", { cancelRemoveTable: "", popClose: "" }, "small")}</p>`, { kind: "dialog", label: `Remove ${name}?` }));
+    }
+    // a refused add with its form open: the refusal is said in the form's popover, over the boxes as they were ticked
+    const formOpen = choosing === t.table && !t.added;
+    const refusedHere = outcome?.table === t.table && "failure" in outcome;
+    if (formOpen) pops.push(pop(anchor, (refusedHere ? renderFailure(outcome.failure) : "") + pickForm(t, columns, ticked), { kind: "dialog", label: `Add ${name}` }));
+    if (outcome?.table === t.table && fresh(outcome, now) && !(formOpen && refusedHere)) {
+      pops.push(pop(anchor, "failure" in outcome ? `${renderFailure(outcome.failure)}${button("Dismiss", { dismissOutcome: "", popClose: "" }, "small")}`
+        : "added" in outcome ? renderTableAdded(outcome.added, shownFileOf(s, outcome.added.file)) : renderTablesRemoved(outcome.removed, shownFileOf(s, outcome.removed.file))));
+    }
+    if (synced?.table === t.table && fresh(synced, now)) {
+      pops.push(pop(anchor, "failure" in synced ? `${renderFailure(synced.failure)}${button("Dismiss", { dismissSynced: "", popClose: "" }, "small")}` : renderSynced(synced.synced, t.table, s)));
+    }
+    return `<tr class="${t.added ? `c-added s-${y?.state ?? "unknown"}` : t.reason ? "c-cannot" : "c-not"}${said_ ? " has-note" : ""}"><th scope="row" class="name"><code class="name" title="${esc(t.table)}">${esc(t.table)}</code></th>` +
+      `<td class="state">${state}${bar}</td>${cell(rows, "num")}${cell(f.key, "mono", f.key)}${last}` +
+      `${t.added ? (sizeOf.has(t.table) ? cell(bytesText(sizeOf.get(t.table)), "num") : cell("—", "num", "not measured yet: a synced table's size is measured every 10 min")) : cell("", "num")}` +
+      `<td class="act" id="${esc(anchor)}">${act}</td></tr>` + note;
+  };
+  const added = s.tables.filter((t) => t.added).length;
+  // a refusal for a table the list does not have (dropped since the run read the catalog): said above the list
+  const stray = outcome !== null && "failure" in outcome && !s.tables.some((t) => t.table === outcome.table) ? renderFailure(outcome.failure) : "";
+  // the search box's text and the state filter: the tables that pass both (the one a form or a confirm is open on stays, whatever they say)
+  const passes = (t) => (show === "added" ? t.added : show === "failed" ? failedTable(t) : show === "not-added" ? !t.added : true) && nameMatches(t.table, filter);
+  const shown = s.tables.filter((t) => passes(t) || t.table === choosing || t.table === removing);
+  // at most `limit` rows written (the one a form or a confirm is open on always): a database of 800 tables costs 100 rows
+  const written = shown.filter((t, i) => i < limit || t.table === choosing || t.table === removing);
+  const matching = filter.trim() ? `<p class="count dim">${n(shown.length)} with “${esc(filter.trim())}” in the name</p>` : "";
+  const sizesFailed = added && sizes && "failure" in sizes ? `<p class="count">The synced tables' own sizes: could not read them (${esc(firstLine(sizes.failure.message))}; ${code("mason usage")} has them)</p>` : "";
+  const rowsHtml_ = written.map(line).join("");
+  return stray + (readOnly === null ? "" : `<p class="count">Tables are not added or removed from this page: ${esc(readOnly)}.</p>`) +
+    (added ? "" : empty("No table added yet", readOnly === null ? `Add one from the list, as ${code("mason add <table>")} does.` : `The sources file names the tables to sync.`)) + matching +
+    panel(`<table class="catalog"><thead><tr>${head.map(([h, c]) => `<th scope="col"${c ? ` class="${c}"` : ""}>${h}</th>`).join("")}</tr></thead>` +
+      `<tbody>${rowsHtml_}</tbody></table>`) + pops.join("") + moreRows("tables", Math.min(limit, shown.length), shown.length, TABLE_ROWS) +
+    (!shown.length ? `<p class="dim">No ${show === "added" ? "added " : show === "failed" ? "failed " : show === "not-added" ? "table that is not added, " : ""}table${filter.trim() ? `'s name has “${esc(filter.trim())}”` : ""}.</p>` : "") + sizesFailed +
+    (added ? `<p class="dim">A synced table's own size is measured every 10 minutes (${code("mason usage")}).</p>` : "");
+}
+
+export const page = {
+  id: "tables",
+  title: "Tables",
+  create(ctx) {
+    const m = { removing: null, choosing: null, columns: null, outcome: null, ticked: null, held: null, heldFilter: null, heldShow: null, filter: "", show: "all", syncing: [], adding: [], synced: null, limit: TABLE_ROWS };
+    const state = () => ctx.read("/api/state")?.body ?? null;
+    const monotone = createMonotone();
+    // the details open (a copy's whole error), by key: a poll rewrites the part, and they stay open
+    const opened = createOpenSet();
+    // WHILE A FORM IS OPEN OR A REMOVE ASKS, THE TABLES ARE RENDERED FROM THE STATE THEY WERE OPENED OVER (`held`): the
+    // run reads the catalog again every few seconds, and a live database's row estimates move, so a part written from
+    // each poll's state would be rewritten under the person — the form's ticks gone, the confirm's button replaced under
+    // the click. So the list is FROZEN for as long as a form stays open or a Remove asks — however long that is, with no
+    // refresh in between (its rows and its added marks may be minutes old) — and is written from the latest state again
+    // once they Add, Cancel or confirm.
+    const hold = () => {
+      const held = m.choosing !== null || m.removing !== null;
+      m.heldFilter = held ? m.held === null ? m.filter : m.heldFilter : null;
+      m.heldShow = held ? m.held === null ? m.show : m.heldShow : null;
+      m.held = held ? m.held ?? state() : null;
+      if (m.choosing === null) m.ticked = null;
+    };
+    const actions = {
+      /** Add a table (`mason add`): the answer beside its actions, then the state read again — the Overview shows its copy starting. */
+      async addTable(table, columns = [], key = []) {
+        if (m.adding.includes(table)) return false;
+        // from the click: the row says Adding… (the page paints before the answer), then the state read again shows the copy
+        m.adding = [...m.adding, table];
+        if (m.choosing !== table) { m.outcome = null; m.synced = null; }
+        const r = await ctx.ask("/api/pick", json("POST", pickBody(table, columns, key)));
+        m.adding = m.adding.filter((x) => x !== table);
+        // refused: said over the form, in its popover, written again with the boxes the person had ticked
+        if ("failure" in r) { m.outcome = { table, failure: r.failure }; if (m.choosing === table) m.ticked = { columns, key }; return false; }
+        m.outcome = { table, added: r.body, at: ctx.now().getTime() }; m.choosing = null; m.columns = null; hold();
+        await ctx.refresh(["/api/state"]);
+        return true;
+      },
+      /** Open a table's form: its columns read now, once (the state the page polls carries none). */
+      async choose(table) {
+        // a question opened takes the last answer away: two popovers never stand on one another
+        m.choosing = table; m.removing = null; m.ticked = null; m.columns = null; m.outcome = null; m.synced = null; hold();
+        const r = await ctx.ask(columnsPath(table));
+        // closed, or another table's opened, while it was read: that answer is not this form's
+        if (m.choosing !== table) return false;
+        m.columns = "failure" in r ? { table, failure: r.failure } : { table, columns: r.body.columns };
+        return true;
+      },
+      cancelChoose() { m.choosing = null; m.columns = null; hold(); },
+      askRemoveTable(table) { m.removing = table; m.choosing = null; m.outcome = null; m.synced = null; hold(); },
+      cancelRemoveTable() { m.removing = null; hold(); },
+      /** Remove a table (`mason remove`), once asked: the answer beside its actions, then the state read again. */
+      async confirmRemoveTable(table) {
+        const r = await ctx.ask("/api/remove", json("POST", { tables: [table] }));
+        m.removing = null; hold();
+        if ("failure" in r) { m.outcome = { table, failure: r.failure }; return false; }
+        m.outcome = { table, removed: r.body, at: ctx.now().getTime() };
+        await ctx.refresh(["/api/state"]);
+        return true;
+      },
+      dismissOutcome() { m.outcome = null; },
+      /** Sync a table now (`mason sync <table>`): the answer beside its Sync, then the state read again. */
+      async syncTable(table) {
+        m.syncing = [...m.syncing, table];
+        m.outcome = null; m.synced = null;
+        const r = await ctx.ask("/api/sync", json("POST", { tables: [table] }));
+        m.syncing = m.syncing.filter((x) => x !== table);
+        m.synced = "failure" in r ? { table, failure: r.failure } : { table, synced: r.body, at: ctx.now().getTime() };
+        await ctx.refresh(["/api/state"]);
+        return !("failure" in r);
+      },
+      dismissSynced() { m.synced = null; },
+      /** The search box's text: kept here, so every poll writes the lists filtered by it. */
+      filterTables(text) { m.filter = text; m.limit = TABLE_ROWS; },
+      /** The state filter beside it (a key of SHOWS; anything else is All). */
+      showTables(which) { m.show = Object.hasOwn(SHOWS, which) ? which : "all"; m.limit = TABLE_ROWS; },
+      /** Write TABLE_ROWS more of the tables that pass, or all of them. */
+      showMoreTables() { m.limit += TABLE_ROWS; },
+      showAllTables() { m.limit = Infinity; },
+    };
+    return {
+      model: m,
+      reads: () => [{ path: "/api/state", everyMs: POLL_MS }, { path: SIZES_PATH, everyMs: 60_000 }],
+      afterRead() {
+        const s = state();
+        if (s === null) return;
+        // a table removed or added elsewhere (mason remove, mason add) takes its confirm or its form with it
+        const added = (table) => s.tables.some((t) => t.table === table && t.added);
+        if (m.removing !== null && !added(m.removing)) m.removing = null;
+        if (m.choosing !== null && added(m.choosing)) m.choosing = null;
+        hold();
+      },
+      actions,
+      view() {
+        const s = m.held ?? state();
+        const sizes = ctx.read(SIZES_PATH);
+        // held still while a form is open or a Remove asks, the search box's text and the state filter included: nothing moves under the person
+        const latest = state();
+        return {
+          "tables-cards": latest ? renderTablesCards(latest) : "",
+          tables: s ? renderTables(s, { removing: m.removing, choosing: m.choosing, columns: m.columns, outcome: m.outcome, ticked: m.ticked, now: ctx.now().getTime(),
+            filter: m.held ? m.heldFilter : m.filter, show: m.held ? m.heldShow : m.show, syncing: m.syncing, adding: m.adding, shares: monotone.of(latest ?? s), before: monotone.before, synced: m.synced, open: opened.has, limit: m.limit,
+            sizes: sizes === undefined ? undefined : sizes.failure ? { failure: sizes.failure } : sizes.body }) : "",
+        };
+      },
+      submit(form, FormData) {
+        // a table's form is written into the tables part: the ticked boxes sent as they are (FormData's getAll: the
+        // values of the boxes ticked, in the page's order)
+        if (form.dataset?.pickForm === undefined) return null;
+        const ticked = new FormData(form);
+        return actions.addTable(form.dataset.pickForm, ticked.getAll("columns"), ticked.getAll("key"));
+      },
+      /** `#tables?show=failed`: the state filter as the hash says (the select beside the search box shows it too). */
+      route(params, { doc } = {}) {
+        if (params.show === undefined) return;
+        actions.showTables(params.show);
+        const select = doc?.getElementById?.("tables-show");
+        if (select) select.value = m.show;
+      },
+      click(d) {
+        if (d.showMore === "tables") return actions.showMoreTables() ?? true;
+        if (d.showAll === "tables") return actions.showAllTables() ?? true;
+        if (d.addTable !== undefined) return actions.addTable(d.addTable);
+        if (d.choose !== undefined) return actions.choose(d.choose);
+        if (d.cancelChoose !== undefined) return actions.cancelChoose() ?? true;
+        if (d.removeTable !== undefined) return actions.askRemoveTable(d.removeTable) ?? true;
+        if (d.cancelRemoveTable !== undefined) return actions.cancelRemoveTable() ?? true;
+        if (d.confirmRemoveTable !== undefined) return actions.confirmRemoveTable(d.confirmRemoveTable);
+        if (d.dismissOutcome !== undefined) return actions.dismissOutcome() ?? true;
+        if (d.syncTable !== undefined) return actions.syncTable(d.syncTable);
+        if (d.dismissSynced !== undefined) return actions.dismissSynced() ?? true;
+        return null;
+      },
+      toggle: (target) => opened.toggle(target),
+      input(target) {
+        if (target.id === "tables-show") return actions.showTables(target.value) ?? true;
+        if (target.id !== "tables-filter") return null;
+        return actions.filterTables(target.value) ?? true;
+      },
+    };
+  },
+};