@intentius/behold 0.29.40 → 0.29.42

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/AGENTS.md +180 -10
  2. package/README.md +6 -2
  3. package/dist/cli.js +16121 -13141
  4. package/example-writes/README.md +1 -1
  5. package/example-writes/chant.config.ts +0 -6
  6. package/package.json +5 -2
  7. package/web/app.js +327 -21
  8. package/web/carve-export.js +142 -0
  9. package/web/carve-narration.js +294 -0
  10. package/web/carve-narration.test.js +48 -0
  11. package/web/change-set-overlay.js +147 -0
  12. package/web/change-set-overlay.test.js +83 -0
  13. package/web/dots-border.js +66 -0
  14. package/web/dots-border.test.js +27 -0
  15. package/web/dots-kiosk.js +279 -0
  16. package/web/dots-kiosk.test.js +60 -0
  17. package/web/dots-layout.d.ts +10 -0
  18. package/web/dots-layout.js +201 -0
  19. package/web/dots-live.js +316 -0
  20. package/web/dots-live.test.js +220 -0
  21. package/web/dots-lod.js +122 -0
  22. package/web/dots-lod.test.js +78 -0
  23. package/web/dots-recording.d.ts +7 -0
  24. package/web/dots-recording.js +247 -0
  25. package/web/dots-recording.test.js +71 -0
  26. package/web/dots-scene.js +294 -0
  27. package/web/dots-scene.test.js +118 -0
  28. package/web/dots-timeline.js +128 -0
  29. package/web/dots-timeline.test.js +83 -0
  30. package/web/dots-tour.js +153 -0
  31. package/web/dots.js +2124 -0
  32. package/web/dots.test.js +15 -0
  33. package/web/event-help-modal.js +1 -1
  34. package/web/index.html +215 -121
  35. package/web/kiosk-carve.js +225 -0
  36. package/web/kiosk-carve.test.js +26 -0
  37. package/web/kiosk-event-help-ui.js +7 -1
  38. package/web/kiosk-link.js +68 -0
  39. package/web/kiosk-link.test.js +69 -0
  40. package/web/kiosk-metrics.js +2 -2
  41. package/web/kiosk-trace.js +1 -1
  42. package/web/kiosk.html +186 -135
  43. package/web/kiosk.js +65 -7
  44. package/web/motion.js +42 -0
  45. package/web/motion.test.js +64 -0
  46. package/web/operator.js +1 -1
  47. package/web/run-playhead.js +102 -19
  48. package/web/run-playhead.test.js +81 -11
  49. package/web/terralith.html +2 -2
  50. package/web/theme.js +99 -26
  51. package/web/theme.test.js +70 -6
  52. package/web/tooltip.js +212 -0
  53. package/web/tooltip.test.js +193 -0
  54. package/web/tour-player.js +204 -0
  55. package/web/tour-player.test.js +115 -0
  56. package/web/tours/behold.tour.v1.schema.json +182 -0
  57. package/web/tours/terralith.json +330 -0
  58. package/web/trunk-lane.js +406 -0
  59. package/web/trunk-lane.test.js +224 -0
  60. package/web/workspace-gates.js +29 -4
  61. package/web/workspace-gates.test.js +23 -2
package/web/kiosk.js CHANGED
@@ -13,6 +13,7 @@
13
13
  // A wave that failed says which waves applied before it and stay applied.
14
14
  // Nothing here is all-or-nothing, and nothing says so.
15
15
 
16
+ import { linkState, linkWords, noteBack, noteRead, readFailed, shareLink } from "./kiosk-link.js";
16
17
  import { CHANT_PANEL_STEPS, chantApprovalModel } from "./chant-pr-marks.js";
17
18
  import { PICK_HOLD_MS, annMark, mergeRun, startRuns, statusIcon } from "./kiosk-runs.js";
18
19
  import { MODES, MODE_STORE, badges as waveBadges, badgeTitle, behindStep, steadyRun, captionModel, doraLine, modeStored, placeBeside, resultModel, shotFor, stepTone, tailLines } from "./kiosk-watch.js";
@@ -25,6 +26,7 @@ import { getThemeName, mountThemePicker, onThemeChange } from "./theme.js";
25
26
  import { cssString, hoverCss, hoverFromMessage, hoverLinks, hoverMessage, isLightBg, rootSegments, rootText } from "./kiosk-roots.js";
26
27
  import { creditLines, filterIndex, keepRun, liveEstimate, liveFor, namesOther, notRunRepo, notRunWords, replayAt, replayBanner, replayIndex, rootNoun, rootWord, runAsOf, scrubDemo, servesRepo, vendorOf } from "./kiosk-vendor.js";
27
28
  import { repoParam, repoUrl, stepCheckout } from "./kiosk-repo.js";
29
+ import { startKioskCarve } from "./kiosk-carve.js";
28
30
  import { STATE_WORDS, changingRoots, costLine, pinsCommit, planFitsPin, pullPin, readEdges, rootsCount, totalsLine, waveRows, blastRows } from "./terragucci-change.js";
29
31
 
30
32
  /** The scenarios terragucci#1014 numbers. An id not here is shown by the title demo.json carries. */
@@ -805,6 +807,9 @@ function drawBar(bar, s, now) {
805
807
  const r = more[i];
806
808
  left.appendChild(r ? leadRow(name, "k-row-more", r.label, elRoots("p", "k-about", r.text, s)) : leadRow(name, "k-row-more"));
807
809
  }
