@intentius/behold 0.29.43 → 0.29.45

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 (67) hide show
  1. package/AGENTS.md +77 -0
  2. package/dist/cli.js +4065 -1918
  3. package/package.json +1 -1
  4. package/web/app.js +1469 -74
  5. package/web/carve-narration.js +33 -1
  6. package/web/chant-live-pace.js +138 -0
  7. package/web/chant-live-pace.test.js +116 -0
  8. package/web/chant-pr-marks.js +417 -39
  9. package/web/chant-pr-marks.test.js +208 -4
  10. package/web/collision-marks.js +124 -0
  11. package/web/collision-marks.test.js +89 -0
  12. package/web/cone.js +269 -0
  13. package/web/cone.test.js +213 -0
  14. package/web/dots-live.test.js +151 -1
  15. package/web/dots-lod.js +20 -0
  16. package/web/dots-lod.test.js +19 -1
  17. package/web/dots-scene.js +110 -10
  18. package/web/dots.js +144 -31
  19. package/web/embed.js +1 -1
  20. package/web/event-help-modal.js +98 -3
  21. package/web/event-help-modal.test.js +85 -1
  22. package/web/feature-flags.js +143 -0
  23. package/web/feature-flags.test.js +96 -0
  24. package/web/index.html +33 -0
  25. package/web/kiosk-carve.js +59 -6
  26. package/web/kiosk-demo-frame.test.js +27 -0
  27. package/web/kiosk-event-help-ui.js +186 -20
  28. package/web/kiosk-event-help.js +175 -15
  29. package/web/kiosk-event-help.test.js +58 -1
  30. package/web/kiosk-highlight.test.js +249 -0
  31. package/web/kiosk-metrics.js +4 -3
  32. package/web/kiosk-runs.js +8 -5
  33. package/web/kiosk-shot.js +157 -3
  34. package/web/kiosk-shot.test.js +223 -1
  35. package/web/kiosk-source.js +43 -0
  36. package/web/kiosk-source.test.js +39 -0
  37. package/web/kiosk-story-gate.test.js +44 -0
  38. package/web/kiosk-track.js +312 -0
  39. package/web/kiosk-track.test.js +148 -0
  40. package/web/kiosk-unknown-step.test.js +58 -0
  41. package/web/kiosk-vendor.js +73 -4
  42. package/web/kiosk-vendor.test.js +103 -3
  43. package/web/kiosk-watch.js +154 -1
  44. package/web/kiosk-watch.test.js +53 -1
  45. package/web/kiosk.html +57 -22
  46. package/web/kiosk.js +583 -53
  47. package/web/kiosk.test.js +2 -1
  48. package/web/small-stage.test.js +150 -0
  49. package/web/terragucci-blocked.test.js +192 -0
  50. package/web/terragucci-change.js +197 -17
  51. package/web/terragucci-components-live.js +189 -13
  52. package/web/terragucci-live-pace.js +92 -0
  53. package/web/terragucci-wave-results.test.js +125 -0
  54. package/web/terralith.html +7 -7
  55. package/web/tg-outside.js +124 -0
  56. package/web/tg-outside.test.js +100 -0
  57. package/web/tg-read-pills.js +145 -0
  58. package/web/tg-read-pills.test.js +158 -0
  59. package/web/theme.js +13 -1
  60. package/web/theme.test.js +21 -1
  61. package/web/tooltip.js +19 -7
  62. package/web/tooltip.test.js +15 -0
  63. package/web/tours/terralith.json +4 -4
  64. package/web/trunk-lane.test.js +1 -1
  65. package/web/view-url.js +8 -2
  66. package/web/why.js +129 -1
  67. package/web/why.test.js +113 -1
