@intentius/behold 0.29.42 → 0.29.44

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 (68) hide show
  1. package/AGENTS.md +77 -0
  2. package/dist/cli.js +3969 -1918
  3. package/package.json +1 -1
  4. package/web/app.js +1463 -80
  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-cards.js +362 -0
  15. package/web/dots-cards.test.js +303 -0
  16. package/web/dots-live.test.js +151 -1
  17. package/web/dots-lod.js +20 -0
  18. package/web/dots-lod.test.js +19 -1
  19. package/web/dots-scene.js +110 -10
  20. package/web/dots.js +489 -87
  21. package/web/embed.js +17 -1
  22. package/web/embed.test.js +19 -1
  23. package/web/event-help-modal.js +85 -3
  24. package/web/event-help-modal.test.js +85 -1
  25. package/web/feature-flags.js +143 -0
  26. package/web/feature-flags.test.js +96 -0
  27. package/web/index.html +33 -0
  28. package/web/kiosk-carve.js +59 -6
  29. package/web/kiosk-event-help-ui.js +150 -19
  30. package/web/kiosk-event-help.js +102 -15
  31. package/web/kiosk-event-help.test.js +58 -1
  32. package/web/kiosk-metrics.js +4 -3
  33. package/web/kiosk-runs.js +8 -5
  34. package/web/kiosk-shot.js +157 -3
  35. package/web/kiosk-shot.test.js +223 -1
  36. package/web/kiosk-source.js +43 -0
  37. package/web/kiosk-source.test.js +39 -0
  38. package/web/kiosk-story-gate.test.js +44 -0
  39. package/web/kiosk-track.js +312 -0
  40. package/web/kiosk-track.test.js +148 -0
  41. package/web/kiosk-unknown-step.test.js +58 -0
  42. package/web/kiosk-vendor.js +71 -4
  43. package/web/kiosk-vendor.test.js +103 -3
  44. package/web/kiosk-watch.js +154 -1
  45. package/web/kiosk-watch.test.js +53 -1
  46. package/web/kiosk.html +57 -22
  47. package/web/kiosk.js +566 -53
  48. package/web/kiosk.test.js +2 -1
  49. package/web/small-stage.test.js +150 -0
  50. package/web/terragucci-blocked.test.js +192 -0
  51. package/web/terragucci-change.js +197 -17
  52. package/web/terragucci-components-live.js +189 -13
  53. package/web/terragucci-live-pace.js +92 -0
  54. package/web/terragucci-wave-results.test.js +125 -0
  55. package/web/terralith.html +7 -7
  56. package/web/tg-outside.js +124 -0
  57. package/web/tg-outside.test.js +100 -0
  58. package/web/tg-read-pills.js +122 -0
  59. package/web/tg-read-pills.test.js +117 -0
  60. package/web/theme.js +13 -1
  61. package/web/theme.test.js +21 -1
  62. package/web/tooltip.js +19 -7
  63. package/web/tooltip.test.js +15 -0
  64. package/web/tours/terralith.json +4 -4
  65. package/web/trunk-lane.test.js +1 -1
  66. package/web/view-url.js +8 -2
  67. package/web/why.js +129 -1
  68. package/web/why.test.js +113 -1
package/web/embed.js CHANGED
@@ -64,7 +64,7 @@ export function viewFromMessage(event, host) {
64
64
  if (typeof v === "boolean") want.radial = v;
65
65
  continue;
66
66
  }
