@intentius/behold 0.29.3 → 0.29.4

package/web/kiosk.html

@@ -85,6 +85,10 @@
       .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 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-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); }
@@ -110,7 +114,18 @@
       .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; }
       .k-unknown { color: var(--foreign); }
-      #view { display: block; width: 100%; height: 100%; border: 0; background: var(--bg); }
+      #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[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; }
+      .k-view + .k-view { border-left: 1px solid var(--rule); }
+      .k-view:hover { color: var(--fg); }
+      .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; }
       .k-legend { color: var(--muted); flex-basis: 100%; }
       .k-fact { color: var(--fg); }
@@ -123,14 +138,17 @@
     <div id="stage">
       <nav id="runs-side" aria-label="pipeline runs"></nav>
       <section id="runs-main" aria-live="polite"></section>
-      <iframe id="view" title="behold's view of the change"></iframe>
+      <section id="view-pane">
+        <div id="views" hidden></div>
+        <iframe id="view" title="behold's view of the change"></iframe>
+      </section>
     </div>
     <footer id="foot"></footer>
     <script type="module">
       import { initTheme } from "/theme.js";
       import { startKiosk } from "/kiosk.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") });
+      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") });
     </script>
   </body>
 </html>

package/web/kiosk.js

@@ -13,8 +13,8 @@
 // A wave that failed says which waves applied before it and stay applied.
 // Nothing here is all-or-nothing, and nothing says so.
 