@@ -0,0 +1,158 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { FLASH_MAX, FLASH_MS, coveredEdges, createReadFlash, dependsLine, hotReads, nearestOn, pillSpots, readKey, readerStates } from "./tg-read-pills.js";
3
+
4
+ // behold#744: the tofu fan-out's reads: cluster-a and cluster-b read network; app-01..06 read cluster-a.
5
+ const apps = ["app-01", "app-02", "app-03", "app-04", "app-05", "app-06"];
6
+ const edges = [
7
+ { from: "cluster-a", to: "network" },
8
+ { from: "cluster-b", to: "network" },
9
+ ...apps.map((a) => ({ from: a, to: "cluster-a" })),
10
+ ];
11
+ const clock = () => {
12
+ let t = 1000;
13
+ return { now: () => t, tick: (ms) => (t += ms) };
14
+ };
15
+ const states = (over) => Object.fromEntries([["cluster-a", "applied"], ["cluster-b", "applied"], ...apps.map((a) => [a, "not-started"]), ...Object.entries(over)]);
16
+
17
+ describe("which reads flash on a kiosk (behold#744)", () => {
18
+ it("shows nothing for a run first seen settled, nor while nothing moves", () => {
19
+ const c = clock();
20
+ const f = createReadFlash({ now: c.now });
21
+ expect(f.live(edges, states({}))).toEqual([]);
22
+ c.tick(500);
23
+ expect(f.live(edges, states({}))).toEqual([]);
24
+ });
25
+
26
+ it("shows a reader's reads once its wave applies it, and lets them go after the hold", () => {
27
+ const c = clock();
28
+ const f = createReadFlash({ now: c.now });
29
+ f.live(edges, states({ "cluster-a": "not-started", "cluster-b": "not-started" }));
30
+ c.tick(100);
31
+ const now = f.live(edges, states({ "cluster-a": "applying", "cluster-b": "applying" }));
32
+ expect(now.map((x) => x.key)).toEqual([readKey(edges[0]), readKey(edges[1])]);
33
+ expect(now.every((x) => x.age === 0)).toBe(true);
34
+ c.tick(2000);
35
+ expect(f.live(edges, states({ "cluster-a": "applying", "cluster-b": "applying" })).map((x) => x.age)).toEqual([2000, 2000]);
36
+ c.tick(FLASH_MS);
37
+ expect(f.live(edges, states({ "cluster-a": "applying", "cluster-b": "applying" }))).toEqual([]);
38
+ });
39
+
40
+ it("shows what a reloaded frame finds on first sight, the failed reader's read first, then applying, then blocked", () => {
41
+ const c = clock();
42
+ const f = createReadFlash({ now: c.now });
43
+ const shown = f.live(edges, states({ "cluster-a": "failed", "app-01": "blocked", "app-02": "blocked", "cluster-b": "applying" })).map((x) => x.key);
44
+ expect(shown).toEqual([readKey(edges[0]), readKey(edges[1]), readKey({ from: "app-01", to: "cluster-a" })]);
45
+ });
46
+
47
+ it("shows a read again when its reader fails or is blocked after it was seen", () => {
48
+ const c = clock();
49
+ const f = createReadFlash({ now: c.now });
50
+ f.live(edges, states({ "cluster-a": "applying" }));
51
+ c.tick(FLASH_MS + 1);
52
+ expect(f.live(edges, states({ "cluster-a": "applying" }))).toEqual([]);
53
+ c.tick(10);
54
+ expect(f.live(edges, states({ "cluster-a": "failed", "app-01": "blocked" })).map((x) => x.key)).toEqual([readKey({ from: "cluster-a", to: "network" }), readKey({ from: "app-01", to: "cluster-a" })]);
55
+ });
56
+
57
+ it("never shows more than a handful at once, the newest first", () => {
58
+ const c = clock();
59
+ const f = createReadFlash({ now: c.now });
60
+ f.live(edges, states({}));
61
+ c.tick(10);
62
+ f.live(edges, states({ "app-01": "applying" }));
63
+ c.tick(10);
64
+ const all = Object.fromEntries(apps.map((a) => [a, "applying"]));
65
+ const shown = f.live(edges, states(all));
66
+ expect(shown.length).toBe(FLASH_MAX);
67
+ expect(shown.map((x) => x.key)).not.toContain(readKey({ from: "app-01", to: "cluster-a" }));
68
+ });
69
+ });
70
+
71
+ describe("the reads a pointer lights (behold#744)", () => {
72
+ it("lights a reader's reads and the reads of the root it reads; a line lights itself alone", () => {
73
+ expect(hotReads(edges, { root: "app-03" })).toEqual([readKey({ from: "app-03", to: "cluster-a" })]);
74
+ expect(hotReads(edges, { root: "network" })).toEqual([readKey(edges[0]), readKey(edges[1])]);
75
+ expect(hotReads(edges, { root: "cluster-a" })).toHaveLength(7);
76
+ expect(hotReads(edges, { key: readKey(edges[1]) })).toEqual([readKey(edges[1])]);
77
+ expect(hotReads(edges, { key: "nope" })).toEqual([]);
78
+ expect(hotReads(edges, {})).toEqual([]);
79
+ });
80
+
81
+ it("reads each reader's state from the components zoom's cards first, then the root states", () => {
82
+ expect(readerStates({ cards: { "app-01": { root: "app-01", wave: 3, state: "blocked" } }, waves: {} }, { "app-01": { state: "not-started" }, network: { state: "applied" } })).toEqual({ "app-01": "blocked", network: "applied" });
83
+ expect(readerStates(null, null)).toEqual({});
84
+ });
85
+
86
+ it("reads a planned card applying while its wave's job runs, and leaves an unchanged one be", () => {
87
+ const marks = {
88
+ cards: { "cluster-a": { root: "cluster-a", wave: 2, state: "planned" }, "cluster-b": { root: "cluster-b", wave: 2, state: "unchanged" }, "app-01": { root: "app-01", wave: 3, state: "planned" } },
89
+ waves: { 2: { status: { status: "running" } }, 3: { status: { status: "queued" } } },
90
+ };
91
+ expect(readerStates(marks, null)).toEqual({ "cluster-a": "applying", "cluster-b": "unchanged", "app-01": "planned" });
92
+ });
93
+ });
94
+
95
+ describe("where a pill goes (behold#744)", () => {
96
+ const card = { x: 100, y: 100, x2: 260, y2: 160 };
97
+ it("tries the side the line leaves from first, touching the card, and the nearest spot is beside p0", () => {
98
+ const p0 = { x: 180, y: 160 }; // the card's bottom border
99
+ const spots = pillSpots(card, p0, 200, 23);
100
+ expect(spots[0].side).toBe("bottom");
101
+ expect(spots[0].r.y).toBe(166);
102
+ expect(spots[0].far).toBeCloseTo(6);
103
+ const nearest = [...spots].sort((a, b) => a.far - b.far)[0];
104
+ expect(nearest.side).toBe("bottom");
105
+ // None of them sits on the card.
106
+ for (const s of spots) expect(s.r.x2 <= card.x || s.r.x >= card.x2 || s.r.y2 <= card.y || s.r.y >= card.y2).toBe(true);
107
+ });
108
+
109
+ it("goes beside a card's left side for a line that leaves it there", () => {
110
+ expect(pillSpots(card, { x: 100, y: 130 }, 120, 23)[0]).toMatchObject({ side: "left", r: { x2: 94 } });
111
+ });
112
+
113
+ it("meets the pill's nearest edge with its leader", () => {
114
+ expect(nearestOn({ x: 0, y: 0, x2: 10, y2: 10 }, { x: 5, y: 20 })).toEqual({ x: 5, y: 10 });
115
+ expect(nearestOn({ x: 0, y: 0, x2: 10, y2: 10 }, { x: -4, y: -4 })).toEqual({ x: 0, y: 0 });
116
+ });
117
+ });
118
+
119
+ describe("a read line stands for the dependency edge on its pair (behold#762)", () => {
120
+ // The tofu fan-out's dependency edges as pinhole draws them: each app on its cluster, each cluster on network.
121
+ const deps = [
122
+ { from: "cluster-a", to: "network" },
123
+ { from: "cluster-b", to: "network" },
124
+ ...apps.map((a) => ({ from: a, to: "cluster-a" })),
125
+ ];
126
+
127
+ it("covers every edge whose pair has a read, and names the read", () => {
128
+ expect(coveredEdges(edges, deps)).toEqual(deps.map((d) => readKey(d)));
129
+ });
130
+
131
+ it("leaves an edge with no read on its pair to draw itself", () => {
132
+ const reads = edges.filter((e) => e.from !== "app-03" && e.to !== "network");
133
+ const out = coveredEdges(reads, deps);
134
+ expect(out[0]).toBeNull();
135
+ expect(out[1]).toBeNull();
136
+ expect(out[deps.findIndex((d) => d.from === "app-03")]).toBeNull();
137
+ expect(out.filter(Boolean)).toHaveLength(5);
138
+ });
139
+
140
+ it("matches the pair in either direction", () => {
141
+ expect(coveredEdges([{ from: "app-01", to: "cluster-a" }], [{ from: "cluster-a", to: "app-01" }])).toEqual(["app-01→cluster-a"]);
142
+ });
143
+
144
+ it("matches a read named by its root's path to a card named after the root, and no other card", () => {
145
+ const reads = [{ from: "apps/app-01", to: "clusters/cluster-a" }];
146
+ expect(coveredEdges(reads, [{ from: "app-01", to: "cluster-a" }, { from: "app-1", to: "cluster-a" }, { from: "pp-01", to: "cluster-a" }])).toEqual(["apps/app-01→clusters/cluster-a", null, null]);
147
+ });
148
+
149
+ it("covers nothing without reads (a chant repo) or without edges", () => {
150
+ expect(coveredEdges([], deps)).toEqual(deps.map(() => null));
151
+ expect(coveredEdges(undefined, deps)).toEqual(deps.map(() => null));
152
+ expect(coveredEdges(edges, [])).toEqual([]);
153
+ });
154
+
155
+ it("says what the hidden edge meant", () => {
156
+ expect(dependsLine({ from: "app-01", to: "cluster-a" })).toBe("app-01 → cluster-a\napp-01 depends on cluster-a, so cluster-a applies first");
157
+ });
158
+ });
package/web/theme.js CHANGED
@@ -542,6 +542,18 @@ export function getTheme() { return _active; }
542
542
  export function getTokens() { return _tokens; }
