@intentius/behold 0.29.7 → 0.29.9

package/web/kiosk-vendor.test.js

@@ -0,0 +1,281 @@
+// behold#571: the per-tool pages' pure parts: live or replay, the replay's pace, the runs kept, and the branding.
+import { describe, expect, it } from "vitest";
+import { VENDOR_TOOLS } from "../src/terragucci-demo.ts";
+import { logRows } from "./kiosk-runs.js";
+import { NO_GRAPH_WORDS, SCENARIOS, legendWords, scenarioHead } from "./kiosk.js";
+import {
+  REPLAY_LAST_HOLD_MS,
+  RUNS_WITH,
+  VENDORS,
+  creditLines,
+  demoTool,
+  filterIndex,
+  keepRun,
+  liveEstimate,
+  liveFor,
+  linkSegments,
+  namesOther,
+  notRunRepo,
+  notRunWords,
+  otherTerms,
+  replayAt,
+  replayBanner,
+  replayIndex,
+  rootWord,
+  runAsOf,
+  scrubDemo,
+  servesRepo,
+  stepDurations,
+  toolCheckout,
+} from "./kiosk-vendor.js";
+
+const demo = (extra = {}) => ({ cycle: 3, scenario: "b-waves", title: "A new subnet", step: "waiting", label: "Wave 2 waits", started_at: "2026-10-20T10:00:00Z", next: { action: "approve wave-2", at: null }, pull: 41, commit: "abc", about: null, intro: null, name: "a new subnet", scenarios: 3, index: 2, ...extra });
+
+describe("which tool a page is live for (behold#571)", () => {
+  it("is demo.json's tool, and Terraform's for a driver before it that ran a scenario the kiosk knows", () => {
+    expect(demoTool(demo({ tool: "terragrunt" }), SCENARIOS)).toBe("terragrunt");
+    expect(demoTool(demo(), SCENARIOS)).toBe("terraform");
+    expect(demoTool(demo({ scenario: "tg-new" }), SCENARIOS)).toBe(null);
+  });
+  it("is live only for the tool whose scenario runs, never on the base", () => {
+    expect(liveFor(demo({ tool: "terragrunt" }), "terragrunt", SCENARIOS)).toBe(true);
+    expect(liveFor(demo({ tool: "terragrunt" }), "terraform", SCENARIOS)).toBe(false);
+    expect(liveFor(demo({ tool: "terraform", scenario: "base" }), "terraform", SCENARIOS)).toBe(false);
+    expect(liveFor(null, "terraform", SCENARIOS)).toBe(false);
+  });
+});
+
+describe("the runs a tool's page keeps (behold#571)", () => {
+  const index = { doc: { schema: "demo.runs/v1", runs: [{ id: 3, repo: "admin/demo-terragrunt", tool: "terragrunt" }, { id: 2, repo: "admin/demo", tool: "terraform" }, { id: 1, tool: "terragrunt" }, { id: 0 }] } };
+  it("keeps the repo's runs, a run's tool without a repo, and a run with neither on Terraform's page alone", () => {
+    expect(filterIndex(index, { tool: "terragrunt", repo: "admin/demo-terragrunt" }).doc.runs.map((r) => r.id)).toEqual([3, 1]);
+    expect(filterIndex(index, { tool: "terraform", repo: "admin/demo" }).doc.runs.map((r) => r.id)).toEqual([2, 0]);
+    expect(keepRun({ id: 9, repo: "admin/demo" }, { tool: "terraform", repo: null })).toBe(false);
+  });
+  it("leaves an answer that is no index as it came", () => {
+    const absent = { doc: null, absent: "no runs" };
+    expect(filterIndex(absent, { tool: "terraform", repo: "x" })).toBe(absent);
+  });
+  it("shows the graph only for the repo this behold serves", () => {
+    expect(servesRepo("forgejo:3000/admin/demo", "admin/demo")).toBe(true);
+    expect(servesRepo("forgejo:3000/admin/demo", "admin/demo-terragrunt")).toBe(false);
+    expect(servesRepo("forgejo:3000/xadmin/demo", "admin/demo")).toBe(false);
+    expect(servesRepo(null, "admin/demo")).toBe(false);
+  });
+});
+
+describe("the replay's pace (behold#571)", () => {
+  const steps = [
+    { step: "pull-request", at: "2026-10-20T10:00:00Z" },
+    { step: "planned", at: "2026-10-20T10:00:40Z" },
+    { step: "merged", at: "2026-10-20T10:01:30Z" },
+    { step: "reset", at: "2026-10-20T10:03:00Z" },
+  ];
+  it("holds each step as long as it was recorded, and the last for the driver's hold", () => {
+    expect(stepDurations(steps)).toEqual([40_000, 50_000, 90_000, REPLAY_LAST_HOLD_MS]);
+  });
+  it("steps through at that pace, standing for the step's time plus the time into it, and loops", () => {
+    expect(replayAt(steps, 0).index).toBe(0);
+    expect(replayAt(steps, 39_999).index).toBe(0);
+    const p = replayAt(steps, 45_000);
+    expect(p.index).toBe(1);
+    expect(p.at.toISOString()).toBe("2026-10-20T10:00:45.000Z");
+    expect(replayAt(steps, 180_000).index).toBe(3);
+    const loop = 180_000 + REPLAY_LAST_HOLD_MS;
+    expect(replayAt(steps, 0).loop).toBe(loop);
+    expect(replayAt(steps, loop + 45_000).index).toBe(1);
+  });
+});
+
+describe("a run as it stood in the replay (behold#571)", () => {
+  const run = {
+    id: 7,
+    status: "success",
+    created_at: "2026-10-20T10:00:00Z",
+    started_at: "2026-10-20T10:00:00Z",
+    ended_at: "2026-10-20T10:01:40Z",
+    jobs: [
+      { id: 1, name: "plan", needs: [], status: "success", started_at: "2026-10-20T10:00:00Z", ended_at: "2026-10-20T10:01:40Z", steps: [{ name: "Plan", status: "success", started_at: "2026-10-20T10:00:00Z", ended_at: "2026-10-20T10:01:40Z", log: ["1", "2", "3", "4"] }] },
+      { id: 2, name: "fmt", needs: [], status: "skipped", started_at: null, ended_at: null, steps: [] },
+    ],
+  };
+  const t = (iso) => Date.parse(iso);
+  it("is queued before it started, running until it ended with its log so far, then as it ended", () => {
+    expect(runAsOf(run, t("2026-10-20T09:59:00Z")).jobs[0].status).toBe("queued");
+    const mid = runAsOf(run, t("2026-10-20T10:00:50Z"));
+    expect([mid.status, mid.ended_at, mid.jobs[0].status, mid.jobs[0].steps[0].log]).toEqual(["running", null, "running", ["1", "2"]]);
+    expect(mid.jobs[1].status).toBe("skipped");
+    const end = runAsOf(run, t("2026-10-20T10:02:00Z"));
+    expect([end.status, end.jobs[0].steps[0].log.length]).toEqual(["success", 4]);
+  });
+  it("lists the cycle's runs created by then, newest first", () => {
+    const later = { ...run, id: 8, created_at: "2026-10-20T10:05:00Z", started_at: "2026-10-20T10:05:00Z", ended_at: "2026-10-20T10:06:00Z" };
+    expect(replayIndex([run, later], t("2026-10-20T10:01:00Z")).doc.runs.map((r) => r.id)).toEqual([7]);
+    expect(replayIndex([run, later], t("2026-10-20T10:07:00Z")).doc.runs.map((r) => r.id)).toEqual([8, 7]);
+  });
+});
+
+describe("the replay's banner (behold#571)", () => {
+  const cycle = { started: "2026-10-20T14:05:00Z", ended: "2026-10-20T14:09:00Z", steps: [{ index: 3, scenarios: 3, at: "2026-10-20T14:05:00Z" }] };
+  it("says when the replayed run was, and about when the tool is live again", () => {
+    expect(replayBanner(cycle, 6)).toBe("Replay of the run at 14:05 UTC · live again in about 6 min");
+    expect(replayBanner(cycle, null)).toBe("Replay of the run at 14:05 UTC");
+  });
+  it("estimates from the loop's order and the cycle's length, and not without them", () => {
+    const now = new Date("2026-10-20T15:01:00Z");
+    // Scenario 1 of 3 started a minute ago; scenario 2 runs before the tool's 3rd: 3 min left, then 4.
+    expect(liveEstimate({ index: 1, scenarios: 3, started_at: "2026-10-20T15:00:00Z" }, cycle, now)).toBe(7);
+    // Scenario 2 is live: the tool's is next.
+    expect(liveEstimate({ index: 2, scenarios: 3, started_at: "2026-10-20T15:00:00Z" }, cycle, now)).toBe(3);
+    expect(liveEstimate({ index: null, scenarios: 3, started_at: "2026-10-20T15:00:00Z" }, cycle, now)).toBe(null);
+    expect(liveEstimate({ index: 1, scenarios: 4, started_at: "2026-10-20T15:00:00Z" }, cycle, now)).toBe(null);
+  });
+});
+
+describe("the branding table (behold#571)", () => {
+  it("has a page for every tool the server routes, and nothing else", () => {
+    expect(Object.keys(VENDORS)).toEqual([...VENDOR_TOOLS]);
+  });
+  it("links every name to an official https site, and shows a logo for choudoufu alone", () => {
+    for (const v of Object.values(VENDORS)) expect(v.url).toMatch(/^https:\/\//);
+    expect(Object.entries(VENDORS).filter(([, v]) => v.logo).map(([id]) => id)).toEqual(["choudoufu"]);
+    expect(VENDORS["cdk-terrain"].url).toBe("https://cdktn.io/");
+    expect(VENDORS.terraform.credit).toContain("Terraform is a trademark of HashiCorp.");
+  });
+  it("says on each page who makes the tool and that they don't endorse the demo, naming no other tool or maker", () => {
+    for (const tool of VENDOR_TOOLS) {
+      const v = VENDORS[tool];
+      const words = [v.name, ...creditLines(tool).map((l) => l.map((s) => s.text).join("")), ...Object.values(notRunWords(v)), legendWords("components", tool), legendWords("resources", tool)];
+      for (const w of words) expect(namesOther(w, tool), `${tool}: ${w}`).toBe(false);
+      // choudoufu is ours: its credit says so instead.
+      if (tool !== "choudoufu") expect(v.credit).toMatch(/(does not|don't) endorse this demo\./);
+    }
+    expect(VENDORS.choudoufu.credit).toMatch(/AWS and Kubernetes/);
+    expect(VENDORS.choudoufu.credit).not.toMatch(/experimental/i);
+  });
+  it("links each name in the footer, the tool's to its site and OpenTofu's where its scenarios run on it", () => {
+    const tf = creditLines("terraform");
+    expect(tf.flat().filter((s) => s.url).map((s) => [s.text, s.url])).toEqual([
+      ["Terraform", VENDORS.terraform.url],
+      ["OpenTofu", RUNS_WITH.opentofu.url],
+    ]);
+    expect(creditLines("terragrunt").flat().filter((s) => s.url).map((s) => s.text)).toEqual(["Terragrunt"]);
+    expect(linkSegments("a b a", [{ name: "a", url: "u" }])).toEqual([{ text: "a", url: "u" }, { text: " b a" }]);
+  });
+  it("counts as a competitor each other tool of the same kind: engines with engines, orchestrators with orchestrators", () => {
+    const matrix = Object.fromEntries(VENDOR_TOOLS.map((t) => [t, otherTerms(t)]));
+    expect(matrix).toEqual({
+      // OpenTofu is an engine too, but Terraform's scenarios really run on it.
+      terraform: ["choudoufu"],
+      terragrunt: ["CDK Terrain", "CDKTN", "Open Construct", "Atmos", "Cloud Posse", "Terramate"],
+      "cdk-terrain": ["Terragrunt", "Gruntwork", "Atmos", "Cloud Posse", "Terramate"],
+      choudoufu: ["Terraform", "HashiCorp", "OpenTofu"],
+    });
+    expect(otherTerms(null)).toEqual([]);
+  });
+  it("lets an orchestrator's page name the engines it runs on, and keeps an engine's page from naming another engine", () => {
+    expect(namesOther("Big Terraform setups run on OpenTofu", "terragrunt")).toBe(false);
+    expect(namesOther("Big Terraform setups", "cdk-terrain")).toBe(false);
+    expect(namesOther("compare with Atmos", "terragrunt")).toBe(true);
+    expect(namesOther("Terragrunt units", "cdk-terrain")).toBe(true);
+    expect(namesOther("Big Terraform setups", "choudoufu")).toBe(true);
+    expect(namesOther("Terraform.", "choudoufu")).toBe(true);
+    expect(namesOther("runs on choudoufu", "terraform")).toBe(true);
+    expect(namesOther("works with OpenTofu", "terraform")).toBe(false);
+    expect(rootWord("choudoufu")).toBe("a root");
+    expect(rootWord("terragrunt")).toBe("a Terraform root");
+  });
+  it("never counts a resource address, a bucket or a path as a brand", () => {
+    for (const t of ["terraform_data.app", "data.terraform_remote_state.network", "state in demo-terraform-state", "s3://demo-terraform-state/edge.tfstate", "developer.hashicorp.com/terraform", ".terraform.lock.hcl", "terragrunt-cache"]) {
+      expect(namesOther(t, "choudoufu"), t).toBe(false);
+      expect(namesOther(t, "cdk-terrain"), t).toBe(false);
+    }
+  });
+  it("leaves out the driver's words that name a competitor, and the loop's count", () => {
+    const d = scrubDemo(demo({ intro: "Big Terraform setups split", about: { changes: "A unit changes", watch: "Terramate plans", shows: "It waits" }, label: "Atmos applies wave 2", title: "CDK Terrain roots" }), "terragrunt");
+    expect([d.intro, d.label, d.title, d.scenarios, d.index]).toEqual(["Big Terraform setups split", "", "a new subnet", null, null]);
+    expect(d.about).toEqual({ changes: "A unit changes", shows: "It waits" });
+    expect(scenarioHead(d, { vendor: "terragrunt" })).toEqual({ kicker: "Scenario · a new subnet", title: "a new subnet" });
+    expect(scenarioHead(demo(), { vendor: "terraform" }).kicker).not.toMatch(/of 3|\d/);
+    expect(scrubDemo(demo({ intro: "Big Terraform setups split" }), "choudoufu").intro).toBe(null);
+  });
+  it("leaves a log line naming a competitor out, says how many, and keeps the engine's lines on an orchestrator's page", () => {
+    const rows = logRows(["plan ok", "Terramate binary", "Terraform v1.9", "edge: s3://demo-terraform-state/edge.tfstate"], { hide: (l) => namesOther(l, "terragrunt") });
+    expect(rows).toEqual([{ n: 1, text: "plan ok" }, { n: 3, text: "Terraform v1.9" }, { n: 4, text: "edge: s3://demo-terraform-state/edge.tfstate" }, { hidden: 1 }]);
+  });
+});
+
+describe("a tool's page, drawn (behold#571)", () => {
+  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 text = (n) => (n.children && n.children.length ? n.children.map(text).join("") : n.textContent || "");
+  const all = (n) => [n, ...(n.children || []).flatMap(all)];
+  it("puts the tool's name before the scenario, the banner over it, and the credit in the foot, with no count", async () => {
+    const { renderKiosk } = await import("./kiosk.js");
+    const was = globalThis.document;
+    globalThis.document = fakeDocument();
+    try {
+      const bar = document.createElement("header");
+      const foot = document.createElement("footer");
+      const about = { changes: "A unit changes", watch: "Terramate would plan it too", shows: "It waits" };
+      const s = { vendor: "terragrunt", mode: "replay", replay: { banner: "Replay of the run at 14:05 UTC" }, noReports: true, demo: { demo: scrubDemo(demo({ tool: "terragrunt", intro: "Big Terraform setups", about }), "terragrunt") }, answer: null, progress: null };
+      renderKiosk(bar, s, new Date("2026-10-20T10:01:00Z"), foot);
+      expect(bar.children[0].className).toBe("k-replay");
+      const title = all(bar).find((n) => n.className === "k-title");
+      expect(title.children.map((c) => c.className)).toEqual(["k-brand", "k-kicker", "k-title-text"]);
+      const brand = title.children[0];
+      expect([brand.href, brand.target, brand.rel, text(brand)]).toEqual([VENDORS.terragrunt.url, "_blank", "noopener", "Terragrunt"]);
+      expect(text(bar)).not.toMatch(/of 3|Terramate/);
+      // behold#571: no intro band at a live step; the intro fills the card's box at reset.
+      expect(text(bar)).not.toContain("Big Terraform setups");
+      // The engine Terragrunt runs on is no competitor: the shared intro stays.
+      const reset = { ...s, demo: { demo: { ...s.demo.demo, step: "reset" } } };
+      const bar2 = document.createElement("header");
+      renderKiosk(bar2, reset, new Date("2026-10-20T10:01:00Z"), document.createElement("footer"));
+      expect(text(bar2)).toContain("Big Terraform setups");
+      // No graph of this repo here: one line in the header says so.
+      expect(all(bar).filter((n) => n.className === "k-nograph-note").map(text)).toEqual([NO_GRAPH_WORDS]);
+      expect(all(foot).filter((n) => n.className === "k-credit").map(text)).toEqual([VENDORS.terragrunt.credit]);
+    } finally {
+      globalThis.document = was;
+    }
+  });
+  it("names the checkout of a tool's repo, and offers it before the first cycle only when it is served", () => {
+    expect(toolCheckout("terraform")).toBe("demo");
+    expect(toolCheckout("terragrunt")).toBe("demo-terragrunt");
+    expect(toolCheckout("nope")).toBe(null);
+    expect(notRunRepo("terragrunt", ["demo", "demo-terragrunt"])).toBe("demo-terragrunt");
+    expect(notRunRepo("terragrunt", ["demo"])).toBe(null);
+    expect(notRunRepo("terragrunt", null)).toBe(null);
+    expect(notRunRepo("nope", ["demo"])).toBe(null);
+  });
+  it("says the graph below is the repo on the base only when there is one", () => {
+    expect(notRunWords(VENDORS.terragrunt).text).not.toContain("Below");
+    expect(notRunWords(VENDORS.terragrunt, { graph: true }).text).toContain("Below, its repo as it stands on the base.");
+    expect(notRunWords(VENDORS.terragrunt, { graph: true }).title).toBe("This scenario hasn't run yet");
+  });
+  it("says calmly that a tool's scenario hasn't run yet, with its name and link", async () => {
+    const { renderKiosk } = await import("./kiosk.js");
+    const was = globalThis.document;
+    globalThis.document = fakeDocument();
+    try {
+      const bar = document.createElement("header");
+      const foot = document.createElement("footer");
+      renderKiosk(bar, { vendor: "choudoufu", mode: "none", demo: null }, new Date(), foot);
+      expect(text(bar)).toContain("This scenario hasn't run yet");
+      const brand = all(bar).find((n) => n.className === "k-brand");
+      expect(brand.href).toBe(VENDORS.choudoufu.url);
+      expect(all(brand).some((n) => n.className === "k-brand-logo" && n.src === VENDORS.choudoufu.logo.src)).toBe(true);
+    } finally {
+      globalThis.document = was;
+    }
+  });
+});

package/web/kiosk.html

@@ -16,20 +16,29 @@
         --edge: #56596d; --managed: #a6e3a1; --foreign: #f9e2af; --pending: #89b4fa;
         --degraded: #f38ba8; --neutral: #6d7187; --runtime: #94e2d5;
         --rule: #4e4f64; --focus: #a3b4d0; --active: #3d4660; --well: #11101f; --shadow: #050507;
+        /* behold#571: the kiosk's surfaces and ink (theme.js kioskSurfaces), the default theme's until initTheme() runs. */
+        --surface-box: #252536; --surface-pane-a: #2b2b3c; --surface-pane-b: #313142; --zebra: #cdd6f4; --soft: #cdd6f4; --muted-ink: #808395;
+        --managed-ink: #a6e3a1; --foreign-ink: #f9e2af; --pending-ink: #89b4fa; --degraded-ink: #f38ba8; --runtime-ink: #94e2d5;
         --font-ui: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
         --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
       }
       * { box-sizing: border-box; }
+      /* behold#571: the kiosk's text is the softened ink, its secondary text and state colours the ones held legible on every surface. */
+      body { --fg: var(--soft); --muted: var(--muted-ink); --managed: var(--managed-ink); --foreign: var(--foreign-ink); --pending: var(--pending-ink); --degraded: var(--degraded-ink); --runtime: var(--runtime-ink); --zebra-row: color-mix(in srgb, var(--zebra) 3.5%, transparent); }
       /* #569 step 3: one screen. The bar is the narration, the frame is
          behold's own view of the change, the foot is the plan's facts. Sizes
          follow the screen's width, so a TV reads it from across a room. */
       html, body { margin: 0; height: 100%; background: var(--bg); color: var(--fg); font: clamp(13px, 0.82vw, 20px)/1.4 var(--font-ui); overflow: hidden; }
       body { display: grid; grid-template-rows: auto minmax(0, 1fr) auto; }
+      #k-head { position: relative; }
       /* #569: the pipeline's runs (left), the selected run's jobs, steps and
          log (middle), behold's view of the change (right). */
-      #stage { display: grid; grid-template-columns: minmax(15em, 18%) minmax(26em, 34%) minmax(0, 1fr); min-height: 0; }
-      #runs-side { overflow-y: auto; border-right: 1px solid var(--rule); background: var(--panel); }
-      #runs-main { overflow: hidden; display: flex; flex-direction: column; min-height: 0; border-right: 1px solid var(--rule); }
+      /* behold#571: each pane its own surface, a gap of the page between them. */
+      #stage { display: grid; grid-template-columns: minmax(15em, 18%) minmax(26em, 34%) minmax(0, 1fr); gap: 5px; padding: 0 5px; min-height: 0; background: var(--bg); }
+      #runs-side { overflow-y: auto; background: var(--surface-pane-b); border-radius: 6px 6px 0 0; }
+      #runs-main { overflow: hidden; display: flex; flex-direction: column; min-height: 0; background: var(--surface-pane-a); border-radius: 6px 6px 0 0; }
+      #k-runs-toggle { display: none; }
+      .r-run:nth-child(even of .r-run), .r-job:nth-child(even of .r-job), .r-log-line:nth-child(even of .r-log-line) { background: var(--zebra-row); }
       .r-side-head { padding: 0.8em 1em 0.5em; }
       .r-side-title { font-weight: 700; font-size: 1.05em; }
       .r-side-note { color: var(--muted); font-size: 0.82em; margin-top: 0.15em; }
@@ -73,7 +82,7 @@
       .r-caret { color: var(--muted); width: 0.8em; font-size: 0.8em; }
       .r-step-name { font-size: 0.88em; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
       .r-open > .r-step-line { background: color-mix(in srgb, var(--active) 60%, transparent); }
-      .r-log { margin: 0.2em 0.6em 0.4em 1.6em; padding: 0.5em 0; background: var(--well); border-radius: 6px; font: 0.76em/1.45 var(--font-mono);
+      .r-log { margin: 0.2em 0.6em 0.4em 1.6em; padding: 0.5em 0; background: var(--surface-pane-b); border-radius: 6px; font: 0.76em/1.45 var(--font-mono);
         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; }
@@ -86,26 +95,70 @@
       @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: 0.45em 1.6em; align-items: start;
-        padding: 0.55em 1.4em 0.6em; background: var(--panel); border-bottom: 1px solid var(--rule); }
+      /* behold#571: a log line's feature: an outlined chip on its first line in the job, a faint dot after; its note opens under the line. */
+      .r-ann { font: 600 0.82em var(--font-ui); color: var(--fg); background: transparent; border: 1px solid var(--rule); border-radius: 999px; padding: 0 0.55em; margin-left: 0.3em; cursor: pointer; white-space: nowrap; vertical-align: 0.05em; }
+      .r-ann:hover, .r-ann:focus-visible { border-color: var(--focus); }
+      .r-ann-dot { display: inline-block; width: 0.55em; height: 0.55em; padding: 0; margin-left: 0.45em; border-radius: 50%; border: 0; background: var(--muted); opacity: 0.55; cursor: pointer; vertical-align: 0.1em; }
+      .r-ann-dot:hover { opacity: 1; }
+      .r-ann-terragucci { border-color: color-mix(in srgb, var(--pending) 70%, transparent); }
+      .r-ann-chant { border-color: color-mix(in srgb, var(--runtime) 70%, transparent); }
+      .r-ann-choudoufu, .r-ann-behold { border-color: color-mix(in srgb, var(--foreign) 70%, transparent); }
+      .r-ann-dot.r-ann-terragucci { background: var(--pending); } .r-ann-dot.r-ann-chant { background: var(--runtime); }
+      .r-ann-note { grid-column: 2; margin: 0.25em 0 0.45em; padding: 0.45em 0.7em; border-left: 3px solid var(--focus); background: var(--surface-box); border-radius: 0 6px 6px 0; font: 1.12em/1.4 var(--font-ui); white-space: normal; }
+      .r-ann-note-head { font: 600 0.8em var(--font-mono); text-transform: uppercase; letter-spacing: 0.05em; color: var(--muted); border: 0; }
+      .r-ann-note-text { margin: 0.15em 0 0.2em; color: var(--fg); }
+      .r-ann-more { color: var(--pending); }
+      .r-flash { background: color-mix(in srgb, var(--focus) 30%, transparent) !important; }
+      @media (prefers-reduced-motion: no-preference) { .r-flash { transition: background 0.6s; } }
+      /* behold#571: folded, whole lines only (fitFeatures); opened, it scrolls inside a bounded box. */
+      .r-feats { padding: 0.1em 1em 0.45em; border-bottom: 1px solid var(--rule); }
+      .r-feats-open .r-feats-list { max-height: 12em; overflow-y: auto; scrollbar-width: thin; }
+      .r-feats-label { padding: 0.3em 0 0.15em; }
+      .r-feats-list { display: flex; flex-wrap: wrap; gap: 0.3em 0.35em; align-items: center; }
+      .r-feats-list > [hidden] { display: none; }
+      .r-feats-product { font: 600 0.7em var(--font-mono); text-transform: uppercase; letter-spacing: 0.05em; color: var(--muted); border: 0; margin: 0 0.15em 0 0.4em; }
+      .r-feats-product:first-child { margin-left: 0; }
+      .r-feat, .r-feats-more { font: 0.8em var(--font-ui); line-height: 1.4; color: var(--fg); background: transparent; border: 1px solid var(--rule); border-radius: 999px; padding: 0.05em 0.6em; cursor: pointer; }
+      .r-feats-more { color: var(--pending); border-style: dashed; }
+      .r-feat:hover, .r-feat:focus-visible { border-color: var(--focus); background: var(--zebra-row); }
+      /*
+       * behold#571: the header in fixed boxes. The title, the card, the step
+       * line, and the hold's box each have a height that holds their text
+       * budget at 1600x1000 and 1920x1080 (terragucci#1061: the card's fields
+       * 120, 220 and 120 characters, the step 200); more scrolls inside the
+       * box, with a fade at the edge, so the panes below never move.
+       */
+      #bar { position: relative; display: grid; grid-template-columns: minmax(0, 1.1fr) minmax(0, 1fr); gap: 0.4em 0.9em; align-items: stretch;
+        padding: 0.45em 1em 0.5em; background: var(--bg); }
       #bar > .k-empty { grid-column: 1 / -1; }
-      /* 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-left { display: grid; grid-template-rows: var(--k-title-h) var(--k-card-h) var(--k-step-h); gap: 0.35em; min-width: 0; }
+      :root { --k-title-h: 1.8em; --k-card-h: 6.2em; --k-step-h: 3.35em; }
+      .k-box { min-height: 0; overflow-y: auto; scrollbar-width: thin; background: var(--surface-box); border-radius: 6px; padding: 0.35em 0.7em; }
+      .k-box.k-more-below { -webkit-mask-image: linear-gradient(to bottom, #000 calc(100% - 1.3em), transparent); mask-image: linear-gradient(to bottom, #000 calc(100% - 1.3em), transparent); }
+      .k-box.k-more-above { -webkit-mask-image: linear-gradient(to top, #000 calc(100% - 1.3em), transparent); mask-image: linear-gradient(to top, #000 calc(100% - 1.3em), transparent); }
+      .k-box.k-more-above.k-more-below { -webkit-mask-image: linear-gradient(to bottom, transparent, #000 1.3em, #000 calc(100% - 1.3em), transparent); mask-image: linear-gradient(to bottom, transparent, #000 1.3em, #000 calc(100% - 1.3em), transparent); }
+      .k-box-title { background: transparent; padding: 0.1em 0.1em 0; overflow: hidden; }
+      /* behold#571: between scenarios the card's box carries what the demo is about. */
+      .k-intro { margin: 0; font-size: 1.12em; line-height: 1.4; color: var(--fg); }
+      .k-intro-head { display: block; font: 600 0.62em var(--font-mono); text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted); margin-bottom: 0.15em; }
       .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; }
