@foldspace_npm/harness 0.1.27 → 0.1.28

package/recipes/lookup-then-view/agent/views/account.ts

@@ -0,0 +1,183 @@
+// The account card, a view card. Once it is drawn, the agent gets what
+// show_account_overview's execute returned - the facts this card draws from:
+// every open deal, person and open case, where the card lists three of each.
+// Laid out to be read in five seconds at chat width:
+//
+//   who the account is   ->  name, industry, size, place, website, owner
+//   the money            ->  four tiles: open pipeline, weighted, deals, cases
+//   what is moving       ->  the biggest open deals, each with stage and close date
+//   who to talk to       ->  the primary contact first, title under the name
+//   what is wrong        ->  open cases, critical ones marked
+//
+// textContent only - never innerHTML with API data. Styles go in `header`.
+
+import { isCritical, type Overview } from "../accounts";
+import { brand } from "./brand";
+import { count, DASH, domain, initials, money, moneyShort, plural, relativeDay, titleCase } from "./format";
+
+const SHOWN = 3;
+
+const CSS = `
+.fs-ac{background:${brand.surface};border:1px solid ${brand.border};border-radius:${brand.radius};font-family:${brand.font};
+  color:${brand.text};width:100%;box-sizing:border-box;font-size:13px;line-height:1.35;overflow:hidden}
+.fs-ac *{box-sizing:border-box;margin:0}
+.fs-ac-head{display:flex;gap:12px;align-items:flex-start;padding:14px}
+.fs-ac-logo{width:40px;height:40px;border-radius:10px;background:${brand.accent};color:${brand.accentText};font-weight:600;font-size:14px;
+  display:flex;align-items:center;justify-content:center;flex-shrink:0}
+.fs-ac-who{min-width:0;flex:1}
+.fs-ac-name{font-size:16px;font-weight:600;color:${brand.textStrong};line-height:1.25}
+.fs-ac-sub{font-size:12px;color:${brand.muted};margin-top:2px}
+.fs-ac-owner{font-size:11px;color:${brand.faint};margin-top:4px}
+.fs-ac-tiles{display:grid;grid-template-columns:repeat(4,1fr);border-top:1px solid ${brand.border};border-bottom:1px solid ${brand.border};background:${brand.surface2}}
+.fs-ac-tile{padding:10px 8px;text-align:center;border-left:1px solid ${brand.border}}
+.fs-ac-tile:first-child{border-left:0}
+.fs-ac-num{display:block;font-size:17px;font-weight:600;color:${brand.textStrong};font-variant-numeric:tabular-nums}
+.fs-ac-num.is-money{color:${brand.good}}
+.fs-ac-num.is-bad{color:${brand.bad}}
+.fs-ac-cap{display:block;font-size:10px;color:${brand.muted};text-transform:uppercase;letter-spacing:.4px;margin-top:2px}
+.fs-ac-hint{display:block;font-size:10px;color:${brand.bad};margin-top:1px}
+.fs-ac-sec{padding:10px 14px 4px}
+.fs-ac-sec-title{display:flex;justify-content:space-between;font-size:11px;font-weight:600;color:${brand.muted};text-transform:uppercase;letter-spacing:.4px;margin-bottom:4px}
+.fs-ac-row{display:flex;align-items:center;gap:10px;padding:7px 0;border-bottom:1px solid ${brand.border}}
+.fs-ac-row:last-child{border-bottom:0}
+.fs-ac-main{flex:1;min-width:0}
+.fs-ac-title{font-weight:600;color:${brand.textStrong};overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.fs-ac-detail{font-size:12px;color:${brand.muted};overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.fs-ac-detail .is-late{color:${brand.warn};font-weight:500}
+.fs-ac-amount{text-align:right;font-weight:600;color:${brand.textStrong};font-variant-numeric:tabular-nums;white-space:nowrap}
+.fs-ac-prob{display:block;font-size:11px;font-weight:400;color:${brand.muted}}
+.fs-ac-chip{display:inline-block;padding:1px 7px;border-radius:999px;background:${brand.accentSoft};color:${brand.accent};font-size:11px;font-weight:500}
+.fs-ac-avatar{width:28px;height:28px;border-radius:50%;background:${brand.surface2};color:${brand.text};border:1px solid ${brand.border};
+  font-size:11px;font-weight:600;display:flex;align-items:center;justify-content:center;flex-shrink:0}
+.fs-ac-tag{font-size:10px;color:${brand.accent};font-weight:600;margin-left:6px}
+.fs-ac-dot{width:8px;height:8px;border-radius:50%;flex-shrink:0;background:${brand.faint}}
+.fs-ac-dot.is-critical{background:${brand.bad}}
+.fs-ac-dot.is-high{background:${brand.warn}}
+.fs-ac-empty{padding:6px 0 8px;color:${brand.faint};font-size:12px}
+.fs-ac-more{font-size:11px;color:${brand.muted};padding:4px 0 8px}
+`;
+
+function el(tag: string, className: string, text?: string): HTMLElement {
+  const node = document.createElement(tag);
+  node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+function tip(node: HTMLElement, text: string): HTMLElement {
+  node.title = text;
+  return node;
+}
+
+function section(title: string, total: number): { box: HTMLElement; list: HTMLElement } {
+  const box = el("div", "fs-ac-sec");
+  const head = el("div", "fs-ac-sec-title");
+  head.append(el("span", "", title), el("span", "", total ? String(total) : ""));
+  const list = el("div", "");
+  box.append(head, list);
+  return { box, list };
+}
+
+function more(list: HTMLElement, total: number): void {
+  if (total > SHOWN) list.append(el("div", "fs-ac-more", `+ ${total - SHOWN} more`));
+}
+
+export function mountAccount(host: HTMLElement, header: HTMLElement, view: Overview, now = Date.now()): void {
+  const style = el("style", "");
+  style.textContent = CSS;
+  header.append(style);
+  const { account, metrics } = view;
+  const cur = account.currency;
+  const card = el("div", "fs-ac");
+
+  // ---- who the account is
+  const head = el("div", "fs-ac-head");
+  head.append(el("div", "fs-ac-logo", initials(account.name)));
+  const who = el("div", "fs-ac-who");
+  who.append(el("div", "fs-ac-name", account.name));
+  const facts = [
+    account.industry,
+    account.employeeCount === null ? null : plural(account.employeeCount, "employee"),
+    account.place,
+    domain(account.website),
+  ].filter(Boolean);
+  who.append(el("div", "fs-ac-sub", facts.length ? facts.join("  ·  ") : "No details on record."));
+  if (account.owner) who.append(el("div", "fs-ac-owner", `Account owner: ${account.owner}`));
+  head.append(who);
+  card.append(head);
+
+  // ---- the money: short in the tile, exact in the tooltip
+  const tiles = el("div", "fs-ac-tiles");
+  const tile = (value: string, caption: string, kind = "", exact?: string, hint?: string) => {
+    const box = el("div", "fs-ac-tile");
+    const num = el("span", `fs-ac-num${kind ? ` is-${kind}` : ""}`, value);
+    if (exact) tip(num, exact);
+    box.append(num, el("span", "fs-ac-cap", caption));
+    if (hint) box.append(el("span", "fs-ac-hint", hint));
+    return box;
+  };
+  tiles.append(
+    tile(moneyShort(metrics.openPipeline, cur), "Open pipeline", "money", money(metrics.openPipeline, cur)),
+    tile(moneyShort(metrics.weightedPipeline, cur), "Weighted", "", `${money(metrics.weightedPipeline, cur)} - each deal times its probability`),
+    tile(count(metrics.openDeals), "Open deals"),
+    tile(count(metrics.openCases), "Open cases", metrics.criticalCases ? "bad" : "", undefined, metrics.criticalCases ? `${metrics.criticalCases} critical` : undefined),
+  );
+  card.append(tiles);
+
+  // ---- what is moving: biggest open deals first
+  const deals = section("Open deals", view.deals.length);
+  if (!view.deals.length) deals.list.append(el("div", "fs-ac-empty", "No open deals."));
+  for (const deal of view.deals.slice(0, SHOWN)) {
+    const row = el("div", "fs-ac-row");
+    const main = el("div", "fs-ac-main");
+    main.append(el("div", "fs-ac-title", deal.name));
+    const detail = el("div", "fs-ac-detail");
+    if (deal.stage) detail.append(el("span", "fs-ac-chip", titleCase(deal.stage)), el("span", "", "  "));
+    const close = relativeDay(deal.closeDate, now);
+    if (close) detail.append(tip(el("span", close.past ? "is-late" : "", close.past ? `Close date passed ${close.label}` : `Closes ${close.label}`), close.full));
+    main.append(detail);
+    const amount = el("div", "fs-ac-amount", money(deal.amount, cur));
+    if (deal.probability !== null) amount.append(el("span", "fs-ac-prob", `${Math.round(deal.probability)}%`));
+    row.append(main, amount);
+    deals.list.append(row);
+  }
+  more(deals.list, view.deals.length);
+  card.append(deals.box);
+
+  // ---- who to talk to: primary contact first
+  const people = section("People", view.people.length);
+  if (!view.people.length) people.list.append(el("div", "fs-ac-empty", "No contacts on record."));
+  for (const person of view.people.slice(0, SHOWN)) {
+    const row = el("div", "fs-ac-row");
+    row.append(el("div", "fs-ac-avatar", initials(person.name)));
+    const main = el("div", "fs-ac-main");
+    const name = el("div", "fs-ac-title", person.name);
+    if (person.primary) name.append(el("span", "fs-ac-tag", "PRIMARY"));
+    main.append(name);
+    main.append(el("div", "fs-ac-detail", [person.title, person.email, person.phone].filter(Boolean).join("  ·  ") || DASH));
+    row.append(main);
+    people.list.append(row);
+  }
+  more(people.list, view.people.length);
+  card.append(people.box);
+
+  // ---- what is wrong: open cases, critical ones marked
+  if (view.cases.length) {
+    const cases = section("Open cases", view.cases.length);
+    for (const item of view.cases.slice(0, SHOWN)) {
+      const row = el("div", "fs-ac-row");
+      const level = isCritical(item.priority) ? " is-critical" : /^high$/i.test(item.priority ?? "") ? " is-high" : "";
+      row.append(el("div", `fs-ac-dot${level}`));
+      const main = el("div", "fs-ac-main");
+      main.append(el("div", "fs-ac-title", item.title));
+      const opened = relativeDay(item.createdAt, now);
+      main.append(el("div", "fs-ac-detail", [item.priority ? titleCase(item.priority) : null, opened ? `opened ${opened.label}` : null].filter(Boolean).join("  ·  ") || DASH));
+      row.append(main);
+      cases.list.append(row);
+    }
+    more(cases.list, view.cases.length);
+    card.append(cases.box);
+  }
+
+  host.textContent = "";
+  host.append(card);
+}

package/recipes/lookup-then-view/agent/views/brand.ts

@@ -0,0 +1,35 @@
+// Placeholder with the keys of the agent/views/brand.ts that
+// `npx foldspace observe styles --write` writes. When you copy this recipe,
+// keep the project's own brand.ts; if it has none yet, run that command.
+
+export const brand = {
+  surface: "#FFFFFF",
+  surface2: "#F6F7FB",
+  text: "#374151",
+  muted: "#6B7280",
+  border: "#E5E7EB",
+  accent: "#3248F2",
+  accentText: "#FFFFFF",
+  font: 'Roboto, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif',
+  radius: "10px",
+  size: { base: "14px", small: "12px" },
+  textStrong: "#111827",
+  faint: "#9CA3AF",
+  row: "#F9FAFB",
+  tableHead: "#F3F4F6",
+  accentDeep: "#2538D6",
+  accentSoft: "#EEF0FE",
+  headerStart: "#F0F1FE",
+  good: "#047857",
+  warn: "#B45309",
+  warnInk: "#FEF3C7",
+  bad: "#B91C1C",
+  primary: "#3248F2",
+  tint: "#F3F4F6",
+  disabled: "#9CA3AF",
+  money: "#047857",
+  ok: "#047857",
+  deals: "#3248F2",
+  contacts: "#2538D6",
+  cases: "#B45309",
+} as const;

package/recipes/lookup-then-view/agent/views/format.ts

@@ -0,0 +1,73 @@
+// How people, accounts and money read on a card. One place, so every card in
+// the project says "$1.2M", "in 12 days" and "-" the same way.
+//
+// - Money: the account's own currency, no cents. Short in a headline tile
+//   ($1.2M) with the full amount in the tooltip; full in a row ($125,000).
+// - Missing is "-", never 0: a deal amount nobody entered is not $0.
+// - Dates: relative ("in 12 days", "3 days ago") with the date in the tooltip.
+// - People: the name first, then the title; contact details as plain text.
+
+function locale(): string {
+  const doc = typeof document !== "undefined" ? (document as Document & { documentElement?: { lang?: string } }) : null;
+  const lang = doc?.documentElement?.lang;
+  return lang || (typeof navigator !== "undefined" && navigator.language) || "en-US";
+}
+
+export const DASH = "-";
+
+export function money(value: number | null, currency = "USD"): string {
+  if (value === null) return DASH;
+  return new Intl.NumberFormat(locale(), { style: "currency", currency, maximumFractionDigits: 0 }).format(value);
+}
+
+export function moneyShort(value: number | null, currency = "USD"): string {
+  if (value === null) return DASH;
+  return new Intl.NumberFormat(locale(), {
+    style: "currency",
+    currency,
+    notation: "compact",
+    maximumFractionDigits: Math.abs(value) >= 1_000_000 ? 1 : 0,
+  }).format(value);
+}
+
+export function count(value: number | null): string {
+  return value === null ? DASH : new Intl.NumberFormat(locale()).format(value);
+}
+
+export function plural(n: number, one: string, many = `${one}s`): string {
+  return `${count(n)} ${n === 1 ? one : many}`;
+}
+
+const DAY = 86_400_000;
+
+/** "today", "in 12 days", "3 days ago" - and whether it is in the past. */
+export function relativeDay(iso: string | null, now = Date.now()): { label: string; past: boolean; full: string } | null {
+  if (!iso) return null;
+  const at = new Date(iso);
+  if (Number.isNaN(at.getTime())) return null;
+  const days = Math.round((Date.UTC(at.getUTCFullYear(), at.getUTCMonth(), at.getUTCDate()) - Date.UTC(new Date(now).getUTCFullYear(), new Date(now).getUTCMonth(), new Date(now).getUTCDate())) / DAY);
+  const label = new Intl.RelativeTimeFormat(locale(), { numeric: "auto" }).format(days, "day");
+  const full = new Intl.DateTimeFormat(locale(), { year: "numeric", month: "short", day: "numeric" }).format(at);
+  return { label, past: days < 0, full };
+}
+
+/** Letters only: "Contoso Branch 01" is CB, not C0. */
+export function initials(name: string): string {
+  const words = name.split(/\s+/).filter((word) => /^\p{L}/u.test(word));
+  if (!words.length) return "-";
+  return (words.length > 1 ? words[0][0] + words[1][0] : words[0].slice(0, 2)).toUpperCase();
+}
+
+/** "https://www.northwind.example/about" -> "northwind.example": shown as text, never as a link out of the app. */
+export function domain(website: string | null): string | null {
+  if (!website) return null;
+  try {
+    return new URL(/^https?:\/\//.test(website) ? website : `https://${website}`).hostname.replace(/^www\./, "");
+  } catch {
+    return website;
+  }
+}
+
+export function titleCase(value: string): string {
+  return value.replace(/[_-]+/g, " ").replace(/\b\p{L}/gu, (c) => c.toUpperCase());
+}

package/recipes/lookup-then-view/agent/views/pick-one.ts

@@ -0,0 +1,240 @@
+// Pick one: the card for "which one did you mean?" - any entity, any list
+// length. Search, pages, one click. Use it wherever the agent has to ask the
+// user to choose a record; it is not specific to accounts.
+//
+// - Long lists: only one page is ever on screen; the next comes from the app.
+// - Search: typing asks the app again (after a short pause); the newest answer wins.
+// - One click chooses, by default. `confirm: true` adds a button instead, for
+//   choices that should be deliberate.
+// - "None of these" and "Cancel" are answers too. Exactly one answer, ever.
+// - After the answer the card shrinks to one line saying what was chosen, so
+//   the conversation history reads right.
+// textContent only - never innerHTML with API data. Styles go in `header`.
+
+import { brand } from "./brand";
+import { initials } from "./format";
+
+export type PickRow = { id: string; primary: string; secondary?: string | null; meta?: string | null };
+export type PickPage = { rows: PickRow[]; total: number };
+
+export type PickOptions = {
+  title: string;
+  note?: string | null;
+  query?: string;
+  placeholder?: string;
+  initial: PickPage;
+  /** Shown first when the search found nothing: the closest names. */
+  suggested?: PickRow[];
+  pageSize: number;
+  fetchPage: (query: string, offset: number) => Promise<PickPage | { error: string }>;
+  confirm?: boolean;
+  confirmLabel?: string;
+  debounceMs?: number;
+  onChoose: (row: PickRow) => void;
+  onNone: () => void;
+  onCancel: () => void;
+};
+
+const CSS = `
+.fs-p1{background:${brand.surface};border:1px solid ${brand.border};border-radius:${brand.radius};font-family:${brand.font};
+  color:${brand.text};width:100%;box-sizing:border-box;font-size:13px;line-height:1.35;overflow:hidden}
+.fs-p1 *{box-sizing:border-box;margin:0}
+.fs-p1-head{padding:12px 14px 8px}
+.fs-p1-title{font-size:14px;font-weight:600;color:${brand.textStrong}}
+.fs-p1-note{font-size:12px;color:${brand.muted};margin-top:2px}
+.fs-p1-search{display:block;width:calc(100% - 28px);margin:4px 14px 8px;padding:8px 10px;border:1px solid ${brand.border};
+  border-radius:8px;font:inherit;color:${brand.textStrong};background:${brand.surface}}
+.fs-p1-search:focus{outline:2px solid ${brand.accentSoft};border-color:${brand.accent}}
+.fs-p1-label{padding:6px 14px 2px;font-size:10px;font-weight:600;letter-spacing:.5px;text-transform:uppercase;color:${brand.faint}}
+.fs-p1-list{display:flex;flex-direction:column;border-top:1px solid ${brand.border}}
+.fs-p1-row{display:flex;align-items:center;gap:10px;width:100%;text-align:left;padding:9px 14px;border:0;border-bottom:1px solid ${brand.border};
+  background:${brand.surface};font:inherit;color:inherit;cursor:pointer}
+.fs-p1-row:hover{background:${brand.surface2}}
+.fs-p1-row:focus{outline:none}
+.fs-p1-row:focus-visible{background:${brand.accentSoft};box-shadow:inset 3px 0 0 ${brand.accent}}
+.fs-p1-row.is-selected{background:${brand.accentSoft};box-shadow:inset 3px 0 0 ${brand.accent}}
+.fs-p1-mark{width:28px;height:28px;border-radius:8px;background:${brand.accentSoft};color:${brand.accent};font-weight:600;font-size:11px;
+  display:flex;align-items:center;justify-content:center;flex-shrink:0}
+.fs-p1-who{flex:1;min-width:0}
+.fs-p1-primary{font-weight:600;color:${brand.textStrong};overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.fs-p1-secondary{font-size:12px;color:${brand.muted};overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.fs-p1-meta{font-size:12px;color:${brand.muted};white-space:nowrap}
+.fs-p1-state{padding:14px;color:${brand.muted};font-size:12px}
+.fs-p1-error{padding:10px 14px;color:${brand.bad};font-size:12px}
+.fs-p1-label:empty,.fs-p1-error:empty{display:none}
+.fs-p1-foot{display:flex;align-items:center;gap:8px;padding:8px 14px}
+.fs-p1-count{flex:1;font-size:12px;color:${brand.muted};font-variant-numeric:tabular-nums}
+.fs-p1-btn{font:inherit;font-size:12px;padding:5px 10px;border-radius:7px;border:1px solid ${brand.border};background:${brand.surface};color:${brand.text};cursor:pointer}
+.fs-p1-btn:disabled{opacity:.45;cursor:default}
+.fs-p1-primary-btn{background:${brand.accent};border-color:${brand.accent};color:${brand.accentText}}
+.fs-p1-link{font:inherit;font-size:12px;border:0;background:none;color:${brand.muted};cursor:pointer;padding:5px 4px}
+.fs-p1-link:hover{color:${brand.textStrong}}
+.fs-p1-done{display:flex;align-items:center;gap:8px;padding:9px 12px;font-size:12px;color:${brand.muted}}
+.fs-p1-done b{color:${brand.textStrong};font-weight:600}
+`;
+
+function el(tag: string, className: string, text?: string): HTMLElement {
+  const node = document.createElement(tag);
+  node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+function button(className: string, text: string): HTMLButtonElement {
+  const node = el("button", className, text) as HTMLButtonElement;
+  node.type = "button";
+  return node;
+}
+function attr(node: HTMLElement, name: string, value: string): void {
+  if (typeof node.setAttribute === "function") node.setAttribute(name, value);
+}
+function focus(node: HTMLElement | undefined): void {
+  if (node && typeof node.focus === "function") node.focus();
+}
+
+export function mountPickOne(host: HTMLElement, header: HTMLElement, options: PickOptions): void {
+  const style = el("style", "");
+  style.textContent = CSS;
+  header.append(style);
+
+  const pageSize = Math.max(1, options.pageSize);
+  let settled = false;
+  let query = options.query ?? "";
+  let offset = 0;
+  let page: PickPage = options.initial;
+  let showingSuggested = Boolean(options.suggested?.length);
+  let selected: PickRow | null = null;
+  let request = 0;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const card = el("div", "fs-p1");
+  const head = el("div", "fs-p1-head");
+  head.append(el("div", "fs-p1-title", options.title));
+  const note = el("div", "fs-p1-note", options.note ?? "");
+  if (options.note) head.append(note);
+  const search = el("input", "fs-p1-search") as HTMLInputElement;
+  search.type = "search";
+  search.value = query;
+  search.placeholder = options.placeholder ?? "Search";
+  attr(search, "aria-label", options.placeholder ?? "Search");
+  const label = el("div", "fs-p1-label");
+  const list = el("div", "fs-p1-list");
+  attr(list, "role", "listbox");
+  const error = el("div", "fs-p1-error");
+  const foot = el("div", "fs-p1-foot");
+  const counter = el("div", "fs-p1-count");
+  const prev = button("fs-p1-btn", "Previous");
+  const next = button("fs-p1-btn", "Next");
+  const go = button("fs-p1-btn fs-p1-primary-btn", options.confirmLabel ?? "Open");
+  go.disabled = true;
+  const all = button("fs-p1-link", "Browse all");
+  const none = button("fs-p1-link", "None of these");
+  const cancel = button("fs-p1-link", "Cancel");
+
+  const finish = (line: HTMLElement, answer: () => void) => {
+    if (settled) return;
+    settled = true;
+    if (timer) clearTimeout(timer);
+    host.textContent = "";
+    host.append(line);
+    answer();
+  };
+  const choose = (row: PickRow) => {
+    const line = el("div", "fs-p1-done");
+    line.append(el("span", "", "Chosen:"), el("b", "", row.primary));
+    if (row.secondary) line.append(el("span", "", row.secondary));
+    finish(line, () => options.onChoose(row));
+  };
+
+  const draw = () => {
+    list.textContent = "";
+    error.textContent = "";
+    const rows = showingSuggested ? options.suggested ?? [] : page.rows;
+    label.textContent = showingSuggested ? "Closest names" : "";
+    if (all.style) all.style.display = showingSuggested ? "" : "none";
+    if (!rows.length) {
+      list.append(el("div", "fs-p1-state", query ? `Nothing matches "${query}".` : "Nothing to choose from."));
+    }
+    const buttons: HTMLButtonElement[] = [];
+    rows.forEach((row, index) => {
+      const item = button(`fs-p1-row${selected?.id === row.id ? " is-selected" : ""}`, "");
+      attr(item, "role", "option");
+      item.append(el("div", "fs-p1-mark", initials(row.primary)));
+      const who = el("div", "fs-p1-who");
+      who.append(el("div", "fs-p1-primary", row.primary));
+      if (row.secondary) who.append(el("div", "fs-p1-secondary", row.secondary));
+      item.append(who);
+      if (row.meta) item.append(el("div", "fs-p1-meta", row.meta));
+      item.addEventListener("click", () => {
+        if (settled) return;
+        if (!options.confirm) return choose(row);
+        selected = row;
+        go.disabled = false;
+        draw();
+      });
+      item.addEventListener("keydown", (event: Event) => {
+        const key = (event as KeyboardEvent).key;
+        if (key === "ArrowDown") focus(buttons[index + 1]);
+        if (key === "ArrowUp") focus(index === 0 ? search : buttons[index - 1]);
+      });
+      buttons.push(item);
+      list.append(item);
+    });
+    const paged = !showingSuggested && page.total > pageSize;
+    // A count only when there is more than one page: "1-2 of 2" is noise.
+    counter.textContent = paged ? `${offset + 1}-${Math.min(offset + page.rows.length, page.total)} of ${page.total}` : "";
+    if (foot.style) foot.style.display = paged || options.confirm ? "" : "none";
+    prev.disabled = !paged || offset === 0;
+    next.disabled = !paged || offset + pageSize >= page.total;
+    if (prev.style) prev.style.display = paged ? "" : "none";
+    if (next.style) next.style.display = paged ? "" : "none";
+  };
+
+  const load = async (nextQuery: string, nextOffset: number) => {
+    const mine = ++request;
+    const answer = await options.fetchPage(nextQuery, nextOffset);
+    if (mine !== request || settled) return; // a newer search, or already answered
+    if ("error" in answer) {
+      error.textContent = answer.error;
+      return;
+    }
+    query = nextQuery;
+    offset = nextOffset;
+    page = answer;
+    // The note follows what is on screen, not the first question.
+    note.textContent = query ? `${page.total} ${page.total === 1 ? "match" : "matches"} for "${query}"` : "";
+    if (!note.parentNode && note.textContent) head.append(note);
+    showingSuggested = false;
+    selected = null;
+    go.disabled = true;
+    draw();
+  };
+
+  search.addEventListener("input", () => {
+    if (settled) return;
+    if (timer) clearTimeout(timer);
+    const typed = search.value.trim();
+    timer = setTimeout(() => void load(typed, 0), options.debounceMs ?? 250);
+  });
+  search.addEventListener("keydown", (event: Event) => {
+    if ((event as KeyboardEvent).key === "ArrowDown") focus(list.querySelector?.("button") as HTMLElement | undefined);
+  });
+  all.addEventListener("click", () => {
+    if (settled) return;
+    showingSuggested = false;
+    draw();
+  });
+  prev.addEventListener("click", () => load(query, Math.max(0, offset - pageSize)));
+  next.addEventListener("click", () => load(query, offset + pageSize));
+  go.addEventListener("click", () => selected && choose(selected));
+  none.addEventListener("click", () => finish(el("div", "fs-p1-done", "None of these."), options.onNone));
+  cancel.addEventListener("click", () => finish(el("div", "fs-p1-done", "Cancelled."), options.onCancel));
+
+  foot.append(counter, prev, next);
+  if (options.confirm) foot.append(go);
+  const actions = el("div", "fs-p1-foot");
+  actions.append(all, none, cancel);
+  card.append(head, search, label, list, error, foot, actions);
+  draw();
+  host.textContent = "";
+  host.append(card);
+}