@intentius/behold 0.29.6 → 0.29.8

package/web/kiosk-approval.js

@@ -0,0 +1,241 @@
+// behold#571: "How this hold ends", the approval panel. From the step a wave
+// waits on through the waves applied, four rows light one by one, each from a
+// record, never from the narration:
+//
+// - Requested: the wave asked for an approval of its plan (by digest). The
+//   gate ledger's pending fact on chant/lifecycle (/api/lifecycle/history,
+//   chant's gate-audit `approval-requested`), and the wave's log line.
+// - Approved: a reviewer approved exactly that plan. The ledger's approval of
+//   that digest, its seal, and whether the seal checks out against the
+//   repo's allowed signers (/api/terragucci/lifecycle's `sealCheck`).
+// - Resumed: `/terragucci apply` started the waves again and the gate found
+//   the approval of this digest. The resume run and its log lines.
+// - Spent: the wave applied under that approval, which is now used up. The
+//   ledger's applied record, and the wave's log line.
+//
+// Each record is this cycle's: no earlier than the cycle's start, and, in a
+// replay, no later than the replay's clock. The digests repeat from cycle to
+// cycle (the loop plans the same change), so the cycle's start is what keeps
+// an older approval of the same plan from lighting a row.
+
+import { findLine } from "./kiosk-annotations.js";
+
+/** The steps the panel shows on: from the wave waiting to the waves applied. */
+export const PANEL_STEPS = ["waiting", "approved", "resumed", "applied"];
+
+/** The panel's title. */
+export const PANEL_TITLE = "How this hold ends";
+
+/** The rows, in order. */
+export const ROWS = [
+  { id: "requested", label: "Requested" },
+  { id: "approved", label: "Approved" },
+  { id: "resumed", label: "Resumed" },
+  { id: "spent", label: "Spent" },
+];
+
+/** A digest's hex part, for comparing `jcs1-sha256:…` with `sha256:…`. */
+export const digestHex = (d) => (typeof d === "string" ? d.slice(d.lastIndexOf(":") + 1).toLowerCase() : "");
+export const sameDigest = (a, b) => !!digestHex(a) && digestHex(a) === digestHex(b);
+/** A digest as a viewer reads it: its first 12 hex digits. */
+export const shortDigest = (d) => digestHex(d).slice(0, 12);
+
+const ms = (t) => (t ? Date.parse(t) : NaN);
+
+/** The runs of the cycle demo.json is at, oldest first: same cycle (or, without one, the same pull request since the cycle started), merges and resumes. */
+export function cycleRuns(runs, demo) {
+  const start = ms(demo && demo.started_at);
+  return (runs || [])
+    .filter((r) => r && (r.trigger === "merge" || isResume(r) || r.trigger === "push"))
+    .filter((r) => (Number.isInteger(r.cycle) && Number.isInteger(demo.cycle) ? r.cycle === demo.cycle : String(r.pull) === String(demo.pull) && !(ms(r.created_at) < start)))
+    .sort((a, b) => ms(a.created_at) - ms(b.created_at) || a.id - b.id);
+}
+
+/** A run that `/terragucci apply` started: the driver's resume, a comment on the merged pull request. */
+export const isResume = (r) => !!r && (r.trigger === "resume" || r.event === "issue_comment");
+
+const waveLine = (wave) => (text) => new RegExp(`^wave ${wave}\\b`).test(text);
+
+/** The line of a run that `ids` know about wave `wave`, with the run's id: `{ run, a, job, step, n, text }` or null. */
+function lineOf(run, ids, wave, more = () => true) {
+  const f = findLine(run, ids, (text, a) => waveLine(wave)(text) && more(text, a));
+  return f ? { run: run.id, ...f } : null;
+}
+
+/**
+ * The wave this cycle holds and the plan it asks about: the newest "waits for
+ * an approval of digest" line (T11) in the cycle's runs, with where it is.
+ * Null when no run of the cycle printed one.
+ */
+export function heldWave(runs) {
+  let found = null;
+  for (const run of runs) {
+    const f = findLine(run, ["T11"]);
+    if (!f) continue;
+    const m = /^wave (\d+) of \d+ waits for an approval of digest (\S+?)\./.exec(f.text);
+    if (m) found = { wave: Number(m[1]), digest: m[2], line: { run: run.id, ...f } };
+  }
+  return found;
+}
+
+/** When a line says it happened: the time in it (T14's approval time is not when it applied), else the run's step's end, else the run's start. */
+function lineTime(run, f) {
+  const job = run.jobs.find((j) => j.name === f.job);
+  const step = job && job.steps ? job.steps[f.step] : null;
+  return (step && (step.ended_at || step.started_at)) || run.started_at || run.created_at || null;
+}
+
+/**
+ * The panel's model: `{ wave, digest, rows: [{ id, label, state, … }] }`, or
+ * null when the step is not one the panel shows or no wave of the cycle
+ * held. `state` is `lit`, `going` (begun, not done) or `dim`. Inputs:
+ *
+ * - `demo`: demo.json (or the replay's step);
+ * - `runs`: the cycle's runs' documents (any order);
+ * - `history`: /api/lifecycle/history's answer;
+ * - `lifecycle`: /api/terragucci/lifecycle's answer;
+ * - `fallback`: `{ wave, digest }` from the run view, for a wave whose log isn't copied yet;
+ * - `now`: the page's clock (the replay's, in a replay), in ms.
+ */
+export function approvalModel({ demo, runs = [], history = null, lifecycle = null, fallback = null, now = Date.now(), driver = null }) {
+  if (!demo || !PANEL_STEPS.includes(demo.step)) return null;
+  const cycle = cycleRuns(runs, demo);
+  const held = heldWave(cycle) || (fallback && fallback.wave ? { wave: fallback.wave, digest: fallback.digest || null, line: null } : null);
+  if (!held) return null;
+  const { wave, digest } = held;
+  const start = ms(demo.started_at);
+  const inCycle = (t) => !(ms(t) < start) && !(ms(t) > now);
+  const gate = `wave-${wave}`;
+  const entries = (history && Array.isArray(history.entries) ? history.entries : []).filter((e) => e.gate === gate && inCycle(e.at) && (!digest || sameDigest(e.digest, digest)));
+  const oldest = (kind) => entries.filter((e) => e.kind === kind).sort((a, b) => ms(a.at) - ms(b.at))[0] || null;
+  const requested = oldest("approval-requested");
+  const approved = entries.filter((e) => e.kind === "approved" && (!requested || ms(e.at) >= ms(requested.at))).sort((a, b) => ms(a.at) - ms(b.at))[0] || null;
+  const lane = lifecycle && Array.isArray(lifecycle.gates) ? lifecycle.gates.find((g) => g.gate === gate) : null;
+
+  // Requested.
+  const reqLine = held.line;
+  const reqRow = { id: "requested", label: "Requested" };
+  if (requested || reqLine) {
+    Object.assign(reqRow, {
+      state: "lit",
+      text: `Wave ${wave} asked for an approval of this plan.`,
+      at: requested ? requested.at : reqLine ? lineTime(cycle.find((r) => r.id === reqLine.run), reqLine) : null,
+      commit: requested && requested.source ? requested.source.commit || null : null,
+      line: reqLine,
+    });
+  } else Object.assign(reqRow, { state: "dim", text: `Wave ${wave} has not asked for an approval yet.` });
+
+  // Approved.
+  const apRow = { id: "approved", label: "Approved" };
+  // The resume runs: started by /terragucci apply after the run that held the wave.
+  const holdRun = reqLine ? cycle.find((r) => r.id === reqLine.run) : null;
+  const resumeRuns = cycle.filter((r) => isResume(r) && (!holdRun || !(ms(r.created_at) < ms(holdRun.created_at))));
+  const gateRead = resumeRuns.map((r) => lineOf(r, ["T09"], wave, (text) => / approved by /.test(text))).find(Boolean) || null;
+  if (approved) {
+    const check = lane && lane.approval && lane.approval.by === approved.actor && ms(lane.approval.at) === ms(approved.at) ? lane.approval.sealCheck || null : null;
+    Object.assign(apRow, {
+      state: "lit",
+      text: `${approved.actor || "A reviewer"} approved exactly this plan.`,
+      seal: sealWords(approved, check),
+      at: approved.at,
+      commit: approved.source ? approved.source.commit || null : null,
+      line: gateRead,
+    });
+  } else if (driver) {
+    Object.assign(apRow, { state: "dim", text: driver.gloss, command: driver.approve });
+  } else Object.assign(apRow, { state: "dim", text: "Waiting for a reviewer to approve this plan." });
+
+  // Resumed: the resume run, and the gate finding the approval in it.
+  const rsRow = { id: "resumed", label: "Resumed" };
+  const resume = resumeRuns[resumeRuns.length - 1] || null;
+  const found = resume ? lineOf(resume, ["T13"], wave) || gateRead : null;
+  const start2 = resume ? findLine(resume, ["T36"]) : null;
+  if (resume && found) {
+    Object.assign(rsRow, {
+      state: "lit",
+      text: "/terragucci apply ran the waves again, and the gate found this approval.",
+      at: resume.started_at || resume.created_at,
+      runId: resume.id,
+      line: start2 ? { run: resume.id, ...start2 } : found,
+    });
+  } else if (resume) {
+    Object.assign(rsRow, { state: "going", text: `/terragucci apply started the waves again; wave ${wave} has not reached its gate yet.`, at: resume.started_at || resume.created_at, runId: resume.id, line: start2 ? { run: resume.id, ...start2 } : null });
+  } else {
+    Object.assign(rsRow, { state: "dim", text: driver && driver.comment ? `Then a comment of ${driver.comment} on ${driver.on} starts the waves again.` : "A comment of /terragucci apply starts the waves again." });
+  }
+
+  // Spent: the ledger's applied record under this approval, or the wave's line.
+  const spRow = { id: "spent", label: "Spent" };
+  const spentLine = cycle.map((r) => lineOf(r, ["T14"], wave, (text) => !approved || !approved.actor || text.includes(` by ${approved.actor} `))).find(Boolean) || null;
+  const appliedRec = lane && lane.applied && approved && lane.applied.approvedBy === approved.actor && ms(lane.applied.approvedAt) === ms(approved.at) && inCycle(lane.applied.at) ? lane.applied : null;
+  if (appliedRec || spentLine) {
+    Object.assign(spRow, {
+      state: "lit",
+      text: `Wave ${wave} applied under that approval, which is now used up.`,
+      at: appliedRec ? appliedRec.at : spentLine ? lineTime(cycle.find((r) => r.id === spentLine.run), spentLine) : null,
+      runId: spentLine ? spentLine.run : null,
+      line: spentLine,
+    });
+  } else Object.assign(spRow, { state: "dim", text: `Once wave ${wave} applies, this approval is used up for good.` });
+
+  return { wave, digest, rows: inferBack([reqRow, apRow, rsRow, spRow], { wave, gateRead, spentLine, resumeRuns }) };
+}
+
+/** The words a row lit only because a later one is, by row. Each says it was inferred; none invents a time. */
+export const INFERRED = {
+  requested: (wave) => `Wave ${wave} asked for an approval of this plan.`,
+  approved: (actor) => `${actor || "A reviewer"} approved this plan.`,
+  resumed: () => "The waves ran again under this approval.",
+};
+
+/**
+ * behold#571: a hold ends in order, so no row is lit after one that isn't.
+ * A lit row lights the rows before it: Spent means the waves ran again
+ * (Resumed), which means the plan was approved, which means it was asked
+ * for. A row lit this way says so (`inferred`), names what the later rows
+ * show (the approver from the gate's or the spend's line, the run), and
+ * carries no time it does not have.
+ */
+export function inferBack(rows, { wave, gateRead = null, spentLine = null, resumeRuns = [] } = {}) {
+  const out = rows.map((r) => ({ ...r }));
+  for (let i = out.length - 1; i > 0; i--) {
+    if (out[i].state !== "lit" || out[i - 1].state === "lit") continue;
+    const r = out[i - 1];
+    const base = { id: r.id, label: r.label, state: "lit", inferred: true };
+    if (r.id === "requested") out[i - 1] = { ...base, text: INFERRED.requested(wave) };
+    else if (r.id === "approved") {
+      const said = [gateRead, spentLine].filter(Boolean).map((l) => / approv(?:ed|al) by (\S+?)[;,\s]/.exec(`${l.text} `)).find(Boolean);
+      out[i - 1] = { ...base, text: INFERRED.approved(said ? said[1] : null), line: gateRead || null };
+    } else if (r.id === "resumed") {
+      const run = resumeRuns[resumeRuns.length - 1] || null;
+      out[i - 1] = { ...base, text: INFERRED.resumed(), runId: run ? run.id : r.runId || (spentLine ? spentLine.run : null), at: r.at || null, line: r.line || null };
+    }
+  }
+  return out;
+}
+
+/**
+ * The seal in words: signed and checked against the repo's allowed signers,
+ * signed and not matching (with chant's reason), signed with nothing to
+ * check it against here, or not signed.
+ */
+export function sealWords(entry, check) {
+  const signed = entry && (entry.seal === "sealed" || (entry.audit && entry.audit.sealed));
+  if (!signed) return { ok: null, text: entry && entry.seal === "review" ? "approved by a pull request review" : "not signed" };
+  if (check && check.ok) return { ok: true, text: "signed; matches the repo's allowed signers" };
+  if (check && check.ok === false) return { ok: false, text: `signed, but the signature does not check out: ${check.reason}` };
+  return { ok: null, text: "signed; behold has not checked the signature" };
+}
+
+/** "04:09:41", in UTC (the panel's head says so). */
+export function clockWords(at) {
+  const t = ms(at);
+  if (Number.isNaN(t)) return null;
+  return new Date(t).toISOString().slice(11, 19);
+}
+
+/** A row's facts after its sentence, in order: the seal, the time, the ledger's commit on chant/lifecycle, the run. */
+export function rowFacts(row) {
+  return [row.inferred ? "inferred from the rows after it" : null, row.seal ? row.seal.text : null, clockWords(row.at), row.commit ? `ledger ${row.commit.slice(0, 8)}` : null, row.runId ? `run #${row.runId}` : null].filter(Boolean);
+}
+