67
- if (k === "env" || k === "gates" || k === "focus" || k === "run") {
67
+ if (k === "env" || k === "gates" || k === "focus" || k === "run" || k === "pull") {
68
68
  // env: null or "" is the source graph. gates: null or "" hands the
69
69
  // gate strip back to the graph's env. focus: null or "" brings nothing forward. run: null or "" draws the newest run again.
70
70
  if (v === null || v === "") want[k] = null;
@@ -99,3 +99,19 @@ export function quietCardLines(svg) {
99
99
  t.setAttribute("data-kiosk-quiet", "1");
100
100
  }
101
101
  }
102
+
103
+ /**
104
+ * Whether a plain wheel (no ctrl or meta key) zooms the graph: in the kiosk's
105
+ * bare frame it does, since the graph is the whole stage and there is nothing
106
+ * of the frame to scroll. A sideways-only scroll is left to the page.
107
+ */
108
+ export function wheelZoomsBare(bare, e) {
109
+ return !!bare && !!e && Math.abs(Number(e.deltaY) || 0) > 0;
110
+ }
111
+
112
+ /** A wheel event's vertical delta in px, whatever its unit: a line is 16 px, a page 800. */
113
+ export function wheelPx(e) {
114
+ const d = Number(e && e.deltaY) || 0;
115
+ const mode = e && e.deltaMode;
116
+ return mode === 1 ? d * 16 : mode === 2 ? d * 800 : d;
117
+ }
package/web/embed.test.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { describe, expect, it } from "vitest";
2
- import { kioskQuietLine, readEmbed, selectMessage, viewFromMessage, THEME_ALIASES } from "./embed.js";
2
+ import { kioskQuietLine, readEmbed, selectMessage, viewFromMessage, THEME_ALIASES, wheelPx, wheelZoomsBare } from "./embed.js";
3
3
 
4
4
  describe("readEmbed (#476)", () => {
5
5
  it("reads embed, an exact host origin and a theme", () => {
@@ -72,3 +72,21 @@ describe("kioskQuietLine (behold#571)", () => {
72
72
  for (const t of ["network", "terraform_data.http_proxy_port", "waiting", "reads network · planned · 1 unknown", "wave 2 · planned", "", null]) expect(kioskQuietLine(t)).toBe(false);
73
73
  });
74
74
  });
75
+
76
+ describe("the wheel in the kiosk's bare frame", () => {
77
+ it("zooms on a plain mouse wheel there, and only there", () => {
78
+ expect(wheelZoomsBare(true, { deltaY: 100 })).toBe(true);
79
+ expect(wheelZoomsBare(true, { deltaY: -3 })).toBe(true);
80
+ expect(wheelZoomsBare(false, { deltaY: 100 })).toBe(false);
81
+ });
82
+ it("leaves a sideways-only scroll to the page", () => {
83
+ expect(wheelZoomsBare(true, { deltaX: 40, deltaY: 0 })).toBe(false);
84
+ expect(wheelZoomsBare(true, null)).toBe(false);
85
+ });
86
+ it("reads the delta in px whatever its unit", () => {
87
+ expect(wheelPx({ deltaY: 100, deltaMode: 0 })).toBe(100);
88
+ expect(wheelPx({ deltaY: 3, deltaMode: 1 })).toBe(48);
89
+ expect(wheelPx({ deltaY: 1, deltaMode: 2 })).toBe(800);
90
+ expect(wheelPx({})).toBe(0);
91
+ });
92
+ });
@@ -36,6 +36,8 @@ export const VERBS = {
36
36
  failed: { verb: "Run again", ing: "Running again…", past: "Running again" },
37
37
  applied: { verb: "Close", ing: "Close", past: "Close" },
38
38
  };
39
+ /** behold#631: a chant failure's button: the driver opens a fix's pull request. */
40
+ export const FIX_VERBS = { verb: "Fix", ing: "Opening the fix…", past: "Fix opened" };
39
41
 
40
42
  /** Whole seconds until `at` (ms), never below 0; null without a time. */
41
43
  export function secondsLeft(at, now) {
@@ -66,12 +68,16 @@ const utc = (ms) => new Date(ms).toISOString().slice(11, 16);
66
68
  * The line that says which mode this is. Narrated says what the driver does
67
69
  * and when; replay says which run it replays; live says nothing extra.
68
70
  */
69
- export function modeLine(mode, kind, { at = null, now = 0, resolved = false, outcome = null, replayAt = null, action = null } = {}) {
71
+ export function modeLine(mode, kind, { at = null, now = 0, resolved = false, outcome = null, replayAt = null, action = null, fix = false } = {}) {
72
+ // behold#631: a "Waiting on…" modal says what it waits on in its title; it has no mode line.
73
+ if (kind === "waiting") return null;
70
74
  if (mode === "replay") return `Replay of the run at ${utc(Number.isFinite(replayAt) ? replayAt : now)} UTC`;
71
75
  if (mode !== "narrated") return null;
72
76
  if (resolved) return outcome ? `Live · ${outcome}` : "Live";
73
77
  const left = secondsLeft(at, now);
74
78
  if (kind === "held") return left === null ? "Live · the driver plays the reviewer" : left > 0 ? `Live · the driver plays the reviewer and approves in ${left} s` : "Live · the driver plays the reviewer and approves now";
79
+ // behold#631: in the kiosk's own words for what comes next, the same as its caption's: the demo is scripted.
80
+ if (kind === "failed" && fix) return left === null ? "next (scripted): the fix opens" : left > 0 ? `next (scripted): the fix opens in ${left} s` : "next (scripted): the fix opens now";
75
81
  if (kind === "failed") return left === null ? "Live · the driver fixes it and runs it again" : left > 0 ? `Live · the driver fixes it and runs it again in ${left} s` : "Live · the driver fixes it and runs it again now";
76
82
  return "Live";
77
83
  }
@@ -99,6 +105,9 @@ export const MODAL_STYLE = `
99
105
  .eh-switch input { margin: 0; accent-color: var(--pending); }
100
106
  .eh-switch:hover { color: var(--fg); }
101
107
  .eh-modal-wrap { position: fixed; inset: 0; z-index: 50; display: flex; align-items: center; justify-content: center; background: color-mix(in srgb, var(--bg) 35%, transparent); }
108
+ /* behold#744: a modal placed off the cards leaves the graph to the pointer (hover a card or a line), not under a sheet that swallows it. */
109
+ .eh-modal-wrap.eh-modal-placed { align-items: flex-start; justify-content: flex-start; pointer-events: none; }
110
+ .eh-modal-wrap.eh-modal-placed > .eh-modal { pointer-events: auto; }
102
111
  .eh-modal { position: relative; width: min(36em, calc(100vw - 32px)); max-height: calc(100vh - 48px); overflow-y: auto; padding: 1em 1.2em 1.1em; border-radius: 12px; background: var(--surface-pane-b, var(--panel)); color: var(--fg);
103
112
  border: 2px solid var(--bar, var(--focus)); box-shadow: 0 16px 48px color-mix(in srgb, var(--shadow) 80%, transparent); font-size: 1.05em; }
104
113
  .eh-modal-held { --bar: var(--bar-foreign, var(--foreign)); } .eh-modal-failed { --bar: var(--bar-degraded, var(--degraded)); } .eh-modal-applied { --bar: var(--bar-managed, var(--managed)); }
@@ -117,6 +126,9 @@ export const MODAL_STYLE = `
117
126
  .eh-modal-act.eh-pressed { background: var(--bar, var(--pending)); color: var(--bg); transform: translateY(1px); }
118
127
  .eh-mode-live .eh-modal-act:not(.eh-pressed) { cursor: pointer; }
119
128
  .eh-modal .k-ap { margin-top: 0.4em; }
129
+ .eh-modal-progress { position: relative; height: 6px; margin-top: 0.7em; border-radius: 3px; background: color-mix(in srgb, var(--muted) 30%, transparent); overflow: hidden; }
130
+ .eh-modal-progress-fill { position: absolute; inset: 0 auto 0 0; background: var(--pending); border-radius: 3px; transition: width 0.9s linear; }
131
+ @media (prefers-reduced-motion: reduce) { .eh-modal-progress-fill { transition: none; } }
120
132
  `;
121
133
 
122
134
  /** Put the modal's style in `doc` once. */
@@ -128,6 +140,46 @@ export function modalStyle(doc) {
128
140
  doc.head.appendChild(style);
129
141
  }
130
142
 
143
+ /**
144
+ * behold#631: where a modal of `size` goes in a window of `win` so it covers
145
+ * none of `avoid` (rects in window coordinates: `{ left, top, width, height }`),
146
+ * or null when the centre does. `prefer` are the other cards: of the spots
147
+ * that clear `avoid`, the one covering none of them (else the least) wins, the
148
+ * nearest the centre on a tie. Spots are tried on a grid inside `bounds` (the
149
+ * graph's frame) when given, else the window. When no spot clears `avoid`,
150
+ * the one that covers least of it.
151
+ */
152
+ export function modalSpot(win, size, avoid, { prefer = [], bounds = null, margin = 16, step = 24 } = {}) {
153
+ const grow = (a) => ({ x0: a.left - 12, y0: a.top - 12, x1: a.left + a.width + 12, y1: a.top + a.height + 12 });
154
+ const rects = (avoid || []).filter((a) => a && a.width > 0 && a.height > 0).map(grow);
155
+ const others = (prefer || []).filter((a) => a && a.width > 0 && a.height > 0).map(grow);
156
+ const area = bounds && bounds.width > 0 ? { x0: bounds.left, y0: bounds.top, x1: bounds.left + bounds.width, y1: bounds.top + bounds.height } : { x0: 0, y0: 0, x1: win.w, y1: win.h };
157
+ const w = Math.min(size.w, win.w - 2 * margin);
158
+ const h = Math.min(size.h, win.h - 2 * margin);
159
+ const cx = (win.w - w) / 2;
160
+ const cy = (win.h - h) / 2;
161
+ const cover = (list, x, y) => list.reduce((sum, r) => sum + Math.max(0, Math.min(x + w, r.x1) - Math.max(x, r.x0)) * Math.max(0, Math.min(y + h, r.y1) - Math.max(y, r.y0)), 0);
162
+ // The centre stands only when it is inside the area a modal may use (a chant kiosk keeps its bottom band clear).
163
+ const inArea = (x, y) => x >= area.x0 - 0.5 && y >= area.y0 - 0.5 && x + w <= area.x1 + 0.5 && y + h <= area.y1 + 0.5;
164
+ const centreOk = !bounds || inArea(cx, cy);
165
+ if (centreOk && !cover(rects, cx, cy) && !cover(others, cx, cy)) return null;
166
+ const x0 = Math.max(margin, area.x0 + margin);
167
+ const y0 = Math.max(margin, area.y0 + margin);
168
+ const x1 = Math.max(x0, Math.min(win.w - margin, area.x1 - margin) - w);
169
+ const y1 = Math.max(y0, Math.min(win.h - margin, area.y1 - margin) - h);
170
+ let best = null;
171
+ for (let y = y0; y <= y1 + 0.5; y += step) {
172
+ for (let x = x0; x <= x1 + 0.5; x += step) {
173
+ const score = [cover(rects, x, y), cover(others, x, y), Math.hypot(x - cx, y - cy)];
174
+ if (!best || score[0] < best.score[0] || (score[0] === best.score[0] && (score[1] < best.score[1] || (score[1] === best.score[1] && score[2] < best.score[2])))) best = { x, y, score };
175
+ }
176
+ }
177
+ if (!best) return null;
178
+ // The centre is as good as any: stay there.
179
+ if (centreOk && best.score[0] >= cover(rects, cx, cy) && best.score[1] >= cover(others, cx, cy)) return null;
180
+ return { left: best.x, top: best.y };
181
+ }
182
+
131
183
  /**
132
184
  * Open the modal in `host` (a document's body, or any element). Returns
133
185
  * `{ resolve(outcome), update(data), close(), state }`.
@@ -187,11 +239,25 @@ export function openEventModal(host, { mode, kind, data = {}, actions = {}, doc
187
239
  x.setAttribute("aria-label", "Close");
188
240
  x.addEventListener("click", close);
189
241
  box.appendChild(x);
190
- const line = modeLine(mode, kind, { at: data.at, now: t, resolved: st.resolved, outcome: st.outcome, replayAt: data.replayAt, action: data.action });
242
+ const line = modeLine(mode, kind, { at: data.at, now: t, resolved: st.resolved, outcome: st.outcome, replayAt: data.replayAt, action: data.action, fix: !!data.fix });
191
243
  if (line) box.appendChild(el("p", `eh-modal-mode eh-modal-${mode}`, line));
192
244
  box.appendChild(el("h2", "eh-modal-title", data.title || ""));
193
- for (const l of data.lines || []) box.appendChild(el("p", `eh-modal-line${l.lit ? " eh-lit" : ""}`, l.text));
245
+ for (const l of data.lines || []) {
246
+ const p = el("p", `eh-modal-line${l.lit ? " eh-lit" : ""}`, l.text);
247
+ if (l.title) p.title = l.title;
248
+ box.appendChild(p);
249
+ }
194
250
  if (data.panel) box.appendChild(data.panel);
251
+ // behold#631: a waiting modal's bar: how far into its usual time the step is, and that time in words.
252
+ if (data.progress) {
253
+ const bar = el("div", "eh-modal-progress");
254
+ const fill = el("i", "eh-modal-progress-fill");
255
+ if (fill.style && Number.isFinite(data.progress.fraction)) fill.style.width = `${Math.round(data.progress.fraction * 1000) / 10}%`;
256
+ bar.appendChild(fill);
257
+ box.appendChild(bar);
258
+ if (data.progress.words) box.appendChild(el("p", "eh-modal-note", data.progress.words));
259
+ }
260
+ if (kind === "waiting") return;
195
261
  const routed = mode === "live" && approveRoute(data.gate);
196
262
  // The panel, when there is one, already carries the command.
197
263
  if (data.command && !routed && !(data.panel && mode !== "live")) {
@@ -217,6 +283,9 @@ export function openEventModal(host, { mode, kind, data = {}, actions = {}, doc
217
283
  if (st.resolved && st.outcome) box.appendChild(el("p", "eh-modal-outcome", st.outcome));
218
284
  if (kind === "applied" && !routed) return;
219
285
  if (mode === "live" && !routed) return; // a gate behold can't clear: the command is the action
286
+ // behold#631: a chant failure's countdown is text, not a control: nothing here is for the viewer to press.
287
+ // Its countdown is the mode line's; there is nothing here to press.
288
+ if (data.fix) return;
220
289
  const b = buttonState(kind, { at: mode === "live" ? null : data.at, from: data.from, now: t, resolved: st.resolved || st.pressing, reduced, verbs: data.verbs || null });
221
290
  const btn = el("button", `eh-modal-act${b.pressed ? " eh-pressed" : ""}`, b.label);
222
291
  btn.type = "button";
@@ -249,15 +318,28 @@ export function openEventModal(host, { mode, kind, data = {}, actions = {}, doc
249
318
  watchTimer = setTimer(() => void look(), LEDGER_WATCH_MS);
250
319
  void look();
251
320
  }
321
+ // behold#631: a modal that must keep things in view (a failed card and the cards it blocked) moves off them.
322
+ const placeClear = () => {
323
+ if (typeof data.avoid !== "function" || !box.getBoundingClientRect || !doc.defaultView) return;
324
+ const r = box.getBoundingClientRect();
325
+ if (!r.width) return;
326
+ const win = { w: doc.defaultView.innerWidth, h: doc.defaultView.innerHeight };
327
+ const spot = modalSpot(win, { w: r.width, h: r.height }, data.avoid() || [], { prefer: typeof data.prefer === "function" ? data.prefer() || [] : [], bounds: typeof data.bounds === "function" ? data.bounds() : null });
328
+ wrap.classList.toggle("eh-modal-placed", !!spot);
329
+ box.style.marginLeft = spot ? `${Math.round(spot.left)}px` : "";
330
+ box.style.marginTop = spot ? `${Math.round(spot.top)}px` : "";
331
+ };
252
332
  const tick = () => {
253
333
  if (st.closed) return;
254
334
  if (st.closeAt !== null && !st.hovered && now() >= st.closeAt) return close();
255
335
  render();
336
+ placeClear();
256
337
  };
257
338
  const timer = setTimer(tick, 250);
258
339
  // The result needs no event to wait for: it closes on its own after its time.
259
340
  if (kind === "applied" && mode !== "live") st.closeAt = now() + MODAL_CLOSE_MS;
260
341
  render();
342
+ placeClear();
261
343
 
262
344
  const api = {
263
345
  state: st,
@@ -3,7 +3,7 @@
3
3
  // real event arrives, narrated and replayed modals never write, and live mode
4
4
  // writes only through the app's existing approve route, or waits on the ledger.
5
5
  import { describe, expect, it, vi } from "vitest";
6
- import { approveRoute, buttonState, modeLine, openEventModal, secondsLeft } from "./event-help-modal.js";
6
+ import { MODAL_STYLE, approveRoute, buttonState, modalSpot, modeLine, openEventModal, secondsLeft } from "./event-help-modal.js";
7
7
 
8
8
  /** Just enough of a DOM for the modal: elements with children, text, attributes and listeners. */
9
9
  function fakeDoc() {
@@ -178,3 +178,87 @@ describe("event-help modal: live mode", () => {
178
178
  vi.unstubAllGlobals();
179
179
  });
180
180
  });
181
+
182
+ // behold#631: the "Wave 2 failed" modal sat right on cluster-a.
183
+ describe("a modal kept off the cards it is about", () => {
184
+ const win = { w: 1920, h: 1080 };
185
+ const size = { w: 576, h: 240 };
186
+ it("stays in the centre when nothing is under it", () => {
187
+ expect(modalSpot(win, size, [{ left: 100, top: 100, width: 130, height: 66 }])).toBeNull();
188
+ expect(modalSpot(win, size, [])).toBeNull();
189
+ });
190
+ it("moves off a failed card in the centre, and off the cards it blocked", () => {
191
+ const failed = { left: 900, top: 500, width: 130, height: 66 };
192
+ const blocked = [{ left: 20, top: 20, width: 600, height: 300 }];
193
+ const spot = modalSpot(win, size, [failed, ...blocked]);
194
+ expect(spot).not.toBeNull();
195
+ const hit = (a) => spot.left < a.left + a.width && spot.left + size.w > a.left && spot.top < a.top + a.height && spot.top + size.h > a.top;
196
+ expect([failed, ...blocked].some(hit)).toBe(false);
197
+ });
198
+ });
199
+
200
+ describe("a chant failure's modal in the graph's empty space (#631)", () => {
201
+ const win = { w: 1920, h: 1080 };
202
+ const size = { w: 576, h: 200 };
203
+ // Wave 3's twelve cards across the top, wave 2's two in the middle, network below; the frame above the caption.
204
+ const card = (left, top) => ({ left, top, width: 130, height: 66 });
205
+ const wave3 = [0, 1, 2, 3, 4, 5].flatMap((i) => [card(480 + i * 160, 115), card(480 + i * 160, 210)]);
206
+ const wave2 = [card(640, 540), card(1160, 540)];
207
+ const network = card(890, 715);
208
+ const bounds = { left: 0, top: 0, width: 1920, height: 840 };
209
+ it("covers no card of the failed wave or the next, and no other card when there is room", () => {
210
+ const spot = modalSpot(win, size, [...wave2, ...wave3], { prefer: [network], bounds });
211
+ expect(spot).not.toBeNull();
212
+ const hit = (a) => spot.left < a.left + a.width + 12 && spot.left + size.w > a.left - 12 && spot.top < a.top + a.height + 12 && spot.top + size.h > a.top - 12;
213
+ expect([...wave2, ...wave3, network].some(hit)).toBe(false);
214
+ // Inside the graph's frame, above the caption.
215
+ expect(spot.top + size.h).toBeLessThanOrEqual(840);
216
+ });
217
+ });
218
+
219
+ describe("a chant failure's countdown (#631)", () => {
220
+ it("is text, not a button: nothing to press", () => {
221
+ expect(modeLine("narrated", "failed", { at: 10_000, now: 0, fix: true })).toBe("next (scripted): the fix opens in 10 s");
222
+ expect(modeLine("narrated", "failed", { now: 0, fix: true })).toBe("next (scripted): the fix opens");
223
+ });
224
+ });
225
+
226
+ describe("a chant modal kept above the bottom band (#631)", () => {
227
+ it("leaves the centre when the centre reaches into the band, and stays inside the graph's area", () => {
228
+ const win = { w: 1920, h: 1080 };
229
+ const size = { w: 576, h: 240 };
230
+ // The graph's area ends at 780: the centre (420..660) fits; at 600 it would not.
231
+ expect(modalSpot(win, size, [], { bounds: { left: 0, top: 0, width: 1920, height: 780 } })).toBeNull();
232
+ const spot = modalSpot(win, size, [], { bounds: { left: 0, top: 0, width: 1920, height: 600 } });
233
+ expect(spot).not.toBeNull();
234
+ expect(spot.top + size.h).toBeLessThanOrEqual(600);
235
+ });
236
+ });
237
+
238
+ describe("a placed modal and the read pills (behold#744)", () => {
239
+ it("keeps off a read pill the frame shows, as off a card", () => {
240
+ const win = { w: 1920, h: 1080 };
241
+ const size = { w: 594, h: 160 };
242
+ const bounds = { left: 5, top: 42, width: 1910, height: 690 };
243
+ // fan-out-tofu's wave 3 under Watch's camera, and app-03's pill above its card, where the "Waiting on" modal sat.
244
+ const card = (left, top) => ({ left, top, width: 165, height: 80 });
245
+ const cards = [0, 1, 2, 3, 4, 5].flatMap((i) => [card(72 + i * 210, 302), card(72 + i * 210, 420)]);
246
+ const pill = { left: 402, top: 238, width: 296, height: 26 };
247
+ // The wave box, and the reads running down to wave 2 under it: the modal goes above the box, by the pill.
248
+ const prefer = [{ left: 60, top: 270, width: 1240, height: 245 }, { left: 0, top: 540, width: 1920, height: 200 }];
249
+ const without = modalSpot(win, size, cards, { bounds, prefer });
250
+ const hit = (s, a) => s.left < a.left + a.width + 12 && s.left + size.w > a.left - 12 && s.top < a.top + a.height + 12 && s.top + size.h > a.top - 12;
251
+ expect(without && hit(without, pill)).toBe(true);
252
+ const spot = modalSpot(win, size, [...cards, pill], { bounds, prefer });
253
+ expect(spot).not.toBeNull();
254
+ expect(hit(spot, pill)).toBe(false);
255
+ expect(cards.some((c) => hit(spot, c))).toBe(false);
256
+ });
257
+ });
258
+
259
+ describe("a placed modal and the pointer (behold#744)", () => {
260
+ it("lets the pointer through its sheet to the graph, and keeps it on the modal itself", () => {
261
+ expect(MODAL_STYLE).toMatch(/\.eh-modal-wrap\.eh-modal-placed \{[^}]*pointer-events: none;/);
262
+ expect(MODAL_STYLE).toMatch(/\.eh-modal-wrap\.eh-modal-placed > \.eh-modal \{ pointer-events: auto; \}/);
263
+ });
264
+ });
@@ -0,0 +1,143 @@
1
+ // #683: feature flags on the graph. Pure words and colours from
2
+ // /api/workspace/flags; app.js draws them.
3
+ //
4
+ // A flag is a workspace record chant reads as one build parameter of one
5
+ // member (chant#4024). chant names no graph node that reads a parameter, so a
6
+ // flag marks every card of its member, with a tag under the card in the
7
+ // environment the tab picks: on in the managed green, off or unset in the
8
+ // neutral grey, any other value in the pending blue. A flag the stale-flag
9
+ // lint reports (WSP118) says so on the tag and in the tab. The tag sits under
10
+ // the card, clear of the change set's tag above it, and the fill stays the
11
+ // live-status channel.
12
+ //
13
+ // behold changes no flag. A flip waiting at a gate opens that gate's change
14
+ // set (#681); otherwise the tab shows the lines a person runs.
15
+
16
+ const short = (s) => (s ? String(s).replace(/^(jcs1-)?sha256:/, "").slice(0, 12) : "");
17
+ const sha7 = (s) => (s ? String(s).slice(0, 7) : "");
18
+ const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
19
+
20
+ /** The colour each state is drawn in. */
21
+ export const STATE_COLORS = { on: "var(--managed)", off: "var(--neutral)", default: "var(--neutral)", set: "var(--pending)" };
22
+ /** The colour of the stale mark. */
23
+ export const STALE_COLOR = "var(--degraded)";
24
+
25
+ /** The note on how cards are tied to flags. */
26
+ export const NODES_NOTE = "chant does not say which resources read a build parameter, so each flag marks every card of its member.";
27
+ /** The note under the lines that turn a flag on. */
28
+ export const TURN_ON_NOTE = "behold does not change flags. Once this commit is green, a release cut from it and promoted to the environment waits at its gate, and its change set opens here.";
29
+ /** The words for a flag the stale-flag lint reports. */
30
+ export const STALE_WORDS = "due for removal (WSP118)";
31
+
32
+ /** A value in words: on, off, unset, or the value. */
33
+ export function stateWords(e) {
34
+ if (!e) return "unset";
35
+ if (e.state === "on") return "on";
36
+ if (e.state === "off") return "off";
37
+ if (e.state === "default") return "unset";
38
+ return JSON.stringify(e.value);
39
+ }
40
+
41
+ /** The tab's first line: what was read, or why it wasn't. */
42
+ export function flagsHeader(a) {
43
+ if (!a || a.error) return { text: `flags not read${a && a.error ? `: ${a.error}` : ""}`, title: "", tone: "refusal" };
44
+ if (a.refusal) return { text: `flags not read: ${a.refusal.error}`, title: [a.refusal.remedy, a.degraded ? `Without it, ${a.degraded}.` : ""].filter(Boolean).join("\n"), tone: "refusal" };
45
+ const stale = a.flags.filter((f) => f.stale).length;
46
+ return { text: `${plural(a.flags.length, "flag")}${stale ? `, ${stale} ${STALE_WORDS}` : ""}`, title: NODES_NOTE, tone: "quiet" };
47
+ }
48
+
49
+ /** The environment to draw: `want` when the answer has it, else the first. */
50
+ export function pickEnv(a, want) {
51
+ const envs = (a && a.environments) || [];
52
+ return envs.includes(want) ? want : envs[0] || null;
53
+ }
54
+
55
+ /** One flag's row in the tab. `env` is the environment the graph draws. */
56
+ export function flagRow(f, env) {
57
+ const facts = [`param ${f.param}`, `owner ${f.owner || "none"}`, f.work ? `work ${f.work.id}${f.work.state ? ` (${f.work.state})` : ""}` : "no work item"];
58
+ const values = Object.entries(f.envs).map(([e, v]) => ({ env: e, text: `${e} ${stateWords(v)}`, color: STATE_COLORS[v.state] || "var(--muted)", current: e === env }));
59
+ const waiting = f.waiting.map((w) => ({
60
+ env: w.env,
61
+ gate: w.gate,
62
+ text: `${f.param} ${JSON.stringify(w.before)} to ${JSON.stringify(w.after)} waits at gate ${w.gate} in ${w.env}`,
63
+ link: `change set ${short(w.changeSet)}`,
64
+ title: [
65
+ `Draw this change set on the graph, as a preview.`,
66
+ w.gitSha ? `commit ${sha7(w.gitSha)}` : "",
67
+ w.releaseDigest ? `release ${short(w.releaseDigest)}` : "",
68
+ ...w.entries.map((e) => `${e.address}${e.node ? ` on ${e.node}` : ", on no graph node"}`),
69
+ ]
70
+ .filter(Boolean)
71
+ .join("\n"),
72
+ }));
73
+ const turnOn = f.turnOn.map((t) => ({ env: t.env, head: `To turn it on in ${t.env}:`, lines: t.lines }));
74
+ return {
75
+ key: f.key,
76
+ title: f.key,
77
+ stale: f.stale ? { text: STALE_WORDS, title: staleTitle(f) } : null,
78
+ facts: facts.join(" · "),
79
+ path: f.path,
80
+ values,
81
+ waiting,
82
+ turnOn,
83
+ };
84
+ }
85
+
86
+ /** Why a stale flag is due for removal, from the decisions its work item implements. */
87
+ export function staleTitle(f) {
88
+ const ds = (f.implements || []).map((d) => `${d.id} (${d.state || "unknown"})`).join(", ");
89
+ return `The stale-flag lint (chant workspace check, WSP118) reports it: ${f.work ? `its work item ${f.work.id}` : "its work item"} implements ${ds || "no decision"}, and every one is confirmed. Remove the record and the parameter it backs.`;
90
+ }
91
+
92
+ /**
93
+ * The marks to draw in `env`: per node id in `ids`, a colour, a tag and a
94
+ * tooltip, for every card whose member has a flag. `memberOf(id)` gives a
95
+ * card's member.
96
+ */
97
+ export function flagMarks(a, env, ids, memberOf) {
98
+ const out = {};
99
+ if (!a || a.error || a.refusal || !a.flags || !env) return out;
100
+ const byMember = new Map();
101
+ for (const f of a.flags) {
102
+ if (!byMember.has(f.member)) byMember.set(f.member, []);
103
+ byMember.get(f.member).push(f);
104
+ }
105
+ for (const id of ids) {
106
+ const flags = byMember.get(memberOf(id));
107
+ if (!flags || !flags.length) continue;
108
+ const on = flags.filter((f) => f.envs[env] && f.envs[env].state === "on").length;
109
+ const stale = flags.filter((f) => f.stale).length;
110
+ let tag;
111
+ if (flags.length === 1) {
112
+ const f = flags[0];
113
+ tag = `${f.id}: ${stateWords(f.envs[env])}${f.stale ? ", stale" : ""}`;
114
+ } else {
115
+ tag = `${plural(flags.length, "flag")}: ${on} on${stale ? `, ${stale} stale` : ""}`;
116
+ }
117
+ const lines = flags.map((f) => `${f.id} (${f.param}): ${stateWords(f.envs[env])} in ${env}${f.stale ? `, ${STALE_WORDS}` : ""}`);
118
+ out[id] = {
119
+ color: on ? STATE_COLORS.on : flags.some((f) => f.envs[env] && f.envs[env].state === "set") ? STATE_COLORS.set : STATE_COLORS.off,
120
+ stale: stale > 0,
121
+ tag,
122
+ title: [`feature flags of ${memberOf(id)} in ${env}:`, ...lines, "", NODES_NOTE].join("\n"),
123
+ };
124
+ }
125
+ return out;
126
+ }
127
+
128
+ /** The flags of one card's member, for the inspect pane. */
129
+ export function flagsFor(a, member, env) {
130
+ if (!a || a.error || a.refusal || !a.flags || !env) return [];
131
+ return a.flags
132
+ .filter((f) => f.member === member)
133
+ .map((f) => ({ text: `${f.id}: ${stateWords(f.envs[env])} in ${env}${f.stale ? `, ${STALE_WORDS}` : ""}`, color: STATE_COLORS[(f.envs[env] || {}).state] || "var(--muted)", title: flagRow(f, env).facts }));
134
+ }
135
+
136
+ /** The lines that say what the answer leaves out: members whose flags could not be read, and reads that failed. */
137
+ export function gapLines(a) {
138
+ if (!a || a.error || a.refusal) return [];
139
+ return [
140
+ ...(a.unreadable || []).map((m) => ({ text: `chant could not read the flag records of ${m}`, title: "Run chant workspace records in the workspace root to see why." })),
141
+ ...(a.refusals || []).map((r) => ({ text: r.gate ? `the change set of ${r.gate} in ${r.env} was not read: ${r.error}` : `${r.env} was not read: ${r.error}`, title: r.remedy || "" })),
142
+ ];
143
+ }
@@ -0,0 +1,96 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { describe, expect, it } from "vitest";
4
+ import { flagsFrom, shownKey } from "../src/feature-flags.ts";
5
+ import { gatesFromStatus } from "../src/workspace-gates.ts";
6
+ import { flagMarks, flagRow, flagsFor, flagsHeader, gapLines, NODES_NOTE, pickEnv, STALE_WORDS, STATE_COLORS, stateWords, TURN_ON_NOTE } from "./feature-flags.js";
7
+
8
+ // #683: the flags drawn from what chant printed for the fixture workspace
9
+ // (src/__fixtures__/feature-flags), as the route answers it: new-checkout on
10
+ // in staging and off in prod, old-banner stale, and a release gate in staging
11
+ // whose change set turns new-checkout on.
12
+ const FIX = join(import.meta.dirname, "..", "src", "__fixtures__", "feature-flags");
13
+ const fixture = (name) => JSON.parse(readFileSync(join(FIX, name), "utf8"));
14
+ const gatesOf = (name) => gatesFromStatus(fixture(name), "/ws").gates.map(({ dir: _dir, ...g }) => g);
15
+ const GATE = "web/release/promote";
16
+ const answer = {
17
+ workspace: true,
18
+ chant: "0.124.29",
19
+ ...flagsFrom({
20
+ status: fixture("status-staging.json"),
21
+ env: "staging",
22
+ gates: [
23
+ { env: "staging", gates: gatesOf("status-staging.json") },
24
+ { env: "prod", gates: gatesOf("status-prod.json") },
25
+ ],
26
+ shown: new Map([[shownKey("staging", GATE), fixture("change-set-show.json")]]),
27
+ at: new Date("2026-10-17T00:00:00Z"),
28
+ }),
29
+ };
30
+ const member = (id) => id.split("/")[0];
31
+ const IDS = ["web/CheckoutFunction", "web/BannerConfig", "api/Queue"];
32
+ const one = { ...answer, flags: answer.flags.filter((f) => f.id === "new-checkout") };
33
+
34
+ describe("flag marks on the graph (#683)", () => {
35
+ it("marks a flagged member's cards on in staging and off in prod, and leaves other members alone", () => {
36
+ const staging = flagMarks(one, "staging", IDS, member);
37
+ expect(Object.keys(staging)).toEqual(["web/CheckoutFunction", "web/BannerConfig"]);
38
+ expect(staging["web/CheckoutFunction"]).toMatchObject({ tag: "new-checkout: on", color: STATE_COLORS.on, stale: false });
39
+ const prod = flagMarks(one, "prod", IDS, member);
40
+ expect(prod["web/CheckoutFunction"]).toMatchObject({ tag: "new-checkout: off", color: STATE_COLORS.off });
41
+ expect(prod["web/CheckoutFunction"].title).toContain(NODES_NOTE);
42
+ });
43
+ it("counts several flags on one card, and names the stale one", () => {
44
+ const prod = flagMarks(answer, "prod", IDS, member);
45
+ expect(prod["web/CheckoutFunction"]).toMatchObject({ tag: "2 flags: 1 on, 1 stale", stale: true });
46
+ expect(prod["web/CheckoutFunction"].title).toContain(`old-banner (banner): on in prod, ${STALE_WORDS}`);
47
+ expect(prod["web/CheckoutFunction"].title).toContain("new-checkout (newCheckout): off in prod");
48
+ });
49
+ it("draws nothing for a refusal, and picks the environment the tab asks for when it has it", () => {
50
+ expect(flagMarks({ refusal: { error: "x" } }, "prod", IDS, member)).toEqual({});
51
+ expect(pickEnv(answer, "prod")).toBe("prod");
52
+ expect(pickEnv(answer, "local")).toBe("staging");
53
+ expect(stateWords({ state: "default", value: null })).toBe("unset");
54
+ expect(stateWords({ state: "set", value: "blue" })).toBe('"blue"');
55
+ });
56
+ it("lists a card's flags in the inspect pane", () => {
57
+ expect(flagsFor(answer, "web", "staging").map((r) => r.text)).toEqual(["new-checkout: on in staging", `old-banner: on in staging, ${STALE_WORDS}`]);
58
+ expect(flagsFor(answer, "api", "staging")).toEqual([]);
59
+ });
60
+ });
61
+
62
+ describe("the Flags tab (#683)", () => {
63
+ it("shows each flag's owner, work item and values", () => {
64
+ const r = flagRow(answer.flags.find((f) => f.id === "new-checkout"), "prod");
65
+ expect(r.title).toBe("web/new-checkout");
66
+ expect(r.facts).toBe("param newCheckout · owner alice · work W-002 (in-progress)");
67
+ expect(r.values.map((v) => [v.text, v.current])).toEqual([
68
+ ["staging on", false],
69
+ ["prod off", true],
70
+ ]);
71
+ expect(r.stale).toBeNull();
72
+ });
73
+ it("opens a flip waiting at a gate as that gate's change set, with no toggle", () => {
74
+ const r = flagRow(answer.flags.find((f) => f.id === "new-checkout"), "staging");
75
+ expect(r.waiting).toEqual([
76
+ expect.objectContaining({ env: "staging", gate: GATE, text: `newCheckout false to true waits at gate ${GATE} in staging`, link: "change set 05c8b35bc9a3" }),
77
+ ]);
78
+ expect(r.waiting[0].title).toContain("web, on no graph node");
79
+ });
80
+ it("gives the lines a person runs to turn it on where nothing waits, and says what follows", () => {
81
+ const r = flagRow(answer.flags.find((f) => f.id === "new-checkout"), "prod");
82
+ expect(r.turnOn).toEqual([{ env: "prod", head: "To turn it on in prod:", lines: expect.arrayContaining([expect.stringContaining("chant workspace records amend new-checkout")]) }]);
83
+ expect(TURN_ON_NOTE).toMatch(/does not change flags/);
84
+ });
85
+ it("marks the flag the stale-flag lint reports, with why", () => {
86
+ const r = flagRow(answer.flags.find((f) => f.id === "old-banner"), "prod");
87
+ expect(r.stale).toEqual({ text: STALE_WORDS, title: expect.stringContaining("W-001 implements d-001 (confirmed)") });
88
+ expect(flagsHeader(answer)).toMatchObject({ text: `2 flags, 1 ${STALE_WORDS}`, tone: "quiet" });
89
+ });
90
+ it("says why nothing was read, and what is missing below the floor", () => {
91
+ const h = flagsHeader({ refusal: { error: "Feature flags needs chant 0.124.29 or newer.", remedy: "Upgrade." }, degraded: "the graph draws no flag marks" });
92
+ expect(h).toMatchObject({ tone: "refusal", text: "flags not read: Feature flags needs chant 0.124.29 or newer." });
93
+ expect(h.title).toContain("Without it, the graph draws no flag marks.");
94
+ expect(gapLines({ ...answer, unreadable: ["api"], refusals: [{ env: "prod", error: "boom", remedy: "r" }] }).map((g) => g.text)).toEqual(["chant could not read the flag records of api", "prod was not read: boom"]);
95
+ });
96
+ });
package/web/index.html CHANGED
@@ -301,6 +301,34 @@
301
301
  .cs-entry::before { content: ""; position: absolute; left: 0; top: 3px; bottom: 3px; width: 3px; border-radius: 2px; background: var(--bar, var(--bar-neutral)); }
302
302
  .cs-entry-head { font-family: var(--font-mono); font-weight: 600; }
303
303
  .cs-entry-facts, .cs-entry-field { color: var(--muted); font-family: var(--font-mono); }
304
+ /* #683: feature flags, on or off per environment. */
305
+ #panel-body #tab-flags.active { display: flex; flex-direction: column; gap: var(--s1); font-size: var(--t-caption); }
306
+ #tab-flags .fl-title { font-weight: 600; }
307
+ #tab-flags .tg-legend { color: var(--ink2); overflow-wrap: anywhere; }
308
+ #tab-flags .tg-refusal { color: var(--degraded); font-weight: 600; overflow-wrap: anywhere; }
309
+ #tab-flags .fl-envs { display: flex; flex-wrap: wrap; align-items: center; gap: var(--s1); color: var(--muted); }
310
+ #tab-flags .fl-env.on { border-color: var(--pending); font-weight: 600; }
311
+ #tab-flags .fl-flag { border: 1px solid var(--rule); border-radius: 6px; padding: var(--s2) var(--s3); display: flex; flex-direction: column; gap: 3px; }
312
+ #tab-flags .fl-flag-title { font-weight: 600; font-family: var(--font-mono); overflow-wrap: anywhere; }
313
+ #tab-flags .fl-stale { color: var(--degraded); }
314
+ #tab-flags .fl-facts, #tab-flags .fl-turn-on { color: var(--muted); overflow-wrap: anywhere; }
315
+ #tab-flags .fl-values { display: flex; flex-wrap: wrap; gap: var(--s2); }
316
+ #tab-flags .fl-value { font-family: var(--font-mono); }
317
+ #tab-flags .fl-value::before { content: ""; display: inline-block; width: 8px; height: 8px; border-radius: 50%; margin-right: 4px; background: var(--dot, var(--neutral)); }
318
+ #tab-flags .fl-value.current { font-weight: 600; }
319
+ #tab-flags .fl-waiting { overflow-wrap: anywhere; }
320
+ #tab-flags a { color: inherit; }
321
+ #tab-flags .lane-change-set { color: var(--pending); }
322
+ #tab-flags .fl-lines { margin: 0; padding: var(--s1) var(--s2); font-family: var(--font-mono); font-size: var(--t-caption); white-space: pre-wrap; overflow-wrap: anywhere; background: var(--panel); border-radius: 4px; }
323
+ /* #684: collision marks. The tab reuses the Flags tab's rows. */
324
+ #panel-body #tab-collisions.active { display: flex; flex-direction: column; gap: var(--s1); font-size: var(--t-caption); }
325
+ #tab-collisions .fl-title { font-weight: 600; }
326
+ #tab-collisions .tg-legend { color: var(--ink2); overflow-wrap: anywhere; }
327
+ #tab-collisions .tg-refusal { color: var(--degraded); font-weight: 600; overflow-wrap: anywhere; }
328
+ #tab-collisions .fl-flag { border: 1px solid var(--rule); border-radius: 6px; padding: var(--s2) var(--s3); display: flex; flex-direction: column; gap: 3px; }
329
+ #tab-collisions .fl-flag-title { font-weight: 600; font-family: var(--font-mono); overflow-wrap: anywhere; }
330
+ #tab-collisions .fl-stale { color: var(--degraded); }
331
+ #tab-collisions .fl-facts { color: var(--muted); font-family: var(--font-mono); overflow-wrap: anywhere; }
304
332
  .rel-strip { border-collapse: collapse; margin: var(--s2) 0; font-size: 12px; }
305
333
  .rel-strip th, .rel-strip td { padding: 3px var(--s2); text-align: left; vertical-align: top; border-bottom: 1px solid var(--neutral); }
306
334
  .rel-strip .rel-component { font-family: var(--font-mono); overflow-wrap: anywhere; }
@@ -388,6 +416,11 @@
388
416
  #inspect .why-list code { font: var(--t-body)/1.45 var(--font-mono); }
389
417
  #inspect .why-meta { color: var(--muted); font-size: var(--t-caption); }
390
418
  #inspect .why-gap, #inspect .why-refusal { color: var(--pending); }
419
+ /* #682: the chain. Each link is a row under its commit; a missing one is in the pending colour. */
420
+ #inspect .why-link { margin: var(--s1) 0 0; }
421
+ #inspect .why-missing { color: var(--pending); }
422
+ #inspect .why-source { display: flex; gap: var(--s2); align-items: center; min-width: 0; }
423
+ #inspect .why-source code { flex: 1; min-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; color: var(--muted); font-size: var(--t-caption); }
391
424
 
392
425
  /* ---- Collapsible JSON (#259) -----------------------------------------
393
426
  web/json-view.js builds this; nothing else styles it. Two colours and