@intentius/behold 0.29.8 → 0.29.10

package/dist/cli.js

@@ -21775,6 +21775,7 @@ function watchSource(projectDir, onChange, debounceMs = 200) {
     clearTimeout(timer);
     timer = setTimeout(onChange, debounceMs);
   });
+  watcher.on("error", (e) => console.warn(`behold: watching ${dir}: ${e.message}`));
   return () => {
     clearTimeout(timer);
     watcher.close();

package/package.json

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

package/web/kiosk-runs.js

@@ -658,30 +658,36 @@ export const FEATURE_LINES = 3;
  * behold#571: fold the features strip to FEATURE_LINES whole lines: what
  * would wrap past them is hidden, never cut through, and a "+N more" button
  * on the last line opens the rest. A tool's name left last on a line with
- * none of its features after it goes too. Measures the drawn list.
+ * none of its features after it goes too. Measures the drawn list, so it runs
+ * after layout and again whenever the list's width or its features change.
+ * The button shows only when it hides at least one feature (never "+0 more"),
+ * and opened, only when there is something to fold back.
  */
 export function fitFeatures(list, open, lines = FEATURE_LINES) {
   if (!list) return;
   const more = list.querySelector(".r-feats-more");
   const items = [...list.children].filter((c) => c !== more);
   for (const i of items) i.hidden = false;
-  if (open) {
-    more.hidden = false;
-    return;
-  }
   more.hidden = true;
   const tops = [...new Set(items.map((i) => i.offsetTop))].sort((a, b) => a - b);
   if (tops.length <= lines) return;
   const last = tops[lines - 1];
+  if (open) {
+    // Folded, it would hide a feature: offer to fold it back.
+    more.hidden = !items.some((i) => i.offsetTop > last && i.classList.contains("r-feat"));
+    return;
+  }
   const shown = items.filter((i) => i.offsetTop <= last);
   for (const i of items) if (i.offsetTop > last) i.hidden = true;
-  more.hidden = false;
   const count = () => items.filter((i) => i.hidden && i.classList.contains("r-feat")).length;
-  more.textContent = `+${count()} more`;
-  // The button sits on the last line: hide features from its end until it fits there.
-  while (more.offsetTop > last && shown.length) {
-    shown.pop().hidden = true;
+  if (count() > 0) {
+    more.hidden = false;
     more.textContent = `+${count()} more`;
+    // The button sits on the last line: hide features from its end until it fits there.
+    while (more.offsetTop > last && shown.length) {
+      shown.pop().hidden = true;
+      more.textContent = `+${count()} more`;
+    }
   }
   // A tool's name with none of its features shown after it.
   const vis = items.filter((i) => !i.hidden);
@@ -894,8 +900,21 @@ export function startRuns(
     const line = mark && mark.closest(".r-ann-line");
     return line ? line.dataset.annKey : null;
   };
+  // behold#571: the features strip folds by measuring its drawn lines, so it measures again
+  // when the panel's width changes (a resize, the panel opening) and once the fonts load.
+  const refitFeatures = () => fitFeatures(main.querySelector && main.querySelector(".r-feats-list"), s.featsOpen);
+  if (typeof ResizeObserver !== "undefined" && typeof Element !== "undefined" && main instanceof Element) {
+    let width = -1;
+    new ResizeObserver((entries) => {
+      const w = Math.round(entries[entries.length - 1].contentRect.width);
+      if (w === width) return;
+      width = w;
+      refitFeatures();
+    }).observe(main);
+  }
+  if (typeof document !== "undefined" && document.fonts && document.fonts.ready) document.fonts.ready.then(refitFeatures, () => {});
   if (main.addEventListener) {
-    const seen = () => (lastPointer = now().getTime());
+    const seen =() => (lastPointer = now().getTime());
     for (const ev of ["pointermove", "pointerdown", "touchstart", "wheel", "keydown"]) document.addEventListener(ev, seen, { passive: true });
     main.addEventListener("pointerover", (e) => {
       if (e.pointerType === "touch") return;

package/web/kiosk-runs.test.js

@@ -252,6 +252,33 @@ describe("the features strip, folded to whole lines (behold#571)", () => {
     expect(open.more.hidden).toBe(false);
   });
 
+  it("never shows \"+0 more\": past the last line only a tool's name, so no button", () => {
+    const items = [item("r-feats-product", 0), item("r-feat", 0), item("r-feat", 20), item("r-feat", 40), item("r-feats-product", 60)];
+    const l = list(items, 40);
+    fitFeatures(l.el, false);
+    expect(items.map((i) => i.hidden)).toEqual([false, false, false, false, true]);
+    expect(l.more.hidden).toBe(true);
+    expect(l.more.textContent).not.toBe("+0 more");
+  });
+
+  it("shows \"+N more\" with N the features hidden, and no button once a wider list fits them all", () => {
+    const items = [item("r-feat", 0), item("r-feat", 20), item("r-feat", 40), item("r-feat", 60), item("r-feat", 60), item("r-feat", 80)];
+    const l = list(items, 40);
+    fitFeatures(l.el, false);
+    expect(l.more).toMatchObject({ hidden: false, textContent: "+3 more" });
+    // Measured again after the list widened: everything on three lines.
+    for (const [i, top] of [0, 0, 20, 20, 40, 40].entries()) items[i].offsetTop = top;
+    fitFeatures(l.el, false);
+    expect(items.every((i) => !i.hidden)).toBe(true);
+    expect(l.more.hidden).toBe(true);
+  });
+
+  it("opened, offers to fold back only when folding would hide a feature", () => {
+    const open = list([item("r-feat", 0), item("r-feat", 20), item("r-feat", 40), item("r-feats-product", 60)], 60);
+    fitFeatures(open.el, true);
+    expect(open.more.hidden).toBe(true);
+  });
+
   it("drops a tool's name left last on a line with none of its features after it", () => {
     const items = [item("r-feat", 0), item("r-feat", 20), item("r-feats-product", 40), item("r-feat", 60)];
     const l = list(items, 40);

package/web/kiosk-vendor.js

@@ -336,14 +336,31 @@ export function replayBanner(cycle, minutes) {
   return Number.isInteger(minutes) && minutes > 0 ? `${head} · live again in about ${minutes} min` : head;
 }
 
-/** The page's words when the tool's scenario has no cycle yet. */
-export function notRunWords(vendor) {
+/** The page's words when the tool's scenario has no cycle yet; with `graph`, they say the graph below is its repo on the base. */
+export function notRunWords(vendor, { graph = false } = {}) {
+  const text = `The ${vendor.name} scenario shows here once it has run through the demo's pipeline.`;
   return {
     title: "This scenario hasn't run yet",
-    text: `The ${vendor.name} scenario shows here once it has run through the demo's pipeline.`,
+    text: graph ? `${text} Below, its repo as it stands on the base.` : text,
   };
 }
 
+/**
+ * The view checkout of a tool's repo, by the names terragucci's demo driver
+ * gives the repos: `demo` for Terraform, `demo-<tool>` for the others. Null
+ * for a tool with no page.
+ */
+export function toolCheckout(tool) {
+  if (!vendorOf(tool)) return null;
+  return tool === "terraform" ? "demo" : `demo-${tool}`;
+}
+
+/** behold#571: the checkout a tool's page shows before its first cycle names its repo: the tool's, when this behold serves it (`/api/project`'s viewRepos); null otherwise. */
+export function notRunRepo(tool, served) {
+  const name = toolCheckout(tool);
+  return name && Array.isArray(served) && served.includes(name) ? name : null;
+}
+
 /** The legend's words, without naming a competing engine on an engine's page. */
 export function rootWord(tool) {
   return namesOther("Terraform", tool) ? "a root" : "a Terraform root";

package/web/kiosk-vendor.test.js

@@ -15,6 +15,7 @@ import {
   liveFor,
   linkSegments,
   namesOther,
+  notRunRepo,
   notRunWords,
   otherTerms,
   replayAt,
@@ -25,6 +26,7 @@ import {
   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 });
@@ -246,6 +248,20 @@ describe("a tool's page, drawn (behold#571)", () => {
       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;

package/web/kiosk.html

@@ -137,6 +137,7 @@
       .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-empty { background: 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); }
@@ -217,6 +218,8 @@
         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-what-pop .k-what-more { margin-top: 0.5em; }
+      #k-what-pop a { color: var(--focus); }
       .k-menu summary { cursor: pointer; color: var(--muted); list-style: none; }
       .k-menu summary::-webkit-details-marker { display: none; }
       .k-menu summary::after { content: " ▾"; }
@@ -228,6 +231,9 @@
       /* 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) and (min-width: 601px) { #bar { grid-template-columns: 1fr; } #stage, body.k-nograph #stage { grid-template-columns: 1fr; } }
       /*

package/web/kiosk.js

@@ -17,7 +17,7 @@ import { PICK_HOLD_MS, annMark, mergeRun, startRuns } from "./kiosk-runs.js";
 import { PANEL_STEPS, PANEL_TITLE, approvalModel, cycleRuns, rowFacts, shortDigest } from "./kiosk-approval.js";
 import { getThemeName, mountThemePicker, onThemeChange } from "./theme.js";
 import { cssString, hoverCss, hoverFromMessage, hoverLinks, hoverMessage, isLightBg, rootSegments, rootText } from "./kiosk-roots.js";
-import { creditLines, filterIndex, keepRun, liveEstimate, liveFor, namesOther, notRunWords, replayAt, replayBanner, replayIndex, rootWord, runAsOf, scrubDemo, servesRepo, vendorOf } from "./kiosk-vendor.js";
+import { creditLines, filterIndex, keepRun, liveEstimate, liveFor, namesOther, notRunRepo, notRunWords, replayAt, replayBanner, replayIndex, rootWord, runAsOf, scrubDemo, servesRepo, vendorOf } from "./kiosk-vendor.js";
 import { repoParam, repoUrl } from "./kiosk-repo.js";
 import { STATE_WORDS, changingRoots, costLine, pinsCommit, planFitsPin, pullPin, readEdges, rootsCount, totalsLine, waveRows, blastRows } from "./terragucci-change.js";
 
@@ -496,7 +496,7 @@ function drawBar(bar, s, now, foot) {
   const vendor = vendorOf(s.vendor);
   if (vendor && s.mode === "none") {
     // behold#571: the tool's scenario has no cycle yet: its name, its link, and a calm line.
-    const words = notRunWords(vendor);
+    const words = notRunWords(vendor, { graph: !!s.notRunGraph });
     const box = el("div", "k-empty");
     const title = el("h1", "k-title");
     title.append(brandEl(vendor), el("span", "k-title-text", words.title));
@@ -584,6 +584,8 @@ function drawBar(bar, s, now, foot) {
     if (panel.note) holdBox.appendChild(elRoots("p", "k-note", panel.note, s));
     else if (panel.stage === "pull-request") for (const u of unreviewedLines(s.answer)) holdBox.appendChild(elRoots("p", "k-note k-unknown", u, s));
   }
+  // behold#571: render what's present: an empty hold keeps its place (nothing moves when one comes) but draws no box.
+  if (!holdBox.children.length) holdBox.className += " k-box-empty";
   right.appendChild(holdBox);
   bar.appendChild(right);
 
@@ -691,8 +693,9 @@ export const LEDGER_POLL_MS = 10_000;
 /** behold#571: the approval panel's words for the approval the driver gives next, over its command. */
 export const DRIVER_SIGNS = "Next the driver plays a reviewer with no hand in the change and signs this plan with that reviewer's key:";
 
-/** behold#571: "What is this?" before demo.json says. */
-export const WHAT_FALLBACK = "A demo that runs a real infrastructure change through its pipeline in a loop, and shows each step as it happens.";
+/** behold#571: "What is this?" says what behold is; the demo's own intro stays on the card between scenarios. */
+export const WHAT_TEXT = "This is behold, a live view of infrastructure. It draws the setup as a graph and shows its pipeline runs, their logs and the approvals they wait for, as they happen. Here it watches a demo pipeline that runs one change through several Terraform states in a loop.";
+export const WHAT_DOCS = { text: "behold's documentation", url: "https://intentius.io/behold/" };
 
 /** behold#571: a fade at a box's edge where its text goes on past it. */
 function fade(b) {
@@ -723,13 +726,18 @@ export function startKiosk({ bar, frame, foot, side, main, views, tools = null }
   /** The time the page shows: the replay's, while it replays. */
   const shownNow = () => (s.mode === "replay" && s.replay && s.replay.at ? s.replay.at : now());
   /** behold#571: the frame and the plan's facts are the served repo's, so a tool's page shows them only for its own repo. */
-  const frameOk = () => !vendor || servesRepo(s.answer && !s.answer.error ? s.answer.project : null, s.repo);
+  const frameOk = () => {
+    if (!vendor) return true;
+    // Before the tool's first cycle: its repo's checkout, when this behold serves it.
+    if (s.mode === "none") return !!notRunRepo(tool, s.viewRepos) && s.aimed === notRunRepo(tool, s.viewRepos);
+    return servesRepo(s.answer && !s.answer.error ? s.answer.project : null, s.repo);
+  };
   // behold#571: a behold serving several repos (`serve --repos`) answers the
   // graph's reads from the checkout of the repo the page is about, asked by
   // name. `viewRepos` is what it serves, `aimed` the repo the reads are for.
   s.viewRepos = null;
   s.aimed = null;
-  const wantRepo = () => repoParam(s.repo, s.viewRepos);
+  const wantRepo = () => repoParam(s.repo, s.viewRepos) || (vendor && s.mode === "none" ? notRunRepo(tool, s.viewRepos) : null);
   const fetchServed = fetchJson;
   fetchJson = (url) => fetchServed(repoUrl(url, wantRepo()));
   /** When the page moves to another served repo, read its project, reports and run view again, and point the frame at it. */
@@ -745,11 +753,13 @@ export function startKiosk({ bar, frame, foot, side, main, views, tools = null }
   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);
+    // behold#571: before the tool's first cycle the frame draws its repo on the base, with nothing in flight.
+    const notRun = !!vendor && s.mode === "none";
+    const d = notRun ? null : s.demo && s.demo.demo;
+    if (!d && !notRun) return; // nothing said yet: the frame keeps its default until the narration is read
+    const roots = d ? focusRoots(d, s.answer, s.progress) : null;
     const focus = roots ? roots.join(",") : null;
-    const run = runPin(d);
+    const run = d ? runPin(d) : "base";
     const zoom = viewZoom(shownView().view);
     const key = `${focus}|${run}|${zoom}`;
     if (!force && key === lastFocus) return;
@@ -848,6 +858,7 @@ export function startKiosk({ bar, frame, foot, side, main, views, tools = null }
     s.view = shown.view;
     const ok = frameOk();
     s.noReports = !ok;
+    s.notRunGraph = !!vendor && s.mode === "none" && ok;
     s.approval = approvalNow();
     // behold#571: the header's boxes redraw every second; each keeps where a viewer scrolled it.
     const scrolled = Object.fromEntries([...bar.querySelectorAll(".k-box")].map((b) => [b.dataset.box, b.scrollTop]));
@@ -860,7 +871,11 @@ export function startKiosk({ bar, frame, foot, side, main, views, tools = null }
     whatText();
     renderViewToggle(views, shown, { components: s.components && ok, onPick: pickView });
     // behold#571: with no graph to show, the graph pane folds away and the runs and the log take its width.
-    if (typeof document !== "undefined" && document.body && document.body.classList) document.body.classList.toggle("k-nograph", !!vendor && !ok);
+    if (typeof document !== "undefined" && document.body && document.body.classList) {
+      document.body.classList.toggle("k-nograph", !!vendor && !ok);
+      // Before the tool's first cycle there are no runs and no log: those panes fold away, and the graph (when there is one) takes the width.
+      document.body.classList.toggle("k-notyet", !!vendor && s.mode === "none");
+    }
     tellFrame(false);
   };
 
@@ -947,14 +962,16 @@ export function startKiosk({ bar, frame, foot, side, main, views, tools = null }
   };
   if (tools && tools.runsToggle) tools.runsToggle.addEventListener("click", () => setRunsOpen(!document.body.classList.contains("k-runs-open")));
 
-  // behold#571: "What is this?" opens the intro over the page (no layout moves); a click elsewhere or Escape closes it.
+  // behold#571: "What is this?" opens what behold is over the page (no layout moves); a click elsewhere or Escape closes it.
   const whatText = () => {
-    if (!tools || !tools.pop) return;
-    const d = s.demo && s.demo.demo;
-    const text = (d && introText(d)) || WHAT_FALLBACK;
-    const p = tools.pop.firstElementChild;
-    if (p && p.textContent === text) return;
-    tools.pop.replaceChildren(el("p", null, text));
+    if (!tools || !tools.pop || tools.pop.firstElementChild) return;
+    const docs = el("a", null, WHAT_DOCS.text);
+    docs.href = WHAT_DOCS.url;
+    docs.target = "_blank";
+    docs.rel = "noopener";
+    const more = el("p", "k-what-more");
+    more.append(docs);
+    tools.pop.replaceChildren(el("p", null, WHAT_TEXT), more);
   };
   if (tools && tools.what && tools.pop) {
     const setWhat = (open) => {