+      .k-title { margin: 0; font-size: 1.3em; line-height: 1.25; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
       /* 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.08em 0.9em; align-items: baseline; margin: 0 0 0.35em; font-size: 0.88em; line-height: 1.25; }
+      .k-about { display: grid; grid-template-columns: max-content minmax(0, 1fr); gap: 0.08em 0.9em; align-items: baseline; margin: 0; 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; margin: 0; font-size: 0.95em; line-height: 1.3; }
+      .k-step { border-left: 4px solid var(--pending); padding: 0 0 0 0.7em; 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.45em; align-content: start; }
+      /* The right column takes the left's height and never sets it: its hold box scrolls instead. */
+      .k-right { display: grid; grid-template-rows: auto auto minmax(0, 1fr); gap: 0.35em; min-width: 0; min-height: 0; contain: size; }
+      .k-where { padding-right: 13em; flex-wrap: nowrap; }
+      .k-next .k-cycle { margin-left: auto; }
       .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); }
@@ -117,6 +170,20 @@
       .k-action { font-family: var(--font-mono); }
       .k-when { color: var(--foreign); font-family: var(--font-mono); }
       .k-approve { border-left: 4px solid var(--foreign); padding-left: 0.8em; }
+      /* behold#571: "How this hold ends": four rows that light from the records. */
+      .k-ap-head { font: 600 0.7em var(--font-mono); text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted); margin: 0 0 0.1em; }
+      .k-ap-head .k-ap-plan { text-transform: none; letter-spacing: 0; color: var(--fg); font-weight: 400; }
+      .k-ap-rows { list-style: none; margin: 0; padding: 0; display: grid; gap: 0.05em; }
+      .k-ap-row { display: grid; grid-template-columns: 1em 6.4em minmax(0, 1fr); gap: 0 0.35em; align-items: baseline; font-size: 0.84em; line-height: 1.28; }
+      .k-ap-mark { width: 0.75em; height: 0.75em; border-radius: 50%; border: 2px solid var(--muted); display: inline-block; align-self: start; margin-top: 0.25em; }
+      .k-ap-lit .k-ap-mark { background: var(--managed); border-color: var(--managed); }
+      .k-ap-going .k-ap-mark { border-color: var(--foreign); background: linear-gradient(90deg, var(--foreign) 50%, transparent 50%); }
+      .k-ap-label { font: 600 0.82em var(--font-mono); text-transform: uppercase; letter-spacing: 0.04em; color: var(--fg); }
+      .k-ap-dim .k-ap-label, .k-ap-dim .k-ap-text { color: var(--muted); }
+      .k-ap-facts { color: var(--muted); font-size: 0.92em; margin-left: 0.35em; }
+      .k-ap-bad { color: var(--degraded); }
+      .k-ap-row .k-command { grid-column: 3; margin: 0.1em 0; padding: 0.25em 0.6em; font-size: 0.92em; }
+      .k-ap .r-ann { font-size: 0.78em; }
       .k-approve p { margin: 0.15em 0; }
       .k-approve-gloss { color: var(--fg); font-size: 0.92em; }
       .k-approve-then { color: var(--muted); font-size: 0.92em; }