810
+ // The live carve's slowed playback, a quiet row of its own once the frame draws one: real time unless a person slows it.
811
+ const slowed = s.slowedControl ? s.slowedControl() : null;
812
+ if (slowed) left.appendChild(leadRow("slowed", "k-row-more", "Playback", slowed));
808
813
 
809
814
  // The pull request's facts, each a chip that wraps whole; never cut off. behold#571: no line on where the narration was read from.
810
815
  const factParts = s.noReports ? [] : factLines(demo, s.answer, nounTool(s));
@@ -992,7 +997,7 @@ function drawDrawer(host, tail, nums, open) {
992
997
  export const DRAWER_EMPTY = "The job's lines show here as it writes them.";
993
998
  /** behold#571: the drawer's two states, said on its head. */
994
999
  export const DRAWER_MORE = "Open the log";
995
- export const DRAWER_LESS = "Fold it back";
1000
+ export const DRAWER_LESS = "Close";
996
1001
 
997
1002
  /** The result card at the end of the run: the result line, the counts, and each wave's numbers. */
998
1003
  function drawResult(host, model, s) {
@@ -1197,6 +1202,8 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
1197
1202
  s.shot = null;
1198
1203
  // behold#571: event-help, started further down once what it reads is in place.
1199
1204
  let ehApi = null;
1205
+ // #715: the live carve's caption and Tips, when the frame draws one (web/kiosk-carve.js).
1206
+ let carveCtl = null;
1200
1207
  // behold#571: the run view as the cycle has seen it (steadyRun), and when a read behind the step last asked again.
1201
1208
  let runMemo = null;
1202
1209
  let freshAt = 0;
@@ -1470,6 +1477,7 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
1470
1477
  if (!s.watchMode && runsParent && main.parentNode !== runsParent) runsParent.insertBefore(main, runsNext);
1471
1478
  }
1472
1479
  if (watch) renderModeToggle(tools && tools.mode, s.watchMode ? "watch" : "inspect", setMode);
1480
+ if (carveCtl) carveCtl.tellMode();
1473
1481
  };
1474
1482
  const setMode = (m) => {
1475
1483
  const next = m === "watch";
@@ -1516,6 +1524,8 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
1516
1524
  }
1517
1525
  s.watchHeld = { secs: Math.ceil(left / 1000) };
1518
1526
  }
1527
+ /** The caption shown now: Watch's own, or the live carve's while it has the camera (#715). */
1528
+ const shownCaption = () => (carveCtl && carveCtl.caption ? carveCtl.caption() || watch.caption : watch.caption);
1519
1529
  /** behold#571: the caption's top, or event-help's trail's when it sits over the caption. */