-import { startRuns } from "./kiosk-runs.js";
-import { STATE_WORDS, changingRoots, costLine, readEdges, rootsCount, totalsLine, waveRows, blastRows } from "./terragucci-change.js";
+import { PICK_HOLD_MS, startRuns } from "./kiosk-runs.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. */
 export const SCENARIOS = {
@@ -59,6 +59,24 @@ export function scenarioHead(demo) {
   return { kicker: `scenario ${known.n} · ${known.name}`, title: demo.title };
 }
 
+/** The card's rows under the title, in order, with the labels the kiosk draws (behold#571). */
+export const ABOUT_ROWS = [
+  { field: "changes", label: "What changes" },
+  { field: "watch", label: "Watch for" },
+  { field: "shows", label: "Shows" },
+];
+
+/**
+ * behold#571: the scenario's card, always open under the title so a TV or a
+ * link opened cold reads it without a click. The text is demo.json's `about`,
+ * as terragucci wrote it; no card when it has none.
+ */
+export function aboutRows(demo) {
+  const about = demo && demo.about;
+  if (!about) return [];
+  return ABOUT_ROWS.filter((r) => typeof about[r.field] === "string" && about[r.field]).map((r) => ({ label: r.label, text: about[r.field] }));
+}
+
 /** The strip: each stop, and whether it is done, current or ahead. A stalled cycle marks no stop current. */
 export function stripStops(step) {
   const at = STRIP.findIndex((s) => s.steps.includes(step));
@@ -112,13 +130,15 @@ const runOf = (progress) => (progress && !progress.error && progress.run && prog
 
 /**
  * The newest pull request's plan, when it is this step's: the pull request
- * demo.json names. A forge never reuses a number, so an older cycle's plan is
- * never shown as this one's.
+ * demo.json names, of its commit before the merge. A forge never reuses a
+ * number, so an older cycle's plan is never shown as this one's.
  */
 export function matchingPull(answer, demo) {
   const pr = pullOf(answer);
   if (!pr || demo.pull === null) return null;
-  return String(pr.run.pull_request) === String(demo.pull) ? pr : null;
+  // From the merge on, demo.json's commit is the merge's, not the plan's.
+  const before = demo.step === "pull-request" || demo.step === "planned";
+  return planFitsPin(pr, before ? pullPin(planPin(demo)) : { pull: String(demo.pull), commit: null }) ? pr : null;
 }
 
 /**
@@ -241,12 +261,24 @@ export function focusRoots(demo, answer, progress) {
   return null;
 }
 
+/**
+ * #569: the pin on this cycle's plan, `pull-<n>-<sha>` (or `pull-<n>`, or bare
+ * `pull` while none is open): the frame draws that plan or none, never the
+ * plan of another cycle's pull request.
+ */
+export function planPin(demo) {
+  if (demo.pull === null || demo.pull === undefined || !/^\d+$/.test(String(demo.pull))) return "pull";
+  const sha = demo.commit && /^[0-9a-f]{7,40}$/.test(demo.commit) ? `-${demo.commit}` : "";
+  return `pull-${demo.pull}${sha}`;
+}
+
 /**
  * #569: which run the framed view draws for this step, so the graph stays on
  * the cycle the narration describes while the loop's next runs (the reset's
  * push back to the base) already go:
  *
- * - before the merge, `none`: no run view, the pull request's plan;
+ * - before the merge, `pull-<n>-<sha>` (planPin): no run view, and only this
+ *   cycle's plan; until the plan job writes it, the roots with no marks;
  * - from the merge to `applied`, the cycle's commit (demo.json's `commit`:
  *   the merge, whose run view the `/terragucci apply` resume rewrites, or
  *   scenario 5's push);
@@ -257,17 +289,112 @@ export function focusRoots(demo, answer, progress) {
 export function runPin(demo) {
   if (!demo) return null;
   if (demo.scenario === "base" || demo.step === "reset") return "base";
-  if (demo.step === "pull-request" || demo.step === "planned") return "none";
+  if (demo.step === "pull-request" || demo.step === "planned") return planPin(demo);
   if (demo.step === "stalled") return demo.commit ? demo.commit : "none";
   return demo.commit || "none";
 }
 
-/** The framed view's address: behold's own page, bare, at the resources zoom, told who its host is. */
-export function frameSrc(origin) {
-  const q = new URLSearchParams({ embed: "1", bare: "1", zoom: "resources", host: origin });
+/** The framed view's address: behold's own page, bare, at a zoom (the resources zoom unless told), told who its host is. */
+export function frameSrc(origin, zoom = "resources") {
+  const q = new URLSearchParams({ embed: "1", bare: "1", zoom, host: origin });
   return `/?${q.toString()}`;
 }
 
+// ---------------------------------------------------------------------------
+// #571: which of behold's two views the frame shows. Before the merge, the
+// resources zoom: what the pull request changes and the reads it plans
+// before their values are known. From the merge on, the components zoom of a
+// terragucci repo (`terragucci.components.json`): one card per root in a box
+// per wave, titled with the job that applies it, in step with the jobs pane.
+// A viewer's click on the toggle holds a view for PICK_HOLD_MS after their
+// last click, as a run picked in the sidebar does; then the step leads again.
+
+/** The two views the toggle offers, with behold's zoom for each. */
+export const VIEWS = [
+  { id: "resources", words: "Resources", zoom: "resources" },
+  { id: "components", words: "Roots by wave", zoom: "components" },
+];
+
+/**
+ * The view a step shows: the pull request's steps the resources (what
+ * changes, the unknown reads), every step from the merge on the components
+ * (the jobs running), and the reset the components at rest. A step behold
+ * doesn't know, and `stalled`, keep the components: the jobs pane says where
+ * the pipeline stopped.
+ */
+export const STEP_VIEW = {
+  "pull-request": "resources",
+  planned: "resources",
+  merged: "components",
+  applying: "components",
+  waiting: "components",
+  approved: "components",
+  failed: "components",
+  resumed: "components",
+  applied: "components",
+  reset: "components",
+  stalled: "components",
+};
+
+/** The view for a step. */
+export function stepView(step) {
+  return Object.prototype.hasOwnProperty.call(STEP_VIEW, step) ? STEP_VIEW[step] : "components";
+}
+
+/**
+ * The view the frame shows, and why: `{ view, pinned, secs }`. Only the
+ * resources view when the repo offers no components zoom (no
+ * `terragucci.components.json`). A viewer's pick (`{ view, at }`, `at` in ms)
+ * holds until PICK_HOLD_MS after it; `secs` is how long it still holds.
+ * Without a demo step yet, the resources view.
+ */
+export function kioskView(demo, { components = false, pick = null, now = Date.now() } = {}) {
+  if (!components) return { view: "resources", pinned: false, secs: null };
+  if (pick && VIEWS.some((v) => v.id === pick.view)) {
+    const left = pick.at + PICK_HOLD_MS - now;
+    if (left > 0) return { view: pick.view, pinned: true, secs: Math.ceil(left / 1000) };
+  }
+  return { view: demo ? stepView(demo.step) : "resources", pinned: false, secs: null };
+}
+
+/** The line under the view saying how to read it, for the view shown. */
+export function legendWords(view) {
+  if (view === "components") {
+    return "Each card is a Terraform root with its own state, in a box per wave titled with the pipeline job that applies it; an arrow is one root reading another's outputs, dashed while it reads planned values. A wave applies its roots together, after the waves it reads.";
+  }
+  return "Each box is a Terraform root with its own state; an arrow is one root reading another's outputs, dashed while it reads planned values. A wave applies its roots together, after the waves it reads.";
+}
+
+/** The behold zoom for a view. */
+export function viewZoom(view) {
+  const v = VIEWS.find((x) => x.id === view);
+  return v ? v.zoom : "resources";
+}
+
+/**
+ * The toggle, "Resources | Roots by wave", over the frame: the view shown
+ * pressed, and a line saying whether the step leads or a click holds it.
+ * Not drawn at all when the repo offers no components zoom.
+ */
+export function renderViewToggle(host, shown, { components = false, onPick = () => {} } = {}) {
+  if (!host) return;
+  host.replaceChildren();
+  host.hidden = !components;
+  if (!components) return;
+  const group = el("div", "k-views");
+  group.setAttribute("role", "group");
+  group.setAttribute("aria-label", "the view");
+  for (const v of VIEWS) {
+    const b = el("button", `k-view${v.id === shown.view ? " k-view-on" : ""}`, v.words);
+    b.type = "button";
+    b.setAttribute("aria-pressed", String(v.id === shown.view));
+    b.addEventListener("click", () => onPick(v.id));
+    group.appendChild(b);
+  }
+  host.appendChild(group);
+  host.appendChild(el("span", "k-view-note", shown.pinned ? `held by a click; the step leads again in ${shown.secs} s` : "follows the step"));
+}
+
 /** The one-line facts under the view: the pull request's totals, cost and blast radius, as #568 has them. */
 export function factLines(demo, answer) {
   const pr = demo ? matchingPull(answer, demo) : null;
@@ -313,6 +440,12 @@ export function renderKiosk(bar, s, now = new Date(), foot = null) {
   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 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));
@@ -354,7 +487,7 @@ export function renderKiosk(bar, s, now = new Date(), foot = null) {
   bar.appendChild(right);
 
   if (foot) {
-    foot.appendChild(el("span", "k-legend", "Each box is a Terraform root with its own state; an arrow is one root reading another's outputs, dashed while it reads planned values. A wave applies its roots together, after the waves it reads."));
+    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`),
@@ -377,34 +510,50 @@ export const DEMO_POLL_MS = 3_000;
  * countdown. When the roots the step is about change, move the framed view
  * with a `behold:view` message; the frame takes them only from this origin.
  */
-export function startKiosk({ bar, frame, foot, side, main }, { fetchJson = defaultFetch, now = () => new Date(), origin = location.origin } = {}) {
-  const s = { demo: null, answer: null, progress: null };
+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" };
   let lastKey = "";
   let lastFocus;
+  const shownView = () => kioskView(s.demo && s.demo.demo, { components: s.components, pick: s.pick, now: now().getTime() });
   const tellFrame = (force) => {
     const d = s.demo && s.demo.demo;
     if (!d) return; // nothing said yet: the frame keeps its default until the narration is read
     const roots = focusRoots(d, s.answer, s.progress);
     const focus = roots ? roots.join(",") : null;
     const run = runPin(d);
-    const key = `${focus}|${run}`;
+    const zoom = viewZoom(shownView().view);
+    const key = `${focus}|${run}|${zoom}`;
     if (!force && key === lastFocus) return;
     lastFocus = key;
-    if (frame && frame.contentWindow) frame.contentWindow.postMessage({ type: "behold:view", member: null, focus, run }, origin);
+    if (frame && frame.contentWindow) frame.contentWindow.postMessage({ type: "behold:view", member: null, focus, run, zoom }, origin);
+  };
+  const pickView = (view) => {
+    s.pick = { view, at: now().getTime() };
+    draw();
   };
   const draw = () => {
+    const shown = shownView();
+    s.view = shown.view;
     renderKiosk(bar, s, now(), foot);
+    renderViewToggle(views, shown, { components: s.components, onPick: pickView });
     tellFrame(false);
   };
   // #569: the pipeline's runs beside the view, CI-page style.
   if (side && main) startRuns({ side, main }, { fetchJson, now, scenarios: SCENARIOS });
-  if (frame) {
-    frame.src = frameSrc(origin);
+  // #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;
+    frame.src = frameSrc(origin, viewZoom(shownView().view));
     // The frame reads its graph after load; tell it again once it has had the time.
     frame.addEventListener("load", () => {
       for (const ms of [1500, 4000, 8000]) setTimeout(() => tellFrame(true), ms);
     });
-  }
+  };
+  void fetchJson("/api/project").then((p) => {
+    s.components = !!(p && !p.error && p.terragucciComponents);
+    openFrame();
+    draw();
+  });
 
   const reports = async (fresh) => {
     s.answer = await fetchJson(`/api/terragucci${fresh ? "?fresh=1" : ""}`);
@@ -413,7 +562,7 @@ export function startKiosk({ bar, frame, foot, side, main }, { fetchJson = defau
   // #569: the run view of the cycle's commit, the same one the frame draws.
   const pinnedCommit = () => {
     const pin = runPin(s.demo && s.demo.demo);
-    return pin && pin !== "none" && pin !== "base" ? pin : null;
+    return pinsCommit(pin) ? pin : null;
   };
   const progress = async (fresh) => {
     const pin = pinnedCommit();

package/web/kiosk.test.js

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
-import { focusRoots, frameSrc, factLines, pendingApproval, runPin } from "./kiosk.js";
+import { STEP_VIEW, STEP_WORDS, aboutRows, focusRoots, 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 });
 const answer = {
@@ -54,8 +55,10 @@ describe("factLines (#569)", () => {
 
 describe("runPin: the frame stays on the cycle's run (#569)", () => {
   it("draws the pull request's plan, then the cycle's commit up to applied, then the base", () => {
-    expect(runPin(demo("pull-request"))).toBe("none");
-    expect(runPin(demo("planned"))).toBe("none");
+    expect(runPin(demo("pull-request"))).toBe("pull-7-abc12345");
+    expect(runPin(demo("planned"))).toBe("pull-7-abc12345");
+    expect(runPin(demo("pull-request", { commit: null }))).toBe("pull-7");
+    expect(runPin(demo("pull-request", { pull: null, commit: null }))).toBe("pull");
     for (const step of ["merged", "applying", "waiting", "approved", "failed", "resumed", "applied"]) expect(runPin(demo(step))).toBe("abc12345");
     expect(runPin(demo("reset"))).toBe("base");
     expect(runPin(demo("applied", { scenario: "base" }))).toBe("base");
@@ -63,3 +66,157 @@ describe("runPin: the frame stays on the cycle's run (#569)", () => {
     expect(runPin(null)).toBe(null);
   });
 });
+
+describe("before the merge, no other cycle's plan (#569)", () => {
+  // Cycle 441's narration at pull-request 989, while the reports' newest plan is cycle 439's pull request 987.
+  const older = { ...answer, pull_request: { ...answer.pull_request, run: { pull_request: "987", commit: "365a4f0d" } } };
+  const sameNumberOtherCommit = { ...answer, pull_request: { ...answer.pull_request, run: { pull_request: "989", commit: "0badc0de" } } };
+  const ours = { ...answer, pull_request: { ...answer.pull_request, run: { pull_request: "989", commit: "659dee43" } } };
+  const now = (step) => demo(step, { pull: 989, commit: "659dee43" });
+  it("pins the frame to this cycle's pull request and commit at pull-request and planned", () => {
+    for (const step of ["pull-request", "planned"]) {
+      expect(runPin(now(step))).toBe("pull-989-659dee43");
+      expect(matchingPull(older, now(step))).toBe(null);
+      expect(matchingPull(sameNumberOtherCommit, now(step))).toBe(null);
+      expect(matchingPull(ours, now(step))).toBe(ours.pull_request);
+      expect(focusRoots(now(step), older, null)).toBe(null);
+      expect(factLines(now(step), older)).toEqual([]);
+      expect(runPanel(now(step), older, null).note).toBe("The plan of pull request #989 isn't in the reports yet: the pipeline is planning it.");
+    }
+  });
+  it("from the merge on, takes the plan by its number: demo.json's commit is the merge's", () => {
+    expect(matchingPull(ours, demo("merged", { pull: 989, commit: "53c1e5d2" }))).toBe(ours.pull_request);
+    expect(matchingPull(older, demo("merged", { pull: 989, commit: "53c1e5d2" }))).toBe(null);
+  });
+});
+
+describe("the scenario's card under the title (behold#571)", () => {
+  const about = { changes: "Network's port goes from 8080 to 9090.", watch: "Wave 2 fails partway.", shows: "Nothing here is atomic." };
+
+  it("has three rows in order, labelled as the kiosk draws them", () => {
+    expect(aboutRows(demo("failed", { about }))).toEqual([
+      { label: "What changes", text: about.changes },
+      { label: "Watch for", text: about.watch },
+      { label: "Shows", text: about.shows },
+    ]);
+  });
+
+  it("has no rows when demo.json has no card", () => {
+    expect(aboutRows(demo("reset", { scenario: "base", about: null }))).toEqual([]);
+    expect(aboutRows(demo("reset"))).toEqual([]);
+  });
+
+  // A DOM just big enough for renderKiosk: elements with a class, text and children.
+  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) : [])));
+
+  it("draws the card right under the title, and none without about", () => {
+    const was = globalThis.document;
+    globalThis.document = fakeDocument();
+    try {
+      const bar = document.createElement("header");
+      const s = { demo: { source: "fx", read: "2026-10-15T03:00:00Z", demo: demo("failed", { scenario: "failure", about }) }, answer: null, progress: null };
+      renderKiosk(bar, s, new Date("2026-10-15T03:01:00Z"));
+      const left = find(bar, "k-left")[0];
+      const kinds = left.children.map((c) => c.className.split(" ")[0]);
+      expect(kinds.indexOf("k-about")).toBe(kinds.indexOf("k-title") + 1);
+      const card = find(bar, "k-about")[0];
+      expect(card.tagName).toBe("dl");
+      expect(card.children.map((c) => [c.tagName, c.textContent])).toEqual([
+        ["dt", "What changes"], ["dd", about.changes],
+        ["dt", "Watch for"], ["dd", about.watch],
+        ["dt", "Shows"], ["dd", about.shows],
+      ]);
+
+      s.demo.demo = demo("reset", { scenario: "base", about: null });
+      renderKiosk(bar, s, new Date("2026-10-15T03:01:00Z"));
+      expect(find(bar, "k-about")).toEqual([]);
+    } finally {
+      globalThis.document = was;
+    }
+  });
+});
+
+describe("which view the frame shows (#571)", () => {
+  it("shows the resources for the pull request's steps and the roots by wave from the merge on", () => {
+    for (const step of ["pull-request", "planned"]) expect(stepView(step)).toBe("resources");
+    for (const step of ["merged", "applying", "waiting", "approved", "failed", "resumed", "applied", "reset"]) expect(stepView(step)).toBe("components");
+    expect(Object.keys(STEP_VIEW).sort()).toEqual(Object.keys(STEP_WORDS).sort());
+  });
+
+  it("follows the step, and only the resources when the repo offers no components zoom", () => {
+    expect(kioskView(demo("planned"), { components: true })).toEqual({ view: "resources", pinned: false, secs: null });
+    expect(kioskView(demo("waiting"), { components: true })).toEqual({ view: "components", pinned: false, secs: null });
+    expect(kioskView(demo("waiting"), { components: false })).toEqual({ view: "resources", pinned: false, secs: null });
+    expect(kioskView(demo("waiting"), { components: false, pick: { view: "components", at: 0 }, now: 1000 }).view).toBe("resources");
+    expect(kioskView(null, { components: true }).view).toBe("resources");
+  });
+
+  it("holds a clicked view for 90 s after the last click, then follows the step again", () => {
+    const pick = { view: "resources", at: 1_000_000 };
+    expect(PICK_HOLD_MS).toBe(90_000);
+    expect(kioskView(demo("applying"), { components: true, pick, now: 1_000_000 })).toEqual({ view: "resources", pinned: true, secs: 90 });
+    expect(kioskView(demo("applying"), { components: true, pick, now: 1_000_000 + 89_500 })).toEqual({ view: "resources", pinned: true, secs: 1 });
+    expect(kioskView(demo("applying"), { components: true, pick, now: 1_000_000 + 90_000 })).toEqual({ view: "components", pinned: false, secs: null });
+    // A pick of a view the toggle doesn't offer holds nothing.
+    expect(kioskView(demo("applying"), { components: true, pick: { view: "logical", at: 1_000_000 }, now: 1_000_000 }).view).toBe("components");
+  });
+
+  it("opens the frame on a view's zoom", () => {
+    expect(frameSrc("https://demo.example")).toContain("zoom=resources");
+    expect(frameSrc("https://demo.example", viewZoom("components"))).toContain("zoom=components");
+    expect(viewZoom("resources")).toBe("resources");
+    expect(viewZoom("nonsense")).toBe("resources");
+  });
+
+  it("says how to read the view shown", () => {
+    expect(legendWords("components")).toMatch(/^Each card is a Terraform root .* titled with the pipeline job that applies it/);
+    expect(legendWords("resources")).toMatch(/^Each box is a Terraform root/);
+  });
+
+  // A DOM for the toggle: elements with attributes and click listeners.
+  const toggleDocument = () => ({
+    createElement: (tag) => {
+      const n = { tagName: tag, className: "", textContent: "", children: [], attrs: {}, hidden: false, listeners: {} };
+      n.appendChild = (c) => (n.children.push(c), c);
+      n.replaceChildren = () => (n.children = []);
+      n.setAttribute = (k, v) => (n.attrs[k] = v);
+      n.addEventListener = (k, f) => (n.listeners[k] = f);
+      return n;
+    },
+  });
+
+  it("draws the toggle with the view shown pressed, says what leads, and hides without a components zoom", () => {
+    const was = globalThis.document;
+    globalThis.document = toggleDocument();
+    try {
+      const host = document.createElement("div");
+      const picked = [];
+      renderViewToggle(host, { view: "components", pinned: false, secs: null }, { components: true, onPick: (v) => picked.push(v) });
+      expect(host.hidden).toBe(false);
+      const buttons = host.children[0].children;
+      expect(buttons.map((b) => [b.textContent, b.attrs["aria-pressed"]])).toEqual([["Resources", "false"], ["Roots by wave", "true"]]);
+      expect(host.children[1].textContent).toBe("follows the step");
+      buttons[0].listeners.click();
+      expect(picked).toEqual(["resources"]);
+
+      renderViewToggle(host, { view: "resources", pinned: true, secs: 42 }, { components: true });
+      expect(host.children[1].textContent).toBe("held by a click; the step leads again in 42 s");
+
+      renderViewToggle(host, { view: "resources", pinned: false, secs: null }, { components: false });
+      expect(host.hidden).toBe(true);
+      expect(host.children).toEqual([]);
+    } finally {
+      globalThis.document = was;
+    }
+  });
+});

package/web/terragucci-change.js

@@ -553,6 +553,55 @@ export function readLabel(e) {
   return `reads ${e.to}'s applied state`;
 }
 
+/**
+ * #569: a `run` pin on one pull request's plan, as the kiosk sends it before
+ * the merge: `pull-<n>`, or `pull-<n>-<sha>` with the commit the plan is of;
+ * bare `pull` while no pull request is open. Null for any other pin.
+ */
+export function pullPin(run) {
+  const m = /^pull(?:-(\d+)(?:-([0-9a-f]{7,40}))?)?$/.exec(String(run || ""));
+  return m ? { pull: m[1] || null, commit: m[2] || null } : null;
+}
+
+/** #569: whether a pin names a commit's run view (not `none`, `base` or a pull request's plan). */
+export function pinsCommit(run) {
+  return !!run && run !== "none" && run !== "base" && !pullPin(run);
+}
+
+const sameSha = (a, b) => !!a && !!b && (a.startsWith(b) || b.startsWith(a));
+
+/** #569: whether a pull request's plan is the one a `pull-…` pin names: its number, and its commit when the pin has one. */
+export function planFitsPin(pr, pin) {
+  if (!pr || !pr.run || !pin || pin.pull === null) return false;
+  if (String(pr.run.pull_request) !== pin.pull) return false;
+  return !pin.commit || sameSha(pr.run.commit, pin.commit);
+}
+
+/**
+ * #569: the reports as the view draws them under its `run` pin. At `base`
+ * nothing is in flight; at `pull-…` only that pull request's plan, so another
+ * cycle's plan is never drawn as this one's. Anything else draws them as read.
+ */
+export function pinnedAnswer(answer, run) {
+  if (!answer || answer.error) return answer;
+  const pin = pullPin(run);
+  if (run === "base" || (pin && !planFitsPin(answer.pull_request, pin))) return { ...answer, pull_request: null };
+  return answer;
+}
+
+/**
+ * #569: the sentence above the boxes when the pin holds the view off every
+ * plan and run: the base, or a pull request whose plan isn't written yet.
+ * Null when the view draws a run, and viewCaption says which.
+ */
+export function pinnedCaption(answer, run) {
+  if (run === "base") return "Nothing in flight: the states went back to the base";
+  const pin = pullPin(run);
+  if (!pin || (answer && !answer.error && planFitsPin(answer.pull_request, pin))) return null;
+  if (pin.pull === null) return "The pull request isn't open yet; its plan shows here once the plan job writes it";
+  return `Pull request #${pin.pull} is being planned; its plan shows here once the plan job writes it`;
+}
+
 /** Which run the view's marks come from, dated: "the plan of pull request #201, 03:11 UTC". */
 export function viewCaption(answer, progress, now = new Date()) {
   const stage = changeStage(answer, progress);

package/web/terragucci-change.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { readCardIds, readLabel, rootStates, viewCaption } from "./terragucci-change.js";
+import { pinnedAnswer, pinnedCaption, pinsCommit, pullPin, readCardIds, readLabel, rootStates, viewCaption } from "./terragucci-change.js";
 
 const roots = ["app", "edge", "network", "other"].map((name) => ({ member: "demo", name, path: name }));
 const prAnswer = {
@@ -97,3 +97,38 @@ describe("viewCaption (#569)", () => {
     expect(viewCaption(prAnswer, run([{ number: 1, state: "applied", roots: ["network"], reads: [] }], []), now)).toBe("the run of merge 6b9f7e25, as of 03:20 UTC");
   });
 });
+
+describe("a pin on one pull request's plan (#569)", () => {
+  it("reads pull-<n>[-<sha>] and bare pull, and tells them from a commit's run view", () => {
+    expect(pullPin("pull-201-c9dfc649")).toEqual({ pull: "201", commit: "c9dfc649" });
+    expect(pullPin("pull-201")).toEqual({ pull: "201", commit: null });
+    expect(pullPin("pull")).toEqual({ pull: null, commit: null });
+    expect(pullPin("c9dfc649")).toBe(null);
+    expect(pinsCommit("c9dfc649")).toBe(true);
+    for (const p of ["pull-201", "none", "base", null]) expect(pinsCommit(p)).toBe(false);
+  });
+  it("draws the pinned pull request's plan, of its commit", () => {
+    expect(pinnedAnswer(prAnswer, "pull-201-c9dfc649")).toBe(prAnswer);
+    expect(pinnedAnswer(prAnswer, "pull-201")).toBe(prAnswer);
+    expect(pinnedCaption(prAnswer, "pull-201-c9dfc649")).toBe(null);
+    expect(rootStates(pinnedAnswer(prAnswer, "pull-201"), null).stage).toBe("pull-request");
+  });
+  it("draws no other cycle's plan before this cycle's is written: no marks, and says it is being planned", () => {
+    for (const pin of ["pull-202", "pull-202-c9dfc649", "pull-201-0123abcd", "pull"]) {
+      const drawn = pinnedAnswer(prAnswer, pin);
+      expect(drawn.pull_request).toBe(null);
+      expect(rootStates(drawn, null)).toEqual({ stage: "none", roots: {} });
+      expect(viewCaption(drawn, null)).toBe(null);
+    }
+    expect(pinnedCaption(prAnswer, "pull-202-c9dfc649")).toBe("Pull request #202 is being planned; its plan shows here once the plan job writes it");
+    expect(pinnedCaption({ roots }, "pull-202")).toBe("Pull request #202 is being planned; its plan shows here once the plan job writes it");
+    expect(pinnedCaption(prAnswer, "pull")).toBe("The pull request isn't open yet; its plan shows here once the plan job writes it");
+  });
+  it("leaves the newest plan to an unpinned view, and none to the base", () => {
+    expect(pinnedAnswer(prAnswer, null)).toBe(prAnswer);
+    expect(pinnedAnswer(prAnswer, "none")).toBe(prAnswer);
+    expect(pinnedAnswer(prAnswer, "base").pull_request).toBe(null);
+    expect(pinnedCaption(prAnswer, "none")).toBe(null);
+    expect(pinnedCaption(prAnswer, "base")).toBe("Nothing in flight: the states went back to the base");
+  });
+});