@@ -127,7 +194,7 @@
       #view-pane { display: flex; flex-direction: column; min-height: 0; min-width: 0; }
       #view { display: block; width: 100%; flex: 1; min-height: 0; border: 0; background: var(--bg); }
       /* #571: the toggle between the two views, over the frame by the view's caption. */
-      #views { display: flex; align-items: center; gap: 0.9em; padding: 0.45em 1em; border-bottom: 1px solid var(--rule); background: var(--panel); }
+      #views { display: flex; align-items: center; gap: 0.9em; padding: 0.45em 1em; border-bottom: 1px solid var(--rule); background: var(--surface-pane-a); border-radius: 6px 6px 0 0; }
       #views[hidden] { display: none; }
       .k-views { display: inline-flex; border: 1px solid var(--rule); border-radius: 999px; overflow: hidden; }
       .k-view { font: 600 0.85em var(--font-ui); color: var(--muted); background: transparent; border: 0; padding: 0.3em 0.95em; cursor: pointer; }
@@ -136,17 +203,85 @@
       .k-view-on { color: var(--bg); background: var(--pending); }
       .k-view-on:hover { color: var(--bg); }
       .k-view-note { color: var(--muted); font-size: 0.8em; }
-      #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; }
+      #foot { display: flex; flex-wrap: wrap; gap: 0.2em 1.6em; padding: 0.5em 1.6em; border-top: 1px solid var(--rule); background: var(--surface-box); font-size: 0.85em; }
       .k-legend { color: var(--muted); flex-basis: 100%; }
