@intentius/behold 0.29.6 → 0.29.8

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-repo.js

@@ -0,0 +1,25 @@
+// behold#571: which repo the kiosk's graph reads, on a behold that serves
+// several (`behold serve --repos`, one checkout per demo repo). The kiosk
+// knows the repo it is about (demo.json's `repo`, or a tool's latest cycle's)
+// and asks for that checkout by name with `?repo=`; the server answers from
+// it, or refuses a name it doesn't serve.
+
+/** The reads that depend on the served checkout: the project, the reports' marks, the run view, and (behold#571's approval panel) the gate ledger read from its chant/lifecycle. */
+const REPO_READS = new Set(["/api/project", "/api/terragucci", "/api/terragucci/progress", "/api/terragucci/lifecycle", "/api/lifecycle/history"]);
+
+/** The checkout name for `repo` ("<owner>/<name>") when the server serves it; null otherwise. */
+export function repoParam(repo, served) {
+  if (typeof repo !== "string" || !repo || !Array.isArray(served)) return null;
+  const name = repo.replace(/\.git$/, "").slice(repo.lastIndexOf("/") + 1);
+  return served.includes(name) ? name : null;
+}
+
+/** `url` asking for `repo`, when it is one of the reads that depend on the checkout. */
+export function repoUrl(url, repo) {
+  if (!repo || typeof url !== "string") return url;
+  const [path, query = ""] = url.split("?");
+  if (!REPO_READS.has(path)) return url;
+  const q = new URLSearchParams(query);
+  q.set("repo", repo);
+  return `${path}?${q.toString()}`;
+}

package/web/kiosk-repo.test.js

@@ -0,0 +1,43 @@
+// behold#571: the kiosk asks for its repo's checkout by name, on a behold that serves several.
+import { describe, expect, it } from "vitest";
+import { repoParam, repoUrl } from "./kiosk-repo.js";
+import { frameSrc } from "./kiosk.js";
+import { pageRepo, withRepo } from "./view-repo.js";
+
+describe("repoParam", () => {
+  it("is the checkout name when the server serves it, else null", () => {
+    expect(repoParam("terragucci-admin/demo-terragrunt", ["demo", "demo-terragrunt"])).toBe("demo-terragrunt");
+    expect(repoParam("terragucci-admin/demo-cdk", ["demo", "demo-terragrunt"])).toBeNull();
+    expect(repoParam("terragucci-admin/demo", null)).toBeNull();
+    expect(repoParam(null, ["demo"])).toBeNull();
+  });
+});
+
+describe("repoUrl", () => {
+  it("adds the repo to the reads about the checkout only", () => {
+    expect(repoUrl("/api/project", "demo-terragrunt")).toBe("/api/project?repo=demo-terragrunt");
+    expect(repoUrl("/api/terragucci?fresh=1", "demo-terragrunt")).toBe("/api/terragucci?fresh=1&repo=demo-terragrunt");
+    expect(repoUrl("/api/terragucci/progress?commit=abc", "demo")).toBe("/api/terragucci/progress?commit=abc&repo=demo");
+    expect(repoUrl("/api/terragucci/lifecycle", "demo")).toBe("/api/terragucci/lifecycle?repo=demo");
+    expect(repoUrl("/api/lifecycle/history?limit=200", "demo")).toBe("/api/lifecycle/history?limit=200&repo=demo");
+    expect(repoUrl("/api/terragucci/demo", "demo")).toBe("/api/terragucci/demo");
+    expect(repoUrl("/api/terragucci/runs/4", "demo")).toBe("/api/terragucci/runs/4");
+    expect(repoUrl("/api/project", null)).toBe("/api/project");
+  });
+});
+
+describe("the frame", () => {
+  it("names the repo it draws, and nothing without one", () => {
+    expect(frameSrc("http://h", "resources")).toBe("/?embed=1&bare=1&zoom=resources&host=http%3A%2F%2Fh");
+    expect(frameSrc("http://h", "components", "demo-terragrunt")).toBe("/?embed=1&bare=1&zoom=components&host=http%3A%2F%2Fh&repo=demo-terragrunt");
+  });
+  it("carries the page's repo on each of its own /api/ reads", () => {
+    expect(pageRepo("?embed=1&repo=demo-terragrunt")).toBe("demo-terragrunt");
+    expect(pageRepo("?embed=1")).toBeNull();
+    expect(withRepo("/api/graph?zoom=resources", "demo-terragrunt", "http://h")).toBe("/api/graph?zoom=resources&repo=demo-terragrunt");
+    expect(withRepo("http://h/api/project", "demo-terragrunt", "http://h")).toBe("http://h/api/project?repo=demo-terragrunt");
+    expect(withRepo("/api/project?repo=demo", "demo-terragrunt", "http://h")).toBe("/api/project?repo=demo");
+    expect(withRepo("./manifest.json", "demo-terragrunt", "http://h")).toBe("./manifest.json");
+    expect(withRepo("https://elsewhere/api/x", "demo-terragrunt", "http://h")).toBe("https://elsewhere/api/x");
+  });
+});

