@intentius/behold 0.29.31 → 0.29.33

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.
@@ -0,0 +1,144 @@
1
+ // behold#571: event-help's events, from what the kiosk already reads. A cycle
2
+ // told as facts in order, the news since the last look, the Tips switch, and
3
+ // the queues that keep tips and modals calm.
4
+ import { describe, expect, it } from "vitest";
5
+ import { EH_STORE, cycleFacts, ehSnapshot, ehStore, ehStored, modalQueue, newEvents, storyTrail, tipsQueue, yodelRefusal } from "./kiosk-event-help.js";
6
+
7
+ const C = "9f3c2a71d04e5b8c6a1f2e3d4c5b6a7980716253";
8
+ const P = "1111111111111111111111111111111111111111";
9
+ const waves = [{ job: "apply-wave-1", wave: 1, roots: ["network", "other"] }, { job: "apply-wave-2", wave: 2, roots: ["app"] }, { job: "apply-wave-3", wave: 3, roots: ["edge"] }];
10
+ const demo = (step, more = {}) => ({ cycle: 7, scenario: "b-waves", step, label: `the ${step} line`, started_at: "2026-10-16T10:00:00Z", pull: 12, commit: step === "pull-request" || step === "planned" ? P : C, ...more });
11
+ const answer = { roots: [], pull_request: { run: { pull_request: 12, commit: P }, roots: ["network", "app"], totals: { create: 5 }, reads: [{ root: "app", upstream: "network", outputs: "planned", unknown: ["subnet_id"] }], waves: [] } };
12
+ const progress = (states) => ({ run: { present: true, commit: C, updated: "2026-10-16T10:01:00Z" }, states, reads: [] });
13
+ const st = (number, state, roots, totals = {}) => ({ number, state, roots, changed: roots.filter((r) => r !== "other"), totals });
14
+ const facts = (step, states = [], more = {}) => cycleFacts(ehSnapshot({ demo: demo(step), answer, progress: states.length ? progress(states) : null, waves, ...more }));
15
+ const texts = (fs) => storyTrail(fs).map((f) => f.text);
16
+
17
+ describe("event-help: the Tips switch", () => {
18
+ it("is on by default, off once a viewer turns it off, and on when storage refuses", () => {
19
+ const mem = () => {
20
+ const m = new Map();
21
+ return { getItem: (k) => (m.has(k) ? m.get(k) : null), setItem: (k, v) => m.set(k, v) };
22
+ };
23
+ const shelf = mem();
24
+ expect(ehStored(shelf)).toBe(true);
25
+ ehStore(shelf, false);
26
+ expect(shelf.getItem(EH_STORE)).toBe("off");
27
+ expect(ehStored(shelf)).toBe(false);
28
+ ehStore(shelf, true);
29
+ expect(ehStored(shelf)).toBe(true);
30
+ expect(ehStored({ getItem: () => { throw new Error("denied"); } })).toBe(true);
31
+ expect(() => ehStore({ setItem: () => { throw new Error("denied"); } }, false)).not.toThrow();
32
+ expect(ehStored(null)).toBe(true);
33
+ });
34
+ });
35
+
36
+ describe("event-help: a cycle told in order", () => {
37
+ it("tells the subnet's story, beat by beat, as the steps move", () => {
38
+ expect(texts(facts("pull-request"))).toEqual(["pull request #12 opened"]);
39
+ expect(texts(facts("planned"))).toEqual(["pull request #12 opened", "the plan creates 5"]);
40
+ const held = facts("waiting", [st(1, "applied", ["network", "other"], { create: 1 }), st(2, "waiting", ["app"]), st(3, "not-started", ["edge"])]);
41
+ expect(texts(held)).toEqual(["pull request #12 opened", "the plan creates 5", "pull request #12 merged", "wave 1 applied: 1 created", "subnet_id now known", "wave 2 held, since app's plan uses subnet_id"]);
42
+ const approval = { wave: 2, rows: [{ id: "requested", state: "lit" }, { id: "approved", state: "lit", text: "demo-reviewer approved exactly this plan.", seal: { ok: true, text: "signed; matches the repo's allowed signers" } }, { id: "resumed", state: "lit" }, { id: "spent", state: "dim" }] };
43
+ const done = facts("applied", [st(1, "applied", ["network", "other"], { create: 1 }), st(2, "applied", ["app"], { create: 4 }), st(3, "applied", ["edge"])], { approval });
44
+ expect(texts(done)).toEqual([
45
+ "pull request #12 opened",
46
+ "the plan creates 5",
47
+ "pull request #12 merged",
48
+ "wave 1 applied: 1 created",
49
+ "subnet_id now known",
50
+ "wave 2 held, since app's plan uses subnet_id",
51
+ "approved by demo-reviewer, signed",
52
+ "/terragucci apply ran the waves again",
53
+ "wave 2 applied under demo-reviewer's approval",
54
+ "wave 3 applied",
55
+ "all 3 waves applied",
56
+ ]);
57
+ });
58
+
59
+ it("holds the whole change when the gate names no wave (chant's pull-request loop)", () => {
60
+ expect(cycleFacts(ehSnapshot({ demo: demo("waiting"), answer })).find((f) => f.kind === "held")).toMatchObject({ text: "the plan waits for an approval", critical: true });
61
+ // A repo with declared waves waits for the run view to name the held wave: no second, vaguer hold first.
62
+ expect(facts("waiting").some((f) => f.kind === "held")).toBe(false);
63
+ });
64
+
65
+ it("names each event's subjects, so the kiosk can place it", () => {
66
+ const held = facts("waiting", [st(1, "applied", ["network", "other"]), st(2, "waiting", ["app"])], { runDoc: { id: 4801, cycle: 7, jobs: [{ name: "apply-wave-2", status: "waiting", steps: [] }] } });
67
+ expect(held.find((f) => f.kind === "held")).toMatchObject({ critical: true, subjects: { roots: ["app"], wave: 2, job: "apply-wave-2", run: 4801 } });
68
+ expect(held.find((f) => f.kind === "known").subjects.roots).toEqual(["network", "app"]);
69
+ });
70
+
71
+ it("says SQL Yodeler's refusal from the failed job's own log, and the re-run", () => {
72
+ const log = ["yodel apply: refused: a pre-migration check of 20261016T0521-unique-email failed under the lock", " step 0, CREATE UNIQUE INDEX CONCURRENTLY users_email_key ON app.users (email), would fail: 1 values of (email) held by more than one row, which a unique index fails on"];
73
+ expect(yodelRefusal(log)).toBe("SQL Yodeler refused, since an email is shared by more than one row");
74
+ expect(yodelRefusal(["dev: apply failed"])).toBeNull();
75
+ const runDoc = { id: 4826, cycle: 7, jobs: [{ name: "apply-wave-2", status: "failure", steps: [{ name: "Apply", status: "failure", log }] }] };
76
+ const failed = facts("failed", [st(1, "applied", ["network", "other"]), st(2, "failed", ["app"])], { runDoc });
77
+ expect(failed.find((f) => f.kind === "refused")).toMatchObject({ text: "SQL Yodeler refused, since an email is shared by more than one row", critical: true, subjects: { wave: 2, job: "apply-wave-2" } });
78
+ // The re-run, once the run view shows the wave applying again in a run where its job no longer failed.
79
+ const again = cycleFacts(ehSnapshot({ demo: demo("resumed"), answer, progress: progress([st(1, "applied", ["network", "other"]), st(2, "applying", ["app"])]), runDoc: { id: 4830, cycle: 7, jobs: [{ name: "apply-wave-2", status: "running", steps: [] }] }, waves }));
80
+ expect(again.some((f) => f.kind === "rerun")).toBe(false); // this snapshot never saw the failure
81
+ // A viewer who arrives after the re-run still gets the refusal, from the cycle's earlier run.
82
+ const later = cycleFacts(ehSnapshot({ demo: demo("waiting"), answer, progress: progress([st(1, "applied", ["network", "other"]), st(2, "waiting", ["app"])]), runDoc: { id: 4830, cycle: 7, jobs: [{ name: "apply-wave-2", status: "waiting", steps: [] }] }, runDocs: [runDoc], waves }));
83
+ expect(storyTrail(later).map((f) => f.kind)).toContain("refused");
84
+ expect(later.find((f) => f.kind === "refused").subjects).toMatchObject({ wave: 2, job: "apply-wave-2", run: 4826 });
85
+ const seenFailing = cycleFacts(ehSnapshot({ demo: demo("resumed"), answer, progress: progress([st(1, "applied", ["network", "other"]), st(2, "applying", ["app"])]), runDoc: { id: 4830, cycle: 7, jobs: [{ name: "apply-wave-2", status: "running", steps: [] }] }, waves, failed: [2] }));
86
+ expect(seenFailing.find((f) => f.kind === "rerun")).toMatchObject({ text: "wave 2 runs again", subjects: { wave: 2 } });
87
+ });
88
+
89
+ it("pops a tip when a wave starts or its numbers land, and tells the story's beat when its trace is ready", () => {
90
+ const metrics = { run: { current: true, label: `This run · ${C.slice(0, 8)}`, waves: [{ wave: 1, seconds: "1.6 s", held: null, changed: "1 created" }] } };
91
+ const waveTraces = { 1: { run: "9", job: "apply-wave-1", trace: { wave: 1, ms: 1600, start: 0, spans: [{ id: "r", parent: null, name: "tf-apply", start: 0, ms: 1600, attrs: {} }, { id: "p", parent: "r", name: "plan", start: 0, ms: 1200, attrs: { "terragucci.phase": "plan" } }] } } };
92
+ const fs = facts("applying", [st(1, "applying", ["network", "other"])], { metrics, waveTraces, runDoc: { id: 9, cycle: 7, jobs: [] } });
93
+ expect(fs.filter((f) => !f.trail).map((f) => f.text)).toEqual(["wave 1 started", "wave 1: 1.6 s · 1 created"]);
94
+ // A wave's trace is a beat of the story, its tip saying what the trace shows; a click on it opens the trace.
95
+ expect(fs.find((f) => f.kind === "trace")).toMatchObject({ trail: true, text: "wave 1's trace is ready; it took 1.6 s, 1.2 s of it in the plan", subjects: { wave: 1, job: "apply-wave-1", run: "9" } });
96
+ expect(fs.find((f) => f.kind === "metrics").subjects.wave).toBe(1);
97
+ // An older run's numbers are not this cycle's news.
98
+ expect(facts("applying", [], { metrics: { run: { current: false, waves: metrics.run.waves } } }).some((f) => f.kind === "metrics")).toBe(false);
99
+ // Nor are the last cycle's, still on screen as a new one opens its pull request.
100
+ expect(facts("pull-request", [], { metrics }).some((f) => f.kind === "metrics")).toBe(false);
101
+ expect(facts("applying", [], { metrics: { run: { ...metrics.run, label: "This run · 0badc0de" } } }).some((f) => f.kind === "metrics")).toBe(false);
102
+ });
103
+ });
104
+
105
+ describe("event-help: what is news", () => {
106
+ it("is nothing on a page's first look (the trail has it), then each fact the first time it shows", () => {
107
+ const a = facts("planned");
108
+ expect(newEvents(null, a)).toEqual([]);
109
+ const seen = new Set(a.map((f) => f.id));
110
+ const b = facts("waiting", [st(1, "applied", ["network", "other"]), st(2, "waiting", ["app"])]);
111
+ // A wave's start beside its own next beat is said by the beat.
112
+ expect(newEvents(seen, b).map((f) => f.kind)).toEqual(["merged", "applied-wave", "known", "held"]);
113
+ const c = facts("applying", [st(1, "applying", ["network", "other"])]);
114
+ expect(newEvents(new Set(), c).map((f) => f.text)).toEqual(["pull request #12 opened", "the plan creates 5", "pull request #12 merged", "wave 1 started"]);
115
+ });
116
+
117
+ it("keeps a fact that turns up late, behind the story already told, for the trail alone", () => {
118
+ const b = facts("waiting", [st(1, "applied", ["network", "other"]), st(2, "waiting", ["app"])]);
119
+ const after = Math.max(...b.map((f) => f.order)) - 10;
120
+ expect(newEvents(new Set(), b, { after }).map((f) => f.kind)).toEqual(["applied-wave", "known", "held"]);
121
+ });
122
+ });
123
+
124
+ describe("event-help: calm queues", () => {
125
+ const ev = (id, critical = false, kind = "applied-wave") => ({ id, kind, critical });
126
+ it("shows two tips at once, each its time, and the rest wait their turn", () => {
127
+ let q = tipsQueue(null, { add: [ev("a"), ev("b"), ev("c")], now: 0 });
128
+ expect(q.shown.map((s) => s.event.id)).toEqual(["a", "b"]);
129
+ expect(q.waiting.map((e) => e.id)).toEqual(["c"]);
130
+ q = tipsQueue(q, { now: 4_999 });
131
+ expect(q.shown.map((s) => s.event.id)).toEqual(["a", "b"]);
132
+ q = tipsQueue(q, { now: 5_000 });
133
+ expect(q.shown.map((s) => s.event.id)).toEqual(["c"]);
134
+ expect(tipsQueue(q, { add: [ev("c")], now: 5_001 }).waiting).toEqual([]);
135
+ });
136
+
137
+ it("opens one modal at a time, never while a viewer is at the page, newest of each kind", () => {
138
+ const held = ev("held", true, "held");
139
+ const held2 = ev("held2", true, "held");
140
+ expect(modalQueue(null, { add: [ev("x"), held], now: 10_000, lastInput: 9_000 })).toEqual({ next: null, waiting: [held] });
141
+ expect(modalQueue({ waiting: [held] }, { add: [held2], now: 30_000 }).next).toBe(held2);
142
+ expect(modalQueue({ waiting: [held] }, { now: 30_000, open: true }).next).toBeNull();
143
+ });
144
+ });
package/web/kiosk-runs.js CHANGED
@@ -604,14 +604,21 @@ export function renderRun(host, answer, ui, { now = new Date(), pickJob = () =>
604
604
  if (!job) return { log: null, steps: null, key: null };
605
605
  // behold#571: a job with a trace in Tempo offers it beside its steps (web/kiosk-trace.js).
606
606
  if (trace && trace.has(job.name)) {
607
+ // behold#571: the job's header carries the toggle between its steps and its trace, so it reads as a choice, not one more chip.
607
608
  const tabs = el("div", "t-tabs");
609
+ const head = el("span", "t-tabs-job");
610
+ head.append(statusIcon(job.status), el("span", "r-steps-job", job.name));
611
+ const seg = el("div", "t-seg");
612
+ seg.setAttribute("role", "group");
613
+ seg.setAttribute("aria-label", `${job.name}: steps or trace`);
608
614
  for (const [view, words] of [["steps", "Steps"], ["trace", "Trace"]]) {
609
615
  const b = el("button", "t-tab", words);
610
616
  b.type = "button";
611
617
  b.setAttribute("aria-pressed", String((jobView === "trace") === (view === "trace")));
612
618
  b.addEventListener("click", () => pickView(view));
613
- tabs.appendChild(b);
619
+ seg.appendChild(b);
614
620
  }
621
+ tabs.append(head, seg);
615
622
  host.appendChild(tabs);
616
623
  if (jobView === "trace") {
617
624
  const box = el("div", "r-steps r-trace");
@@ -1095,6 +1102,16 @@ export function startRuns(
1095
1102
  if (s.run && s.run.doc && s.run.doc.id === run) draw();
1096
1103
  else void readRun();
1097
1104
  };
1105
+ /** behold#571: a job of a run from elsewhere (Watch's wave boxes, event-help's tips): its steps, or its trace. */
1106
+ s.showJob = (run, job, view = "steps") => {
1107
+ if (run !== null && run !== undefined) s.selected = Number.isNaN(Number(run)) ? run : Number(run);
1108
+ follow = false;
1109
+ s.picked = now().getTime();
1110
+ s.ui = { job, open: null, setup: null };
1111
+ jobView = view;
1112
+ if (s.run && s.run.doc && String(s.run.doc.id) === String(run)) draw();
1113
+ else void readRun();
1114
+ };
1098
1115
  return s;
1099
1116
  }
1100
1117
 
@@ -192,9 +192,14 @@ export function runStrip(traces) {
192
192
 
193
193
  const STYLE = `
194
194
  .t-trace { padding: 0.2em 0 0.6em; font-size: 0.86em; }
195
- .t-tabs { display: flex; gap: 0.3em; padding: 0.5em 1em 0.1em; flex-wrap: wrap; }
196
- .t-tab { font: 600 0.78em var(--font-mono); text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted); background: transparent; border: 1px solid var(--rule); border-radius: 999px; padding: 0.2em 0.8em; cursor: pointer; }
197
- .t-tab[aria-pressed="true"] { color: var(--fg); background: var(--active); border-color: var(--focus); }
195
+ .t-tabs { display: flex; align-items: center; justify-content: space-between; gap: 0.6em; padding: 0.45em 1em 0.35em; flex-wrap: wrap; border-bottom: 1px solid color-mix(in srgb, var(--rule) 55%, transparent); }
196
+ .t-tabs-job { display: inline-flex; align-items: center; gap: 0.5em; min-width: 0; }
197
+ .t-tabs-job .r-icon { margin: 0; }
198
+ .t-seg { display: inline-flex; border: 1px solid var(--rule); border-radius: 999px; overflow: hidden; flex: none; }
199
+ .t-tab { font: 600 0.9em var(--font-ui); color: var(--muted); background: transparent; border: 0; padding: 0.25em 1em; cursor: pointer; }
200
+ .t-tab + .t-tab { border-left: 1px solid var(--rule); }
201
+ .t-tab:hover { color: var(--fg); }
202
+ .t-tab[aria-pressed="true"], .t-tab[aria-pressed="true"]:hover { color: var(--bg); background: var(--pending); }
198
203
  .t-sec { font: 600 0.8em var(--font-mono); text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted); padding: 0.6em 1em 0.25em; }
199
204
  .t-strip, .t-rows { display: flex; flex-direction: column; }
200
205
  .t-row { display: grid; grid-template-columns: minmax(10em, 38%) minmax(0, 1fr) 4.6em; align-items: center; gap: 0.6em; padding: 0.08em 1em; min-height: 1.55em; cursor: default; }
@@ -0,0 +1,104 @@
1
+ // behold#571: each wave's trace, for the places Watch already shows a wave's
2
+ // numbers: the badge on its box, the applied result card (a mini waterfall
3
+ // per wave), the drawer, and event-help's "trace ready" tip. Pure: it reads
4
+ // /api/traces answers (src/tempo-traces.ts) the kiosk already fetches, one
5
+ // per run of the cycle, and keeps the newest trace of each wave.
6
+
7
+ /** The phases a wave's job runs, in order, as terragucci names them on its stage's spans. */
8
+ export const PHASES = ["plan", "gate", "apply", "report", "upload"];
9
+
10
+ /**
11
+ * The newest trace of each wave across the cycle's runs' answers:
12
+ * `{ [wave]: { run, job, trace } }`. A trace names its wave (`wave`) and its
13
+ * job; a resumed run applies several waves in one job, each its own trace.
14
+ */
15
+ export function waveTraces(answers) {
16
+ const out = {};
17
+ for (const a of answers || []) {
18
+ if (!a || a.error || !Array.isArray(a.traces)) continue;
19
+ for (const t of a.traces) {
20
+ const w = Number(t.wave);
21
+ if (!Number.isInteger(w) || !Array.isArray(t.spans) || !t.spans.length) continue;
22
+ if (!out[w] || out[w].trace.start < t.start) out[w] = { run: String(a.run), job: t.job, trace: t };
23
+ }
24
+ }
25
+ return out;
26
+ }
27
+
28
+ const attrs = (s) => s.attrs || {};
29
+
30
+ /**
31
+ * One wave's trace as phase bars: `[{ phase, ms, at, width, wait }]`, `at` and
32
+ * `width` 0..1 across the stage, in time order. A gate that held a wave for an
33
+ * approval is split: the hold (`phase: "held"`, a wait) and the rest of the
34
+ * gate. Only the phases the trace has; nothing for a trace without them.
35
+ */
36
+ export function phaseBars(trace) {
37
+ const spans = trace && Array.isArray(trace.spans) ? trace.spans : [];
38
+ const root = spans.find((s) => !s.parent) || null;
39
+ if (!root || !(root.ms > 0)) return [];
40
+ const t0 = root.start;
41
+ const span = root.ms;
42
+ const bar = (phase, start, ms, wait = false) => ({ phase, ms, at: Math.max(0, (start - t0) / span), width: Math.max(0, Math.min(1, ms / span)), wait });
43
+ const out = [];
44
+ for (const s of spans.filter((x) => x.parent === root.id && attrs(x)["terragucci.phase"]).sort((a, b) => a.start - b.start)) {
45
+ const phase = String(attrs(s)["terragucci.phase"]);
46
+ const held = attrs(s)["terragucci.gate.held_seconds"];
47
+ if (phase === "gate" && typeof held === "number" && held > 0) {
48
+ const heldMs = Math.min(s.ms, held * 1000);
49
+ out.push(bar("held", s.start, heldMs, true));
50
+ if (s.ms - heldMs > 0) out.push(bar("gate", s.start + heldMs, s.ms - heldMs));
51
+ } else out.push(bar(phase, s.start, s.ms, phase === "gate" && attrs(s)["terragucci.gate.status"] === "waiting"));
52
+ }
53
+ return out;
54
+ }
55
+
56
+ /** "70 ms", "1.6 s", "25 s", "2 min 5 s". */
57
+ export function msShort(ms) {
58
+ if (!(ms >= 0)) return null;
59
+ if (ms < 1000) return `${Math.max(1, Math.round(ms))} ms`;
60
+ const s = ms / 1000;
61
+ if (s < 10) return `${Math.round(s * 10) / 10} s`;
62
+ if (s < 60) return `${Math.round(s)} s`;
63
+ const m = Math.floor(s / 60);
64
+ const r = Math.round(s - m * 60);
65
+ return r ? `${m} min ${r} s` : `${m} min`;
66
+ }
67
+
68
+ /** The words a phase bar carries: "plan 1.2 s", "held 25 s for an approval". */
69
+ export function phaseWords(b) {
70
+ if (b.phase === "held") return `held ${msShort(b.ms)} for an approval`;
71
+ return `${b.phase} ${msShort(b.ms)}`;
72
+ }
73
+
74
+ /**
75
+ * What a wave's trace shows, in one line, for its "trace ready" tip: how long
76
+ * the job took, and where the time went: the hold when an approval held it,
77
+ * else the longest phase. "wave 2 took 1.6 s, 1.2 s of it in the plan".
78
+ */
79
+ export function traceReadyWords(wave, trace) {
80
+ if (!trace || !(trace.ms > 0)) return null;
81
+ const bars = phaseBars(trace);
82
+ const took = `wave ${wave}'s trace is ready; it took ${msShort(trace.ms)}`;
83
+ const held = bars.find((b) => b.phase === "held");
84
+ if (held) return `${took}, ${msShort(held.ms)} of it held for an approval`;
85
+ const longest = bars.filter((b) => !b.wait).sort((a, b) => b.ms - a.ms)[0];
86
+ return longest ? `${took}, ${msShort(longest.ms)} of it in the ${longest.phase}` : took;
87
+ }
88
+
89
+ /**
90
+ * The applied card's mini waterfall: one row per wave that has a trace, in
91
+ * wave order: `{ wave, run, job, ms, words, bars }`. No row for a wave
92
+ * without one.
93
+ */
94
+ export function miniWaterfall(traces) {
95
+ return Object.keys(traces || {})
96
+ .map(Number)
97
+ .sort((a, b) => a - b)
98
+ .map((w) => {
99
+ const { run, job, trace } = traces[w];
100
+ const bars = phaseBars(trace);
101
+ return bars.length ? { wave: w, run, job, ms: trace.ms, words: msShort(trace.ms), bars } : null;
102
+ })
103
+ .filter(Boolean);
104
+ }
@@ -0,0 +1,53 @@
1
+ // behold#571: each wave's trace for Watch: which trace is a wave's, its
2
+ // phases as bars, the "trace ready" line, and the applied card's rows.
3
+ import { describe, expect, it } from "vitest";
4
+ import { miniWaterfall, msShort, phaseBars, phaseWords, traceReadyWords, waveTraces } from "./kiosk-wave-traces.js";
5
+
6
+ const span = (id, parent, start, ms, attrs = {}, name = id) => ({ id, parent, name, service: "terragucci", start, ms, attrs });
7
+ const trace = (wave, start, phases, job = `apply-wave-${wave}`) => {
8
+ const ms = phases.reduce((a, p) => a + p.ms, 0);
9
+ let t = start;
10
+ const spans = [span(`root${wave}`, null, start, ms, { "terragucci.stage": "tf-apply", "terragucci.wave": wave })];
11
+ for (const p of phases) {
12
+ spans.push(span(`${p.phase}${wave}`, `root${wave}`, t, p.ms, { "terragucci.phase": p.phase, ...(p.held ? { "terragucci.gate.held_seconds": p.held } : {}) }));
13
+ t += p.ms;
14
+ }
15
+ return { wave, job, start, ms, spans };
16
+ };
17
+
18
+ describe("wave traces: whose trace is it", () => {
19
+ it("keeps each wave's newest trace across the cycle's runs, a resumed run's job applying several waves", () => {
20
+ const merge = { run: "4855", traces: [trace(1, 1000, [{ phase: "plan", ms: 400 }]), trace(2, 2000, [{ phase: "plan", ms: 300 }])] };
21
+ const resume = { run: "4856", traces: [trace(2, 9000, [{ phase: "plan", ms: 200 }], "apply-comment")] };
22
+ const w = waveTraces([merge, resume, { error: "no tempo" }, null]);
23
+ expect(Object.keys(w)).toEqual(["1", "2"]);
24
+ expect(w[1]).toMatchObject({ run: "4855", job: "apply-wave-1" });
25
+ expect(w[2]).toMatchObject({ run: "4856", job: "apply-comment" });
26
+ });
27
+ });
28
+
29
+ describe("wave traces: the phases", () => {
30
+ it("lays the stage's phases out in time, and splits a gate's hold from its check", () => {
31
+ const t = trace(2, 0, [{ phase: "plan", ms: 1000 }, { phase: "gate", ms: 26_000, held: 25 }, { phase: "apply", ms: 2000 }, { phase: "report", ms: 500 }, { phase: "upload", ms: 500 }]);
32
+ const bars = phaseBars(t);
33
+ expect(bars.map((b) => [b.phase, b.ms, b.wait])).toEqual([["plan", 1000, false], ["held", 25_000, true], ["gate", 1000, false], ["apply", 2000, false], ["report", 500, false], ["upload", 500, false]]);
34
+ expect(bars[1].at).toBeCloseTo(1000 / 30_000);
35
+ expect(bars.reduce((a, b) => a + b.width, 0)).toBeCloseTo(1);
36
+ expect(bars.map(phaseWords)).toEqual(["plan 1 s", "held 25 s for an approval", "gate 1 s", "apply 2 s", "report 500 ms", "upload 500 ms"]);
37
+ expect(phaseBars({ spans: [] })).toEqual([]);
38
+ });
39
+
40
+ it("says what a trace shows: the hold when an approval held the wave, else its longest phase", () => {
41
+ expect(traceReadyWords(2, trace(2, 0, [{ phase: "plan", ms: 1200 }, { phase: "apply", ms: 400 }]))).toBe("wave 2's trace is ready; it took 1.6 s, 1.2 s of it in the plan");
42
+ expect(traceReadyWords(2, trace(2, 0, [{ phase: "plan", ms: 1000 }, { phase: "gate", ms: 26_000, held: 25 }]))).toBe("wave 2's trace is ready; it took 27 s, 25 s of it held for an approval");
43
+ expect(traceReadyWords(2, null)).toBeNull();
44
+ expect([msShort(70), msShort(1600), msShort(48_400), msShort(125_000)]).toEqual(["70 ms", "1.6 s", "48 s", "2 min 5 s"]);
45
+ });
46
+
47
+ it("gives the applied card one row per wave that has a trace, and none for one that hasn't", () => {
48
+ const w = waveTraces([{ run: "1", traces: [trace(3, 0, [{ phase: "apply", ms: 900 }]), trace(1, 0, [{ phase: "plan", ms: 300 }])] }]);
49
+ const rows = miniWaterfall(w);
50
+ expect(rows.map((r) => [r.wave, r.words, r.bars.length])).toEqual([[1, "300 ms", 1], [3, "900 ms", 1]]);
51
+ expect(miniWaterfall({})).toEqual([]);
52
+ });
53
+ });
package/web/kiosk.html CHANGED
@@ -459,6 +459,30 @@
459
459
  #k-result { width: min(30em, 36vw); padding: 0.9em 1.2em 1em; background: color-mix(in srgb, var(--managed) 8%, var(--surface-box)); border: 2px solid var(--bar-managed); border-radius: 12px;
460
460
  box-shadow: 0 10px 34px color-mix(in srgb, var(--shadow) 75%, transparent), 0 0 0 6px color-mix(in srgb, var(--managed) 12%, transparent); }
461
461
  #k-result[hidden], #k-callout[hidden], #k-drawer[hidden] { display: none; }
462
+ /* behold#571: a wave's trace, one click from its numbers: its badge, the result card's bars, the drawer. */
463
+ .k-badge.k-badge-trace { pointer-events: auto; cursor: pointer; border-color: color-mix(in srgb, var(--pending) 60%, var(--rule)); }
464
+ .k-badge.k-badge-trace:hover { border-color: var(--pending); background: var(--active); }
465
+ .k-badge-go { margin-left: 0.55em; color: var(--pending); font-weight: 600; }
466
+ .k-badge-go::after, .k-wf-go::after { content: " ›"; }
467
+ #k-drawer.k-trace-only .k-drawer-tail, #k-drawer.k-trace-only .k-drawer-body { display: none; }
468
+ #k-drawer.k-trace-only #k-traces { max-height: 60vh; border-top: 1px solid var(--rule); }
469
+ #k-drawer.k-trace-only #k-traces:empty::before { content: "Reading the trace from Tempo…"; display: block; padding: 0.8em 1em; color: var(--muted); }
470
+ #k-drawer.k-trace-only #k-traces:empty { display: block; }
471
+ .k-wf { margin-top: 0.7em; padding-top: 0.5em; border-top: 1px solid var(--rule); display: grid; gap: 0.25em; }
472
+ .k-wf-row { display: grid; grid-template-columns: 4.2em minmax(6em, 1fr) auto auto; align-items: center; gap: 0.6em; width: 100%; padding: 0.2em 0.3em; border: 0; border-radius: 6px; background: transparent; color: var(--fg); font: inherit; text-align: left; cursor: pointer; }
473
+ .k-wf-row:hover, .k-wf-row:focus-visible { background: var(--active); }
474
+ .k-wf-wave { font: 600 0.88em var(--font-mono); color: var(--muted); }
475
+ .k-wf-track { position: relative; height: 0.85em; border-radius: 3px; background: color-mix(in srgb, var(--rule) 45%, transparent); overflow: hidden; }
476
+ .k-wf-seg { position: absolute; top: 0; bottom: 0; min-width: 2px; }
477
+ .k-wf-ms { font-size: 0.86em; font-variant-numeric: tabular-nums; white-space: nowrap; }
478
+ .k-wf-go { font-size: 0.82em; font-weight: 600; color: var(--pending); }
479
+ .k-wf-plan, .k-wf-apply { background: var(--runtime); }
480
+ .k-wf-apply { background: color-mix(in srgb, var(--managed) 75%, transparent); }
481
+ .k-wf-held { background: repeating-linear-gradient(135deg, var(--foreign) 0 4px, color-mix(in srgb, var(--foreign) 45%, transparent) 4px 8px); }
482
+ .k-wf-gate, .k-wf-report, .k-wf-upload { background: color-mix(in srgb, var(--muted) 70%, transparent); }
483
+ .k-wf-key { display: flex; flex-wrap: wrap; gap: 0.2em 0.9em; margin: 0.2em 0 0; color: var(--muted); font-size: 0.78em; }
484
+ .k-wf-key span { display: inline-flex; align-items: center; gap: 0.3em; }
485
+ .k-wf-sw { display: inline-block; width: 1.2em; height: 0.55em; border-radius: 2px; }
462
486
  .k-result-head { margin: 0 0 0.2em; font: 700 1.5em var(--font-ui); color: var(--managed); }
463
487
  .k-result-line { margin: 0 0 0.6em; font-size: 1.12em; line-height: 1.35; color: var(--fg); }
464
488
  .k-result-counts { list-style: none; margin: 0 0 0.6em; padding: 0; display: flex; flex-wrap: wrap; gap: 0.35em 0.5em; }
@@ -502,6 +526,8 @@
502
526
  <div id="k-what-pop" role="dialog" aria-label="What is this?" hidden></div>
503
527
  </div>
504
528
  <header id="bar" aria-live="polite"></header>
529
+ <!-- behold#571: event-help's story trail, the cycle's beats as chips. -->
530
+ <nav id="eh-trail" aria-label="This cycle" hidden></nav>
505
531
  </div>
506
532
  <div id="stage">
507
533
  <nav id="runs-side" aria-label="pipeline runs"></nav>
@@ -528,6 +554,9 @@
528
554
  <footer id="k-caption" aria-live="polite"></footer>
529
555
  </div>
530
556
  </div>
557
+ <!-- behold#571: event-help's tips and its modal, over everything. -->
558
+ <div id="eh-tips" aria-live="polite"></div>
559
+ <div id="eh-modals"></div>
531
560
  <script type="module">
532
561
  import { initTheme, KIOSK_THEME } from "/theme.js";
533
562
  import { startKiosk } from "/kiosk.js";
@@ -538,6 +567,7 @@
538
567
  {
539
568
  bar: document.getElementById("bar"), frame: document.getElementById("view"), read: document.getElementById("k-read"), side: document.getElementById("runs-side"), main: document.getElementById("runs-main"), views: document.getElementById("views"),
540
569
  tools: { what: document.querySelector(".k-what"), pop: document.getElementById("k-what-pop"), theme: document.getElementById("k-theme"), runsToggle: document.getElementById("k-runs-toggle"), mode: document.getElementById("k-mode") },
570
+ eh: { switchHost: document.getElementById("k-tools"), trailHost: document.getElementById("eh-trail"), tipsHost: document.getElementById("eh-tips"), modalHost: document.getElementById("eh-modals") },
541
571
  watch: { layer: document.getElementById("k-watch"), caption: document.getElementById("k-caption"), callout: document.getElementById("k-callout"), drawer: document.getElementById("k-drawer"), badges: document.getElementById("k-badges"), result: document.getElementById("k-result") },
542
572
  },
543
573
  { tool: pageTool(document) },