@intentius/behold 0.29.6 → 0.29.7

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"');
+  });
+});

package/web/kiosk-runs.js

@@ -10,6 +10,8 @@
 // A job held at a terragucci gate is `waiting`: it waits for an approval, and
 // is never drawn as a failure. Step names are shown as the driver wrote them.
 
+import { rootColour, rootSegments, rootText, rootsOfWave, waveOfJob } from "./kiosk-roots.js";
+
 /** The run, job and step statuses, as a viewer reads them. */
 export const STATUS_WORDS = {
   queued: "queued",
@@ -405,7 +407,14 @@ export function renderSidebar(host, index, selectedId, { now = new Date(), scena
  * null for the defaults. Returns what it drew, so the caller can keep a log's
  * scroll.
  */
-export function renderRun(host, answer, ui, { now = new Date(), pickJob = () => {}, toggleStep = () => {}, toggleSetup = () => {}, entry = null } = {}) {
+export function renderRun(host, answer, ui, { now = new Date(), pickJob = () => {}, toggleStep = () => {}, toggleSetup = () => {}, entry = null, roots = [], waves = [], light = false } = {}) {
+  // behold#571: a root's name with its colour's dot, where the line names one.
+  const textOf = (cls, text) => {
+    if (!roots.length || !rootSegments(text, roots).some((x) => x.root)) return el("span", cls, text);
+    const n = el("span", cls);
+    n.appendChild(rootText(document, text, roots, { light }));
+    return n;
+  };
   host.replaceChildren();
   if (!answer || answer.error || answer.absent || !answer.doc) {
     host.appendChild(el("p", "r-note", answer ? answer.absent || answer.error : "Reading the run…"));
@@ -440,6 +449,20 @@ export function renderRun(host, answer, ui, { now = new Date(), pickJob = () =>
     li.style.setProperty("--depth", String(j.depth));
     li.appendChild(statusIcon(j.status));
     li.appendChild(el("span", "r-job-name", j.name));
+    // behold#571: a wave's job row names the roots it applies, each with its dot, and lights its wave box on hover.
+    const wave = waveOfJob(j.name, waves);
+    const applies = wave !== null ? rootsOfWave(wave, waves).filter((r) => rootColour(r, roots, { light })) : [];
+    if (wave !== null && waves.length) li.dataset.kWave = String(wave);
+    if (applies.length) {
+      const box = el("span", "r-job-roots");
+      for (const r of applies) {
+        const name = el("span", "k-root", r);
+        name.dataset.kRoot = r;
+        name.style.setProperty("--k-root", rootColour(r, roots, { light }));
+        box.appendChild(name);
+      }
+      li.appendChild(box);
+    }
     if (j.needs && j.needs.length) li.appendChild(el("span", "r-job-needs", `after ${j.needs.join(", ")}`));
     li.appendChild(el("span", "r-dur", j.status === "waiting" ? "held at the gate" : durationWords(j.started_at, j.ended_at, now) || STATUS_WORDS[j.status] || ""));
     li.addEventListener("click", () => pickJob(j.name));
@@ -491,7 +514,7 @@ export function renderRun(host, answer, ui, { now = new Date(), pickJob = () =>
         }
         const ln = el("div", `r-log-line${row.quiet ? " r-log-quiet" : ""}`);
         const shown = logLineWords(job.status, row.text);
-        ln.append(el("span", "r-ln", String(row.n)), el("span", shown.held ? "r-lt r-wait" : "r-lt", shown.text));
+        ln.append(el("span", "r-ln", String(row.n)), row.quiet ? el("span", shown.held ? "r-lt r-wait" : "r-lt", shown.text) : textOf(shown.held ? "r-lt r-wait" : "r-lt", shown.text));
         pre.appendChild(ln);
       }
       if (!s.log.length) pre.appendChild(el("div", "r-log-cut", s.status === "running" ? "waiting for output…" : "no output"));
@@ -537,7 +560,7 @@ export const PICK_HOLD_MS = 90_000;
  * is live), and redraw. The live run is selected until a viewer picks
  * another, and again {@link PICK_HOLD_MS} after their last pick.
  */
-export function startRuns({ side, main }, { fetchJson, now = () => new Date(), scenarios = {}, titles = () => ({}), names = () => ({}), onLive = () => {} } = {}) {
+export function startRuns({ side, main }, { fetchJson, now = () => new Date(), scenarios = {}, titles = () => ({}), names = () => ({}), onLive = () => {}, roots = () => [], waves = () => [], light = () => false } = {}) {
   const s = { index: null, run: null, selected: null, picked: 0, ui: { job: null, open: null, setup: null } };
   let follow = true;
   let lastRunKey = "";
@@ -569,6 +592,9 @@ export function startRuns({ side, main }, { fetchJson, now = () => new Date(), s
     const drawn = renderRun(main, ans, s.ui, {
       now: now(),
       entry,
+      roots: roots(),
+      waves: waves(),
+      light: light(),
       pickJob: (name) => {
         s.ui = { job: name, open: null, setup: null };
         hold();

package/web/kiosk.html

@@ -58,6 +58,9 @@
       .r-job.r-selected { background: var(--active); }
       .r-job-name { font: 600 0.92em var(--font-mono); }
       .r-job-needs { color: var(--muted); font-size: 0.78em; }
+      /* behold#571: each root's colour, as a dot by its name; never a text or fill colour, which mean a state. */
+      .k-root::before { content: ""; display: inline-block; width: 0.6em; height: 0.6em; border-radius: 50%; background: var(--k-root); margin: 0 0.28em 0.1em 0.05em; vertical-align: middle; }
+      .r-job-roots { display: inline-flex; gap: 0.75em; font-size: 0.82em; color: var(--fg); }
       .r-dur { margin-left: auto; color: var(--muted); font-size: 0.8em; white-space: nowrap; }
       .r-job-skipped { color: var(--muted); font-size: 0.78em; cursor: default; }
       .r-steps { display: flex; flex-direction: column; min-height: 0; flex: 1; overflow-y: auto; padding-bottom: 0.5em; }

package/web/kiosk.js

@@ -14,6 +14,7 @@
 // Nothing here is all-or-nothing, and nothing says so.
 
 import { PICK_HOLD_MS, startRuns } from "./kiosk-runs.js";
+import { cssString, hoverCss, hoverFromMessage, hoverLinks, hoverMessage, isLightBg, rootSegments, rootText } from "./kiosk-roots.js";
 import { STATE_WORDS, changingRoots, costLine, pinsCommit, planFitsPin, pullPin, readEdges, rootsCount, totalsLine, waveRows, blastRows } from "./terragucci-change.js";
 
 /** The scenarios terragucci#1014 numbers. An id not here is shown by the title demo.json carries. */
@@ -218,14 +219,17 @@ export function unreviewedLines(answer) {
 
 /**
  * The approval the driver gives at a waiting wave, as terragucci's
- * stack/demo.sh gives it: `approve_wave` runs chant's approve, sealed with
- * the driver's ssh key, then `resume_pull` posts `/terragucci apply` on the
- * merged pull request. The actor and the key are placeholders: the kiosk
- * never names a path or a secret.
+ * stack/demo.sh gives it: `approve_wave` runs chant's approve as the
+ * reviewer (terragucci#1052: the driver plays two people, demo-author who
+ * opens, merges and comments, and demo-reviewer who approves, since an
+ * approval only counts from someone who had no hand in the change), sealed
+ * with the reviewer's own signing key; then `resume_pull` posts
+ * `/terragucci apply` on the merged pull request. The actor and the key are
+ * placeholders: the kiosk never names a path or a secret.
  */
 export function driverApproveLines(wave, pull) {
   return {
-    approve: `chant approve tf-apply wave-${wave} --actor <driver> --sign <driver key>`,
+    approve: `chant approve tf-apply wave-${wave} --actor <reviewer> --sign <reviewer key>`,
     comment: "/terragucci apply",
     on: pull !== null && pull !== undefined ? `pull request #${pull}` : "the merged pull request",
   };
@@ -254,12 +258,13 @@ export function pendingApproval(demo, progress) {
 
 /**
  * behold#571: the approval in plain words, before the command, for a viewer
- * who has never approved a pipeline: who the driver is, what it signs. The
+ * who has never approved a pipeline: who the driver plays, what it signs
+ * with (terragucci#1052: a reviewer apart from the change's author). The
  * plan's digest is on the wave's box in the view.
  */
 export function approveGloss(appr) {
   const roots = appr.roots.length ? ` (${appr.roots.join(", ")})` : "";
-  return `The driver stands in for a person: it approves wave ${appr.wave}${roots} with its own signing key.`;
+  return `The driver plays a reviewer who had no hand in the change, and approves wave ${appr.wave}${roots} with that reviewer's own signing key.`;
 }
 
 /**
@@ -457,6 +462,15 @@ const el = (tag, cls, text) => {
   return n;
 };
 
+/** behold#571: an element whose text puts a dot in its root's colour by each whole-word root name. */
+const elRoots = (tag, cls, text, s) => {
+  const roots = (s && (s.rootNames || s.roots)) || [];
+  if (text === undefined || text === null || !rootSegments(String(text), roots).some((x) => x.root)) return el(tag, cls, text);
+  const n = el(tag, cls);
+  n.appendChild(rootText(document, String(text), roots, { light: !!(s && s.light) }));
+  return n;
+};
+
 /** Draw the bar and the foot from what the kiosk holds. Pure over its arguments, but for the DOM. */
 export function renderKiosk(bar, s, now = new Date(), foot = null) {
   bar.replaceChildren();
@@ -482,11 +496,11 @@ export function renderKiosk(bar, s, now = new Date(), foot = null) {
   const rows = aboutRows(demo);
   if (rows.length) {
     const card = el("dl", "k-about");
-    for (const r of rows) card.append(el("dt", "k-about-label", r.label), el("dd", "k-about-text", r.text));
+    for (const r of rows) card.append(el("dt", "k-about-label", r.label), elRoots("dd", "k-about-text", r.text, s));
     left.appendChild(card);
   }
   const said = el("p", `k-step k-step-${demo.step}`);
-  said.append(el("span", "k-step-word", STEP_WORDS[demo.step] || demo.step), el("span", "k-label", demo.label));
+  said.append(el("span", "k-step-word", STEP_WORDS[demo.step] || demo.step), elRoots("span", "k-label", demo.label, s));
   left.appendChild(said);
   bar.appendChild(left);
 
@@ -500,14 +514,14 @@ export function renderKiosk(bar, s, now = new Date(), foot = null) {
   const nx = nextWords(demo, now);
   const next = el("div", "k-next");
   next.appendChild(el("span", "k-next-word", "next, by the driver"));
-  next.appendChild(el("span", "k-action", nx.action));
+  next.appendChild(elRoots("span", "k-action", nx.action, s));
   next.appendChild(el("span", "k-when", nx.when));
   right.appendChild(next);
 
   const appr = pendingApproval(demo, s.progress);
   if (appr) {
     const a = el("div", "k-approve");
-    a.appendChild(el("p", "k-approve-gloss", approveGloss(appr)));
+    a.appendChild(elRoots("p", "k-approve-gloss", approveGloss(appr), s));
     a.appendChild(el("code", "k-command", appr.approve));
     const then = el("p", "k-approve-then");
     then.append(`then comments `, el("code", "k-inline", appr.comment), ` on ${appr.on}, and the waves run again.`);
@@ -515,18 +529,22 @@ export function renderKiosk(bar, s, now = new Date(), foot = null) {
     right.appendChild(a);
   } else {
     const panel = runPanel(demo, s.answer, s.progress);
-    if (panel.note) right.appendChild(el("p", "k-note", panel.note));
-    else if (panel.stage === "pull-request") for (const u of unreviewedLines(s.answer)) right.appendChild(el("p", "k-note k-unknown", u));
+    if (panel.note) right.appendChild(elRoots("p", "k-note", panel.note, s));
+    else if (panel.stage === "pull-request") for (const u of unreviewedLines(s.answer)) right.appendChild(elRoots("p", "k-note k-unknown", u, s));
   }
   bar.appendChild(right);
 
   if (foot) {
     foot.appendChild(el("span", "k-legend", legendWords(s.view || "resources")));
     // behold#571: no line on where the narration was read from: a viewer new to the demo reads the facts.
-    for (const f of factLines(demo, s.answer)) foot.appendChild(el("span", "k-fact", f));
+    for (const f of factLines(demo, s.answer)) foot.appendChild(elRoots("span", "k-fact", f, s));
   }
 }
 
+/** behold#571: how a hovered root's name and wave's job row light. A background and a shadow: nothing moves. */
+export const HOVER_ROOT_RULE = "background: color-mix(in srgb, var(--focus) 32%, transparent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--focus) 32%, transparent); border-radius: 3px;";
+export const HOVER_JOB_RULE = "background: color-mix(in srgb, var(--focus) 24%, transparent); box-shadow: inset 4px 0 0 var(--focus);";
+
 /** How often the kiosk asks for demo.json. The server shares one read between kiosks. */
 export const DEMO_POLL_MS = 3_000;
 
@@ -538,7 +556,7 @@ export const DEMO_POLL_MS = 3_000;
  * with a `behold:view` message; the frame takes them only from this origin.
  */
 export function startKiosk({ bar, frame, foot, side, main, views }, { fetchJson = defaultFetch, now = () => new Date(), origin = location.origin } = {}) {
-  const s = { demo: null, answer: null, progress: null, components: false, pick: null, view: "resources" };
+  const s = { demo: null, answer: null, progress: null, components: false, pick: null, view: "resources", roots: [], waves: [], light: false, hover: null, frameHover: null };
   let lastKey = "";
   let lastFocus;
   const shownView = () => kioskView(s.demo && s.demo.demo, { components: s.components, pick: s.pick, now: now().getTime() });
@@ -558,7 +576,59 @@ export function startKiosk({ bar, frame, foot, side, main, views }, { fetchJson
     s.pick = { view, at: now().getTime() };
     draw();
   };
+  // behold#571: the roots' colours and the hover links between the panes and the frame.
+  const rootList = () => (s.roots.length ? s.roots : s.answer && Array.isArray(s.answer.roots) ? s.answer.roots.map((r) => r.path) : []);
+  const glow = () => {
+    let style = document.getElementById("k-hover-style");
+    if (!style) {
+      style = document.createElement("style");
+      style.id = "k-hover-style";
+      document.head.appendChild(style);
+    }
+    const a = hoverLinks(s.hover, s.waves);
+    const b = hoverLinks(s.frameHover, s.waves);
+    const links = { roots: [...new Set([...a.roots, ...b.roots])], waves: [...new Set([...a.waves, ...b.waves])] };
+    style.textContent = [
+      hoverCss({ roots: links.roots, waves: [] }, { root: (r) => `.k-root[data-k-root=${cssString(r)}]` }, HOVER_ROOT_RULE),
+      hoverCss({ roots: [], waves: links.waves }, { wave: (w) => `.r-job[data-k-wave="${w}"]` }, HOVER_JOB_RULE),
+    ].join("\n");
+  };
+  const tellHover = (h) => {
+    if (frame && frame.contentWindow) frame.contentWindow.postMessage(hoverMessage(h), origin);
+  };
+  const hoverAt = (target) => {
+    const t = target && target.closest ? target.closest("[data-k-root],[data-k-wave]") : null;
+    if (!t) return null;
+    if (t.dataset.kRoot) return { root: t.dataset.kRoot };
+    const w = Number(t.dataset.kWave);
+    return Number.isInteger(w) ? { wave: w } : null;
+  };
+  const setHover = (h) => {
+    if ((h && h.root) === (s.hover && s.hover.root) && (h && h.wave) === (s.hover && s.hover.wave)) return;
+    s.hover = h;
+    glow();
+    tellHover(h);
+  };
+  if (typeof document !== "undefined" && document.addEventListener) {
+    document.addEventListener("pointerover", (e) => setHover(hoverAt(e.target)));
+    document.documentElement.addEventListener("pointerleave", () => setHover(null));
+    // A click or Escape anywhere here is a click elsewhere for the frame's pinned popover.
+    const unpin = () => frame && frame.contentWindow && frame.contentWindow.postMessage({ type: "behold:unpin" }, origin);
+    document.addEventListener("pointerdown", unpin);
+    document.addEventListener("keydown", (e) => {
+      if (e.key === "Escape") unpin();
+    });
+    window.addEventListener("message", (e) => {
+      if (e.origin !== origin || !frame || e.source !== frame.contentWindow) return;
+      const h = hoverFromMessage(e.data);
+      if (h === undefined) return;
+      s.frameHover = h;
+      glow();
+    });
+  }
   const draw = () => {
+    s.light = typeof document !== "undefined" && document.documentElement ? isLightBg(getComputedStyle(document.documentElement).getPropertyValue("--bg")) : false;
+    s.rootNames = rootList();
     const shown = shownView();
     s.view = shown.view;
     renderKiosk(bar, s, now(), foot);
@@ -569,7 +639,7 @@ export function startKiosk({ bar, frame, foot, side, main, views }, { fetchJson
   // behold#571: the titles and names demo.json has carried, by scenario, for the runs' subtitles.
   const titles = {};
   const names = {};
-  if (side && main) startRuns({ side, main }, { fetchJson, now, scenarios: SCENARIOS, titles: () => titles, names: () => names });
+  if (side && main) startRuns({ side, main }, { fetchJson, now, scenarios: SCENARIOS, titles: () => titles, names: () => names, roots: rootList, waves: () => s.waves, light: () => s.light });
   // #571: whether the repo offers the components zoom (a terragucci.components.json), read before the frame opens so it opens on the step's view.
   const openFrame = () => {
     if (!frame) return;
@@ -581,6 +651,11 @@ export function startKiosk({ bar, frame, foot, side, main, views }, { fetchJson
   };
   void fetchJson("/api/project").then((p) => {
     s.components = !!(p && !p.error && p.terragucciComponents);
+    // behold#571: the declared roots (their colours' order) and the wave jobs that apply them.
+    if (p && p.terragucciRoots) {
+      s.roots = Array.isArray(p.terragucciRoots.roots) ? p.terragucciRoots.roots : [];
+      s.waves = Array.isArray(p.terragucciRoots.waves) ? p.terragucciRoots.waves : [];
+    }
     openFrame();
     draw();
   });

package/web/kiosk.test.js

@@ -283,8 +283,8 @@ describe("the kiosk for a viewer new to the demo (behold#571)", () => {
   });
 
   it("says who the driver is before the command it runs", () => {
-    expect(approveGloss({ wave: 2, roots: ["app"], digest: "jcs1-sha256:0accc105ba06" })).toBe("The driver stands in for a person: it approves wave 2 (app) with its own signing key.");
-    expect(approveGloss({ wave: 3, roots: [], digest: null })).toBe("The driver stands in for a person: it approves wave 3 with its own signing key.");
+    expect(approveGloss({ wave: 2, roots: ["app"], digest: "jcs1-sha256:0accc105ba06" })).toBe("The driver plays a reviewer who had no hand in the change, and approves wave 2 (app) with that reviewer's own signing key.");
+    expect(approveGloss({ wave: 3, roots: [], digest: null })).toBe("The driver plays a reviewer who had no hand in the change, and approves wave 3 with that reviewer's own signing key.");
     const p = progress([{ number: 2, state: "waiting", roots: ["app"], reads: [], digest: "jcs1-sha256:0accc105ba06" }]);
     const was = globalThis.document;
     globalThis.document = fakeDocument();
@@ -293,7 +293,7 @@ describe("the kiosk for a viewer new to the demo (behold#571)", () => {
       renderKiosk(bar, { demo: { source: "fx", read: "2026-10-15T03:00:00Z", demo: demo("waiting", { next: { action: "approve wave-2", at: null } }) }, answer: null, progress: p }, new Date("2026-10-15T03:01:00Z"));
       const card = find(bar, "k-approve")[0];
       expect(card.children.map((c) => c.className)).toEqual(["k-approve-gloss", "k-command", "k-approve-then"]);
-      expect(card.children[1].textContent).toBe("chant approve tf-apply wave-2 --actor <driver> --sign <driver key>");
+      expect(card.children[1].textContent).toBe("chant approve tf-apply wave-2 --actor <reviewer> --sign <reviewer key>");
     } finally {
       globalThis.document = was;
     }