package/web/kiosk-approval.test.js

@@ -0,0 +1,122 @@
+// behold#571: "How this hold ends" lights its rows from records (the fixture runs approve as terragucci-admin): the ledger's
+// requested and approved entries, the lane's seal check and applied record,
+// and the cycle's runs' log lines. Never from the step the narration is at.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { PANEL_STEPS, ROWS, approvalModel, inferBack, clockWords, cycleRuns, heldWave, rowFacts, sameDigest, sealWords, shortDigest } from "./kiosk-approval.js";
+
+const FIX = join(import.meta.dirname, "..", "src", "__fixtures__", "terragucci-demo", "runs");
+const run = (id) => JSON.parse(readFileSync(join(FIX, `${id}.json`), "utf8"));
+const D2 = "jcs1-sha256:0accc105ba060b9974468c91def518039d935ad6629f8a15869f6e89ef748b61";
+const demo = (step) => ({ step, cycle: 90, pull: 278, started_at: "2026-10-15T04:08:30Z", commit: "ef959409b8d590f4c3b05f0b7154cd576c9e1abf" });
+const history = (kinds) => ({
+  entries: [
+    { kind: "approved", gate: "wave-2", at: "2026-10-15T04:10:08.707Z", digest: D2, actor: "terragucci-admin", seal: "sealed", audit: { sealed: true }, source: { commit: "4cba487a0000" } },
+    { kind: "approval-requested", gate: "wave-2", at: "2026-10-15T04:09:41Z", digest: D2, source: { commit: "57869649aaaa" } },
+    // An earlier cycle's approval of the same plan: the loop plans the same change every time.
+    { kind: "approved", gate: "wave-2", at: "2026-10-15T03:56:09.124Z", digest: D2, actor: "terragucci-admin", seal: "sealed", source: { commit: "0ld" } },
+  ].filter((e) => kinds.includes(e.kind)),
+});
+const lane = (over = {}) => ({ gates: [{ gate: "wave-2", approval: { by: "terragucci-admin", at: "2026-10-15T04:10:08.707Z", signed: true, sealCheck: { ok: true } }, ...over }] });
+const state = (m) => Object.fromEntries(m.rows.map((r) => [r.id, r.state]));
+
+describe("the approval panel (behold#571)", () => {
+  it("shows from the wave waiting through the waves applied, and has four rows", () => {
+    expect(PANEL_STEPS).toEqual(["waiting", "approved", "resumed", "applied"]);
+    expect(ROWS.map((r) => r.label)).toEqual(["Requested", "Approved", "Resumed", "Spent"]);
+    expect(approvalModel({ demo: demo("applying"), runs: [run(444)] })).toBe(null);
+    expect(approvalModel({ demo: demo("waiting"), runs: [] })).toBe(null);
+  });
+
+  it("finds the held wave and its plan in the cycle's runs", () => {
+    const cycle = cycleRuns([run(445), run(444), run(443), run(447)], demo("waiting"));
+    expect(cycle.map((r) => r.id)).toEqual([444, 445]);
+    const h = heldWave(cycle);
+    expect(h).toMatchObject({ wave: 2, digest: D2, line: { run: 444, job: "apply-wave-2" } });
+  });
+
+  it("lights Requested at the hold, from the log line alone and then the ledger", () => {
+    const m = approvalModel({ demo: demo("waiting"), runs: [run(444)], now: Date.parse("2026-10-15T04:09:50Z") });
+    expect(state(m)).toEqual({ requested: "lit", approved: "dim", resumed: "dim", spent: "dim" });
+    expect(m.rows[0].line.a.id).toBe("T11");
+    const withLedger = approvalModel({ demo: demo("waiting"), runs: [run(444)], history: history(["approval-requested", "approved"]), now: Date.parse("2026-10-15T04:09:50Z") });
+    // The approval at 04:10:08 is after the page's clock, so it is not there yet.
+    expect(state(withLedger).approved).toBe("dim");
+    expect(withLedger.rows[0].commit).toBe("57869649aaaa");
+  });
+
+  it("puts the driver's command in the Approved row until the approval is recorded", () => {
+    const driver = { gloss: "Next the driver signs.", approve: "chant approve tf-apply wave-2", comment: "/terragucci apply", on: "pull request #278" };
+    const m = approvalModel({ demo: demo("waiting"), runs: [run(444)], driver, now: Date.parse("2026-10-15T04:09:50Z") });
+    expect(m.rows[1]).toMatchObject({ state: "dim", command: "chant approve tf-apply wave-2" });
+  });
+
+  it("lights Approved for exactly this plan, this cycle, with its seal checked", () => {
+    const m = approvalModel({ demo: demo("approved"), runs: [run(444)], history: history(["approval-requested", "approved"]), lifecycle: lane(), now: Date.parse("2026-10-15T04:10:09Z") });
+    expect(state(m)).toEqual({ requested: "lit", approved: "lit", resumed: "dim", spent: "dim" });
+    expect(m.rows[1].text).toBe("terragucci-admin approved exactly this plan.");
+    expect(m.rows[1].seal.ok).toBe(true);
+    expect(m.rows[1].at).toBe("2026-10-15T04:10:08.707Z");
+    // Only an earlier cycle's approval of the same digest: nothing lights.
+    const old = approvalModel({ demo: demo("approved"), runs: [run(444)], history: { entries: history(["approved"]).entries.filter((e) => e.source.commit === "0ld") }, now: Date.parse("2026-10-15T04:10:09Z") });
+    expect(state(old).approved).toBe("dim");
+  });
+
+  it("lights Resumed and Spent from the resume run's lines and the ledger's applied record", () => {
+    const m = approvalModel({
+      demo: demo("applied"),
+      runs: [run(444), run(445)],
+      history: history(["approval-requested", "approved"]),
+      lifecycle: lane({ applied: { at: "2026-10-15T04:10:15Z", approvedAt: "2026-10-15T04:10:08.707Z", approvedBy: "terragucci-admin" } }),
+      now: Date.parse("2026-10-15T04:11:00Z"),
+    });
+    expect(state(m)).toEqual({ requested: "lit", approved: "lit", resumed: "lit", spent: "lit" });
+    expect(m.rows[2].line.a.id).toBe("T36");
+    expect(m.rows[3].line).toMatchObject({ run: 445, a: { id: "T14" } });
+    expect(m.rows[3].at).toBe("2026-10-15T04:10:15Z");
+    expect(m.rows[1].line.a.id).toBe("T09");
+  });
+
+  it("says what the seal is", () => {
+    expect(sealWords({ seal: "sealed" }, { ok: true }).ok).toBe(true);
+    expect(sealWords({ seal: "sealed" }, { ok: false, reason: "no key" }).text).toMatch(/does not check out: no key$/);
+    expect(sealWords({ seal: "sealed" }, null).ok).toBe(null);
+    expect(sealWords({ seal: "unsigned" }, null).text).toBe("not signed");
+  });
+
+  it("reads digests and times the way the panel shows them", () => {
+    expect(sameDigest(D2, `sha256:${D2.slice(12)}`)).toBe(true);
+    expect(shortDigest(D2)).toBe("0accc105ba06");
+    expect(clockWords("2026-10-15T04:10:08.707Z")).toBe("04:10:08");
+    expect(rowFacts({ at: "2026-10-15T04:10:08Z", commit: "4cba487a0000", runId: 445 })).toEqual(["04:10:08", "ledger 4cba487a", "run #445"]);
+  });
+
+  it("never lights a row after one that is not lit", () => {
+    const resumeless = { ...run(445), trigger: "merge", event: "push" };
+    const inputs = {
+      runs: [[run(444)], [run(444), run(445)], [run(444), resumeless], [run(445)]],
+      history: [null, history(["approval-requested"]), history(["approval-requested", "approved"]), history(["approved"])],
+      lifecycle: [null, lane(), lane({ applied: { at: "2026-10-15T04:10:15Z", approvedAt: "2026-10-15T04:10:08.707Z", approvedBy: "terragucci-admin" } })],
+    };
+    for (const step of PANEL_STEPS)
+      for (const runs of inputs.runs)
+        for (const h of inputs.history)
+          for (const l of inputs.lifecycle) {
+            const m = approvalModel({ demo: demo(step), runs, history: h, lifecycle: l, fallback: { wave: 2, digest: D2 }, now: Date.parse("2026-10-15T04:11:00Z") });
+            if (!m) continue;
+            const lit = m.rows.map((r) => r.state === "lit");
+            expect(lit.findIndex((x, i) => x && i > 0 && !lit[i - 1]), `${step}: ${m.rows.map((r) => r.state).join(",")}`).toBe(-1);
+          }
+  });
+
+  it("lights Resumed from the spend when no resume run was copied, says so, and invents no time", () => {
+    const resumeless = { ...run(445), trigger: "merge", event: "push" };
+    const m = approvalModel({ demo: demo("applied"), runs: [run(444), resumeless], now: Date.parse("2026-10-15T04:11:00Z") });
+    expect(m.rows.map((r) => r.state)).toEqual(["lit", "lit", "lit", "lit"]);
+    expect(m.rows[2]).toMatchObject({ inferred: true, runId: 445, at: null });
+    expect(rowFacts(m.rows[2])).toEqual(["inferred from the rows after it", "run #445"]);
+    expect(m.rows[1]).toMatchObject({ inferred: true, text: "terragucci-admin approved this plan." });
+    expect(inferBack([{ id: "requested", state: "dim" }, { id: "approved", state: "dim" }], { wave: 2 }).map((r) => r.state)).toEqual(["dim", "dim"]);
+  });
+});

