@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
@@ -79,7 +79,7 @@ export function mergeLandings(tips, names = {}) {
79
79
  * bar, caption: elements to draw into; tipsHost, modalHost: where bubbles and
80
80
  * modals go; origin(): the page offset of the layer the state's box rects are in.
81
81
  */
82
- export function createNarration({ bar, caption, tipsHost, modalHost, origin }) {
82
+ export function createNarration({ bar, caption, tipsHost, modalHost, origin, quiet = () => null, docked = () => false }) {
83
83
  if (!document.getElementById(TIPS_STYLE_ID)) {
84
84
  const st = el("style");
85
85
  st.id = TIPS_STYLE_ID;
@@ -100,6 +100,17 @@ export function createNarration({ bar, caption, tipsHost, modalHost, origin }) {
100
100
  };
101
101
  const placeTip = (state) => {
102
102
  if (!tip) return;
103
+ // A bubble about no one estate (the end), while the kiosk docks them: at the stage's top left, where the frame
104
+ // keeps the boxes clear of it (web/kiosk-carve.js), never over the middle of the stage.
105
+ const dockIt = !tip.t.estate && docked();
106
+ tip.node.classList.toggle("eh-tip-dock", dockIt);
107
+ if (dockIt) {
108
+ const o = origin();
109
+ const at = `translate(${Math.round(o.left + 12)}px, ${Math.round(o.top + 12)}px)`;
110
+ tip.node.style.setProperty("--eh-at", at);
111
+ tip.node.style.transform = at;
112
+ return;
113
+ }
103
114
  const size = { w: tip.node.offsetWidth, h: tip.node.offsetHeight };
104
115
  const win = { w: window.innerWidth, h: window.innerHeight };
105
116
  let p;
@@ -155,6 +166,18 @@ export function createNarration({ bar, caption, tipsHost, modalHost, origin }) {
155
166
  placeTip(state);
156
167
  };
157
168
 
169
+ /** The quiet line (web/kiosk-watch.js quietWords), from the kiosk; nothing from a page that gives none, such as the static export's replay. */
170
+ const quietLine = () => {
171
+ const q = quiet();
172
+ if (!q || !q.text) return null;
173
+ const p = el("p", "cx-quiet k-quiet");
174
+ if (q.said) p.append(el("span", "k-quiet-said", q.said), el("span", "k-quiet-sep", " · "));
175
+ p.append(el("span", "k-quiet-tail", q.tail || q.text));
176
+ p.setAttribute("role", "status");
177
+ if (q.title) p.title = q.title;
178
+ return p;
179
+ };
180
+
158
181
  let lastChapter = null;
159
182
  const draw = (state) => {
160
183
  if (caption && state.tour) return drawTour(state);
@@ -208,6 +231,9 @@ export function createNarration({ bar, caption, tipsHost, modalHost, origin }) {
208
231
  : `${fmt(tot.done)} of ${fmt(tot.moves)} flown · ${tot.refused} refused · ${estatesW}`;
209
232
  tally.append(el("span", "cx-label", "moves"), el("span", "cx-text", tallyText));
210
233
  caption.appendChild(tally);
234
+ // Under the caption's fixed rows, so they keep their places.
235
+ const q = quietLine();
236
+ if (q) caption.appendChild(q);
211
237
  }
212
238
  };
213
239
 
@@ -254,6 +280,8 @@ export function createNarration({ bar, caption, tipsHost, modalHost, origin }) {
254
280
  card.appendChild(h);
255
281
  for (const line of tr.lines) card.appendChild(el("p", "cx-card-line", line));
256
282
  caption.appendChild(card);
283
+ const q = quietLine();
284
+ if (q) caption.appendChild(q);
257
285
  if (tr.card && tr.card.length) {
258
286
  const grid = el("dl", "cx-numbers");
259
287
  for (const r of tr.card) {
@@ -274,6 +302,10 @@ export function createNarration({ bar, caption, tipsHost, modalHost, origin }) {
274
302
  onLinkChange(() => { if (last) draw(last); });
275
303
 
276
304
  return {
305
+ /** Draw again with what the frame last said: the quiet line changes between the frame's states. */
306
+ redraw() {
307
+ if (last) draw(last);
308
+ },
277
309
  update(state) {
278
310
  if (state.type !== "behold:dots-state") {
279
311
  if (state.type === "behold:dots-ready") shown.clear();
@@ -0,0 +1,138 @@
1
+ // behold#631: a chant apply played at a pace a viewer can follow.
2
+ //
3
+ // On a fast estate (floci) a whole pr-apply settles in about three seconds,
4
+ // less than the time between two uploads of its events, so the view would
5
+ // jump from the first wave applying straight to everything settled. The
6
+ // answer's `live.apply.timeline` (src/chant-pr-events.ts) holds every change
7
+ // of state in stream order. This plays it: each wave shows applying for at
8
+ // least `apply` ms, then done for at least `done` ms, before the next wave's
9
+ // states show. Nothing is invented: every state shown is one the events gave,
10
+ // at a step no later than the stream has reached.
11
+ //
12
+ // - Once the stream has settled, the rest plays at the catch-up pace, so the
13
+ // view reaches the end within a few seconds.
14
+ // - A run first seen already settled (a reload, a late viewer) shows its
15
+ // settled state at once, with no replay.
16
+ // - Without a timeline (an older answer, a repo without events) the answer
17
+ // is shown as it came.
18
+ //
19
+ // Pure apart from the clock it is given.
20
+
21
+ /** Minimum dwell per wave, in ms: applying, then done. The catch-up pace applies once the stream settled. */
22
+ export const PACE = { apply: 3000, done: 1500, catchApply: 1200, catchDone: 600 };
23
+
24
+ const SETTLE = new Set(["applied", "failed", "gated"]);
25
+ const WAVE_SETTLE = new Set(["applied", "failed", "gated"]);
26
+
27
+ /** A run's key: a new run (a re-run, the fix's apply) plays from its own start. */
28
+ const keyOf = (live) => `${live.stage}|${live.runId || ""}|${live.gitSha || ""}|${live.source || ""}`;
29
+
30
+ /**
31
+ * A pacer. `view(live)` answers what to show of that stage's events now, and
32
+ * `pending` whether more is still to come (so a caller keeps redrawing).
33
+ */
34
+ export function createLivePacer({ now = () => Date.now(), pace = PACE } = {}) {
35
+ const runs = new Map();
36
+ let pending = false;
37
+
38
+ const view = (live) => {
39
+ pending = false;
40
+ if (!live || !Array.isArray(live.timeline) || !live.timeline.length) return live;
41
+ const tl = live.timeline;
42
+ const key = keyOf(live);
43
+ let st = runs.get(key);
44
+ if (!st) {
45
+ // First seen settled: no replay. First seen running: play from its start.
46
+ st = { cursor: live.settled ? tl.length : 0, waveStart: new Map(), lastSettleAt: null, lastSettleWave: null };
47
+ runs.set(key, st);
48
+ if (runs.size > 8) runs.delete(runs.keys().next().value);
49
+ }
50
+ const t = now();
51
+ const dwellApply = live.settled ? pace.catchApply : pace.apply;
52
+ const dwellDone = live.settled ? pace.catchDone : pace.done;
53
+ while (st.cursor < tl.length) {
54
+ const e = tl[st.cursor];
55
+ if (e.kind === "wave" && e.state === "running") {
56
+ // The next wave waits until the one before showed done long enough.
57
+ if (st.lastSettleAt !== null && t - st.lastSettleAt < dwellDone) break;
58
+ st.waveStart.set(e.wave, t);
59
+ } else if ((e.kind === "wave" && WAVE_SETTLE.has(e.state)) || (e.kind === "component" && SETTLE.has(e.state))) {
60
+ // A wave's results wait until it showed applying long enough.
61
+ const started = st.waveStart.get(e.wave);
62
+ if (started !== undefined && t - started < dwellApply) break;
63
+ if (e.kind === "wave") {
64
+ st.lastSettleAt = t;
65
+ st.lastSettleWave = e.wave;
66
+ }
67
+ }
68
+ st.cursor++;
69
+ }
70
+ pending = st.cursor < tl.length;
71
+ if (st.cursor >= tl.length) return live;
72
+ return shownAt(live, st.cursor);
73
+ };
74
+
75
+ return {
76
+ view,
77
+ /**
78
+ * The answer with its `live.apply` as it shows now. While the play is
79
+ * behind the stream, the apply's summary waits too (it would say how
80
+ * every card ended), and the stage reads as still running.
81
+ */
82
+ answer(a) {
83
+ if (!a || !a.live || !a.live.apply) {
84
+ pending = false;
85
+ return a;
86
+ }
87
+ const apply = view(a.live.apply);
88
+ if (apply === a.live.apply) return a;
89
+ const running = a.running || (a.apply ? { stage: "apply", run: a.apply.run || null, job: "apply", status: "running", started_at: null } : null);
90
+ return { ...a, apply: null, running, live: { ...a.live, apply } };
91
+ },
92
+ get pending() {
93
+ return pending;
94
+ },
95
+ };
96
+ }
97
+
98
+ /** The stage as its first `n` steps leave it: each state the last step gave, nothing settled yet. */
99
+ export function shownAt(live, n) {
100
+ const tl = live.timeline.slice(0, n);
101
+ const compState = new Map();
102
+ const waveState = new Map();
103
+ for (const e of tl) {
104
+ if (e.kind === "component") compState.set(e.component, e.state);
105
+ else waveState.set(e.wave, e.state);
106
+ }
107
+ const components = {};
108
+ for (const [name, c] of Object.entries(live.components || {})) {
109
+ const state = compState.get(name) || "waiting";
110
+ // An error or a blocker belongs to the state it came with.
111
+ const same = state === c.state;
112
+ components[name] = {
113
+ component: name,
114
+ wave: c.wave,
115
+ ...(c.waveFrom ? { waveFrom: c.waveFrom } : {}),
116
+ ...(Number.isInteger(c.graphWave) ? { graphWave: c.graphWave } : {}),
117
+ state,
118
+ ...(same && c.error ? { error: c.error } : {}),
119
+ ...(same && c.failedIn ? { failedIn: c.failedIn } : {}),
120
+ ...(same && c.blockedBy ? { blockedBy: c.blockedBy, blockedFrom: c.blockedFrom } : {}),
121
+ };
122
+ }
123
+ const waves = (live.waves || []).map((w) => {
124
+ const counts = { applied: 0, failed: 0, blocked: 0, alreadyApplied: 0, running: 0, waiting: 0 };
125
+ for (const name of w.components) {
126
+ const s = components[name] ? components[name].state : "waiting";
127
+ if (s === "applied") counts.applied++;
128
+ else if (s === "failed") counts.failed++;
129
+ else if (s === "blocked") counts.blocked++;
130
+ else if (s === "already-applied") counts.alreadyApplied++;
131
+ else if (s === "running") counts.running++;
132
+ else if (s !== "gated" && s !== "not-run") counts.waiting++;
133
+ }
134
+ return { ...w, state: waveState.get(w.wave) || "waiting", counts };
135
+ });
136
+ const last = tl[tl.length - 1];
137
+ return { ...live, settled: false, status: null, seq: last ? last.seq : live.seq, at: last ? last.at : live.at, waves, components, paced: true };
138
+ }
@@ -0,0 +1,116 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { PACE, createLivePacer, shownAt } from "./chant-live-pace.js";
3
+
4
+ // behold#631: a fan-out apply that settled in about three seconds (floci),
5
+ // faster than its events were uploaded, played at a pace a viewer can follow.
6
+ const step = (seq, kind, state, more) => ({ seq, at: null, kind, state, ...more });
7
+ const comp = (seq, component, wave, state) => step(seq, "component", state, { component, wave });
8
+ const wave = (seq, n, state) => step(seq, "wave", state, { wave: n });
9
+ const timeline = [
10
+ comp(0, "network", 1, "waiting"),
11
+ comp(0, "cluster-a", 2, "waiting"),
12
+ comp(0, "app-01", 3, "waiting"),
13
+ wave(0, 1, "waiting"),
14
+ wave(0, 2, "waiting"),
15
+ wave(0, 3, "waiting"),
16
+ wave(1, 1, "running"),
17
+ comp(2, "network", 1, "running"),
18
+ comp(3, "network", 1, "applied"),
19
+ wave(4, 1, "applied"),
20
+ wave(5, 2, "running"),
21
+ comp(6, "cluster-a", 2, "running"),
22
+ comp(7, "cluster-a", 2, "failed"),
23
+ wave(8, 2, "failed"),
24
+ comp(9, "app-01", 3, "blocked"),
25
+ ];
26
+ const final = {
27
+ stage: "apply",
28
+ runId: "r1",
29
+ gitSha: "a".repeat(40),
30
+ source: "s3://r/14/x/pr-apply.events.jsonl",
31
+ seq: 10,
32
+ at: null,
33
+ settled: true,
34
+ status: "failed",
35
+ waves: [
36
+ { wave: 1, state: "applied", components: ["network"], counts: {} },
37
+ { wave: 2, state: "failed", components: ["cluster-a"], counts: {} },
38
+ { wave: 3, state: "blocked", components: ["app-01"], counts: {} },
39
+ ],
40
+ components: {
41
+ network: { component: "network", wave: 1, state: "applied" },
42
+ "cluster-a": { component: "cluster-a", wave: 2, state: "failed", error: "stack reached ROLLBACK_COMPLETE", failedIn: "apply" },
43
+ "app-01": { component: "app-01", wave: 3, state: "blocked", blockedBy: "cluster-a", blockedFrom: "event" },
44
+ },
45
+ timeline,
46
+ };
47
+ /** The stream as the first upload had it: network applying, nothing settled. */
48
+ const early = { ...shownAt(final, 8), paced: undefined, settled: false, status: null, timeline: timeline.slice(0, 8) };
49
+
50
+ describe("a fast chant apply, played at a viewer's pace (behold#631)", () => {
51
+ it("shows a run first seen settled at once, with no replay", () => {
52
+ const p = createLivePacer({ now: () => 0 });
53
+ expect(p.view(final)).toBe(final);
54
+ expect(p.pending).toBe(false);
55
+ });
56
+
57
+ it("plays a run first seen running: each wave applying, then done, before the next wave's states", () => {
58
+ let t = 0;
59
+ const p = createLivePacer({ now: () => t });
60
+ // First read: network applying.
61
+ let v = p.view(early);
62
+ expect(v.components.network.state).toBe("running");
63
+ expect(v.waves[0].state).toBe("running");
64
+ // The next upload has the whole run settled, but wave 1 has not shown applying long enough.
65
+ t = 500;
66
+ v = p.view(final);
67
+ expect(v.components.network.state).toBe("running");
68
+ expect(v.settled).toBe(false);
69
+ expect(p.pending).toBe(true);
70
+ // Settled, the rest plays at the catch-up pace: wave 1 done after its applying dwell.
71
+ t = PACE.catchApply;
72
+ v = p.view(final);
73
+ expect(v.components.network.state).toBe("applied");
74
+ expect(v.waves[0].state).toBe("applied");
75
+ expect(v.waves[1].state).toBe("waiting");
76
+ // Wave 2 starts only after wave 1 showed done.
77
+ t += PACE.catchDone;
78
+ v = p.view(final);
79
+ expect(v.waves[1].state).toBe("running");
80
+ expect(v.components["cluster-a"].state).toBe("running");
81
+ expect(v.components["cluster-a"].error).toBeUndefined();
82
+ // Its failure, with the error it came with, after its applying dwell.
83
+ t += PACE.catchApply;
84
+ v = p.view(final);
85
+ expect(v.components["cluster-a"]).toMatchObject({ state: "failed", error: "stack reached ROLLBACK_COMPLETE" });
86
+ expect(v.components["app-01"]).toMatchObject({ state: "blocked", blockedBy: "cluster-a" });
87
+ // Then the end: the answer as it came.
88
+ t += PACE.catchDone;
89
+ expect(p.view(final)).toBe(final);
90
+ expect(p.pending).toBe(false);
91
+ });
92
+
93
+ it("catches up within a few seconds once the stream settled", () => {
94
+ const waves = final.waves.length;
95
+ expect(waves * (PACE.catchApply + PACE.catchDone)).toBeLessThanOrEqual(6000);
96
+ });
97
+
98
+ it("never shows a state the events did not give", () => {
99
+ const states = new Set(timeline.map((e) => e.state));
100
+ for (let n = 0; n <= timeline.length; n++) {
101
+ const v = shownAt(final, n);
102
+ for (const c of Object.values(v.components)) expect(states.has(c.state)).toBe(true);
103
+ }
104
+ });
105
+
106
+ it("hides the apply's summary while it plays, and the stage reads as running", () => {
107
+ let t = 0;
108
+ const p = createLivePacer({ now: () => t });
109
+ const a = { live: { apply: early }, apply: null, running: { stage: "apply", run: 9, job: "apply", status: "running" } };
110
+ p.answer(a);
111
+ t = 100;
112
+ const b = p.answer({ live: { apply: final }, apply: { stage: "apply", run: 9, status: "failed", members: [] }, running: null });
113
+ expect(b.apply).toBeNull();
114
+ expect(b.running).toMatchObject({ stage: "apply", run: 9, status: "running" });
115
+ });
116
+ });