@intentius/behold 0.29.7 → 0.29.9

package/web/kiosk.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-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 { INTRO_HEAD, STEP_VIEW, STEP_WORDS, aboutRows, approvalPanel, 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 });
@@ -127,8 +127,9 @@ describe("the scenario's card under the title (behold#571)", () => {
       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);
+      // behold#571: the title, the card and the step, each in its own fixed box.
+      expect(left.children.map((c) => c.className.split(" ")[0])).toEqual(["k-box", "k-box", "k-box"]);
+      expect(left.children.map((c) => c.children.map((x) => x.className.split(" ")[0]))).toEqual([["k-title"], ["k-about"], ["k-step"]]);
       const card = find(bar, "k-about")[0];
       expect(card.tagName).toBe("dl");
       expect(card.children.map((c) => [c.tagName, c.textContent])).toEqual([
@@ -140,6 +141,65 @@ describe("the scenario's card under the title (behold#571)", () => {
       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([]);
+
+      // behold#571: no intro band at a live step; between scenarios the intro takes the card's box.
+      const intro = "Terraform keeps what it built in a state file.";
+      s.demo.demo = demo("waiting", { scenario: "failure", about, intro });
+      renderKiosk(bar, s, new Date("2026-10-15T03:01:00Z"));
+      expect(find(bar, "k-intro")).toEqual([]);
+      s.demo.demo = demo("reset", { scenario: "failure", about, intro });
+      renderKiosk(bar, s, new Date("2026-10-15T03:01:00Z"));
+      const shown = find(bar, "k-intro");
+      expect(shown).toHaveLength(1);
+      expect(shown[0].children.map((c) => c.textContent)).toEqual([INTRO_HEAD, intro]);
+      expect(find(bar, "k-about")).toEqual([]);
+    } finally {
+      globalThis.document = was;
+    }
+  });
+});
+
+describe("the approval panel's drawing (behold#571)", () => {
+  // A DOM with what the panel's chip needs: attributes, data and a click.
+  const panelDocument = () => ({
+    createElement: (tag) => {
+      const n = { tagName: tag, className: "", textContent: "", children: [], attrs: {}, dataset: {}, listeners: {} };
+      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.setAttribute = (k, v) => (n.attrs[k] = v);
+      n.addEventListener = (k, f) => (n.listeners[k] = f);
+      return n;
+    },
+  });
+  const find = (n, cls) => ((n.className || "").split(" ").includes(cls) ? [n] : []).concat(...(n.children || []).map((c) => find(c, cls)));
+
+  it("draws four rows, lit as the model says, and a chip that shows its log line", () => {
+    const was = globalThis.document;
+    globalThis.document = panelDocument();
+    try {
+      const a = { id: "T11", product: "terragucci", feature: "Waiting for approval", note: "The wave stops here.", docs: { product: "terragucci", path: "/guides/approve-a-wave/" } };
+      const line = { run: 444, job: "apply-wave-2", step: 2, n: 13, a };
+      const shown = [];
+      const model = {
+        wave: 2,
+        digest: "jcs1-sha256:0accc105ba060b9974468c91def518039d935ad6629f8a15869f6e89ef748b61",
+        rows: [
+          { id: "requested", label: "Requested", state: "lit", text: "Wave 2 asked for an approval of this plan.", at: "2026-10-15T04:09:41Z", commit: "57869649aaaa", line },
+          { id: "approved", label: "Approved", state: "dim", text: "Next the driver signs.", command: "chant approve tf-apply wave-2" },
+          { id: "resumed", label: "Resumed", state: "dim", text: "Then the waves run again." },
+          { id: "spent", label: "Spent", state: "dim", text: "Then the approval is used up." },
+        ],
+      };
+      const panel = approvalPanel(model, { showLine: (l) => shown.push(l) });
+      const head = find(panel, "k-ap-head")[0];
+      expect([head.textContent, ...head.children.map((c) => c.textContent)].join("")).toBe("How this hold ends · wave 2 plan 0accc105ba06 · times in UTC");
+      expect(find(panel, "k-ap-row").map((r) => r.className)).toEqual(["k-ap-row k-ap-lit", "k-ap-row k-ap-dim", "k-ap-row k-ap-dim", "k-ap-row k-ap-dim"]);
+      expect(find(panel, "k-ap-facts")[0].textContent).toBe("04:09:41 · ledger 57869649");
+      expect(find(panel, "k-command")[0].textContent).toBe("chant approve tf-apply wave-2");
+      const chip = find(panel, "r-ann")[0];
+      expect(chip.textContent).toBe("terragucci · Waiting for approval");
+      chip.listeners.click();
+      expect(shown).toEqual([line]);
     } finally {
       globalThis.document = was;
     }
@@ -174,6 +234,9 @@ describe("which view the frame shows (#571)", () => {
   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");
+    // behold#571: the kiosk's theme goes to the frame with the repo.
+    expect(frameSrc("https://demo.example", "components", "demo", "Dawnfox")).toContain("theme=Dawnfox");
+    expect(frameSrc("https://demo.example", "components", null, null)).not.toContain("theme=");
     expect(viewZoom("resources")).toBe("resources");
     expect(viewZoom("nonsense")).toBe("resources");
   });
@@ -247,11 +310,13 @@ describe("the kiosk for a viewer new to the demo (behold#571)", () => {
     }
   };
 
-  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([]);
+  it("shows the intro in the card's box between scenarios, never as a band, and none without one", () => {
+    // behold#571: a live step has no intro band; "What is this?" holds it.
+    expect(find(draw(demo("planned", { intro })).bar, "k-intro")).toEqual([]);
+    const shown = find(draw(demo("reset", { intro })).bar, "k-intro");
+    expect(shown).toHaveLength(1);
+    expect(shown[0].children.map((c) => c.textContent)).toEqual([INTRO_HEAD, intro]);
+    expect(find(draw(demo("reset")).bar, "k-intro")).toEqual([]);
     expect(find(draw(demo("planned", { intro: null })).bar, "k-intro")).toEqual([]);
     expect(introText(demo("planned", { intro: "   " }))).toBe(null);
   });

package/web/theme.js

@@ -186,6 +186,114 @@ export function tokensFor(th) {
     // pending change).
     runtime: th.palette[6],   // cyan   — runtime child (expected, not drift)
     cat: [1, 2, 3, 4, 5, 6, 9, 10, 11, 12, 13, 14].map((i) => th.palette[i]),
+    ...kioskSurfaces(th),
+  };
+}
+
+// --- the kiosk's surfaces (behold#571) -------------------------------------
+// The kiosk lays several panes side by side; on one flat near-black they run
+// together. Each region gets its own calm level instead: the page, a step up
+// for the header's boxes, and two alternating pane levels, with a zebra tint
+// for list rows and softened ink for text. All derived from the palette, so
+// every theme gets them; theme.test.js holds the floors across the corpus.
+
+/** The zebra row's tint: this share of --fg over the row's surface. */
+export const ZEBRA = 0.035;
+/** The surfaces' steps in OKLCH lightness from --bg, toward --fg's side. */
+export const SURFACE_STEPS = { box: 0.03, paneA: 0.055, paneB: 0.08 };
+/** How bright body ink may get against --bg: softer than a pure white on near-black. */
+export const SOFT_CEILING = 13;
+/** The least OKLCH lightness between two neighbouring levels, so each reads as its own box. */
+export const MIN_STEP = 0.02;
+
+/** The root dots' hues, by theme (behold#571): violet, orange, orchid, silver, tan. Never a state's. */
+export const ROOT_HUES = {
+  dark: ["#b392f0", "#ff9f5a", "#e66ce8", "#e4e4e4", "#c89b6d"],
+  light: ["#7c3aed", "#c2410c", "#a21caf", "#334155", "#8b5a2b"],
+};
+
+/** A colour pushed until it clears `floor` against every one of `against` (worst first). */
+function pushAll(hex, against, floor, dark) {
+  let out = hex;
+  for (let i = 0; i < 4; i++) {
+    const worst = against.reduce((w, b) => (contrast(out, b) < contrast(out, w) ? b : w), against[0]);
+    if (contrast(out, worst) >= floor) return out;
+    out = pushForContrast(out, worst, floor, dark);
+  }
+  return out;
+}
+
+/**
+ * The surfaces and the ink that reads on them: `surfaceBox` (the header's
+ * boxes), `surfacePaneA` and `surfacePaneB` (the panes, alternating), each a
+ * step further from --bg in OKLCH lightness (lighter on a dark theme, darker
+ * on a light one; the other way where the palette leaves no room), `zebra`
+ * (the tint list rows alternate with), `soft` (body ink: --fg, eased toward
+ * --bg where it would glare, and never under 4.5:1 on any surface or zebra
+ * row), `mutedInk` (secondary ink, 3:1 on all of them), each state colour's
+ * `*Ink` (3:1 on all of them) and `roots` (the root dots, 3:1 on all of them).
+ */
+export function kioskSurfaces(th) {
+  const b = hexToOklch(th.bg);
+  const f = hexToOklch(th.fg);
+  // Toward fg's side (lighter on a dark theme), unless that runs out of room or
+  // eats the text's headroom on a mid-tone ground (Blue Dolphin, Hot Dog Stand).
+  // The ink's side: --fg's, unless even the far end of it can't clear 4.5:1 with
+  // room to spare (white on Hot Dog Stand's red): then the other side.
+  let inkUp = f.L >= b.L;
+  if (contrast(inkUp ? "#ffffff" : "#000000", th.bg) < 5.5) inkUp = !inkUp;
+  const fgSide = inkUp === f.L >= b.L;
+  const towardInk = inkUp ? 1 : -1;
+  const roomFor = (d) => (d > 0 ? b.L + 0.12 <= 0.97 : b.L - 0.12 >= 0.03);
+  const want = fgSide && contrast(th.fg, th.bg) >= 7 ? towardInk : -towardInk;
+  const dir = roomFor(want) ? want : -want;
+  // Each level at least MIN_STEP of OKLCH lightness past the one before, as the
+  // colour rounds to 8 bits (near black, small steps all round to #000000).
+  const levels = [];
+  let prev = b.L;
+  for (const dl of [SURFACE_STEPS.box, SURFACE_STEPS.paneA - SURFACE_STEPS.box, SURFACE_STEPS.paneB - SURFACE_STEPS.paneA]) {
+    let want = prev + dir * dl;
+    let hex = oklchToHex({ ...b, L: clamp(want, 0, 1) });
+    for (let i = 0; i < 40 && Math.abs(hexToOklch(hex).L - prev) < MIN_STEP; i++) {
+      want += dir * 0.005;
+      hex = oklchToHex({ ...b, L: clamp(want, 0, 1) });
+    }
+    levels.push(hex);
+    prev = hexToOklch(hex).L;
+  }
+  const [surfaceBox, surfacePaneA, surfacePaneB] = levels;
+  const surfaces = [th.bg, surfaceBox, surfacePaneA, surfacePaneB];
+  const grounds = [...surfaces, ...surfaces.map((s) => mix(s, th.fg, ZEBRA))];
+  const lightInk = inkUp;
+  // Body ink: --fg eased toward --bg until it sits at SOFT_CEILING, then held at 4.5:1 on every ground.
+  let soft = fgSide ? th.fg : inkUp ? "#ffffff" : "#000000";
+  if (fgSide && contrast(th.fg, th.bg) > SOFT_CEILING) {
+    let lo = 0, hi = 1;
+    for (let i = 0; i < 20; i++) {
+      const t = (lo + hi) / 2;
+      if (contrast(mix(th.fg, th.bg, t), th.bg) > SOFT_CEILING) lo = t;
+      else hi = t;
+    }
+    soft = mix(th.fg, th.bg, lo);
+  }
+  soft = pushAll(soft, grounds, 4.5, lightInk);
+  const muted = pushAll(desaturate(mix(th.bg, th.fg, 0.5), 0.75), grounds, 3, lightInk);
+  const P = th.palette;
+  const ink = (c) => pushAll(c, grounds, 3, lightInk);
+  const hues = th.dark ? ROOT_HUES.dark : ROOT_HUES.light;
+  return {
+    surfaceBox,
+    surfacePaneA,
+    surfacePaneB,
+    zebra: th.fg,
+    soft,
+    mutedInk: muted,
+    managedInk: ink(P[2]),
+    foreignInk: ink(P[3]),
+    pendingInk: ink(P[4]),
+    degradedInk: ink(P[1]),
+    runtimeInk: ink(P[6]),
+    roots: hues.map(ink),
   };
 }
 
@@ -193,6 +301,8 @@ export function tokensFor(th) {
 // block in index.html mirrors these for the DEFAULT theme — smoke/ui-smoke.mjs
 // recomputes it from here and fails if the two ever drift apart.
 const CSS_VARS = ["bg", "panel", "line", "fg", "muted", "edge", "managed", "foreign", "pending", "degraded", "neutral", "runtime", "rule", "focus", "active", "well", "shadow"];
+// behold#571: the kiosk's surfaces and ink, as --surface-box, --soft, --managed-ink and the like; the root dots as --root-0 … --root-4.
+const KIOSK_VARS = { surfaceBox: "surface-box", surfacePaneA: "surface-pane-a", surfacePaneB: "surface-pane-b", zebra: "zebra", soft: "soft", mutedInk: "muted-ink", managedInk: "managed-ink", foreignInk: "foreign-ink", pendingInk: "pending-ink", degradedInk: "degraded-ink", runtimeInk: "runtime-ink" };
 
 // pinhole (the graph painter) reads its OWN vars, `--pin-<token>` (emitted as
 // `var(--pin-token, <baked default>)`). Derive them from the active Ghostty theme so the graph
@@ -249,6 +359,8 @@ export function applyTheme(tokens = _tokens) {
   if (!tokens || typeof document === "undefined") return;
   const root = document.documentElement;
   for (const k of CSS_VARS) root.style.setProperty("--" + k, tokens[k]);
+  for (const [k, v] of Object.entries(KIOSK_VARS)) if (tokens[k]) root.style.setProperty("--" + v, tokens[k]);
+  (tokens.roots || []).forEach((c, i) => root.style.setProperty(`--root-${i}`, c));
   if (_active) { const pin = pinTokensFor(_active); for (const k of PIN_VARS) root.style.setProperty("--pin-" + k, pin[k]); }
   root.style.setProperty("color-scheme", tokens.dark ? "dark" : "light");
 }

package/web/theme.test.js

@@ -6,7 +6,7 @@
 // sweeps all 552 palettes for the same assertion; this pins the exact
 // palette the issue was filed against, with no browser involved.
 import { describe, it, expect } from "vitest";
-import { contrast, desaturate, mix, tokensFor } from "./theme.js";
+import { MIN_STEP, SOFT_CEILING, ZEBRA, contrast, desaturate, hexToOklch, mix, tokensFor } from "./theme.js";
 import { THEMES } from "./themes.js";
 
 describe("tokensFor — the --muted contrast floor (#240)", () => {
@@ -33,3 +33,53 @@ describe("tokensFor — the --muted contrast floor (#240)", () => {
     }
   });
 });
+
+// behold#571: the kiosk's surfaces. The page, the header's boxes and two
+// alternating pane levels, a zebra tint for list rows, softened body ink, and
+// the state and root colours as ink: every shipped palette has to come out
+// of tokensFor() with each region its own box and every word legible on it.
+describe("tokensFor — the kiosk's surfaces (behold#571)", () => {
+  const each = (fn) => {
+    const bad = [];
+    for (const th of Object.values(THEMES)) {
+      const t = tokensFor(th);
+      const surfaces = [th.bg, t.surfaceBox, t.surfacePaneA, t.surfacePaneB];
+      const grounds = [...surfaces, ...surfaces.map((x) => mix(x, t.zebra, ZEBRA))];
+      const why = fn(t, th, { surfaces, grounds });
+      if (why) bad.push(`${th.name}: ${why}`);
+    }
+    return bad;
+  };
+
+  it("keeps body ink at 4.5:1 or better on every surface and zebra row", () => {
+    expect(each((t, _th, { grounds }) => grounds.filter((g) => contrast(t.soft, g) < 4.5).map((g) => `${t.soft} on ${g} is ${contrast(t.soft, g).toFixed(2)}`)[0])).toEqual([]);
+  });
+
+  it("keeps secondary ink at 3:1 or better on every surface and zebra row", () => {
+    expect(each((t, _th, { grounds }) => grounds.filter((g) => contrast(t.mutedInk, g) < 3).map((g) => `${t.mutedInk} on ${g} is ${contrast(t.mutedInk, g).toFixed(2)}`)[0])).toEqual([]);
+  });
+
+  it("keeps the state colours and the root colours at 3:1 or better on every surface and zebra row", () => {
+    const inks = (t) => [t.managedInk, t.foreignInk, t.pendingInk, t.degradedInk, t.runtimeInk, ...t.roots];
+    expect(each((t, _th, { grounds }) => inks(t).flatMap((c) => grounds.filter((g) => contrast(c, g) < 3).map((g) => `${c} on ${g}`))[0])).toEqual([]);
+  });
+
+  it("tells each surface from the one beside it: at least MIN_STEP of OKLCH lightness apart", () => {
+    expect(each((_t, _th, { surfaces }) => {
+      const L = surfaces.map((x) => hexToOklch(x).L);
+      const i = L.findIndex((l, k) => k > 0 && Math.abs(l - L[k - 1]) < MIN_STEP - 1e-9);
+      return i > 0 ? `${surfaces[i - 1]} and ${surfaces[i]} are ${Math.abs(L[i] - L[i - 1]).toFixed(3)} apart` : null;
+    })).toEqual([]);
+  });
+
+  it("softens a glaring white on near-black and leaves a calm --fg as it is", () => {
+    const glare = Object.values(THEMES).find((th) => th.fg.toLowerCase() === "#ffffff" && th.bg.toLowerCase() === "#000000");
+    const t = tokensFor(glare);
+    expect(t.soft.toLowerCase()).not.toBe("#ffffff");
+    // At the ceiling, give or take the 8-bit rounding of the eased colour.
+    expect(contrast(t.soft, glare.bg)).toBeLessThanOrEqual(SOFT_CEILING + 0.15);
+    expect(contrast(t.soft, glare.bg)).toBeLessThan(contrast(glare.fg, glare.bg));
+    const mocha = tokensFor(THEMES["Catppuccin Mocha"]);
+    expect(mocha.soft).toBe(THEMES["Catppuccin Mocha"].fg);
+  });
+});

package/web/view-repo.js

@@ -0,0 +1,44 @@
+// behold#571: the repo this page reads, on a server that serves several
+// (`behold serve --repos`). The kiosk opens behold's own page in its frame
+// with `?repo=<name>`; every read the page makes then carries it, so the
+// graph, the reports and the popover are that repo's. Imported first by
+// app.js, so the wrap is in place before the page's first read. Without
+// `repo` in the address nothing changes.
+
+/** The page's `repo`, or null. */
+export function pageRepo(search) {
+  const v = new URLSearchParams(search || "").get("repo");
+  return v ? v : null;
+}
+
+/** `url` with `repo` set, when it is one of this server's /api/ reads; otherwise `url` unchanged. */
+export function withRepo(url, repo, origin) {
+  if (!repo || typeof url !== "string") return url;
+  let u;
+  try {
+    u = new URL(url, origin);
+  } catch {
+    return url;
+  }
+  if (u.origin !== origin || !u.pathname.startsWith("/api/") || u.searchParams.has("repo")) return url;
+  u.searchParams.set("repo", repo);
+  return url.startsWith(origin) ? u.toString() : `${u.pathname}${u.search}${u.hash}`;
+}
+
+/** Wrap fetch and EventSource so each /api/ read carries `repo`. */
+export function followRepo(win, repo) {
+  if (!repo || !win) return;
+  const origin = win.location.origin;
+  const fetch0 = win.fetch && win.fetch.bind(win);
+  if (fetch0) win.fetch = (input, init) => fetch0(typeof input === "string" ? withRepo(input, repo, origin) : input, init);
+  const ES = win.EventSource;
+  if (ES) {
+    win.EventSource = class extends ES {
+      constructor(url, opts) {
+        super(withRepo(String(url), repo, origin), opts);
+      }
+    };
+  }
+}
+
+if (typeof window !== "undefined") followRepo(window, pageRepo(window.location.search));