@intentius/behold 0.29.6 → 0.29.7

package/web/kiosk-popover.js

@@ -0,0 +1,234 @@
+// 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.",
+  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 };
+}

package/web/kiosk-popover.test.js

@@ -0,0 +1,180 @@
+import { describe, expect, it } from "vitest";
+import { MAX_LINES, PIN_HOLD_MS, WORDS, attributeLine, placePopover, popReduce, popState, resourcePopover, rootPopover, valueWords } from "./kiosk-popover.js";
+
+// behold#571: the shape /api/terragucci answers (src/terragucci-overlay.ts):
+// the checkout's roots, the marks on each card with each attribute's values,
+// and what the newest applied wave wrote.
+const run = (o = {}) => ({ stage: "tf-plan", finished: "2026-10-20T10:01:40.000Z", commit: "a1b2c3d4", pull_request: "41", report: "r.html", ...o });
+const answer = (o = {}) => ({
+  roots: [
+    { member: "repo", name: "network", path: "network", plan: { changes: 1 } },
+    { member: "repo", name: "app", path: "app", plan: { changes: 1 } },
+    { member: "repo", name: "other", path: "other" },
+  ],
+  pull_request: { roots: ["network", "app"] },
+  cards: {
+    "repo/network/terraform_data.http_proxy_port": [
+      {
+        verdict: "plan",
+        action: "update",
+        words: "would update",
+        addresses: ["terraform_data.http_proxy_port"],
+        attributes: ["input"],
+        values: [{ address: "terraform_data.http_proxy_port", path: "input", before: 8080, after: 9090 }],
+        run: run(),
+      },
+    ],
+    "repo/app/terraform_data.listener_port": [
+      {
+        verdict: "plan",
+        action: "update",
+        words: "would update",
+        addresses: ["terraform_data.listener_port"],
+        attributes: ["input"],
+        values: [{ address: "terraform_data.listener_port", path: "input", before: 8070, unknown: true }],
+        run: run(),
+      },
+    ],
+  },
+  applied: {},
+  ...o,
+});
+
+describe("what the popover says about a resource (behold#571)", () => {
+  it("says a change one attribute a line, before -> after, and that the left is what is applied now", () => {
+    const p = resourcePopover(answer(), "repo/network/terraform_data.http_proxy_port");
+    expect(p).toMatchObject({ address: "terraform_data.http_proxy_port", root: "network", head: "The plan changes this resource.", change: true, unknown: false, more: 0 });
+    expect(p.lines).toEqual([{ text: "input: 8080 -> 9090", tone: null }]);
+    expect(p.note).toBe(WORDS.leftIsApplied);
+    expect(p.applied).toBeNull();
+  });
+
+  it("says an attribute known only after apply in the unknown tone, and that no review shows it", () => {
+    const p = resourcePopover(answer(), "repo/app/terraform_data.listener_port");
+    expect(p.unknown).toBe(true);
+    expect(p.lines).toEqual([{ text: "input: 8070 -> known after apply, so no review shows this value", tone: "unknown" }]);
+    expect(attributeLine({ path: "input", unknown: true })).toEqual({ text: "input: known after apply, so no review shows this value", tone: "unknown" });
+  });
+
+  it("says no change for a card the plan leaves alone, and that a root the plan does not hold is untouched", () => {
+    const a = answer();
+    expect(resourcePopover(a, "repo/network/terraform_data.release")).toMatchObject({ address: "terraform_data.release", head: WORDS.same, lines: [], change: false });
+    expect(resourcePopover(a, "repo/other/terraform_data.backup_schedule")).toMatchObject({ root: "other", head: WORDS.untouched, change: false });
+    expect(resourcePopover({ roots: a.roots, cards: {} }, "repo/other/terraform_data.backup_schedule").head).toBe(WORDS.noPlan);
+    expect(resourcePopover(a, "elsewhere/x")).toBeNull();
+    expect(resourcePopover({ error: "no" }, "repo/network/terraform_data.release")).toBeNull();
+  });
+
+  it("caps the lines at six and counts the rest", () => {
+    const values = Array.from({ length: 9 }, (_, i) => ({ address: "terraform_data.http_proxy_port", path: `a${i}`, before: i, after: i + 1 }));
+    const a = answer();
+    a.cards["repo/network/terraform_data.http_proxy_port"][0].values = values;
+    const p = resourcePopover(a, "repo/network/terraform_data.http_proxy_port");
+    expect(p.lines).toHaveLength(MAX_LINES);
+    expect(p.more).toBe(3);
+  });
+
+  it("shows what the newest applied wave wrote for the attributes that change, when it applied after the plan", () => {
+    const applied = { "repo/network/terraform_data.http_proxy_port": { values: [{ address: "terraform_data.http_proxy_port", path: "input", before: 8080, after: 9090 }, { address: "x", path: "unrelated", after: 1 }], run: run({ stage: "tf-apply", wave: 1, finished: "2026-10-20T10:04:10.000Z" }) } };
+    const p = resourcePopover(answer({ applied }), "repo/network/terraform_data.http_proxy_port", new Date("2026-10-20T11:00:00Z"));
+    expect(p.applied).toEqual({ when: "The applied state holds these values now, from wave 1 at 10:04 UTC.", lines: [{ text: "input: 9090", tone: null }] });
+    expect(p.note).toBeNull();
+    // An apply older than the plan says nothing of now.
+    const old = { "repo/network/terraform_data.http_proxy_port": { ...applied["repo/network/terraform_data.http_proxy_port"], run: run({ stage: "tf-apply", wave: 1, finished: "2026-10-19T00:00:00.000Z" }) } };
+    expect(resourcePopover(answer({ applied: old }), "repo/network/terraform_data.http_proxy_port").applied).toBeNull();
+  });
+
+  it("writes values plainly: a string bare, the rest as JSON, cut short", () => {
+    expect(valueWords("http://app:9080")).toBe("http://app:9080");
+    expect(valueWords("")).toBe('""');
+    expect(valueWords(null)).toBe("null");
+    expect(valueWords({ a: "x".repeat(60) })).toHaveLength(40);
+    expect(attributeLine({ path: "input", after: 1 }).text).toBe("input: none yet -> 1");
+    expect(attributeLine({ path: "input", before: 1 }).text).toBe("input: 1 -> gone");
+    expect(attributeLine({ path: "policy", long: true }).text).toBe("policy: too long to show here");
+  });
+});
+
+describe("what the popover says about a root, in Roots by wave (behold#571)", () => {
+  it("lists its resources, each changes, no change or known after apply, and counts the changes", () => {
+    const resources = [
+      { kind: "terraform_remote_state", id: "app/data.terraform_remote_state.network" },
+      { kind: "terraform_data", id: "app/terraform_data.listener_port" },
+    ];
+    const p = rootPopover(answer(), "app", resources);
+    expect(p.head).toBe("1 of 2 resources change.");
+    expect(p.rows).toEqual([
+      { address: "data.terraform_remote_state.network", state: "same", words: "no change" },
+      { address: "terraform_data.listener_port", state: "unknown", words: "known after apply" },
+    ]);
+    const net = rootPopover(answer(), "network", [{ kind: "terraform_data", id: "network/terraform_data.http_proxy_port" }]);
+    expect(net.rows[0]).toMatchObject({ state: "change", words: "changes" });
+    expect(net.head).toBe("1 of 1 resource changes.");
+    expect(rootPopover(answer(), "other", [{ kind: "terraform_data", id: "other/terraform_data.backup_schedule" }]).head).toBe(WORDS.noRootChange);
+    expect(rootPopover(answer(), "other", []).head).toBe(WORDS.noResources);
+  });
+});
+
+describe("when the popover shows (behold#571)", () => {
+  it("shows nothing until someone points, follows the pointer, and hides when it leaves", () => {
+    let s = popState();
+    expect(s.shown).toBeNull();
+    s = popReduce(s, { type: "enter", id: "a" }, 0);
+    expect(s).toEqual({ shown: "a", pinned: false, at: 0 });
+    s = popReduce(s, { type: "enter", id: "b" }, 0);
+    expect(s.shown).toBe("b");
+    expect(popReduce(s, { type: "leave", id: "a" }, 0)).toBe(s);
+    expect(popReduce(s, { type: "leave", id: "b" }, 0).shown).toBeNull();
+  });
+
+  it("pins on a click, keeps the pinned card while the pointer moves, and closes on a click elsewhere or Escape", () => {
+    let s = popReduce(popState(), { type: "click", id: "a" }, 1000);
+    expect(s).toEqual({ shown: "a", pinned: true, at: 1000 });
+    expect(popReduce(s, { type: "enter", id: "b" }, 2000)).toBe(s);
+    expect(popReduce(s, { type: "leave", id: "a" }, 2000)).toBe(s);
+    expect(popReduce(s, { type: "outside" }, 2000)).toEqual(popState());
+    expect(popReduce(s, { type: "escape" }, 2000)).toEqual(popState());
+    // Another card's click moves the pin to it.
+    s = popReduce(s, { type: "click", id: "b" }, 3000);
+    expect(s).toEqual({ shown: "b", pinned: true, at: 3000 });
+  });
+
+  it("lets a pin go 90 seconds after the click, as the view toggle's hold does", () => {
+    expect(PIN_HOLD_MS).toBe(90_000);
+    const s = popReduce(popState(), { type: "click", id: "a" }, 1000);
+    expect(popReduce(s, { type: "tick" }, 1000 + PIN_HOLD_MS - 1)).toBe(s);
+    expect(popReduce(s, { type: "tick" }, 1000 + PIN_HOLD_MS)).toEqual(popState());
+    const hovered = popReduce(popState(), { type: "enter", id: "a" }, 0);
+    expect(popReduce(hovered, { type: "tick" }, 10 * PIN_HOLD_MS)).toBe(hovered);
+  });
+});
+
+describe("where the popover goes (behold#571)", () => {
+  const frame = { width: 900, height: 700 };
+  const pop = { width: 300, height: 160 };
+  const overlaps = (a, b) => !(a.left + a.width <= b.left || a.left >= b.left + b.width || a.top + a.height <= b.top || a.top >= b.top + b.height);
+  const inside = (p) => p.left >= 0 && p.top >= 0 && p.left + pop.width <= frame.width && p.top + pop.height <= frame.height;
+
+  it("sits right of the card when it fits, else left, else below, else above, never over the card", () => {
+    for (const card of [
+      { left: 100, top: 100, width: 200, height: 60 },
+      { left: 560, top: 100, width: 200, height: 60 },
+      { left: 300, top: 100, width: 320, height: 60 },
+      { left: 300, top: 600, width: 320, height: 60 },
+      { left: 10, top: 640, width: 200, height: 50 },
+    ]) {
+      const p = placePopover(card, pop, frame);
+      expect(overlaps({ ...p, ...pop }, card)).toBe(false);
+      expect(inside(p)).toBe(true);
+    }
+    expect(placePopover({ left: 100, top: 100, width: 200, height: 60 }, pop, frame).side).toBe("right");
+    expect(placePopover({ left: 560, top: 100, width: 200, height: 60 }, pop, frame).side).toBe("left");
+    expect(placePopover({ left: 300, top: 100, width: 320, height: 60 }, pop, frame).side).toBe("below");
+    expect(placePopover({ left: 300, top: 500, width: 320, height: 160 }, pop, frame).side).toBe("above");
+  });
+
+  it("stays inside the frame when no side has room", () => {
+    const p = placePopover({ left: 100, top: 100, width: 700, height: 500 }, pop, frame);
+    expect(inside(p)).toBe(true);
+  });
+});