+      /* behold#571: a tool's page. Its name (and logo where allowed) before the scenario, the replay's banner, the credit. */
+      .k-brand { display: inline-flex; align-items: center; gap: 0.35em; margin-right: 0.8em; color: var(--fg); text-decoration: none; font-weight: 700; vertical-align: 0.05em; }
+      .k-brand:hover .k-brand-name { text-decoration: underline; }
+      .k-brand-logo { width: 1.25em; height: 1.25em; }
+      .k-replay { grid-column: 1 / -1; margin: 0; padding: 0.2em 0.7em; padding-right: 16em; border-left: 4px solid var(--neutral); background: var(--surface-box); color: var(--fg); font-size: 0.92em; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+      /* behold#571: "What is this?" and the theme, at the header's top right, outside the boxes that redraw. */
+      #k-tools { position: absolute; top: 0.4em; right: 1em; z-index: 5; display: flex; gap: 0.7em; align-items: center; font-size: 0.8em; }
+      .k-what { font: inherit; color: var(--pending); background: transparent; border: 0; padding: 0.1em 0; cursor: pointer; text-decoration: underline; text-underline-offset: 2px; }
+      #k-what-pop { position: absolute; top: 1.8em; right: 0; width: min(34em, calc(100vw - 32px)); padding: 0.7em 0.9em; background: var(--surface-pane-b); color: var(--fg); border: 1px solid var(--focus);
+        border-radius: 8px; box-shadow: 0 6px 24px color-mix(in srgb, var(--shadow) 70%, transparent); font-size: 1.15em; line-height: 1.45; }
+      #k-what-pop[hidden] { display: none; }
+      #k-what-pop p { margin: 0; }
+      .k-menu summary { cursor: pointer; color: var(--muted); list-style: none; }
+      .k-menu summary::-webkit-details-marker { display: none; }
+      .k-menu summary::after { content: " ▾"; }
+      .k-menu[open] summary { color: var(--fg); }
+      .k-menu-body { position: absolute; right: 0; top: 1.8em; padding: 0.5em; background: var(--surface-pane-b); border: 1px solid var(--rule); border-radius: 8px; }
+      .k-credit { color: var(--muted); flex-basis: 100%; }
+      .k-credit-link { color: var(--fg); }
+      .k-nograph-note { grid-column: 1 / -1; margin: 0; color: var(--muted); font-size: 0.88em; }
+      /* With no graph to show, the graph pane folds away and the runs and the log take its width. */
+      body.k-nograph #stage { grid-template-columns: minmax(15em, 22%) minmax(0, 1fr); }
+      body.k-nograph #view-pane { display: none; }
+      /* behold#571: before the tool's first cycle, no runs and no log: those panes fold away, the repo's graph takes the width, or nothing shows below the header. */
+      body.k-notyet #runs-side, body.k-notyet #runs-main, body.k-notyet #k-runs-toggle { display: none !important; }
+      body.k-notyet #stage { grid-template-columns: minmax(0, 1fr); }
       .k-fact { color: var(--fg); }
