@intentius/behold 0.29.5 → 0.29.7

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. */
@@ -51,12 +52,38 @@ export const STEP_WORDS = {
   stalled: "stalled",
 };
 
-/** "Scenario 3 of 6 · B on waves", or the driver's title alone for an id behold doesn't know. */
+const counted = (n) => Number.isInteger(n) && n > 0;
+
+/** demo.json's `name`, the scenario's short label in plain words (terragucci#1050); null without one. */
+export function scenarioName(demo) {
+  const n = demo && demo.name;
+  return typeof n === "string" && n.trim() ? n.trim() : null;
+}
+
+/**
+ * The kicker and the title over the card. behold#571: "Scenario 2 of 5" when
+ * demo.json counts the loop (`index` of `scenarios`), "Scenario 2" with the
+ * index alone, with the title in plain words. Without an index, today's
+ * kicker: "scenario 3 · B on waves" from SCENARIOS, demo.json's `name` in
+ * place of SCENARIOS' label when it has one; the driver's title alone for an
+ * id behold doesn't know.
+ */
 export function scenarioHead(demo) {
   const known = Object.prototype.hasOwnProperty.call(SCENARIOS, demo.scenario) ? SCENARIOS[demo.scenario] : null;
-  if (!known) return { kicker: `scenario ${demo.scenario}`, title: demo.title };
-  if (known.n === null) return { kicker: demo.title || "The base", title: demo.title || "The base" };
-  return { kicker: `scenario ${known.n} · ${known.name}`, title: demo.title };
+  const name = scenarioName(demo);
+  if (counted(demo.index)) {
+    const of = counted(demo.scenarios) && demo.index <= demo.scenarios ? ` of ${demo.scenarios}` : "";
+    return { kicker: `Scenario ${demo.index}${of}`, title: demo.title || name || (known ? known.name : demo.scenario) };
+  }
+  if (!known) return { kicker: name ? `scenario · ${name}` : `scenario ${demo.scenario}`, title: demo.title };
+  if (known.n === null) return { kicker: demo.title || name || "The base", title: demo.title || name || "The base" };
+  return { kicker: `scenario ${known.n} · ${name || known.name}`, title: demo.title };
+}
+
+/** behold#571: demo.json's `intro`, one paragraph on the problem the demo solves; null without one. */
+export function introText(demo) {
+  const t = demo && demo.intro;
+  return typeof t === "string" && t.trim() ? t.trim() : null;
 }
 
 /** The card's rows under the title, in order, with the labels the kiosk draws (behold#571). */
@@ -192,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",
   };