package/web/kiosk-roots.js

@@ -0,0 +1,199 @@
+// 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). theme.js pushes each, per theme, to 3:1 on every kiosk surface
+// (--root-0 … --root-4), and the page paints a dot with that, this as its fallback.
+//
+// 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.
+
+import { ROOT_HUES } from "./theme.js";
+
+/** The root hues, by theme: violet, orange, orchid, silver, tan. theme.js holds them, and derives each theme's own (--root-0 …). */
+export { ROOT_HUES };
+
+/** 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 root's paint: the theme's own root colour (--root-<i>), with rootColour's as its fallback; null for a name that is not a root. */
+export function rootPaint(name, roots, { light = false } = {}) {
+  const c = rootColour(name, roots, { light });
+  if (!c) return null;
+  const hues = light ? ROOT_HUES.light : ROOT_HUES.dark;
+  return `var(--root-${rootOrder(roots).indexOf(name) % hues.length}, ${c})`;
+}
+
+// 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", rootPaint(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 ")}"`;
+}

package/web/kiosk-roots.test.js

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+import { ROOT_HUES, cssString, hoverCss, hoverFromMessage, hoverLinks, hoverMessage, isLightBg, rootColour, rootOrder, rootSegments, rootsOfWave, waveOfJob } from "./kiosk-roots.js";
+
+// behold#571: the demo repo's roots and the wave jobs of its terragucci.components.json.
+const ROOTS = ["network", "other", "app", "edge"];
+const WAVES = [
+  { job: "apply-wave-1", wave: 1, roots: ["network", "other"] },
+  { job: "apply-wave-2", wave: 2, roots: ["app"] },
+  { job: "apply-wave-3", wave: 3, roots: ["edge"] },
+];
+const names = (text) => rootSegments(text, ROOTS).filter((s) => s.root).map((s) => s.root);
+
+describe("a colour per root (behold#571)", () => {
+  it("follows the sorted root list, so it is the same on every cycle and in any order", () => {
+    expect(rootOrder(ROOTS)).toEqual(["app", "edge", "network", "other"]);
+    const a = Object.fromEntries(ROOTS.map((r) => [r, rootColour(r, ROOTS)]));
+    const b = Object.fromEntries(ROOTS.map((r) => [r, rootColour(r, [...ROOTS].reverse())]));
+    expect(a).toEqual(b);
+    expect(a.app).toBe(ROOT_HUES.dark[0]);
+    expect(new Set(Object.values(a)).size).toBe(4);
+    expect(rootColour("app", ROOTS, { light: true })).toBe(ROOT_HUES.light[0]);
+    expect(rootColour("nope", ROOTS)).toBeNull();
+  });
+
+  it("uses no state colour: not the green, amber, red, blue or teal of the theme", () => {
+    const state = ["#a6e3a1", "#f9e2af", "#f38ba8", "#89b4fa", "#94e2d5", "#6d7187"];
+    for (const hue of [...ROOT_HUES.dark, ...ROOT_HUES.light]) expect(state).not.toContain(hue.toLowerCase());
+    expect(new Set(ROOT_HUES.dark).size).toBe(ROOT_HUES.dark.length);
+    expect(new Set(ROOT_HUES.light).size).toBe(ROOT_HUES.light.length);
+  });
+
+  it("tells a light background from a dark one", () => {
+    expect(isLightBg("#ffffff")).toBe(true);
+    expect(isLightBg(" #1e1e2e")).toBe(false);
+    expect(isLightBg("")).toBe(false);
+  });
+});
+
+describe("root names in a line (behold#571)", () => {
+  it("finds whole-word names, possessives and names in brackets, and keeps the line's text", () => {
+    const line = "app reads subnet_id from network, known only after network applies: the review does not show the value app gets.";
+    expect(names(line)).toEqual(["app", "network", "network", "app"]);
+    expect(rootSegments(line, ROOTS).map((s) => s.text).join("")).toBe(line);
+    expect(names("approves wave 2 (app) with network's key")).toEqual(["app", "network"]);
+    expect(names("app: Plan: 0 to add, 1 to change, 0 to destroy.")).toEqual(["app"]);
+  });
+
+  it("leaves names inside addresses, hosts, URLs, paths, hashes and longer words alone", () => {
+    expect(names("terraform_data.app_x and data.terraform_remote_state.network")).toEqual([]);
+    expect(names("upstream http://app:9080 and app:8070")).toEqual([]);
+    expect(names("report copied to demo/forgejo:3000/terragucci-admin/demo/2026/10/ef95/tf-apply-wave-1")).toEqual([]);
+    expect(names("set digest jcs1-sha256:0accc105ba06 and commit a1b2c3d4e5")).toEqual([]);
+    expect(names("apply-wave-2 appliance networks edge-proxy network.tfstate")).toEqual([]);
+    expect(names("key=network")).toEqual([]);
+  });
+
+  it("says nothing without roots", () => {
+    expect(rootSegments("network", [])).toEqual([{ text: "network" }]);
+    expect(rootSegments("", ROOTS)).toEqual([]);
+  });
+});
+
+describe("hover links between the panes (behold#571)", () => {
+  it("ties a wave's job to its roots, from the declared jobs or the job's name", () => {
+    expect(waveOfJob("apply-wave-2", WAVES)).toBe(2);
+    expect(waveOfJob("apply-wave-7", [])).toBe(7);
+    expect(waveOfJob("check", WAVES)).toBeNull();
+    expect(rootsOfWave(1, WAVES)).toEqual(["network", "other"]);
+    expect(rootsOfWave(9, WAVES)).toEqual([]);
+  });
+
+  it("lights a root's mentions and its wave, and a wave's job and its roots", () => {
+    expect(hoverLinks({ root: "other" }, WAVES)).toEqual({ roots: ["other"], waves: [1] });
+    expect(hoverLinks({ wave: 1 }, WAVES)).toEqual({ roots: ["network", "other"], waves: [1] });
+    expect(hoverLinks({ root: "lonely" }, WAVES)).toEqual({ roots: ["lonely"], waves: [] });
+    expect(hoverLinks(null, WAVES)).toEqual({ roots: [], waves: [] });
+  });
+
+  it("carries a hover between the frame and the kiosk as a message, and takes only that message", () => {
+    expect(hoverMessage({ root: "app" })).toEqual({ type: "behold:hover", root: "app", wave: null });
+    expect(hoverMessage(null)).toEqual({ type: "behold:hover", root: null, wave: null });
+    expect(hoverFromMessage(hoverMessage({ wave: 2 }))).toEqual({ wave: 2 });
+    expect(hoverFromMessage(hoverMessage({ root: "app" }))).toEqual({ root: "app" });
+    expect(hoverFromMessage(hoverMessage(null))).toBeNull();
+    expect(hoverFromMessage({ type: "behold:view" })).toBeUndefined();
+    expect(hoverFromMessage("behold:hover")).toBeUndefined();
+  });
+
+  it("writes one rule for what a hover lights, quoting names", () => {
+    const css = hoverCss(hoverLinks({ wave: 2 }, WAVES), { root: (r) => `.k-root[data-k-root=${cssString(r)}]`, wave: (w) => `.r-job[data-k-wave="${w}"]` }, "outline: 1px solid");
+    expect(css).toBe('.k-root[data-k-root="app"],\n.r-job[data-k-wave="2"] { outline: 1px solid }');
+    expect(hoverCss({ roots: [], waves: [] }, { root: () => "x", wave: () => "y" }, "z")).toBe("");
+    expect(cssString('a"b')).toBe('"a\\"b"');
+  });
+});