@intentius/behold 0.29.5 → 0.29.6

package/dist/cli.js

@@ -24215,6 +24215,7 @@ var UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
 var isRecord17 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 var str13 = (v) => typeof v === "string";
 var int = (v) => typeof v === "number" && Number.isInteger(v);
+var positive = (v) => int(v) && v > 0 ? v : null;
 function demoProblem(doc) {
   if (!isRecord17(doc)) return "it is not an object";
   if (!int(doc.cycle)) return "cycle is not an integer";
@@ -24269,7 +24270,11 @@ async function readDemo(source2, now = /* @__PURE__ */ new Date()) {
       next: d.next ? { action: d.next.action, at: d.next.at } : null,
       pull: d.pull,
       commit: d.commit,
-      about: d.about ? { changes: d.about.changes, watch: d.about.watch, shows: d.about.shows } : null
+      about: d.about ? { changes: d.about.changes, watch: d.about.watch, shows: d.about.shows } : null,
+      intro: str13(d.intro) && d.intro.trim() ? d.intro.trim() : null,
+      name: str13(d.name) && d.name.trim() ? d.name.trim() : null,
+      scenarios: positive(d.scenarios),
+      index: positive(d.index)
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/behold",
-  "version": "0.29.5",
+  "version": "0.29.6",
   "license": "Apache-2.0",
   "type": "module",
   "description": "behold — a live control plane on chant. See your whole estate (every substrate in one graph), coloured by drift; act through delegated, gated Ops.",

package/web/app.js

@@ -10,7 +10,7 @@
 // renderPanelView never rewrites, so the select mounts once and survives re-renders).
 import { createRefreshQueue } from "./refresh-queue.js";
 import { readViewQuery, writeViewQuery, settleView, settlePlace, refusalLine } from "./view-url.js";
-import { readEmbed, selectMessage, viewFromMessage } from "./embed.js";
+import { quietCardLines, readEmbed, selectMessage, viewFromMessage } from "./embed.js";
 import { gateCards } from "./workspace-gates.js";
 import { cornerOf, estateLine, hrefOf as tgHref, legend as tgLegend, markLine, rootRows as tgRootRows, waveCards } from "./terragucci.js";
 import { laneElement as tgLane, rootOfCard as tgRootOfCard, historyElement as tgHistoryLane } from "./terragucci-timeline.js";
@@ -3502,7 +3502,7 @@ function drawTgReads() {
   }
   for (const t of svg.querySelectorAll("[data-tg-hid]")) {
     t.removeAttribute("data-tg-hid");
-    t.removeAttribute("visibility");
+    if (!t.hasAttribute("data-kiosk-quiet")) t.removeAttribute("visibility");
   }
   for (const g of svg.querySelectorAll("[data-tg-dim]")) {
     g.removeAttribute("data-tg-dim");
@@ -5329,6 +5329,8 @@ function render(ir, svg, m) {
     svgEl.removeAttribute("width");
     svgEl.removeAttribute("height");
     svgEl.setAttribute("preserveAspectRatio", "xMidYMid meet");
+    // behold#571: the kiosk's frame drops the cards' kind and meta lines.
+    if (embedOpts.bare) quietCardLines(svgEl);
     setupGraphViewBox(svgEl);
     wireEdgeHighlight(svgEl, ir);
     // Mark each wave lane as a GitLab CI stage when the CI projection is loaded

package/web/embed.js

@@ -79,3 +79,23 @@ export function viewFromMessage(event, host) {
   }
   return want;
 }
+
+/**
+ * behold#571: a card's line the kiosk's frame leaves out, for a viewer new to
+ * Terraform: the kind line ("Component · chant", "terraform_data ·
+ * terraform"), and the `archetype:`, `wave:` and `root:` meta lines (the wave
+ * or the root is the box the card sits in). behold's own page keeps them.
+ */
+export function kioskQuietLine(text) {
+  const t = typeof text === "string" ? text.trim() : "";
+  return /^Component\b/.test(t) || /^[\w.-]+ · [\w.-]+$/.test(t) || /^archetype:\s*\S/.test(t) || /^wave:\s*\d+$/.test(t) || /^root:\s*\S+$/.test(t);
+}
+
+/** Hide the kioskQuietLine lines of every card in a drawn graph; marks them so a redraw of the marks leaves them hidden. */
+export function quietCardLines(svg) {
+  for (const t of svg.querySelectorAll("[data-node-id] text")) {
+    if (!kioskQuietLine(t.textContent)) continue;
+    t.setAttribute("visibility", "hidden");
+    t.setAttribute("data-kiosk-quiet", "1");
+  }
+}

package/web/embed.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { readEmbed, selectMessage, viewFromMessage, THEME_ALIASES } from "./embed.js";
+import { kioskQuietLine, readEmbed, selectMessage, viewFromMessage, THEME_ALIASES } from "./embed.js";
 
 describe("readEmbed (#476)", () => {
   it("reads embed, an exact host origin and a theme", () => {
@@ -63,3 +63,12 @@ describe("viewFromMessage focus (#569)", () => {
     expect(viewFromMessage({ origin: host, data: { type: "behold:view", focus: "" } }, host)).toEqual({ focus: null });
   });
 });
+
+describe("kioskQuietLine (behold#571)", () => {
+  it("leaves out a card's kind and meta lines in the kiosk's frame", () => {
+    for (const t of ["Component · chant", "terraform_data · terraform", "archetype: infra", "wave: 2", " root: app "]) expect(kioskQuietLine(t)).toBe(true);
+  });
+  it("keeps the names, the states and the reads", () => {
+    for (const t of ["network", "terraform_data.http_proxy_port", "waiting", "reads network · planned · 1 unknown", "wave 2 · planned", "", null]) expect(kioskQuietLine(t)).toBe(false);
+  });
+});

package/web/kiosk-runs.js

@@ -227,12 +227,88 @@ export function agoWords(at, now = new Date()) {
   return `${Math.floor(s / 86400)} d ago`;
 }
 
-/** "a-output" as the kiosk names scenarios, with the cycle: "A, read through .output · cycle 90". */
-export function placeWords(run, scenarios) {
-  const sc = run.scenario && scenarios && Object.prototype.hasOwnProperty.call(scenarios, run.scenario) ? scenarios[run.scenario].name : run.scenario;
+/**
+ * behold#571: whether a scenario's short label reads as code to someone new
+ * to the demo: a lettered label ("A, read through .output", "B on waves"), a
+ * code token in it, or the bare id ("a-output").
+ */
+export function codeish(label) {
+  return typeof label === "string" && (/^[A-Z]\b/.test(label) || /\.[A-Za-z]|[_`]/.test(label) || /^[a-z0-9]+(?:-[a-z0-9]+)+$/.test(label));
+}
+
+const MERGE_TITLE = /^Merge pull request '(.+)' \(#\d+\)/;
+
+/**
+ * behold#571: each scenario's title in plain words, by id: from the merge
+ * runs' titles (the pull request is titled after its scenario), and from
+ * `known` (the titles demo.json has carried, which win).
+ */
+export function scenarioTitles(runs, known = {}) {
+  const out = {};
+  for (const r of [...(runs || [])].reverse()) {
+    const m = r && r.scenario && typeof r.title === "string" ? MERGE_TITLE.exec(r.title) : null;
+    if (m) out[r.scenario] = m[1];
+  }
+  for (const [id, title] of Object.entries(known || {})) if (typeof title === "string" && title) out[id] = title;
+  return out;
+}
+
+/**
+ * The scenario and the cycle under a run: "a failure mid-apply · cycle 90".
+ * The scenario's name as demo.json last carried it (`names`, terragucci#1050)
+ * comes first, then the kiosk's SCENARIOS label; a label that reads as code
+ * gives way to the scenario's title when one is known (behold#571).
+ */
+export function placeWords(run, scenarios, titles = {}, names = {}) {
+  const own = (m) => !!(run.scenario && m && Object.prototype.hasOwnProperty.call(m, run.scenario));
+  const short = own(names) && names[run.scenario] ? names[run.scenario] : own(scenarios) ? scenarios[run.scenario].name : run.scenario;
+  const title = own(titles) ? titles[run.scenario] : null;
+  const sc = title && (!short || codeish(short)) ? title : short;
   return [sc, run.cycle !== null && run.cycle !== undefined ? `cycle ${run.cycle}` : null].filter(Boolean).join(" · ");
 }
 
+/**
+ * behold#571: a runner's or an action's set-up line, not terragucci's own:
+ * git's hints, the checkout's `[command]` lines and groups, the runner's
+ * docker and fetch lines.
+ */
+export const SETUP_LINES = [
+  /^hint:/,
+  /^\[command\]/,
+  /^##\[(?:group|endgroup)\]/,
+  /^Initialized empty Git repository\b/,
+  /^::(?:add|remove)-matcher\b/,
+  /^\s*❓\s*add-matcher\b/u,
+  /^\s*🐳\s+docker\b/u,
+  /^\s*☁️\s+git fetch\b/u,
+  /^git version \d/,
+  /^Temporarily overriding HOME=/,
+  /^Adding repository directory to the temporary git global config\b/,
+  /^Deleting the contents of '/,
+  /^Syncing repository: /,
+  /^Working directory is '/,
+];
+
+/** Whether a log line is set-up noise (SETUP_LINES). */
+export function setupLine(line) {
+  return typeof line === "string" && SETUP_LINES.some((re) => re.test(line));
+}
+
+/**
+ * behold#571: a step's log as the kiosk draws it. The set-up lines fold into
+ * one row at the top, `{ setup: n }`, so terragucci's own lines come first;
+ * opened (`open`), the row heads the whole log in order. Every line keeps
+ * its number in the log. A log with no set-up lines is drawn as it came.
+ */
+export function logRows(lines, { open = false, from = 0 } = {}) {
+  const all = (lines || []).map((text, i) => ({ n: from + i + 1, text, setup: setupLine(text) }));
+  const n = all.filter((l) => l.setup).length;
+  if (!n) return all.map(({ n: num, text }) => ({ n: num, text }));
+  const head = { setup: n, open };
+  const body = open ? all : all.filter((l) => !l.setup);
+  return [head, ...body.map(({ n: num, text, setup }) => (open && setup ? { n: num, text, quiet: true } : { n: num, text }))];
+}
+
 // ---------------------------------------------------------------------------
 // Drawing.
 
@@ -277,7 +353,7 @@ export function statusIcon(status) {
 }
 
 /** The sidebar: the live run pinned, then the recent ones. `pick(id)` selects one; nothing here writes. */
-export function renderSidebar(host, index, selectedId, { now = new Date(), scenarios = {}, pick = () => {}, merged = null } = {}) {
+export function renderSidebar(host, index, selectedId, { now = new Date(), scenarios = {}, titles = {}, names = {}, pick = () => {}, merged = null } = {}) {
   host.replaceChildren();
   const head = el("div", "r-side-head");
   head.appendChild(el("div", "r-side-title", "Pipeline runs"));
@@ -290,6 +366,7 @@ export function renderSidebar(host, index, selectedId, { now = new Date(), scena
   // The selected run as its page draws it, when its own document is newer than the index.
   const runs = sidebarRuns(index.doc.runs).map((r) => (merged && merged.id === r.id ? merged : r));
   const live = runs[0];
+  const named = scenarioTitles(index.doc.runs, titles);
   const list = el("ol", "r-runs");
   runs.forEach((r, i) => {
     if (i === 0) list.appendChild(el("li", "r-group", LIVE.has(live.status) ? "Live" : "Latest"));
@@ -300,7 +377,7 @@ export function renderSidebar(host, index, selectedId, { now = new Date(), scena
     li.appendChild(statusIcon(r.status));
     const body = el("div", "r-run-body");
     body.appendChild(el("div", "r-run-title", triggerWords(r)));
-    const place = placeWords(r, scenarios);
+    const place = placeWords(r, scenarios, named, names);
     if (place) body.appendChild(el("div", "r-run-place", place));
     const meta = el("div", "r-run-meta");
     meta.append(
@@ -328,7 +405,7 @@ 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 = () => {}, entry = null } = {}) {
+export function renderRun(host, answer, ui, { now = new Date(), pickJob = () => {}, toggleStep = () => {}, toggleSetup = () => {}, entry = null } = {}) {
   host.replaceChildren();
   if (!answer || answer.error || answer.absent || !answer.doc) {
     host.appendChild(el("p", "r-note", answer ? answer.absent || answer.error : "Reading the run…"));
@@ -398,12 +475,25 @@ export function renderRun(host, answer, ui, { now = new Date(), pickJob = () =>
     if (i === open) {
       const pre = el("pre", "r-log");
       if (s.truncated) pre.appendChild(el("div", "r-log-cut", `… ${s.truncated} earlier lines not kept`));
-      s.log.forEach((l, n) => {
-        const ln = el("div", "r-log-line");
-        const shown = logLineWords(job.status, l);
-        ln.append(el("span", "r-ln", String((s.truncated || 0) + n + 1)), el("span", shown.held ? "r-lt r-wait" : "r-lt", shown.text));
+      const key = logKey(run.id, job.name, i);
+      for (const row of logRows(s.log, { open: ui.setup === key, from: s.truncated || 0 })) {
+        if (row.setup) {
+          const fold = el("div", `r-log-setup${row.open ? " r-log-setup-open" : ""}`, `${row.open ? "▾" : "▸"} setup (${row.setup} line${row.setup === 1 ? "" : "s"})`);
+          fold.setAttribute("role", "button");
+          fold.tabIndex = 0;
+          fold.setAttribute("aria-expanded", String(row.open));
+          fold.addEventListener("click", () => toggleSetup(key));
+          fold.addEventListener("keydown", (e) => {
+            if (e.key === "Enter" || e.key === " ") toggleSetup(key);
+          });
+          pre.appendChild(fold);
+          continue;
+        }
+        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));
         pre.appendChild(ln);
-      });
+      }
       if (!s.log.length) pre.appendChild(el("div", "r-log-cut", s.status === "running" ? "waiting for output…" : "no output"));
       if (s.status === "running") pre.appendChild(el("div", "r-log-live", "▍"));
       row.appendChild(pre);
@@ -447,8 +537,8 @@ 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 = {}, onLive = () => {} } = {}) {
-  const s = { index: null, run: null, selected: null, picked: 0, ui: { job: null, open: null } };
+export function startRuns({ side, main }, { fetchJson, now = () => new Date(), scenarios = {}, titles = () => ({}), names = () => ({}), onLive = () => {} } = {}) {
+  const s = { index: null, run: null, selected: null, picked: 0, ui: { job: null, open: null, setup: null } };
   let follow = true;
   let lastRunKey = "";
   // The open log and whether the pane follows its end; a viewer who scrolls up stops it until they come back.
@@ -470,7 +560,7 @@ export function startRuns({ side, main }, { fetchJson, now = () => new Date(), s
     const ans = s.run && (!s.run.doc || s.run.doc.id === id) ? s.run : null;
     // One merged read of the selected run for both the sidebar and its page.
     const merged = ans && ans.doc ? mergeRun(entry, ans.doc) : null;
-    renderSidebar(side, s.index, id, { now: now(), scenarios, pick, merged });
+    renderSidebar(side, s.index, id, { now: now(), scenarios, titles: titles(), names: names(), pick, merged });
     // The redraw replaces the scrollers: keep where a viewer left them.
     const old = main.querySelector(".r-log");
     const oldSteps = main.querySelector(".r-steps");
@@ -480,12 +570,17 @@ export function startRuns({ side, main }, { fetchJson, now = () => new Date(), s
       now: now(),
       entry,
       pickJob: (name) => {
-        s.ui = { job: name, open: null };
+        s.ui = { job: name, open: null, setup: null };
         hold();
         draw();
       },
       toggleStep: (job, i) => {
-        s.ui = { job, open: i };
+        s.ui = { job, open: i, setup: null };
+        hold();
+        draw();
+      },
+      toggleSetup: (key) => {
+        s.ui = { ...s.ui, setup: s.ui.setup === key ? null : key };
         hold();
         draw();
       },
@@ -528,7 +623,7 @@ export function startRuns({ side, main }, { fetchJson, now = () => new Date(), s
     s.selected = id;
     follow = false;
     s.picked = now().getTime();
-    s.ui = { job: null, open: null };
+    s.ui = { job: null, open: null, setup: null };
     void readRun();
   };
   const readIndex = async () => {
@@ -545,7 +640,7 @@ export function startRuns({ side, main }, { fetchJson, now = () => new Date(), s
     // A run that ended reads once; one still going reads on every tick.
     const key = `${id}|${entry ? entry.status : ""}|${entry ? entry.ended_at : ""}`;
     if (key === lastRunKey && entry && !LIVE.has(entry.status) && s.run && s.run.doc && s.run.doc.id === id) return draw();
-    if (s.run && s.run.doc && s.run.doc.id !== id) s.ui = { job: null, open: null };
+    if (s.run && s.run.doc && s.run.doc.id !== id) s.ui = { job: null, open: null, setup: null };
     lastRunKey = key;
     s.run = await fetchJson(`/api/terragucci/runs/${id}`);
     draw();

package/web/kiosk-runs.test.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
-import { FOLLOW_LINES, followsLog, logKey, nearEnd, mergeRun, newerOf, agoWords, defaultJob, defaultStep, durationWords, jobOrder, liveRun, logLineWords, placeWords, sidebarRuns, splitSkipped, STATUS_TONE, triggerWords } from "./kiosk-runs.js";
+import { FOLLOW_LINES, followsLog, logKey, nearEnd, mergeRun, newerOf, agoWords, defaultJob, defaultStep, durationWords, jobOrder, liveRun, codeish, logLineWords, logRows, placeWords, scenarioTitles, setupLine, sidebarRuns, splitSkipped, STATUS_TONE, triggerWords } from "./kiosk-runs.js";
 
 const FIX = join(import.meta.dirname, "..", "src", "__fixtures__", "terragucci-demo", "runs");
 const run = (id) => JSON.parse(readFileSync(join(FIX, `${id}.json`), "utf8"));
@@ -131,3 +131,55 @@ describe("the log pane follows its end, like a CI page's log", () => {
     expect(nearEnd({ scrollTop: 0, clientHeight: 400, scrollHeight: 1000 }, slack)).toBe(false);
   });
 });
+
+describe("the runs for a viewer new to the demo (behold#571)", () => {
+  const SC = { "a-output": { name: "A, read through .output" }, "b-waves": { name: "B on waves" }, failure: { name: "a failure mid-apply" } };
+  it("prefers the scenario's title when its short label reads as code", () => {
+    expect(codeish("A, read through .output")).toBe(true);
+    expect(codeish("B on waves")).toBe(true);
+    expect(codeish("a-output")).toBe(true);
+    expect(codeish("a failure mid-apply")).toBe(false);
+    expect(codeish("the base")).toBe(false);
+    const titles = { "a-output": "The same change, read once it is built", failure: "One root fails partway" };
+    expect(placeWords({ scenario: "a-output", cycle: 90 }, SC, titles)).toBe("The same change, read once it is built · cycle 90");
+    expect(placeWords({ scenario: "failure", cycle: 92 }, SC, titles)).toBe("a failure mid-apply · cycle 92");
+    expect(placeWords({ scenario: "b-waves", cycle: 91 }, SC, titles)).toBe("B on waves · cycle 91");
+    expect(placeWords({ scenario: "c-new", cycle: 93 }, SC, { "c-new": "A new one" })).toBe("A new one · cycle 93");
+    expect(placeWords({ scenario: "a-output", cycle: 90 }, SC)).toBe("A, read through .output · cycle 90");
+  });
+  it("takes demo.json's name for a scenario before the table's label (terragucci#1050)", () => {
+    const names = { "b-waves": "a new subnet", failure: "a failure halfway" };
+    expect(placeWords({ scenario: "b-waves", cycle: 12 }, SC, {}, names)).toBe("a new subnet · cycle 12");
+    expect(placeWords({ scenario: "failure", cycle: 12 }, SC, { failure: "One root fails" }, names)).toBe("a failure halfway · cycle 12");
+    expect(placeWords({ scenario: "a-output", cycle: 12 }, SC, {}, names)).toBe("A, read through .output · cycle 12");
+  });
+  it("learns titles from the merge runs, and demo.json's win", () => {
+    const runs = index().runs;
+    const t = scenarioTitles(runs);
+    expect(t["a-known"]).toBe("A port change, known when it plans");
+    expect(scenarioTitles(runs, { "a-known": "A plain title" })["a-known"]).toBe("A plain title");
+    expect(scenarioTitles([], {})).toEqual({});
+  });
+  it("knows the runner's set-up lines from terragucci's own", () => {
+    for (const l of ["hint: Using 'master' as the name", "[command]/usr/bin/git init /workspace/demo", "##[group]Initializing the repository", "##[endgroup]", "Initialized empty Git repository in /workspace/demo/.git/"]) expect(setupLine(l)).toBe(true);
+    for (const l of ["wave 2 of 3: planning app", "app: Plan: 0 to add, 1 to change, 0 to destroy.", "  terragucci approve wave-2 --plan jcs1-sha256:0a", "⚙️ [runner]: exitcode '3': failure"]) expect(setupLine(l)).toBe(false);
+  });
+  it("folds the set-up lines into one row at the top, and opens it in order", () => {
+    const log = ["##[group]Init", "[command]/usr/bin/git init", "wave 1 of 3: planning network", "hint: x", "##[endgroup]", "wave 1 of 3: applied"];
+    expect(logRows(log)).toEqual([{ setup: 4, open: false }, { n: 3, text: "wave 1 of 3: planning network" }, { n: 6, text: "wave 1 of 3: applied" }]);
+    const open = logRows(log, { open: true });
+    expect(open[0]).toEqual({ setup: 4, open: true });
+    expect(open.slice(1).map((r) => r.n)).toEqual([1, 2, 3, 4, 5, 6]);
+    expect(open.filter((r) => r.quiet).map((r) => r.n)).toEqual([1, 2, 4, 5]);
+    expect(logRows(["a", "b"], { from: 10 })).toEqual([{ n: 11, text: "a" }, { n: 12, text: "b" }]);
+  });
+  it("folds the checkout's set-up in a real held job's log, and leaves terragucci's step as it came", () => {
+    const job = run(444).jobs.find((j) => j.status === "waiting");
+    const checkout = job.steps.find((s) => s.name.includes("checkout") && !s.name.startsWith("Post"));
+    const rows = logRows(checkout.log);
+    expect(rows[0].setup).toBeGreaterThan(40);
+    expect(rows.slice(1).some((r) => /^hint:|^\[command\]|^##\[/.test(r.text))).toBe(false);
+    const own = job.steps.find((s) => /^Apply wave/.test(s.name));
+    expect(logRows(own.log)).toEqual(own.log.map((text, i) => ({ n: i + 1, text })));
+  });
+});

package/web/kiosk.html

@@ -74,30 +74,36 @@
         white-space: pre-wrap; overflow-wrap: anywhere; overflow-y: auto; max-height: 52vh; min-height: 6em; }
       .r-log-line { display: grid; grid-template-columns: 3.2em 1fr; gap: 0.8em; padding: 0 0.8em 0 0; }
       .r-ln { color: var(--muted); text-align: right; user-select: none; opacity: 0.7; }
+      /* behold#571: the runner's set-up lines, folded into one row so terragucci's own lines come first. */
+      .r-log-setup { color: var(--muted); padding: 0 0.8em 0.2em 4em; cursor: pointer; user-select: none; }
+      .r-log-setup:hover { color: var(--fg); }
+      .r-log-quiet .r-lt { color: var(--muted); }
       .r-log-cut { color: var(--muted); padding: 0 0.8em 0.2em 4em; font-style: italic; }
       .r-log-live { color: var(--foreign); padding-left: 4em; }
       @media (prefers-reduced-motion: no-preference) { .r-log-live { animation: r-blink 1s steps(2) infinite; } }
       @keyframes r-blink { 50% { opacity: 0; } }
       .r-note { color: var(--muted); padding: 0 1em; font-size: 0.88em; }
-      #bar { display: grid; grid-template-columns: minmax(0, 1.25fr) minmax(0, 1fr); gap: 1.6em; align-items: start;
-        padding: 0.7em 1.4em 0.7em; background: var(--panel); border-bottom: 1px solid var(--rule); }
+      #bar { display: grid; grid-template-columns: minmax(0, 1.25fr) minmax(0, 1fr); gap: 0.45em 1.6em; align-items: start;
+        padding: 0.55em 1.4em 0.6em; background: var(--panel); border-bottom: 1px solid var(--rule); }
       #bar > .k-empty { grid-column: 1 / -1; }
-      .k-kicker { display: flex; gap: 1.2em; font: 600 0.78em var(--font-mono); text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted); }
-      .k-cycle { text-transform: none; letter-spacing: 0; font-weight: 400; }
-      .k-title { margin: 0.05em 0 0.25em; font-size: 1.45em; line-height: 1.15; }
+      /* behold#571: the problem the demo solves, always on, across the bar's top. */
+      .k-intro { grid-column: 1 / -1; margin: 0; font-size: 1em; line-height: 1.35; color: var(--fg); }
+      .k-kicker { font: 600 0.58em var(--font-mono); text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted); margin-right: 0.9em; vertical-align: 0.2em; white-space: nowrap; }
+      .k-cycle { color: var(--muted); font: 0.78em var(--font-mono); white-space: nowrap; }
+      .k-title { margin: 0 0 0.2em; font-size: 1.35em; line-height: 1.2; }
       /* behold#571: the scenario's card, three labelled rows under the title. */
-      .k-about { display: grid; grid-template-columns: max-content minmax(0, 1fr); gap: 0.12em 0.9em; align-items: baseline; margin: 0 0 0.45em; font-size: 0.9em; line-height: 1.3; }
+      .k-about { display: grid; grid-template-columns: max-content minmax(0, 1fr); gap: 0.08em 0.9em; align-items: baseline; margin: 0 0 0.35em; font-size: 0.88em; line-height: 1.25; }
       .k-about-label { font: 600 0.74em var(--font-mono); text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted); }
       .k-about-text { margin: 0; color: var(--fg); }
       .k-muted { color: var(--muted); margin: 0.25em 0; }
-      .k-step { border-left: 4px solid var(--pending); padding: 0.1em 0 0.1em 0.8em; }
-      .k-step-word { font: 600 0.75em var(--font-mono); text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted); }
-      .k-label { font-size: 1.02em; margin: 0.1em 0 0; }
+      .k-step { border-left: 4px solid var(--pending); padding: 0.1em 0 0.1em 0.8em; margin: 0; font-size: 0.95em; line-height: 1.3; }
+      .k-step-word { font: 600 0.72em var(--font-mono); text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted); margin-right: 0.7em; }
       .k-step-waiting { border-left-color: var(--foreign); }
       .k-step-failed, .k-step-stalled { border-left-color: var(--degraded); }
       .k-step-applied { border-left-color: var(--managed); }
       .k-step-reset { border-left-color: var(--neutral); }
-      .k-right { display: grid; gap: 0.6em; align-content: start; }
+      .k-right { display: grid; gap: 0.45em; align-content: start; }
+      .k-where { display: flex; flex-wrap: wrap; gap: 0.35em 1em; align-items: center; }
       .k-strip { list-style: none; display: flex; flex-wrap: wrap; gap: 0.35em; padding: 0; margin: 0; }
       .k-stop { font: 0.82em var(--font-mono); padding: 0.25em 0.7em; border-radius: 999px; border: 1px solid var(--rule); color: var(--muted); }
       .k-done { color: var(--fg); border-color: var(--managed); }
@@ -109,7 +115,8 @@
       .k-when { color: var(--foreign); font-family: var(--font-mono); }
       .k-approve { border-left: 4px solid var(--foreign); padding-left: 0.8em; }
       .k-approve p { margin: 0.15em 0; }
-      .k-approve-head, .k-approve-then { color: var(--muted); font-size: 0.92em; }
+      .k-approve-gloss { color: var(--fg); font-size: 0.92em; }
+      .k-approve-then { color: var(--muted); font-size: 0.92em; }
       .k-command { display: block; margin: 0.25em 0; padding: 0.45em 0.7em; background: var(--well); border-radius: 6px; font: 0.88em var(--font-mono); overflow-wrap: anywhere; user-select: none; }
       .k-inline { font-family: var(--font-mono); color: var(--fg); background: var(--well); padding: 0.05em 0.35em; border-radius: 4px; user-select: none; }
       .k-note { color: var(--muted); margin: 0; font-size: 0.92em; }
@@ -129,7 +136,6 @@
       #foot { display: flex; flex-wrap: wrap; gap: 0.2em 1.6em; padding: 0.55em 1.6em; border-top: 1px solid var(--rule); background: var(--panel); font-size: 0.85em; }
       .k-legend { color: var(--muted); flex-basis: 100%; }
       .k-fact { color: var(--fg); }
-      .k-source { color: var(--muted); margin-left: auto; }
       @media (max-width: 900px) { #bar { grid-template-columns: 1fr; } #stage { grid-template-columns: 1fr; } }
     </style>
   </head>

package/web/kiosk.js

@@ -51,12 +51,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). */
@@ -226,6 +252,16 @@ 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
+ * 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.`;
+}
+
 /**
  * #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
@@ -435,27 +471,31 @@ 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));
     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), el("span", "k-label", demo.label));
   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");
@@ -467,13 +507,7 @@ export function renderKiosk(bar, s, now = new Date(), foot = null) {
   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(el("p", "k-approve-gloss", approveGloss(appr)));
     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.`);
@@ -488,18 +522,11 @@ export function renderKiosk(bar, s, now = new Date(), foot = null) {
 
   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));
-    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`),
-    );
   }
 }
 
-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`;
-};
-
 /** How often the kiosk asks for demo.json. The server shares one read between kiosks. */
 export const DEMO_POLL_MS = 3_000;
 
@@ -539,7 +566,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 });
   // #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;
@@ -577,6 +607,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 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.");
+    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 <driver> --sign <driver key>");
+    } finally {
+      globalThis.document = was;
+    }
+  });
+});