@@ -226,6 +256,17 @@ 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 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 plays a reviewer who had no hand in the change, and approves wave ${appr.wave}${roots} with that reviewer's own signing key.`;
+}
+
 /**
  * #569: the roots the step is about, for the framed view to bring forward:
  * the pull request's roots while it is planned; from the merge on, the wave
@@ -421,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();
@@ -435,45 +485,43 @@ export function renderKiosk(bar, s, now = new Date(), foot = null) {
   const demo = s.demo.demo;
   const head = scenarioHead(demo);
 
+  const intro = introText(demo);
+  if (intro) bar.appendChild(el("p", "k-intro", intro));
+
+  // behold#571: the kicker on the title's line, so the bar has room for the intro.
   const left = el("div", "k-left");
-  const kick = el("div", "k-kicker");
-  kick.append(el("span", null, head.kicker), el("span", "k-cycle", cycleWords(demo, now)));
-  left.appendChild(kick);
-  left.appendChild(el("h1", "k-title", head.title));
+  const title = el("h1", "k-title");
+  title.append(el("span", "k-kicker", head.kicker), el("span", "k-title-text", head.title));
+  left.appendChild(title);
   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("div", `k-step k-step-${demo.step}`);
-  said.appendChild(el("span", "k-step-word", STEP_WORDS[demo.step] || demo.step));
-  said.appendChild(el("p", "k-label", demo.label));
+  const said = el("p", `k-step k-step-${demo.step}`);
+  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);
 
   const right = el("div", "k-right");
   const strip = el("ol", "k-strip");
   for (const stop of stripStops(demo.step)) strip.appendChild(el("li", `k-stop k-${stop.state}`, stop.words));
-  right.appendChild(strip);
+  const where = el("div", "k-where");
+  where.append(strip, el("span", "k-cycle", cycleWords(demo, now)));
+  right.appendChild(where);
 
   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-head",
-        `The driver approves wave ${appr.wave}${appr.roots.length ? ` (${appr.roots.join(", ")})` : ""}, signed with its own key${appr.digest ? `, for the plan ${appr.digest.replace(/^jcs1-sha256:/, "").slice(0, 12)}` : ""}:`,
-      ),
-    );
+    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.`);
@@ -481,24 +529,21 @@ 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")));
-    for (const f of factLines(demo, s.answer)) foot.appendChild(el("span", "k-fact", f));
-    foot.appendChild(
-      el("span", "k-source", `narration read ${clockOf(s.demo.read)} from ${s.demo.source}${demo.pull !== null ? ` · pull request #${demo.pull}` : ""}${demo.commit ? ` · commit ${demo.commit.slice(0, 8)}` : ""} · nothing here writes`),
-    );
+    // 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(elRoots("span", "k-fact", f, s));
   }
 }
 
-const clockOf = (iso) => {
-  const d = new Date(iso);
-  return Number.isNaN(d.getTime()) ? iso : `${String(d.getUTCHours()).padStart(2, "0")}:${String(d.getUTCMinutes()).padStart(2, "0")}:${String(d.getUTCSeconds()).padStart(2, "0")} UTC`;
-};
+/** 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;
@@ -511,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() });
@@ -531,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);
@@ -539,7 +636,10 @@ export function startKiosk({ bar, frame, foot, side, main, views }, { fetchJson
     tellFrame(false);
   };
   // #569: the pipeline's runs beside the view, CI-page style.
-  if (side && main) startRuns({ side, main }, { fetchJson, now, scenarios: SCENARIOS });
+  // 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, 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;
@@ -551,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();
   });
@@ -577,6 +682,8 @@ export function startKiosk({ bar, frame, foot, side, main, views }, { fetchJson
   const demo = async () => {
     s.demo = await fetchJson("/api/terragucci/demo");
     const d = s.demo && s.demo.demo;
+    if (d && d.scenario && typeof d.title === "string" && d.title) titles[d.scenario] = d.title;
+    if (d && d.scenario && scenarioName(d)) names[d.scenario] = scenarioName(d);
     const key = d ? `${d.cycle}|${d.step}|${d.commit}|${d.pull}` : "";
     if (key !== lastKey) {
       lastKey = key;

package/web/kiosk.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { STEP_VIEW, STEP_WORDS, aboutRows, focusRoots, frameSrc, factLines, kioskView, legendWords, matchingPull, pendingApproval, renderKiosk, renderViewToggle, runPanel, runPin, stepView, viewZoom } from "./kiosk.js";
+import { STEP_VIEW, STEP_WORDS, aboutRows, approveGloss, focusRoots, introText, scenarioHead, frameSrc, factLines, kioskView, legendWords, matchingPull, pendingApproval, renderKiosk, renderViewToggle, runPanel, runPin, stepView, viewZoom } from "./kiosk.js";
 import { PICK_HOLD_MS } from "./kiosk-runs.js";
 
 const demo = (step, extra = {}) => ({ cycle: 1, scenario: "a-output", title: "t", step, label: "", started_at: "2026-10-15T03:00:00Z", next: null, pull: 7, commit: "abc12345", ...extra });
@@ -220,3 +220,82 @@ describe("which view the frame shows (#571)", () => {
     }
   });
 });
+
+describe("the kiosk for a viewer new to the demo (behold#571)", () => {
+  const intro = "One change can touch many Terraform states; this demo shows how terragucci applies them in order.";
+  const fakeDocument = () => {
+    const make = (tag) => {
+      const n = { tagName: tag, className: "", textContent: "", children: [] };
+      n.appendChild = (c) => (n.children.push(c), c);
+      n.append = (...cs) => cs.forEach((c) => n.children.push(typeof c === "string" ? { tagName: "#text", textContent: c, children: [] } : c));
+      n.replaceChildren = () => (n.children = []);
+      return n;
+    };
+    return { createElement: make };
+  };
+  const find = (n, cls) => (n.className.split(" ").includes(cls) ? [n] : []).concat(...(n.children || []).map((c) => (c.className !== undefined ? find(c, cls) : [])));
+  const draw = (d) => {
+    const was = globalThis.document;
+    globalThis.document = fakeDocument();
+    try {
+      const bar = document.createElement("header");
+      const foot = document.createElement("footer");
+      renderKiosk(bar, { demo: { source: "s3://demo-reports/demo", read: "2026-10-15T03:00:00Z", demo: d }, answer: null, progress: null }, new Date("2026-10-15T03:01:00Z"), foot);
+      return { bar, foot };
+    } finally {
+      globalThis.document = was;
+    }
+  };
+
+  it("shows the intro first in the bar, and none without one", () => {
+    const { bar } = draw(demo("planned", { intro }));
+    expect(bar.children[0].className).toBe("k-intro");
+    expect(bar.children[0].textContent).toBe(intro);
+    expect(find(draw(demo("planned")).bar, "k-intro")).toEqual([]);
+    expect(find(draw(demo("planned", { intro: null })).bar, "k-intro")).toEqual([]);
+    expect(introText(demo("planned", { intro: "   " }))).toBe(null);
+  });
+
+  it("says which scenario of how many, with the title and no short label", () => {
+    expect(scenarioHead(demo("planned", { index: 2, scenarios: 5, title: "The same change, read once it is built" }))).toEqual({ kicker: "Scenario 2 of 5", title: "The same change, read once it is built" });
+    const { bar } = draw(demo("planned", { index: 2, scenarios: 5, title: "The same change, read once it is built" }));
+    expect(find(bar, "k-kicker")[0].textContent).toBe("Scenario 2 of 5");
+    expect(find(bar, "k-title-text")[0].textContent).toBe("The same change, read once it is built");
+  });
+
+  it("leaves the count out when scenarios is missing, 0 or less than the index", () => {
+    expect(scenarioHead(demo("planned", { index: 2, title: "t" })).kicker).toBe("Scenario 2");
+    expect(scenarioHead(demo("planned", { index: 2, scenarios: 0, title: "t" })).kicker).toBe("Scenario 2");
+    expect(scenarioHead(demo("planned", { index: 6, scenarios: 5, title: "t" })).kicker).toBe("Scenario 6");
+  });
+
+  it("falls back to the short label without an index, demo.json's name before the table's", () => {
+    expect(scenarioHead(demo("planned", { title: "t" }))).toEqual({ kicker: "scenario 2 · A, read through .output", title: "t" });
+    expect(scenarioHead(demo("planned", { index: 0, scenarios: 5 })).kicker).toBe("scenario 2 · A, read through .output");
+    expect(scenarioHead(demo("planned", { index: null, scenarios: 0, name: "the same change, read late" })).kicker).toBe("scenario 2 · the same change, read late");
+    expect(scenarioHead(demo("reset", { scenario: "base", title: "The base", index: null, scenarios: 0, name: null }))).toEqual({ kicker: "The base", title: "The base" });
+    expect(scenarioHead(demo("planned", { scenario: "new-one", title: "A new one" }))).toEqual({ kicker: "scenario new-one", title: "A new one" });
+  });
+
+  it("has no line on where the narration was read from", () => {
+    const { foot } = draw(demo("planned", { intro }));
+    expect(JSON.stringify(foot)).not.toMatch(/narration read|s3:\/\/|nothing here writes/);
+  });
+
+  it("says who the driver is before the command it runs", () => {
+    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();
+    try {
+      const bar = document.createElement("header");
+      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 <reviewer> --sign <reviewer key>");
+    } finally {
+      globalThis.document = was;
+    }
+  });
+});