package/web/kiosk-roots.js

@@ -0,0 +1,191 @@
+// behold#571: one colour per Terraform root across the kiosk's panes, and the
+// hover links between them. Pure logic, plus two small DOM helpers.
+//
+// A root's colour is its identity, never a state: the state colours (green
+// applied, amber waiting or unknown, red failed, blue planned, teal running)
+// already mean something, so a root shows its colour only as a small dot by
+// its name, never as a text or fill colour. The hues below are none of those,
+// and each passes 4.5:1 on its theme's background and panel (checked against
+// #1e1e2e, #2e2f40, #11101f and #0f141d for dark; #ffffff and #f6f8fa for
+// light).
+//
+// The colour follows the root's place in the sorted list of declared roots
+// (terragucci.components.json), so it is the same on every cycle and on every
+// screen showing the same repo.
+
+/** The root hues, by theme: violet, orange, orchid, silver, tan. */
+export const ROOT_HUES = {
+  dark: ["#b392f0", "#ff9f5a", "#e66ce8", "#e4e4e4", "#c89b6d"],
+  light: ["#7c3aed", "#c2410c", "#a21caf", "#334155", "#8b5a2b"],
+};
+
+/** The declared roots, sorted and without repeats: the order colours follow. */
+export function rootOrder(roots) {
+  return [...new Set((roots || []).filter((r) => typeof r === "string" && r))].sort();
+}
+
+/** A root's colour, or null for a name that is not a declared root. */
+export function rootColour(name, roots, { light = false } = {}) {
+  const order = rootOrder(roots);
+  const i = order.indexOf(name);
+  if (i < 0) return null;
+  const hues = light ? ROOT_HUES.light : ROOT_HUES.dark;
+  return hues[i % hues.length];
+}
+
+// A token holding any of these is an address, a path, a hash or a key=value:
+// a root name inside it is not a mention of the root.
+const NOT_PROSE = /:\/\/|\/|=|^[0-9a-f]{7,}$|^jcs\d|sha\d+:/i;
+const WORD = /[\w-]/;
+
+/**
+ * Split a line into runs of plain text and whole-word root names, for the
+ * kiosk to put a dot by each name. A name counts only as a word of its own:
+ * not inside a URL, a path, a hash or an address such as
+ * `terraform_data.app_x` or `app:9080`, and not as part of a longer word
+ * (`apply-wave-2`, `appliance`). "network's" and "(app)" count.
+ * Returns `[{ text }, { text, root }, …]`; joined, the texts are the line.
+ */
+export function rootSegments(text, roots) {
+  const s = typeof text === "string" ? text : "";
+  const names = rootOrder(roots).sort((a, b) => b.length - a.length);
+  if (!s || !names.length) return s ? [{ text: s }] : [];
+  const out = [];
+  let plain = "";
+  const flush = () => {
+    if (plain) out.push({ text: plain });
+    plain = "";
+  };
+  // Whitespace runs and tokens, in order.
+  for (const part of s.split(/(\s+)/)) {
+    if (!part) continue;
+    if (/^\s+$/.test(part) || NOT_PROSE.test(part)) {
+      plain += part;
+      continue;
+    }
+    let i = 0;
+    while (i < part.length) {
+      const name = names.find((n) => part.startsWith(n, i) && wholeWord(part, i, n.length));
+      if (!name) {
+        plain += part[i];
+        i += 1;
+        continue;
+      }
+      flush();
+      out.push({ text: name, root: name });
+      i += name.length;
+    }
+  }
+  flush();
+  return out;
+}
+
+function wholeWord(token, at, len) {
+  const before = at > 0 ? token[at - 1] : "";
+  const after = token[at + len] || "";
+  const rest = token.slice(at + len + 1);
+  if (before && (WORD.test(before) || before === "." || before === ":" || before === "@" || before === "#")) return false;
+  if (!after) return true;
+  if (WORD.test(after)) return false;
+  // `terraform_data.app.x`, `app:9080`: an address or a host, not the root.
+  if ((after === "." || after === ":") && rest && /[\w"[]/.test(rest[0])) return false;
+  return true;
+}
+
+/** The wave a pipeline job applies: from the declared jobs, else from its name (`apply-wave-2`). */
+export function waveOfJob(job, waves = []) {
+  const w = (waves || []).find((x) => x.job === job);
+  if (w) return w.wave;
+  const m = /^apply-wave-(\d+)$/.exec(job || "");
+  return m ? Number(m[1]) : null;
+}
+
+/** The roots a wave applies, from the declared jobs. */
+export function rootsOfWave(wave, waves = []) {
+  const w = (waves || []).find((x) => x.wave === wave);
+  return w ? [...w.roots] : [];
+}
+
+/**
+ * What a hover lights across the panes. A root lights its own mentions and
+ * box or card, and the job row and box of the wave that applies it; a wave
+ * (a job row, a wave box) lights its own row and box, and the roots it
+ * applies. Null lights nothing.
+ */
+export function hoverLinks(hover, waves = []) {
+  const out = { roots: [], waves: [] };
+  if (!hover) return out;
+  if (typeof hover.root === "string" && hover.root) {
+    out.roots.push(hover.root);
+    for (const w of waves || []) if (w.roots.includes(hover.root) && !out.waves.includes(w.wave)) out.waves.push(w.wave);
+  } else if (typeof hover.wave === "number") {
+    out.waves.push(hover.wave);
+    for (const r of rootsOfWave(hover.wave, waves)) if (!out.roots.includes(r)) out.roots.push(r);
+  }
+  return out;
+}
+
+/** The `behold:hover` message both sides send: a root, a wave, or null for neither. */
+export function hoverMessage(hover) {
+  return { type: "behold:hover", root: hover && typeof hover.root === "string" ? hover.root : null, wave: hover && typeof hover.wave === "number" ? hover.wave : null };
+}
+
+/** A `behold:hover` message reduced to a hover, or undefined when it is not one. */
+export function hoverFromMessage(data) {
+  if (!data || typeof data !== "object" || data.type !== "behold:hover") return undefined;
+  if (typeof data.root === "string" && data.root) return { root: data.root };
+  if (typeof data.wave === "number" && Number.isInteger(data.wave)) return { wave: data.wave };
+  return null;
+}
+
+/** Whether a background colour (`#rrggbb`) is light. */
+export function isLightBg(hex) {
+  const m = /^#?([0-9a-f]{6})$/i.exec((hex || "").trim());
+  if (!m) return false;
+  const n = parseInt(m[1], 16);
+  return (0.2126 * (n >> 16) + 0.7152 * ((n >> 8) & 255) + 0.0722 * (n & 255)) / 255 > 0.5;
+}
+
+/** A dot in a root's colour, for beside its name. */
+export function rootDot(doc, name, colour) {
+  const dot = doc.createElement("span");
+  dot.className = "k-root-dot";
+  dot.setAttribute("aria-hidden", "true");
+  dot.style.setProperty("--k-root", colour);
+  dot.dataset.kRoot = name;
+  return dot;
+}
+
+/** A line as nodes: plain text, and each root name in a span with its dot. */
+export function rootText(doc, text, roots, { light = false } = {}) {
+  const frag = doc.createDocumentFragment();
+  for (const seg of rootSegments(text, roots)) {
+    if (!seg.root) {
+      frag.appendChild(doc.createTextNode(seg.text));
+      continue;
+    }
+    const span = doc.createElement("span");
+    span.className = "k-root";
+    span.dataset.kRoot = seg.root;
+    span.style.setProperty("--k-root", rootColour(seg.root, roots, { light }));
+    span.textContent = seg.text;
+    frag.appendChild(span);
+  }
+  return frag;
+}
+
+/**
+ * The CSS that lights what a hover links, as one rule set: a style element
+ * holding it survives the panes' redraws, which replace their nodes every
+ * second. `sel` builds the selectors for a root name and for a wave
+ * number; quote a name with cssString.
+ */
+export function hoverCss(links, sel, rule) {
+  const parts = [...links.roots.map((r) => sel.root(r)), ...links.waves.map((w) => sel.wave(w))].filter(Boolean);
+  return parts.length ? `${parts.join(",\n")} { ${rule} }` : "";
+}
+
+/** A value quoted for an attribute selector. */
+export function cssString(s) {
+  return `"${String(s).replace(/["\\]/g, "\\$&").replace(/\n/g, "\\a ")}"`;
+}