543
543
  export function getThemeName() { return _active && _active.name; }
544
544
  export function onThemeChange(cb) { _subs.add(cb); return () => _subs.delete(cb); }
545
+ /** behold#755: the theme `dir` steps (+1 next, -1 previous) from `current` in `names`, wrapping at both ends; the first for a name not in the list. */
546
+ export function themeStep(names, current, dir) {
547
+ if (!names.length) return null;
548
+ const i = names.indexOf(current);
549
+ if (i < 0) return names[0];
550
+ return names[(((i + dir) % names.length) + names.length) % names.length];
551
+ }
552
+ /** behold#755: the kiosk's < and > beside the picker: the next or previous theme, kept like a pick. */
553
+ export function stepTheme(dir) {
554
+ const name = themeStep(listThemes(), getThemeName(), dir);
555
+ return name ? setTheme(name) : false;
556
+ }
545
557
 
546
558
  /**
547
559
  * behold#725: every custom property applyTheme sets for `tokens`, as
@@ -601,7 +613,7 @@ export function setTheme(nameOrObj, { persist = true } = {}) {
601
613
  }
602
614
 
603
615
  /** behold#571: the kiosk's theme for a viewer who hasn't picked one; the app keeps DEFAULT_THEME. */
604
- export const KIOSK_THEME = "Sea Shells";
616
+ export const KIOSK_THEME = "Box"; // behold#758; Batman (behold#755) and Sea Shells before
605
617
 