package/web/kiosk-popover.js

@@ -0,0 +1,235 @@
+// behold#571: the kiosk frame's popover. In the kiosk the graph is framed
+// bare (`?embed=1&bare=1`), with no Inspect pane, so a visitor pointing at a
+// card sees what the plan does to it here instead: in the Resources view, the
+// resource's planned change one attribute a line; in Roots by wave, the
+// root's resources and which of them change. Pure logic: what the popover
+// says, where it goes, and when it stays open. app.js draws it.
+//
+// The values come from the same terragucci read the Inspect pane's
+// terragucci sections use (/api/terragucci: the marks on each card, which
+// now carry each attribute's before and after, and what the newest applied
+// wave wrote). Nothing here reads anything else.
+
+import { PICK_HOLD_MS } from "./kiosk-runs.js";
+import { clock } from "./terragucci.js";
+
+/** How many attribute lines the popover shows before "and N more". */
+export const MAX_LINES = 6;
+
+/** How long a click keeps the popover open: as long as a click holds the view toggle. */
+export const PIN_HOLD_MS = PICK_HOLD_MS;
+
+/** The plan's action on a resource, in words for a viewer new to Terraform. */
+export const ACTION_HEAD = {
+  create: "The plan creates this resource.",
+  update: "The plan changes this resource.",
+  replace: "The plan destroys this resource and creates it again.",
+  delete: "The plan destroys this resource.",
+  forget: "The plan drops this resource from the state and leaves it running.",
+  import: "The plan brings this resource into the state.",
+};
+
+export const WORDS = {
+  same: "The plan leaves this resource as it is.",
+  untouched: "This plan does not touch its root, so nothing changes here.",
+  noPlan: "No plan yet for this resource.",
+  unknown: "known after apply, so no review shows this value",
+  long: "too long to show here",
+  noneYet: "none yet",
+  gone: "gone",
+  leftIsApplied: "Left of each arrow is the value applied now.",
+  pinHint: "Click to keep this open.",
+  pinnedHint: "Click elsewhere or press Escape to close this.",
+  tapPinnedHint: "Tap elsewhere to close this.",
+  noResources: "No resources found for this root.",
+  noRootChange: "No resource in this root changes.",
+  changes: "changes",
+  same2: "no change",
+  unknown2: "known after apply",
+};
+
+/** A value as a line shows it: a string bare, anything else as JSON, cut to `max` characters. */
+export function valueWords(v, max = 40) {
+  let s;
+  if (typeof v === "string") s = v === "" ? '""' : v;
+  else if (v === null) s = "null";
+  else s = JSON.stringify(v);
+  if (s === undefined) s = String(v);
+  return s.length > max ? `${s.slice(0, max - 3)}...` : s;
+}
+
+/** The instance part of an address beyond its block (`[0]`, `["a"]`), or "". */
+function instanceKey(address) {
+  const m = /(\[[^\]]*\])$/.exec(address || "");
+  return m ? m[1] : "";
+}
+
+/** One attribute's line: `path: before -> after`, or the unknown and long cases. */
+export function attributeLine(v, { prefix = "" } = {}) {
+  const name = `${prefix}${v.path}`;
+  if (v.unknown) return { text: `${name}: ${"before" in v ? `${valueWords(v.before)} -> ` : ""}${WORDS.unknown}`, tone: "unknown" };
+  if (v.long) return { text: `${name}: ${WORDS.long}`, tone: null };
+  const before = "before" in v ? valueWords(v.before) : WORDS.noneYet;
+  const after = "after" in v ? valueWords(v.after) : WORDS.gone;
+  return { text: `${name}: ${before} -> ${after}`, tone: null };
+}
+
+/** The mark the popover reads: a waiting wave's (the newest plan) before the pull request's plan. Drift marks are not a plan. */
+export function planMark(marks) {
+  const list = Array.isArray(marks) ? marks : [];
+  return list.find((m) => m.verdict === "wave") || list.find((m) => m.verdict === "plan") || null;
+}
+
+/** The root entry of the terragucci read a card sits in: the longest `<member>/<name>/` prefix of its id. */
+export function cardRoot(answer, nodeId) {
+  if (!answer || !Array.isArray(answer.roots) || !nodeId) return null;
+  let best = null;
+  for (const r of answer.roots) {
+    const prefix = `${r.member}/${r.name}/`;
+    if (nodeId.startsWith(prefix) && (!best || prefix.length > best.prefix.length)) best = { prefix, root: r };
+  }
+  return best ? { ...best.root, block: nodeId.slice(best.prefix.length) } : null;
+}
+
+/** Whether the read's plan holds a root: the pull request's plan, or any plan or wave report on it. */
+function rootPlanned(answer, root) {
+  if (answer.pull_request && Array.isArray(answer.pull_request.roots)) return answer.pull_request.roots.includes(root.path);
+  return !!(root.plan || (root.apply && root.apply.approval === "waiting"));
+}
+
+/**
+ * What the popover says about one resource card (the Resources view):
+ * `{ address, root, head, lines, more, applied, note }`. `lines` is at most
+ * MAX_LINES `{ text, tone }`, `more` how many it left out. `applied`, when the
+ * root's newest applied wave wrote any of the attributes that change,
+ * `{ when, lines }`; else `note` says the left of each arrow is what is
+ * applied now. Null when the card is not one of the read's roots.
+ */
+export function resourcePopover(answer, nodeId, now = new Date()) {
+  if (!answer || answer.error) return null;
+  const at = cardRoot(answer, nodeId);
+  if (!at) return null;
+  const marks = answer.cards ? answer.cards[nodeId] : null;
+  const mark = planMark(marks);
+  const address = mark && mark.addresses && mark.addresses.length === 1 ? mark.addresses[0] : at.block.split("/").join(".");
+  const out = { address, root: at.name, head: "", lines: [], more: 0, applied: null, note: null, change: false, unknown: false };
+  if (!mark) {
+    out.head = rootPlanned(answer, at) ? WORDS.same : answer.pull_request || at.plan ? WORDS.untouched : WORDS.noPlan;
+    return out;
+  }
+  out.change = true;
+  out.head = ACTION_HEAD[mark.action] || ACTION_HEAD.update;
+  const values = Array.isArray(mark.values) ? mark.values : [];
+  const several = (mark.addresses || []).length > 1;
+  const lines = values.map((v) => attributeLine(v, { prefix: several ? `${instanceKey(v.address) || v.address} ` : "" }));
+  out.unknown = values.some((v) => v.unknown);
+  out.lines = lines.slice(0, MAX_LINES);
+  out.more = Math.max(0, lines.length - MAX_LINES);
+  // What the state holds now: the newest applied wave's values, when it wrote one of these attributes after this plan.
+  const applied = answer.applied ? answer.applied[nodeId] : null;
+  const paths = new Set(values.map((v) => v.path));
+  const fresh = applied && applied.run && (!mark.run || !mark.run.finished || applied.run.finished >= mark.run.finished);
+  const wrote = fresh ? applied.values.filter((v) => paths.has(v.path) && !v.unknown && "after" in v) : [];
+  if (wrote.length) {
+    out.applied = {
+      when: `The applied state holds these values now, from wave ${applied.run.wave ?? "?"} at ${clock(applied.run.finished, now)}.`,
+      lines: wrote.slice(0, MAX_LINES).map((v) => ({ text: `${v.path}: ${valueWords(v.after)}`, tone: null })),
+    };
+  } else if (values.some((v) => "before" in v)) out.note = WORDS.leftIsApplied;
+  return out;
+}
+
+/** A card id for a resource of the components zoom's resources facet (`<root>/<block>`): `<member>/<root>/<block>`. */
+export function resourceCardId(answer, root, resourceId) {
+  const r = answer && Array.isArray(answer.roots) ? answer.roots.find((x) => x.name === root || x.path === root) : null;
+  if (!r) return null;
+  const rest = resourceId.startsWith(`${r.name}/`) ? resourceId.slice(r.name.length + 1) : resourceId;
+  return `${r.member}/${r.name}/${rest}`;
+}
+
+/**
+ * What the popover says about one root's card (Roots by wave): its
+ * resources, each "changes", "no change" or "known after apply", and how
+ * many change. `resources` is the components zoom's resources facet for the
+ * card (`[{ kind, id }]`).
+ */
+export function rootPopover(answer, root, resources) {
+  const list = Array.isArray(resources) ? resources : [];
+  const rows = list.map((res) => {
+    const id = answer && !answer.error ? resourceCardId(answer, root, res.id) : null;
+    const mark = id && answer.cards ? planMark(answer.cards[id]) : null;
+    const address = res.id.startsWith(`${root}/`) ? res.id.slice(root.length + 1).split("/").join(".") : res.id;
+    if (!mark) return { address, state: "same", words: WORDS.same2 };
+    const unknown = (mark.values || []).some((v) => v.unknown);
+    return { address, state: unknown ? "unknown" : "change", words: unknown ? WORDS.unknown2 : WORDS.changes };
+  });
+  const changed = rows.filter((r) => r.state !== "same").length;
+  const head = !rows.length ? WORDS.noResources : changed === 0 ? WORDS.noRootChange : `${changed} of ${rows.length} ${rows.length === 1 ? "resource changes" : "resources change"}.`;
+  const shown = rows.slice(0, MAX_LINES + 2);
+  return { root, head, rows: shown, more: rows.length - shown.length, changed };
+}
+
+// ---------------------------------------------------------------------------
+// Open, pinned, closed. Nothing shows until someone points: a hover shows the
+// card's popover while the pointer is on it; a click pins it, and it stays
+// until a click elsewhere, Escape, or PIN_HOLD_MS after the pin.
+
+/** The popover's state before anyone points: nothing shown. */
+export function popState() {
+  return { shown: null, pinned: false, at: 0 };
+}
+
+/**
+ * The next state after an event: `{ type: "enter" | "leave" | "click", id }`,
+ * `{ type: "outside" }` (a click anywhere but the shown card or the popover),
+ * `{ type: "escape" }`, or `{ type: "tick" }`. `now` in ms.
+ */
+export function popReduce(s, ev, now) {
+  switch (ev.type) {
+    case "enter":
+      return s.pinned ? s : { shown: ev.id, pinned: false, at: 0 };
+    case "leave":
+      return s.pinned || s.shown !== ev.id ? s : popState();
+    case "click":
+      return { shown: ev.id, pinned: true, at: now };
+    case "outside":
+    case "escape":
+      return popState();
+    case "tick":
+      return s.pinned && now - s.at >= PIN_HOLD_MS ? popState() : s;
+    default:
+      return s;
+  }
+}
+
+/**
+ * Where the popover goes: beside the card, never over it, inside the frame.
+ * Right of the card when it fits, else left, else below, else above; along
+ * that side, as near the card's top (or left) as the frame allows. When no
+ * side fits, the side with the most room, kept inside the frame. All boxes
+ * are `{ left, top, width, height }` in the frame's pixels.
+ */
+export function placePopover(card, pop, frame, { gap = 12, margin = 8 } = {}) {
+  const clamp = (v, lo, hi) => Math.max(lo, Math.min(v, Math.max(lo, hi)));
+  const right = card.left + card.width;
+  const bottom = card.top + card.height;
+  const room = {
+    right: frame.width - margin - (right + gap),
+    left: card.left - gap - margin,
+    below: frame.height - margin - (bottom + gap),
+    above: card.top - gap - margin,
+  };
+  const at = (side) => {
+    if (side === "right") return { left: right + gap, top: clamp(card.top, margin, frame.height - margin - pop.height), side };
+    if (side === "left") return { left: card.left - gap - pop.width, top: clamp(card.top, margin, frame.height - margin - pop.height), side };
+    if (side === "below") return { left: clamp(card.left, margin, frame.width - margin - pop.width), top: bottom + gap, side };
+    return { left: clamp(card.left, margin, frame.width - margin - pop.width), top: card.top - gap - pop.height, side };
+  };
+  if (room.right >= pop.width) return at("right");
+  if (room.left >= pop.width) return at("left");
+  if (room.below >= pop.height) return at("below");
+  if (room.above >= pop.height) return at("above");
+  const best = Object.entries({ right: room.right / pop.width, left: room.left / pop.width, below: room.below / pop.height, above: room.above / pop.height }).sort((a, b) => b[1] - a[1])[0][0];
+  const p = at(best);
+  return { left: clamp(p.left, margin, frame.width - margin - pop.width), top: clamp(p.top, margin, frame.height - margin - pop.height), side: best };
+}