1520
1530
  const captionTop = (cap) => {
1521
1531
  const trail = eh && eh.trailHost;
@@ -1526,7 +1536,7 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
1526
1536
  const shotInsets = (shot) => {
1527
1537
  if (!watch || !frame || isPhone() || !frame.getBoundingClientRect) return {};
1528
1538
  const f = frame.getBoundingClientRect();
1529
- const cap = watch.caption.getBoundingClientRect();
1539
+ const cap = shownCaption().getBoundingClientRect();
1530
1540
  const bottom = Math.max(0, f.bottom - captionTop(cap)) + 16;
1531
1541
  const side = shot.kind === "held" ? watch.callout : shot.kind === "active" ? watch.drawer : shot.kind === "result" ? watch.result : null;
1532
1542
  // The result card sits right beside the graph (placeBeside's gap): an inset of its width and that gap centres the two together.
@@ -1634,7 +1644,7 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
1634
1644
  }
1635
1645
  const L = watch.layer.getBoundingClientRect();
1636
1646
  const F = frame.getBoundingClientRect();
1637
- const capTop = captionTop(watch.caption.getBoundingClientRect()) - L.top;
1647
+ const capTop = captionTop(shownCaption().getBoundingClientRect()) - L.top;
1638
1648
  const view = { x: F.left - L.left, y: F.top - L.top, w: F.width, h: capTop - (F.top - L.top) };
1639
1649
  const boxOf = (n) => {
1640
1650
  const waves = (s.boxes && s.boxes.waves) || {};
@@ -1647,10 +1657,12 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
1647
1657
  return { x: x + view.x, y: y + view.y, w: Math.max(...ok.map((b) => b.x + b.w)) - x, h: Math.max(...ok.map((b) => b.y + b.h)) - y };
1648
1658
  };
1649
1659
  const taken = [];
1660
+ // While the live carve has the camera, the graph shows dots, not the wave boxes: the panes sit at the view's top right.
1661
+ const carvingNow = shownCaption() !== watch.caption;
1650
1662
  const put = (node, n) => {
1651
1663
  if (node.hidden) return;
1652
1664
  const size = { w: node.offsetWidth, h: node.offsetHeight };
1653
- const box = boxOf(n);
1665
+ const box = carvingNow ? null : boxOf(n);
1654
1666
  // Before the frame says where the box is: the right of the view, under its top.
1655
1667
  const labels = ((s.boxes && s.boxes.labels) || []).map((r) => ({ x: r.x + view.x, y: r.y + view.y, w: r.w, h: r.h }));
1656
1668
  const p = box ? placeBeside(box, size, view, 18, labels) : { x: view.x + view.w - size.w - 20, y: view.y + 20, side: "below" };
@@ -1668,7 +1680,7 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
1668
1680
  put(watch.result, null); // beside the whole graph
1669
1681
  const hits = (r) => taken.some((t) => r.x < t.x2 && r.x2 > t.x && r.y < t.y2 && r.y2 > t.y);
1670
1682
  for (const b of watch.badges.children) {
1671
- const box = boxOf(Number(b.dataset.kWave));
1683
+ const box = carvingNow ? null : boxOf(Number(b.dataset.kWave));
1672
1684
  b.classList.remove("k-placed");
1673
1685
  if (!box) continue;
1674
1686
  const w = b.offsetWidth;
@@ -1770,7 +1782,8 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
1770
1782
  boxes: s.boxes,
1771
1783
  frame,
1772
1784
  watch: s.watchMode,
1773
- caption: watch ? watch.caption : null,
1785
+ // The caption shown now: the live carve's while it has the camera (web/kiosk-carve.js).
1786
+ caption: watch ? shownCaption() : null,
1774
1787
  replay: s.mode === "replay",
1775
1788
  approveLine: appr ? appr.approve : null,
1776
1789
  label: d.label || "",
@@ -2108,6 +2121,9 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
2108
2121
  // A frame that never says it drew still swaps in, late, rather than never.
2109
2122
  bufferTimer = setTimeout(swapFrame, FRAME_SWAP_MS);
2110
2123
  };
2124
+ // #715: a frame drawing a live carve tells the kiosk what to say; one that does not says nothing, and nothing here changes.
2125
+ if (typeof window !== "undefined" && window.addEventListener && watch) carveCtl = startKioskCarve({ frame: () => frame, watch, eh, origin, isWatch: () => s.watchMode });
2126
+ s.slowedControl = () => (carveCtl ? carveCtl.slowedControl() : null);
2111
2127
  if (typeof window !== "undefined" && window.addEventListener) {
2112
2128
  window.addEventListener("message", (e) => {
2113
2129
  if (e.origin !== origin || !e.data || e.data.type !== "behold:drawn") return;
@@ -2192,8 +2208,32 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
2192
2208
  };
2193
2209
  const CYCLE_REREAD_MS = 60_000;
2194
2210
 
2211
+ // behold#725: the stopped-updating cue. The demo poll and the event stream
2212
+ // report whether they came back; while one fails, a line over the header
2213
+ // says since when nothing has come in (web/kiosk-link.js).
2214
+ const link = linkState();
2215
+ let linkLine = null;
2216
+ let linkWas = null;
2217
+ const paintLink = () => {
2218
+ const words = linkWords(link);
2219
+ // The tour's live badge and its lag follow the cue (web/carve-narration.js liveBadge).
2220
+ if (words !== linkWas) { linkWas = words; shareLink(link); }
2221
+ if (!linkLine && !words) return;
2222
+ if (!linkLine) {
2223
+ const host = bar && bar.parentNode;
2224
+ if (!host || typeof document === "undefined" || !host.insertBefore) return;
2225
+ linkLine = el("p", "k-link");
2226
+ linkLine.setAttribute("role", "status");
2227
+ host.insertBefore(linkLine, bar);
2228
+ }
2229
+ linkLine.hidden = !words;
2230
+ linkLine.textContent = words || "";
2231
+ };
2232
+
2195
2233
  const demo = async () => {
2196
2234
  const live = await fetchJson("/api/terragucci/demo");
2235
+ noteRead(link, "poll", !readFailed(live), now());
2236
+ paintLink();
2197
2237
  s.live = live;
2198
2238
  if (!vendor) {
2199
2239
  s.repo = live && live.demo ? live.demo.repo : null;
@@ -2223,6 +2263,17 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
2223
2263
 
2224
2264
  if (typeof EventSource !== "undefined") {
2225
2265
  const es = new EventSource("/api/terragucci/events");
2266
+ // behold#725: the browser retries a dropped stream by itself (CONNECTING);
2267
+ // one it closed for good (a 404, say) leaves the polls to carry the cue.
2268
+ es.addEventListener("open", () => { noteBack(link, "stream"); paintLink(); });
2269
+ es.addEventListener("error", () => {
2270
+ if (es.readyState === 2) noteBack(link, "stream");
2271
+ else noteRead(link, "stream", false, now());
2272
+ paintLink();
2273
+ });
2274
+ const heard = () => { noteRead(link, "stream", true, now()); paintLink(); };
2275
+ es.addEventListener("reports", heard);
2276
+ es.addEventListener("progress", heard);
2226
2277
  es.addEventListener("reports", () => void reports(false));
2227
2278
  es.addEventListener("progress", (e) => {
2228
2279
  try {
@@ -2242,13 +2293,20 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
2242
2293
  return s;
2243
2294
  }
2244
2295
 
2296
+ // behold#725: `unreachable` marks a read that never got an answer, or got a
2297
+ // server error, so the stopped-updating cue can tell it from a source that
2298
+ // answered with an error of its own (kiosk-link.js readFailed).
2245
2299
  async function defaultFetch(url) {
2246
2300
  try {
2247
2301
  const r = await fetch(url, { headers: { accept: "application/json" } });
2302
+ if (r.status >= 500) {
2303
+ const body = await r.json().catch(() => ({}));
2304
+ return { error: body.error || `${url} answered ${r.status}`, ...body, unreachable: true };
2305
+ }
2248
2306
  const body = await r.json();
2249
2307
  return r.ok ? body : { error: body.error || `${url} answered ${r.status}`, ...body };
2250
2308
  } catch (e) {
2251
- return { error: `${url}: ${e instanceof Error ? e.message : String(e)}` };
2309
+ return { error: `${url}: ${e instanceof Error ? e.message : String(e)}`, unreachable: true };
2252
2310
  }
2253
2311
  }
2254
2312
 
package/web/motion.js ADDED
@@ -0,0 +1,42 @@
1
+ // behold#725: the page's motion, in one place. Every looping animation in
2
+ // index.html and kiosk.html runs on the root's --beat (a spinner turns once a
3
+ // beat, a pulse takes two), so they keep time with each other. This module
4
+ // marks the root with data-motion="paused" while the tab is hidden, and the
5
+ // stylesheets hold every animation where it is under that mark, so a tab in
6
+ // the background spends nothing on frames nobody sees. Reduced motion is the
7
+ // stylesheets' own business (prefers-reduced-motion); `motionReduced` is here
8
+ // for script that animates.
9
+
10
+ /** The beat in milliseconds: the stylesheets' --beat, for script that wants to keep time with them. */
11
+ export const BEAT_MS = 1200;
12
+
13
+ /** The mark the root carries while the tab is hidden; null when it is shown. */
14
+ export function motionMark(doc) {
15
+ return doc && doc.hidden ? "paused" : null;
16
+ }
17
+
18
+ /** True when the viewer asked for reduced motion. */
19
+ export function motionReduced(win = typeof window !== "undefined" ? window : null) {
20
+ try {
21
+ return !!(win && win.matchMedia && win.matchMedia("(prefers-reduced-motion: reduce)").matches);
22
+ } catch {
23
+ return false;
24
+ }
25
+ }
26
+
27
+ /**
28
+ * Keep the root's data-motion in step with the tab's visibility. Returns a
29
+ * function that stops listening.
30
+ */
31
+ export function installMotion(doc = typeof document !== "undefined" ? document : null) {
32
+ if (!doc || !doc.documentElement) return () => {};
33
+ const root = doc.documentElement;
34
+ const sync = () => {
35
+ const mark = motionMark(doc);
36
+ if (mark) root.setAttribute("data-motion", mark);
37
+ else root.removeAttribute("data-motion");
38
+ };
39
+ doc.addEventListener("visibilitychange", sync);
40
+ sync();
41
+ return () => doc.removeEventListener("visibilitychange", sync);
42
+ }
@@ -0,0 +1,64 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { BEAT_MS, installMotion, motionMark, motionReduced } from "./motion.js";
3
+
4
+ // behold#725: a stand-in document, enough for installMotion: a hidden flag, a root's attributes, and its listeners.
5
+ const fakeDoc = (hidden = false) => {
6
+ const attrs = new Map();
7
+ const listeners = new Map();
8
+ return {
9
+ hidden,
10
+ documentElement: {
11
+ setAttribute: (k, v) => attrs.set(k, String(v)),
12
+ removeAttribute: (k) => attrs.delete(k),
13
+ getAttribute: (k) => (attrs.has(k) ? attrs.get(k) : null),
14
+ },
15
+ addEventListener: (type, fn) => listeners.set(type, fn),
16
+ removeEventListener: (type, fn) => { if (listeners.get(type) === fn) listeners.delete(type); },
17
+ fire: (type) => listeners.get(type) && listeners.get(type)(),
18
+ listening: (type) => listeners.has(type),
19
+ };
20
+ };
21
+
22
+ describe("the page's motion (behold#725)", () => {
23
+ it("keeps the stylesheets' beat", () => {
24
+ expect(BEAT_MS).toBe(1200);
25
+ });
26
+
27
+ it("marks the root paused while the tab is hidden and clears the mark when it shows again", () => {
28
+ const doc = fakeDoc(false);
29
+ installMotion(doc);
30
+ expect(doc.documentElement.getAttribute("data-motion")).toBe(null);
31
+ doc.hidden = true;
32
+ doc.fire("visibilitychange");
33
+ expect(doc.documentElement.getAttribute("data-motion")).toBe("paused");
34
+ doc.hidden = false;
35
+ doc.fire("visibilitychange");
36
+ expect(doc.documentElement.getAttribute("data-motion")).toBe(null);
37
+ });
38
+
39
+ it("starts paused on a page that opens in a background tab", () => {
40
+ const doc = fakeDoc(true);
41
+ installMotion(doc);
42
+ expect(doc.documentElement.getAttribute("data-motion")).toBe("paused");
43
+ });
44
+
45
+ it("stops listening when asked", () => {
46
+ const doc = fakeDoc(false);
47
+ const stop = installMotion(doc);
48
+ expect(doc.listening("visibilitychange")).toBe(true);
49
+ stop();
50
+ expect(doc.listening("visibilitychange")).toBe(false);
51
+ });
52
+
53
+ it("does nothing without a document", () => {
54
+ expect(() => installMotion(null)()).not.toThrow();
55
+ expect(motionMark(null)).toBe(null);
56
+ });
57
+
58
+ it("reads reduced motion from the media query, and a window that can't answer as no", () => {
59
+ expect(motionReduced({ matchMedia: (q) => ({ matches: q === "(prefers-reduced-motion: reduce)" }) })).toBe(true);
60
+ expect(motionReduced({ matchMedia: () => ({ matches: false }) })).toBe(false);
61
+ expect(motionReduced({ matchMedia: () => { throw new Error("no"); } })).toBe(false);
62
+ expect(motionReduced(null)).toBe(false);
63
+ });
64
+ });
package/web/operator.js CHANGED
@@ -475,7 +475,7 @@ export function renderConvergeGateCard(gate, actions = {}) {
475
475
  box.appendChild(el("div", "run-gate-meta", NO_APPROVE[actions.why] || NO_APPROVE.host));
476
476
  return box;
477
477
  }
478
- // Standalone, chant records whoever runs behold. Said before the click.
478
+ // Standalone, chant records the approver /api/project names (#690). Said before the click.
479
479
  const approve = el("button", "approve", actions.approver ? `Record approval as ${actions.approver}` : "Record approval");
480
480
  approve.title =
481
481
  `${(gate.approve && gate.approve.method) || "POST"} ${(gate.approve && gate.approve.path) || ""} — ` +
@@ -13,7 +13,11 @@
13
13
  * - the pending gate as a first-class card (#234): who is waiting, since when,
14
14
  * what it holds back, and an Approve button that POSTs the EXISTING
15
15
  * op-signal route. behold never signals on its own initiative.
16
- * - the settled steps, in the order they settled.
16
+ * - the run's steps as chant's run events report them (#679): running,
17
+ * then how each settled (ok, failed, skipped with chant's reason, cached,
18
+ * gated, waiting), in the order they started.
19
+ * - where the steps came from, so a degraded run (a chant older than the
20
+ * run-events floor) says so.
17
21
  */
18
22
 
19
23
  /** Settled-step tones, in the same token vocabulary the apply progress panel
@@ -22,8 +26,12 @@
22
26
  import { barVarFor } from "./theme.js";
23
27
 
24
28
  export const RUN_STEP_COLOR = {
29
+ running: "var(--pending)",
25
30
  ok: "var(--managed)",
26
- fail: "var(--degraded)",
31
+ cached: "var(--managed)",
32
+ failed: "var(--degraded)",
33
+ gated: "var(--pending)",
34
+ waiting: "var(--pending)",
27
35
  skipped: "var(--muted)",
28
36
  };
29
37
 
@@ -35,10 +43,12 @@ export const RUN_STATUS_COLOR = {
35
43
  running: "var(--pending)",
36
44
  ok: "var(--managed)",
37
45
  failed: "var(--degraded)",
46
+ gated: "var(--pending)",
47
+ waiting: "var(--pending)",
38
48
  lost: "var(--foreign)",
39
49
  };
40
50
 
41
- /** `1062` → `1.1s`. */
51
+ /** `1062` is `1.1s`. */
42
52
  export function took(ms) {
43
53
  return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
44
54
  }
@@ -67,33 +77,95 @@ export function waitingFor(since, now = Date.now()) {
67
77
  */
68
78
  export function runVerdict(run) {
69
79
  if (!run || !run.op) return null;
70
- const n = (run.records || []).length;
80
+ const n = (run.steps || []).filter((s) => s.state !== "running").length;
71
81
  const settled = `${n} step${n === 1 ? "" : "s"} settled`;
72
82
  if (run.status === "idle") {
73
- return { text: `${run.op}: no per-step records — this session didn't start the run`, tone: "idle" };
83
+ return { text: `${run.op}: no per-step events; this session didn't start the run`, tone: "idle" };
74
84
  }
75
85
  if (run.status === "running") {
76
86
  return {
77
- text: `${run.op}: running — ${settled}`,
87
+ text: `${run.op}: ${run.following ? "running (followed)" : "running"}, ${settled}`,
78
88
  tone: "running",
79
89
  };
80
90
  }
81
- if (run.status === "ok") return { text: `${run.op}: exited cleanly — ${settled}`, tone: "ok" };
82
- if (run.status === "failed") return { text: `${run.op}: a step failed — ${settled}`, tone: "failed" };
83
- if (run.status === "gated") return { text: `${run.op}: stopped at a gate — ${settled}; approve it, then run the Op again`, tone: "running" };
84
- return { text: `${run.op}: stream lost — frozen at ${settled}`, tone: "lost" };
91
+ if (run.status === "ok") return { text: `${run.op}: settled ok, ${settled}`, tone: "ok" };
92
+ if (run.status === "failed") return { text: `${run.op}: a step failed, ${settled}`, tone: "failed" };
93
+ if (run.status === "gated") return { text: `${run.op}: stopped at a gate, ${settled}; approve it, then run the Op again`, tone: "gated" };
94
+ if (run.status === "waiting") return { text: `${run.op}: waiting on a decision point, ${settled}; answer it, then run the Op again`, tone: "waiting" };
95
+ return { text: `${run.op}: stream lost, frozen at ${settled}`, tone: "lost" };
85
96
  }
86
97
 
87
- /** The settled steps, in arrival order, as rows. */
98
+ /**
99
+ * How one step reads in its row: `running`, a duration, `skipped (receipt)`,
100
+ * `cached`, `gated`, `waiting`. chant's skip reasons are said in words a
101
+ * person reads, with chant's own term kept in brackets.
102
+ */
103
+ export const SKIP_WORDS = {
104
+ receipt: "already applied (receipt)",
105
+ resumed: "carried from an earlier run (resumed)",
106
+ refused: "refused (refused)",
107
+ "not-run": "not run: an earlier step stopped the run (not-run)",
108
+ };
109
+ export function stepTook(s) {
110
+ if (s.state === "running") return "running";
111
+ if (s.state === "skipped") return s.skip ? `skipped: ${SKIP_WORDS[s.skip] || s.skip}` : "skipped";
112
+ if (s.state === "cached" || s.state === "gated" || s.state === "waiting") return s.state;
113
+ return typeof s.durationMs === "number" ? took(s.durationMs) : s.state;
114
+ }
115
+
116
+ /** The run's steps, in the order they started (or settled), as rows. */
88
117
  export function stepRows(run) {
89
- return (run?.records || []).map((r) => ({
90
- label: `${r.phase} · ${r.fn}`,
91
- status: r.status,
92
- took: r.status === "skipped" ? "skipped" : took(r.durationMs),
93
- error: r.error || null,
118
+ return (run?.steps || []).map((s) => ({
119
+ label: `${s.component ? `${s.component} · ` : ""}${s.phase} · ${s.step}`,
120
+ status: s.state,
121
+ took: stepTook(s),
122
+ error: s.error || s.message || null,
123
+ approvedBy: s.approvedBy || null,
94
124
  }));
95
125
  }
96
126
 
127
+ /**
128
+ * Where a run's progress came from, as one line beside it (#679), or null
129
+ * when there is nothing to qualify. `source` is the server's: `events`
130
+ * (chant's run events), `progress` (an older chant, degraded), `classifier`
131
+ * (a pipeline chant did not run, read from its log), `forge` (a forge's own
132
+ * job states). `note` is the server's own reason when it gave one.
133
+ */
134
+ export function sourceLabel(source, note) {
135
+ if (source === "events") return { text: "from chant's run events", tone: "ok" };
136
+ if (source === "progress") return { text: note || "degraded: an older chant's progress stream, with no step starts, skip reasons, cache hits or gate events", tone: "lost" };
137
+ if (source === "classifier") {
138
+ return { text: "best-effort: chant did not run this pipeline, so its steps are read from the runner's log; only the exit code is certain", tone: "lost" };
139
+ }
140
+ if (source === "forge") return { text: "job states from the forge, not chant's run events", tone: "idle" };
141
+ return note ? { text: note, tone: "idle" } : null;
142
+ }
143
+
144
+ /**
145
+ * One component's chip on the dial (#679): its name, the step it is on and
146
+ * how that step stands, then the component's own state. `c` is the server's
147
+ * ApplyComponentState (src/apply.ts).
148
+ */
149
+ export function applyChipText(name, c) {
150
+ const where = [c.phase, c.step].filter(Boolean).join(" · ");
151
+ const how = c.stepState ? stepTook({ state: c.stepState, skip: c.skip, durationMs: null }) : null;
152
+ const detail = where ? ` · ${where}${how && how !== c.status ? ` ${how}` : ""}` : "";
153
+ return `${name}${detail} (${c.status})`;
154
+ }
155
+
156
+ /** What a component run waits on, from chant's `gate-waiting`, or null. */
157
+ export function waitingLine(w) {
158
+ if (!w) return null;
159
+ const on = w.gate ? `gate ${w.gate}` : `decision point ${w.point}`;
160
+ return `waiting on ${on}${w.component ? ` (${w.component})` : ""} since ${w.since}${w.message ? `: ${w.message}` : ""}`;
161
+ }
162
+
163
+ /** The decision point a run waits on, as a line, or null. */
164
+ export function pointLine(run) {
165
+ if (!run || !run.point) return null;
166
+ return `waiting on decision point ${run.point.id} since ${run.point.since}${run.point.message ? `: ${run.point.message}` : ""}; answer it with chant workspace points answer ${run.point.id}`;
167
+ }
168
+
97
169
  /**
98
170
  * The pending gate card (#234), from the run state alone.
99
171
  *
@@ -119,7 +191,7 @@ export function gateCardFrom(run) {
119
191
 
120
192
  /** Does the panel have anything to show at all? */
121
193
  export function hasPlayhead(run) {
122
- return Boolean(run && (run.op || (run.records && run.records.length)));
194
+ return Boolean(run && (run.op || (run.steps && run.steps.length)));
123
195
  }
124
196
 
125
197
  // ── the DOM half ─────────────────────────────────────────────────────────────
@@ -147,8 +219,19 @@ export function renderPlayhead(host, run, card, actions = {}) {
147
219
  line.style.color = RUN_STATUS_COLOR[verdict.tone] || "var(--muted)";
148
220
  host.appendChild(line);
149
221
 
222
+ // #679: where the steps came from; a degraded run's reason is its label,
223
+ // and any other reason (a steward run, a run with no kept events) follows it.
224
+ const from = sourceLabel(run.source, run.source === "progress" ? run.sourceNote : null);
225
+ if (from) {
226
+ const src = el("div", "run-source", from.text);
227
+ src.style.color = RUN_STATUS_COLOR[from.tone] || "var(--muted)";
228
+ host.appendChild(src);
229
+ }
230
+ if (run.sourceNote && run.source !== "progress") host.appendChild(el("div", "run-source", run.sourceNote));
150
231
  if (run.lost) host.appendChild(el("div", "run-lost", run.lost));
151
- if (run.gateNote) host.appendChild(el("div", "run-lost", `Gate state unavailable — ${run.gateNote}`));
232
+ if (run.gateNote) host.appendChild(el("div", "run-lost", `Gate state unavailable: ${run.gateNote}`));
233
+ const point = pointLine(run);
234
+ if (point) host.appendChild(el("div", "run-gate-meta", point));
152
235
 
153
236
  const gate = card || gateCardFrom(run);
154
237
  if (gate) host.appendChild(renderGateCard(gate, actions));
@@ -165,7 +248,7 @@ export function renderPlayhead(host, run, card, actions = {}) {
165
248
  row.appendChild(dot);
166
249
  row.appendChild(el("span", "grow", r.label));
167
250
  row.appendChild(el("span", "run-took", r.took));
168
- if (r.error) row.title = r.error;
251
+ if (r.error || r.approvedBy) row.title = [r.error, r.approvedBy ? `approved by ${r.approvedBy}` : null].filter(Boolean).join("; ");
169
252
  list.appendChild(row);
170
253
  }
171
254
  host.appendChild(list);
@@ -5,13 +5,13 @@
5
5
  // approve button POSTs) is a function from data to data; the DOM half is
6
6
  // smoke/ui-smoke.mjs's job.
7
7
  import { describe, it, expect } from "vitest";
8
- import { runVerdict, stepRows, gateCardFrom, hasPlayhead, took, waitingFor } from "./run-playhead.js";
8
+ import { runVerdict, stepRows, gateCardFrom, hasPlayhead, took, waitingFor, stepTook, sourceLabel, pointLine, applyChipText, waitingLine } from "./run-playhead.js";
9
9
 
10
10
  const base = {
11
11
  op: "playhead-probe",
12
12
  mode: "temporal",
13
13
  status: "running",
14
- records: [],
14
+ steps: [],
15
15
  gate: null,
16
16
  gateNote: null,
17
17
  startedAt: "2026-08-29T18:00:00.000Z",
@@ -20,7 +20,7 @@ const base = {
20
20
  };
21
21
  const withRecords = (n) => ({
22
22
  ...base,
23
- records: Array.from({ length: n }, (_, i) => ({ phase: "P", fn: `f${i}`, status: "ok", durationMs: 1000 })),
23
+ steps: Array.from({ length: n }, (_, i) => ({ component: null, phase: "P", step: `f${i}`, state: "ok", durationMs: 1000 })),
24
24
  });
25
25
 
26
26
  describe("took", () => {
@@ -48,7 +48,7 @@ describe("waitingFor", () => {
48
48
  describe("runVerdict", () => {
49
49
  it("has nothing to say before anything has run", () => {
50
50
  expect(runVerdict(null)).toBeNull();
51
- expect(runVerdict({ op: null, status: "idle", records: [] })).toBeNull();
51
+ expect(runVerdict({ op: null, status: "idle", steps: [] })).toBeNull();
52
52
  });
53
53
 
54
54
  it("never calls a lost stream finished", () => {
@@ -63,8 +63,16 @@ describe("runVerdict", () => {
63
63
  expect(runVerdict({ ...withRecords(2), status: "failed" }).text).toContain("a step failed");
64
64
  });
65
65
 
66
- it("counts settled steps while a local run streams them (#459: --progress-json)", () => {
67
- expect(runVerdict({ ...withRecords(1), mode: "local" }).text).toContain("running — 1 step settled");
66
+ it("counts settled steps while a local run streams them, not the one running (#679)", () => {
67
+ const run = { ...withRecords(1), steps: [...withRecords(1).steps, { component: null, phase: "P", step: "g", state: "running" }] };
68
+ expect(runVerdict(run).text).toContain("running, 1 step settled");
69
+ expect(runVerdict({ ...run, following: true }).text).toContain("running (followed)");
70
+ });
71
+
72
+ it("says a run waiting on a decision point waits on a person, not that it failed (#679)", () => {
73
+ const v = runVerdict({ ...withRecords(1), status: "waiting" });
74
+ expect(v.text).toContain("waiting on a decision point");
75
+ expect(v.tone).toBe("waiting");
68
76
  });
69
77
 
70
78
  it("says a gated run stopped at its gate and runs again after approval (#459)", () => {
@@ -84,10 +92,10 @@ describe("runVerdict", () => {
84
92
  describe("stepRows", () => {
85
93
  it("keeps arrival order and labels a skip as a skip, not a duration", () => {
86
94
  const rows = stepRows({
87
- records: [
88
- { phase: "Build", fn: "chantBuild", status: "ok", durationMs: 1062 },
89
- { phase: "Verify", fn: "httpCheck", status: "fail", durationMs: 15164, error: "fetch failed" },
90
- { phase: "Never", fn: "httpCheck", status: "skipped", durationMs: 0 },
95
+ steps: [
96
+ { component: null, phase: "Build", step: "chantBuild", state: "ok", durationMs: 1062 },
97
+ { component: null, phase: "Verify", step: "httpCheck", state: "failed", durationMs: 15164, error: "fetch failed" },
98
+ { component: null, phase: "Never", step: "httpCheck", state: "skipped", durationMs: 0 },
91
99
  ],
92
100
  });
93
101
  expect(rows.map((r) => `${r.label} ${r.took}`)).toEqual([
@@ -135,7 +143,69 @@ describe("gateCardFrom", () => {
135
143
  describe("hasPlayhead", () => {
136
144
  it("is false on a fresh session and true once an Op is being watched", () => {
137
145
  expect(hasPlayhead(null)).toBe(false);
138
- expect(hasPlayhead({ op: null, records: [] })).toBe(false);
146
+ expect(hasPlayhead({ op: null, steps: [] })).toBe(false);
139
147
  expect(hasPlayhead(base)).toBe(true);
140
148
  });
141
149
  });
150
+
151
+ // #679: every state chant's run events report, as it happens.
152
+ describe("stepTook", () => {
153
+ it("reads each state chant reports, and says why a step skipped", () => {
154
+ expect(stepTook({ state: "running" })).toBe("running");
155
+ expect(stepTook({ state: "ok", durationMs: 6 })).toBe("6ms");
156
+ expect(stepTook({ state: "skipped", skip: "receipt" })).toBe("skipped: already applied (receipt)");
157
+ expect(stepTook({ state: "skipped", skip: "not-run" })).toBe("skipped: not run: an earlier step stopped the run (not-run)");
158
+ expect(stepTook({ state: "skipped", skip: null })).toBe("skipped");
159
+ expect(stepTook({ state: "cached", durationMs: 3 })).toBe("cached");
160
+ expect(stepTook({ state: "gated", durationMs: 680 })).toBe("gated");
161
+ expect(stepTook({ state: "waiting" })).toBe("waiting");
162
+ // The older stream's component steps carry no timing.
163
+ expect(stepTook({ state: "ok", durationMs: null })).toBe("ok");
164
+ });
165
+
166
+ it("names the component and who approved a gate on a row", () => {
167
+ const [row] = stepRows({ steps: [{ component: "db", phase: "Apply", step: "gate:approve-db", state: "ok", durationMs: 40, approvedBy: "alex" }] });
168
+ expect(row.label).toBe("db · Apply · gate:approve-db");
169
+ expect(row.approvedBy).toBe("alex");
170
+ });
171
+ });
172
+
173
+ describe("sourceLabel", () => {
174
+ it("labels the classifier path best-effort, and a degraded run with the server's reason", () => {
175
+ expect(sourceLabel("classifier").text).toMatch(/^best-effort: chant did not run this pipeline/);
176
+ expect(sourceLabel("classifier").text).toContain("only the exit code is certain");
177
+ expect(sourceLabel("progress", "degraded: this project's chant (0.124.24) is older than 0.124.28").text).toContain("0.124.24");
178
+ expect(sourceLabel("progress").text).toMatch(/^degraded/);
179
+ expect(sourceLabel("events").text).toBe("from chant's run events");
180
+ expect(sourceLabel("forge").text).toContain("forge");
181
+ expect(sourceLabel(undefined)).toBeNull();
182
+ expect(sourceLabel(null, "a steward run keeps no events on this host").text).toContain("steward");
183
+ });
184
+ });
185
+
186
+ describe("pointLine", () => {
187
+ it("names a decision point and the command that answers it", () => {
188
+ expect(pointLine({ point: { id: "pt-1", since: "2026-10-17T04:24:48.329Z" } })).toBe(
189
+ "waiting on decision point pt-1 since 2026-10-17T04:24:48.329Z; answer it with chant workspace points answer pt-1",
190
+ );
191
+ expect(pointLine({ point: null })).toBeNull();
192
+ });
193
+ });
194
+
195
+ describe("applyChipText", () => {
196
+ it("shows the step a component is on and how it stands, as it happens", () => {
197
+ expect(applyChipText("loom-db", { status: "running", phase: "Apply", step: "cfn-deploy", stepState: "running" })).toBe("loom-db · Apply · cfn-deploy (running)");
198
+ expect(applyChipText("sf", { status: "ok", phase: "Apply", step: "cfn-deploy", stepState: "skipped", skip: "receipt" })).toBe("sf · Apply · cfn-deploy skipped: already applied (receipt) (ok)");
199
+ expect(applyChipText("sf", { status: "running", phase: "Apply", step: "cfn-outputs", stepState: "cached" })).toBe("sf · Apply · cfn-outputs cached (running)");
200
+ expect(applyChipText("db", { status: "gated", phase: "Apply", step: "gate:approve-db", stepState: "gated" })).toBe("db · Apply · gate:approve-db (gated)");
201
+ expect(applyChipText("db", { status: "pending" })).toBe("db (pending)");
202
+ });
203
+ });
204
+
205
+ describe("waitingLine", () => {
206
+ it("names the gate or decision point a component run waits on", () => {
207
+ expect(waitingLine({ gate: "approve-db", point: null, component: "loom-db", since: "t" })).toBe("waiting on gate approve-db (loom-db) since t");
208
+ expect(waitingLine({ gate: null, point: "pt-1", component: null, since: "t", message: "which region?" })).toBe("waiting on decision point pt-1 since t: which region?");
209
+ expect(waitingLine(null)).toBeNull();
210
+ });
211
+ });
@@ -11,11 +11,11 @@
11
11
  <style>
12
12
  /* The pre-paint fallback: Sea Shells' tokens (KIOSK_THEME in theme.js), which initTheme() replaces with the viewer's theme. */
13
13
  :root {
14
- --bg: #09141b; --panel: #1c2325; --line: #2c2e2d; --fg: #deb88d; --muted: #746a5c;
14
+ --bg: #09141b; --panel: #1c2325; --line: #2c2e2d; --fg: #deb88d; --muted: #91877a; --ink2: #ceb395;
15
15
  --edge: #4d483f; --managed: #027c9b; --foreign: #fca02f; --pending: #1e4950;
16
16
  --degraded: #d15123; --neutral: #695e4e; --runtime: #50a3b5;
17
17
  --rule: #3d4142; --focus: #364548; --active: #243235; --well: #01070d; --shadow: #010304;
18
- --surface-box: #101b22; --surface-pane-a: #152128; --surface-pane-b: #1b272e; --soft: #deb88d; --muted-ink: #7c7365;
18
+ --surface-box: #161a1d; --surface-pane-a: #1c2023; --surface-pane-b: #222629; --soft: #deb88d; --muted-ink: #9a9083;
19
19
  --managed-ink: #0e7f9e; --foreign-ink: #fca02f; --pending-ink: #567b82; --runtime-ink: #50a3b5;
20
20
  --font-ui: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
21
21
  --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;