606
618
  // Restore the persisted theme (or `fallback`, else the default) and apply. Call once on boot.
607
619
  export function initTheme(fallback = null) {
package/web/theme.test.js CHANGED
@@ -6,9 +6,29 @@
6
6
  // sweeps all 552 palettes for the same assertion; this pins the exact
7
7
  // palette the issue was filed against, with no browser involved.
8
8
  import { describe, it, expect } from "vitest";
9
- import { BAR_FLOOR, BAR_STATES, FRAME_STATES, INK2_FLOOR, MIN_STEP, MUTED_FLOOR, SURFACE_CHROMA, barGrounds, barInks, barVars, SOFT_CEILING, ZEBRA, contrast, desaturate, frameGrounds, frameInks, hexToOklch, ink2Grounds, mix, PAINT_KEY, paintFor, pinTokensFor, tokensFor } from "./theme.js";
9
+ import { BAR_FLOOR, BAR_STATES, FRAME_STATES, INK2_FLOOR, KIOSK_THEME, MIN_STEP, MUTED_FLOOR, SURFACE_CHROMA, barGrounds, barInks, barVars, SOFT_CEILING, ZEBRA, contrast, desaturate, frameGrounds, frameInks, hexToOklch, ink2Grounds, mix, PAINT_KEY, paintFor, pinTokensFor, themeStep, tokensFor } from "./theme.js";
10
10
  import { THEMES } from "./themes.js";
11
11
 
12
+ describe("themeStep — the kiosk's < and > (behold#755)", () => {
13
+ const names = ["A", "B", "C"];
14
+ it("steps forward and back", () => {
15
+ expect(themeStep(names, "B", 1)).toBe("C");
16
+ expect(themeStep(names, "B", -1)).toBe("A");
17
+ });
18
+ it("wraps at both ends", () => {
19
+ expect(themeStep(names, "C", 1)).toBe("A");
20
+ expect(themeStep(names, "A", -1)).toBe("C");
21
+ });
22
+ it("starts at the first for a name not in the list, and has nothing for no names", () => {
23
+ expect(themeStep(names, "Z", 1)).toBe("A");
24
+ expect(themeStep([], "A", 1)).toBe(null);
25
+ });
26
+ it("the kiosk opens on Box, a theme that exists (behold#758)", () => {
27
+ expect(KIOSK_THEME).toBe("Box");
28
+ expect(THEMES[KIOSK_THEME]).toBeTruthy();
29
+ });
30
+ });
31
+
12
32
  describe("tokensFor — the --muted contrast floor (#240)", () => {
13
33
  it("Darkermatrix's naive fg/panel mix reads at ~1.25:1, the issue's reported ratio — the floor push has to move it", () => {
14
34
  const th = THEMES["Darkermatrix"];
package/web/tooltip.js CHANGED
@@ -92,10 +92,20 @@ export function reachBadges(root) {
92
92
  return n;
93
93
  }
94
94
 
95
+ /**
96
+ * behold#744: an edge, or a line drawn over the graph, whose tooltip goes by
97
+ * the pointer: its own box can span the drawing. The edges are also all a
98
+ * kiosk frame shows a tooltip for: its cards have the frame's popover.
99
+ */
100
+ export function isLine(node) {
101
+ return !!(node && node.hasAttribute && (node.hasAttribute("data-edge-from") || node.hasAttribute("data-tg-read-hit")));
102
+ }
103
+
95
104
  /**
96
105
  * Wire the tooltip into `doc`. `scope` names the part of the page whose SVG
97
106
  * badges get tab stops as they are drawn. A kiosk frame (the root's .bare) has
98
- * its own popover and nothing to focus, so it gets neither.
107
+ * its own popover and nothing to focus, so it gets neither, save a tooltip on
108
+ * an edge (behold#744), which the browser's own shows late or not at all.
99
109
  */
100
110
  export function installTooltips(doc = typeof document !== "undefined" ? document : null, { scope = "#graph", setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
101
111
  if (!doc || !doc.documentElement || !doc.body) return () => {};
@@ -118,7 +128,8 @@ export function installTooltips(doc = typeof document !== "undefined" ? document
118
128
  const t = ensureTip();
119
129
  t.textContent = current.text;
120
130
  t.hidden = false;
121
- const r = current.host.getBoundingClientRect();
131
+ const at0 = current.at;
132
+ const r = at0 ? { left: at0.x - 6, right: at0.x + 6, top: at0.y - 6, bottom: at0.y + 6 } : current.host.getBoundingClientRect();
122
133
  const s = t.getBoundingClientRect();
123
134
  const view = { width: (win && win.innerWidth) || doc.documentElement.clientWidth, height: (win && win.innerHeight) || doc.documentElement.clientHeight };
124
135
  const at = placeTip(r, { width: s.width, height: s.height }, view);
@@ -142,7 +153,7 @@ export function installTooltips(doc = typeof document !== "undefined" ? document
142
153
  else host.removeAttribute("aria-describedby");
143
154
  current = null;
144
155
  };
145
- const enter = (host, delay) => {
156
+ const enter = (host, delay, at = null) => {
146
157
  if (current && current.host === host) return;
147
158
  leave();
148
159
  const title = host.hasAttribute("data-tip") ? null : ownTitle(host);
@@ -150,16 +161,17 @@ export function installTooltips(doc = typeof document !== "undefined" ? document
150
161
  if (!text) return;
151
162
  // Emptied now, before the browser's own tooltip can rise.
152
163
  if (title) title.textContent = "";
153
- current = { host, title, text, timer: null };
164
+ current = { host, title, text, timer: null, at };
154
165
  if (delay > 0) current.timer = setTimer(show, delay);
155
166
  else show();
156
167
  };
157
168
  const inside = (outer, node) => { for (let n = node; n; n = n.parentNode) if (n === outer) return true; return false; };
158
169
 
159
170
  const onOver = (e) => {
160
- if (off()) return;
161
- const host = tipHost(e.target, current && current.host);
162
- if (host) enter(host, HOVER_MS);
171
+ let host = tipHost(e.target, current && current.host);
172
+ if (off() && !isLine(host)) host = null; // behold#744: a kiosk frame's edges only
173
+ const at = isLine(host) && typeof e.clientX === "number" ? { x: e.clientX, y: e.clientY } : null;
174
+ if (host) enter(host, HOVER_MS, at);
163
175
  else if (current && !inside(current.host, e.target)) leave();
164
176
  };
165
177
  const onOut = (e) => { if (current && !inside(current.host, e.relatedTarget)) leave(); };
@@ -190,4 +190,19 @@ describe("installTooltips (behold#725)", () => {
190
190
  expect(t.queue.length).toBe(0);
191
191
  expect(g.badgeTitle.textContent).toContain("wave 2");
192
192
  });
193
+
194
+ it("shows an edge's words in a kiosk frame too, by the pointer (behold#744)", () => {
195
+ const g = graph();
196
+ const path = g.edge.appendChild(new El("path"));
197
+ const doc = fakeDoc(g.body, { bare: true });
198
+ const t = timers();
199
+ installTooltips(doc, t);
200
+ doc.fire("pointerover", { target: path, clientX: 300, clientY: 200 });
201
+ t.run();
202
+ const tip = doc.getElementById(TIP_ID);
203
+ expect(tip.hidden).toBe(false);
204
+ expect(tip.textContent).toBe("data dependency");
205
+ // Under the pointer, not under the edge's whole box.
206
+ expect(tip.style.top).toBe("214px");
207
+ });
193
208
  });
@@ -170,9 +170,9 @@
170
170
  "trigger": {
171
171
  "beat": "split"
172
172
  },
173
- "title": "Split: move ownership, not resources",
173
+ "title": "Team B moves out, and nothing is recreated",
174
174
  "text": [
175
- "Each team's resources move to its own estate by a tag write.",
175
+ "Team B's resources move to an estate of their own by a tag write. The other teams stay in the terralith for now.",
176
176
  "{moved} resources moved, {refused} refused."
177
177
  ],
178
178
  "focus": {
@@ -219,8 +219,8 @@
219
219
  },
220
220
  "title": "A change across estates",
221
221
  "text": [
222
- "The terralith publishes a value, and each team reads it.",
223
- "Wave 1 plans the terralith; wave 2 plans the teams on {value}."
222
+ "The terralith publishes a value, and team B reads it.",
223
+ "Wave 1 plans the terralith; wave 2 plans team B with log_retention_days = {value}."
224
224
  ],
225
225
  "focus": {
226
226
  "boxes": "all"
@@ -54,7 +54,7 @@ const R1 = `jcs1-sha256:${"1".repeat(64)}`;
54
54
  const R2 = `jcs1-sha256:${"2".repeat(64)}`;
55
55
  const R3 = `jcs1-sha256:${"3".repeat(64)}`;
56
56
  const revocation = { tag: `ci/revoked/${C3}`, tagged: "2026-10-05T00:00:00Z", phase: "test", run: run(113, "failure"), signer: null };
57
- const ROLLBACK = "chant components rollback staging --component api";
57
+ const ROLLBACK = "chant components rollback staging --release v2";
58
58
  const unsigned = { status: "unsigned", reason: "the cut carries no signature" };
59
59
  const releases = [
60
60
  { member: "web", releaseDigest: R3, label: "v3", commit: C3, listed: true, artifacts: 1, previous: { releaseDigest: R2, label: "v2" }, configOnly: false, cut: { by: "github:alice", at: "2026-10-04T09:00:00Z", signature: { status: "unverified", reason: "there is no signers file (.chant/allowed_signers) at base to check the cut's signature against" } }, revoked: { ...revocation, rollback: [ROLLBACK] }, runs: [{ env: "staging", components: ["api"] }], waits: [{ env: "prod", gate: "web/release/promote", state: "superseded" }], next: null },
package/web/view-url.js CHANGED
@@ -17,7 +17,7 @@
17
17
  * `none` (no run view: the newest pull request's plan), `pull-<n>[-<sha>]`
18
18
  * (no run view, and only that pull request's plan, of that commit) or `base`
19
19
  * (nothing in flight); absent, the newest. */
20
- export const VIEW_KEYS = ["member", "zoom", "env", "tier", "lens", "node", "radial", "gates", "focus", "run"];
20
+ export const VIEW_KEYS = ["member", "zoom", "env", "tier", "lens", "node", "radial", "gates", "focus", "run", "pull"];
21
21
 
22
22
  /** An env name as the server takes one (src/workspace-gates.ts isEnvName). */
23
23
  export function isEnvName(env) {
@@ -49,7 +49,7 @@ export function readViewQuery(search) {
49
49
  want.env = v || null;
50
50
  continue;
51
51
  }
52
- if (k === "focus" || k === "run") {
52
+ if (k === "focus" || k === "run" || k === "pull") {
53
53
  want[k] = v || null;
54
54
  continue;
55
55
  }
@@ -83,6 +83,7 @@ export function writeViewQuery(search, state, defaults = {}) {
83
83
  if (s.gates) q.set("gates", s.gates);
84
84
  if (s.focus) q.set("focus", s.focus);
85
85
  if (s.run) q.set("run", s.run);
86
+ if (s.pull) q.set("pull", s.pull);
86
87
  const out = q.toString();
87
88
  return out ? `?${out}` : "";
88
89
  }
@@ -135,6 +136,11 @@ export function settleView(want, offer) {
135
136
  if (want.run === null || /^([0-9a-f]{7,40}|none|base|pull(-\d+(-[0-9a-f]{7,40})?)?)$/.test(String(want.run))) apply.run = want.run;
136
137
  else refused.push({ key: "run", value: want.run, reason: "run is a commit sha, none, base or pull-<number>[-<sha>]" });
137
138
  }
139
+ if ("pull" in want) {
140
+ // The pull request a commit's run merged (the kiosk's cycle): the frame never draws another's plan for it. null: any.
141
+ if (want.pull === null || /^\d+$/.test(String(want.pull))) apply.pull = want.pull;
142
+ else refused.push({ key: "pull", value: want.pull, reason: "pull is a pull request's number" });
143
+ }
138
144
  if (want.member) apply.member = want.member;
139
145
  if (want.node) apply.node = want.node;
140
146
  return { apply, refused };
package/web/why.js CHANGED
@@ -7,6 +7,16 @@
7
7
  // chant's order; behold neither re-ranks nor filters them. A proposed decision
8
8
  // links to its review in hud when behold was started with --hud, and is named
9
9
  // by its id otherwise.
10
+ //
11
+ // #682: the chain, from chant 0.124.29 (`trace`, chant#4023). For each commit
12
+ // chant walked: the work items it names ("asked for by"), the ones whose
13
+ // window it fell in (kept apart, never a link), its ci tag, the release that
14
+ // shipped it and the gate resolution that let that release through, and its
15
+ // deploys per environment. Each link carries chant's `source`, the record it
16
+ // came from, which the pane gives as the git line that opens it. A link chant
17
+ // found nothing for is drawn as missing, with chant's reason when it gives one.
18
+ // behold joins nothing: a commit names its release and deploys by id, and
19
+ // those ids are looked up in the same trace.
10
20
 
11
21
  /** The query for a member or a node. A node wins: it names a smaller region. */
12
22
  export function whyQuery({ member = null, node = null } = {}) {
@@ -32,6 +42,31 @@ const RELEVANCE = {
32
42
  };
33
43
 
34
44
  const short = (sha) => String(sha || "").slice(0, 8);
45
+ /** How many of the chain's commits the pane draws; the rest are counted. Matches the server's WHY_COMMITS_SHOWN. */
46
+ const SHOWN = 8;
47
+ /** A digest, short enough to read: `jcs1-sha256:773f0087`. */
48
+ const shortDigest = (d) => {
49
+ const s = String(d || "");
50
+ const i = s.lastIndexOf(":");
51
+ return i < 0 ? s.slice(0, 12) : `${s.slice(0, i + 1)}${s.slice(i + 1, i + 9)}`;
52
+ };
53
+
54
+ /**
55
+ * The git line that opens a link's source record, from chant's `source.ref`:
56
+ * a path on the lifecycle branch, a tag, a commit, or a work record's file
57
+ * (from the repository root, read at HEAD).
58
+ */
59
+ export function sourceLine(source) {
60
+ if (!source || !source.ref) return null;
61
+ const ref = String(source.ref);
62
+ const open = ref.startsWith("chant/lifecycle:") || ref.startsWith("refs/") || /^[0-9a-f]{7,64}$/.test(ref) ? `git show ${ref}` : `git show HEAD:${ref}`;
63
+ return { open, title: `${source.field}: ${source.value}\nfrom ${ref}` };
64
+ }
65
+
66
+ /** "let through by bob on cli at 2026-10-16T10:30:00.000Z", the words for one gate resolution. */
67
+ export function letThrough(g) {
68
+ return `let through by ${g.resolvedBy}${g.channel ? ` on ${g.channel}` : ""} at ${g.at}`;
69
+ }
35
70
 
36
71
  /**
37
72
  * The section's content for an answer from /api/workspace/why: a headline,
@@ -50,6 +85,7 @@ export function whyView(answer) {
50
85
  runs: [],
51
86
  commits: [],
52
87
  gaps: [],
88
+ chain: null,
53
89
  footer: footer(answer),
54
90
  };
55
91
  }
@@ -94,9 +130,101 @@ export function whyView(answer) {
94
130
  const more = answer.commitsTotal > answer.commits.length ? answer.commitsTotal - answer.commits.length : 0;
95
131
  const gaps = answer.gaps.map((g) => g.message || g.code);
96
132
  if (answer.uncommittedLines) gaps.unshift(`${answer.uncommittedLines} line${answer.uncommittedLines === 1 ? " isn't" : "s aren't"} committed yet.`);
97
- return { headline, decisions, runs, commits, more, gaps, footer: footer(answer) };
133
+ return { headline, decisions, runs, commits, more, gaps, chain: chainView(answer), footer: footer(answer) };
134
+ }
135
+
136
+ const WORK_MISSING = {
137
+ unlinked: "no work item: the commit names none in a Chant-Record or Chant-Lease trailer",
138
+ wrong: "the commit names a work item chant could not take as its link",
139
+ };
140
+
141
+ /**
142
+ * #682: the chain section for an answer, or null when the answer has no
143
+ * `chain` field (a server before #682). `note` instead of rows when chant
144
+ * wrote no chain. Each commit has `rows`: `{ label, text, meta, source,
145
+ * missing }`, with `source` from {@link sourceLine} or null, and `missing`
146
+ * true for a link chant found nothing for.
147
+ */
148
+ export function chainView(answer) {
149
+ const chain = answer && answer.chain;
150
+ if (!chain) return null;
151
+ const trace = answer.trace;
152
+ if (!chain.full || !trace) return { note: chain.note || `The chain from work item to release needs chant ${chain.floor} or newer.`, reasons: [], commits: [], more: 0 };
153
+ if (trace.commits.length === 0) return { note: "chant walked no commit for this region, so there is no chain to show.", reasons: trace.reasons.map((r) => `Part of the chain could not be read (${r.code}): ${r.message}`), commits: [], more: 0 };
154
+ const releaseOf = new Map(trace.releases.map((r) => [r.releaseDigest, r]));
155
+ const deployOf = new Map(trace.deploys.map((d) => [d.id, d]));
156
+ const releaseName = (digest) => {
157
+ const r = releaseOf.get(digest);
158
+ return r && r.label ? r.label : shortDigest(digest);
159
+ };
160
+ const reasons = trace.reasons.map((r) => `Part of the chain could not be read (${r.code}): ${r.message}`);
161
+ const shown = trace.commits.slice(0, SHOWN);
162
+
163
+ const commits = shown.map((c) => {
164
+ const rows = [];
165
+ const row = (label, text, meta, source, missing = false) => rows.push({ label, text, meta: meta || "", source: sourceLine(source), missing });
166
+
167
+ // Who asked for it: the trailer's work items, judged as chant judges them.
168
+ const problems = c.work ? c.work.problems.map((p) => `${p.trailer}: ${p.message}`).join("; ") : "";
169
+ if (!c.work) row("asked for by", "nothing read", "chant read no work kind, so it judged no link", null, true);
170
+ else if (c.work.state === "merge") row("asked for by", "a merge commit", "chant judges the commits it merges, not the merge", null);
171
+ else if (c.work.items.length === 0) row("asked for by", "missing", [WORK_MISSING[c.work.state] || c.work.state, problems].filter(Boolean).join("; "), null, true);
172
+ else {
173
+ for (const w of c.work.items) row("asked for by", w.id, [w.title, c.work.state === "wrong" ? WORK_MISSING.wrong : null, w.node ? null : "chant read no record with this id", problems].filter(Boolean).join(" · "), w.source, c.work.state === "wrong");
174
+ }
175
+ // The window: listed apart, and never a link.
176
+ if (c.windowMatches.length) row("in the window of", c.windowMatches.map((w) => w.id).join(", "), "the commit fell in its window, which does not link them", null);
177
+
178
+ // The ci tag.
179
+ const t = c.tag;
180
+ if (t.state === "revoked" && t.revoked) row("ci tag", t.revoked.tag, ["revoked", t.revoked.phase ? `phase ${t.revoked.phase} failed` : null, t.revoked.tagged].filter(Boolean).join(" · "), t.revoked.source);
181
+ else if (t.state === "green" && t.green) row("ci tag", t.green.tag, [t.green.signer ? `signed by ${t.green.signer}` : "counts unsigned", t.green.tagged].filter(Boolean).join(" · "), t.green.source);
182
+ else row("ci tag", "no green tag", t.ignored.length ? t.ignored.map((x) => `${x.tag} is ${x.status}: ${x.reason}`).join("; ") : "", null, true);
183
+
184
+ // The release that shipped it, and the gate resolution that let it through.
185
+ if (c.releases.length === 0) row("release", "missing", "no release is cut from this commit or from one that has it in its history", null, true);
186
+ for (const link of c.releases) {
187
+ const r = releaseOf.get(link.release);
188
+ const cut = r && r.cuts[0];
189
+ row(
190
+ "release",
191
+ releaseName(link.release),
192
+ [link.link === "cut-from" ? "cut from this commit" : `contains this commit; cut from ${short(r ? r.commit : link.source.value)}`, cut ? `cut by ${cut.actor} at ${cut.timestamp}${cut.signed ? ", signed" : ""}` : null].filter(Boolean).join(" · "),
193
+ link.source,
194
+ );
195
+ if (!r) continue;
196
+ if (r.gates.length === 0) row("gate", "missing", `no release gate resolution names ${releaseName(link.release)}`, null, true);
197
+ for (const g of r.gates) {
198
+ const facts = [`${g.gate}${g.environment ? ` in ${g.environment}` : ""}`, g.relayedBy ? `relayed by ${g.relayedBy}` : null, g.sealed ? "sealed" : null, g.empty ? "an empty change set, passed by the promote itself, not a person's approval" : null];
199
+ row("gate", letThrough(g), facts.filter(Boolean).join(" · "), g.source);
200
+ if (g.changeSet) row("change set", `chant change-set show ${g.changeSet}${r.member ? ` --member ${r.member}` : ""}`, "the change set the approval was for", g.changeSetSource);
201
+ else if (g.planDigest) row("change set", "missing", `chant stored no change set under the plan ${shortDigest(g.planDigest)}`, null, true);
202
+ }
203
+ }
204
+
205
+ // The deploys, per environment.
206
+ if (c.deploys.length === 0) row("deploy", "missing", "no deploy record is built from this commit or from one that has it in its history", null, true);
207
+ for (const link of c.deploys) {
208
+ const d = deployOf.get(link.deploy);
209
+ if (!d) {
210
+ row(`deploy ${link.env}`, link.deploy, "", link.source);
211
+ continue;
212
+ }
213
+ const admitted = d.admittedBy ? `admitted by ${d.admittedBy.gate}, ${letThrough(d.admittedBy)}` : "admitted by no gate resolution chant could find";
214
+ const work = d.plan && Array.isArray(d.plan.document.work) && d.plan.document.work.length ? `release plan: ${d.plan.document.work.join(", ")}` : null;
215
+ row(
216
+ `deploy ${link.env}`,
217
+ `${d.component} run ${d.runId} at ${d.timestamp}`,
218
+ [d.release ? `release ${releaseName(d.release)}` : "names no release", admitted, d.approver ? `approved by ${d.approver}` : null, link.link === "contains" ? `built from ${short(d.gitSha)}, which contains this commit` : null, work].filter(Boolean).join(" · "),
219
+ link.source,
220
+ );
221
+ }
222
+ return { sha: short(c.sha), subject: c.subject || "", rows };
223
+ });
224
+ return { note: null, reasons, commits, more: Math.max(0, trace.commits.length - shown.length) };
98
225
  }
99
226
 
227
+
100
228
  function footer(answer) {
101
229
  const parts = [];
102
230
  if (typeof answer.ms === "number") parts.push(`read in ${seconds(answer.ms)}`);