-      @media (max-width: 900px) { #bar { grid-template-columns: 1fr; } #stage { grid-template-columns: 1fr; } }
+      @media (max-width: 900px) and (min-width: 601px) { #bar { grid-template-columns: 1fr; } #stage, body.k-nograph #stage { grid-template-columns: 1fr; } }
+      /*
+       * behold#571: a phone. One column that scrolls as a page: the header
+       * (its boxes as tall as their text), the graph, then the runs and their
+       * logs behind "Runs and logs". Nothing wider than the screen.
+       */
+      @media (max-width: 600px) {
+        html, body { height: auto; overflow-x: hidden; overflow-y: auto; font-size: 14px; }
+        body { display: block; }
+        #bar { display: block; padding: 0.5em 16px 0.6em; }
+        #bar > * + * { margin-top: 0.45em; }
+        .k-left, .k-right { display: block; contain: none; }
+        .k-left > * + *, .k-right > * + * { margin-top: 0.4em; }
+        .k-box { height: auto; max-height: none; overflow: visible; -webkit-mask-image: none !important; mask-image: none !important; }
+        .k-title { white-space: normal; }
+        .k-where { padding-right: 0; }
+        .k-replay { padding-right: 0.7em; white-space: normal; }
+        #k-tools { position: static; justify-content: flex-end; margin: 0; padding: 0.4em 16px 0; }
+        #k-what-pop { right: 16px; left: 16px; width: auto; top: 2.2em; }
+        .k-ap-row { grid-template-columns: 1.1em 5.6em minmax(0, 1fr); }
+        #stage, body.k-nograph #stage { display: flex; flex-direction: column; padding: 0; gap: 0; }
+        #view-pane { order: 1; height: 64vh; }
+        body.k-nograph #view-pane { display: none; }
+        #k-runs-toggle { order: 2; display: block; margin: 0.6em 16px; padding: 0.6em 1em; font: 600 1em var(--font-ui); color: var(--fg); background: var(--surface-pane-b); border: 1px solid var(--rule); border-radius: 8px; cursor: pointer; text-align: left; }
+        #k-runs-toggle::after { content: " ▸"; }
+        body.k-runs-open #k-runs-toggle::after { content: " ▾"; }
+        #runs-side { order: 3; display: none; max-height: 50vh; border-radius: 0; }
+        #runs-main { order: 4; display: none; height: 85vh; border-radius: 0; }
+        body.k-runs-open #runs-side, body.k-runs-open #runs-main { display: flex; flex-direction: column; }
+        body.k-runs-open #runs-side { display: block; }
+        .r-log { margin-left: 0.4em; max-height: 60vh; }
+        .r-log-line { grid-template-columns: 2.4em 1fr; gap: 0.5em; }
+        .r-ann-note { grid-column: 1 / -1; }
+        #foot { padding: 0.5em 16px; }
+      }
     </style>
   </head>
   <body>
-    <header id="bar" aria-live="polite"></header>
+    <div id="k-head">
+      <div id="k-tools">
+        <button type="button" class="k-what" aria-expanded="false" aria-controls="k-what-pop">What is this?</button>
+        <details class="k-menu"><summary>Theme</summary><div class="k-menu-body" id="k-theme"></div></details>
+        <div id="k-what-pop" role="dialog" aria-label="What is this?" hidden></div>
+      </div>
+      <header id="bar" aria-live="polite"></header>
+    </div>
     <div id="stage">
       <nav id="runs-side" aria-label="pipeline runs"></nav>
       <section id="runs-main" aria-live="polite"></section>
+      <button type="button" id="k-runs-toggle" aria-expanded="false">Runs and logs</button>
       <section id="view-pane">
         <div id="views" hidden></div>
         <iframe id="view" title="behold's view of the change"></iframe>
@@ -156,8 +291,16 @@
     <script type="module">
       import { initTheme } from "/theme.js";
       import { startKiosk } from "/kiosk.js";
+      import { pageTool } from "/kiosk-vendor.js";
       initTheme();
-      startKiosk({ bar: document.getElementById("bar"), frame: document.getElementById("view"), foot: document.getElementById("foot"), side: document.getElementById("runs-side"), main: document.getElementById("runs-main"), views: document.getElementById("views") });
+      // behold#571: /<tool> serves this page with its tool in a meta tag; /kiosk has none.
+      startKiosk(
+        {
+          bar: document.getElementById("bar"), frame: document.getElementById("view"), foot: document.getElementById("foot"), side: document.getElementById("runs-side"), main: document.getElementById("runs-main"), views: document.getElementById("views"),
+          tools: { what: document.querySelector(".k-what"), pop: document.getElementById("k-what-pop"), theme: document.getElementById("k-theme"), runsToggle: document.getElementById("k-runs-toggle") },
+        },
+        { tool: pageTool(document) },
+      );
     </script>
   </body>
 </html>