@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
@@ -77,6 +77,8 @@ body.k-carving.k-watch #k-carve { display: grid; }
77
77
  /* behold#725: sentence case. The tour file writes its labels in lower case ("cycle time"), so the label raises its first letter. */
78
78
  #k-carve .cx-label::first-letter, #k-carve .cx-follow-label::first-letter, #k-carve .cx-ch-kicker::first-letter, #k-carve .cx-num dt::first-letter { text-transform: uppercase; }
79
79
  #k-carve .cx-num dd { margin: 0; font-size: 1.25em; font-weight: 600; color: var(--fg); font-variant-numeric: tabular-nums; }
80
+ /* The quiet line: what runs while nothing new comes in (web/kiosk-watch.js quietWords). One muted line, no spinner. */
81
+ #k-carve .cx-quiet { margin: 0; padding-left: var(--s3); color: var(--muted); font-size: 0.92em; line-height: 1.35; font-variant-numeric: tabular-nums; }
80
82
  #k-carve .cx-notes { margin: 0; font: 12px/1.35 var(--font-mono); color: var(--ink2, var(--muted)); padding-left: var(--s3); overflow-wrap: anywhere; }
81
83
  /* A phone: in the page's flow under the graph, where Watch's caption goes (web/kiosk.html). */
82
84
  @media (max-width: 600px) {
@@ -96,12 +98,25 @@ body.k-carving.k-watch #k-carve { display: grid; }
96
98
  #k-carve .cx-card-title { font-size: 17px; }
97
99
  #k-carve .cx-card-line { font-size: 14px; }
98
100
  #k-carve .cx-num dd { font-size: 16px; }
101
+ #k-carve .cx-quiet { font-size: 13px; }
99
102
  }
103
+ /* While the carve has the stage in Watch, event-help's modal (web/event-help-modal.js) docks at the stage's top left,
104
+ under the top row and clear of the frame's zoom rail and its top-right controls, with no backdrop; the frame is
105
+ told its height as a top inset, so the director frames the boxes under it, never behind it. A phone keeps it centred. */
106
+ @media (min-width: 601px) {
107
+ body.k-carving.k-watch .eh-modal-wrap { inset: auto; top: var(--k-dock-top, 4em); left: var(--k-dock-left, 16px); display: block; background: transparent; pointer-events: none; }
108
+ body.k-carving.k-watch .eh-modal { pointer-events: auto; width: min(30em, var(--k-dock-w, 40vw)); max-height: 34vh; }
109
+ }
110
+ .eh-tip.eh-tip-dock::after { display: none; }
100
111
  /* Slowed playback, in Inspect's quiet rows: off (real time) unless a person picks it. */
101
112
  .k-slowed { font: 12px var(--font-ui); background: var(--well, transparent); color: var(--fg); border: 1px solid var(--line); border-radius: 5px; padding: 2px 8px; cursor: pointer; }
102
113
  .k-slowed[aria-pressed="true"] { border-color: var(--bar-pending); }
103
114
  `;
104
115
 
116
+ /** The docked modal's gap from the stage's edges, and the room it leaves at the stage's right for the frame's zoom rail and controls, in px. */
117
+ export const DOCK_GAP = 12;
118
+ export const DOCK_RIGHT = 240;
119
+
105
120
  /** Whether a message is the framed dots layer's live state, from this origin. */
106
121
  export function liveCarveMessage(e, origin) {
107
122
  return !!(e && e.origin === origin && e.data && e.data.type === "behold:dots-state" && e.data.live === true);
@@ -115,13 +130,16 @@ export function liveCarveMessage(e, origin) {
115
130
  */
116
131
  export function startKioskCarve({ frame, watch, eh, origin = location.origin, isWatch = () => true }) {
117
132
  const trail = eh && eh.trailHost ? eh.trailHost : null;
118
- if (typeof window === "undefined" || typeof document === "undefined" || !watch || !watch.layer) return { tellMode() {}, caption: () => (watch ? watch.caption : null), slowedControl: () => null };
133
+ if (typeof window === "undefined" || typeof document === "undefined" || !watch || !watch.layer) return { tellMode() {}, caption: () => (watch ? watch.caption : null), slowedControl: () => null, lastWriteAt: () => null, setQuiet() {} };
119
134
  let node = null;
120
135
  let narration = null;
121
136
  let carving = false;
122
137
  // The frame last told the kiosk's mode: a frame swapped in (a new view) is told again.
123
138
  let told = null;
124
- let lastBottom = -1;
139
+ let lastBottom = "";
140
+ // The newest progress line the frame has told of, and the quiet line the kiosk works out from it (web/kiosk.js).
141
+ let writeAt = null;
142
+ let quiet = null;
125
143
  // Slowed playback: a person's choice, real time until then. One button, kept across the header's redraws.
126
144
  let slowed = 1;
127
145
  let slowedNode = null;
@@ -171,8 +189,32 @@ export function startKioskCarve({ frame, watch, eh, origin = location.origin, is
171
189
  const f = frame();
172
190
  return f ? f.getBoundingClientRect() : { left: 0, top: 0, width: window.innerWidth, height: window.innerHeight };
173
191
  },
192
+ quiet: () => quiet,
193
+ docked: () => carving && isWatch() && !phone(),
174
194
  });
175
195
  };
196
+ const phone = () => typeof matchMedia === "function" && matchMedia("(max-width: 600px)").matches;
197
+ /** Where event-help's modal docks while the carve has the stage: the stage's top left, in the window's px. */
198
+ const dock = () => {
199
+ const f = frame();
200
+ if (!f) return;
201
+ const g = f.getBoundingClientRect();
202
+ const root = document.documentElement;
203
+ root.style.setProperty("--k-dock-top", `${Math.round(g.top + DOCK_GAP)}px`);
204
+ root.style.setProperty("--k-dock-left", `${Math.round(g.left + DOCK_GAP)}px`);
205
+ // Clear of the frame's zoom rail and its top-right controls (web/kiosk.js FRAME_CONTROLS).
206
+ root.style.setProperty("--k-dock-w", `${Math.max(240, Math.round(g.width - DOCK_RIGHT - 2 * DOCK_GAP))}px`);
207
+ };
208
+ /** The lowest edge of what is docked at the stage's top (event-help's modal, an end bubble) below the stage's top, in px; 0 with none up or on a phone. */
209
+ const dockedBelow = (g) => {
210
+ if (phone() || !isWatch()) return 0;
211
+ let low = 0;
212
+ for (const m of document.querySelectorAll(".eh-modal-wrap .eh-modal, .eh-tip.eh-tip-dock")) {
213
+ const r = m.getBoundingClientRect();
214
+ if (r.height) low = Math.max(low, Math.round(r.bottom - g.top + DOCK_GAP));
215
+ }
216
+ return low;
217
+ };
176
218
  const insets = () => {
177
219
  const f = frame();
178
220
  if (!f || !node || !carving) return { top: 0, bottom: 0 };
@@ -182,7 +224,7 @@ export function startKioskCarve({ frame, watch, eh, origin = location.origin, is
182
224
  const tr = trail && !trail.hidden ? trail.getBoundingClientRect() : null;
183
225
  const top = tr && tr.height && tr.top < c.top && tr.bottom >= c.top - 2 ? tr.top : c.top;
184
226
  const over = c.height && top < g.bottom && c.bottom > g.top ? g.bottom - top : 0;
185
- return { top: 0, bottom: Math.max(0, Math.round(over)) };
227
+ return { top: dockedBelow(g), bottom: Math.max(0, Math.round(over)) };
186
228
  };
187
229
  const tellMode = () => {
188
230
  const f = frame();
@@ -208,12 +250,15 @@ export function startKioskCarve({ frame, watch, eh, origin = location.origin, is
208
250
  document.body.classList.toggle("k-carving", carving);
209
251
  tellMode();
210
252
  }
253
+ writeAt = typeof e.data.lastWriteAt === "number" ? e.data.lastWriteAt : null;
211
254
  // The caption shows only while the carve has the camera (body.k-carving); the Tips come either way.
212
255
  narration.update(e.data);
213
256
  // The caption's height follows its words: the frame keeps the boxes clear of it as it changes.
257
+ if (carving) dock();
214
258
  const ins = insets();
215
- if (ins.bottom !== lastBottom) {
216
- lastBottom = ins.bottom;
259
+ const key = `${ins.top}|${ins.bottom}`;
260
+ if (key !== lastBottom) {
261
+ lastBottom = key;
217
262
  tellMode();
218
263
  }
219
264
  });
@@ -221,5 +266,13 @@ export function startKioskCarve({ frame, watch, eh, origin = location.origin, is
221
266
  const caption = () => (carving && node && isWatch() ? node : watch.caption);
222
267
  /** The slowed control for Inspect's quiet rows, once a frame draws a live carve; null before. */
223
268
  const slowedControl = () => (node ? slowedButton() : null);
224
- return { tellMode, caption, slowedControl };
269
+ /** The newest progress line's time the frame has told of, in ms; null before one. */
270
+ const lastWriteAt = () => writeAt;
271
+ /** The quiet line from the kiosk, or null: drawn at once when it changes. */
272
+ const setQuiet = (q) => {
273
+ const was = quiet ? quiet.text : null;
274
+ quiet = q || null;
275
+ if (narration && (quiet ? quiet.text : null) !== was) narration.redraw();
276
+ };
277
+ return { tellMode, caption, slowedControl, lastWriteAt, setQuiet };
225
278
  }
@@ -0,0 +1,27 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { demoFrameOk } from "./kiosk.js";
3
+ import { CHANT_DEMO_READS, TERRAGUCCI_READS } from "./kiosk-source.js";
4
+
5
+ // behold#765: /chant-fanout under --chant-demo reads chant's records, so there is
6
+ // no terragucci answer naming the served repo, and a behold serving one checkout
7
+ // sends no viewRepos for repoParam to match. frameOk was false, the body took
8
+ // k-nograph and the graph pane folded away while the frame held all 15 cards.
9
+ const REPO = "chant-demo/fan-out-estate";
10
+
11
+ describe("whether chant's demo shows its graph (behold#765)", () => {
12
+ it("one checkout served: the operator paired it with the demo, so the frame is the demo's repo", () => {
13
+ expect(demoFrameOk(CHANT_DEMO_READS.own, true, REPO, null)).toBe(true);
14
+ // Before the step names a repo too.
15
+ expect(demoFrameOk(CHANT_DEMO_READS.own, true, null, null)).toBe(true);
16
+ });
17
+ it("several served (--repos): only when one of them is the step's repo", () => {
18
+ expect(demoFrameOk(CHANT_DEMO_READS.own, false, REPO, ["fan-out-estate", "demo-fanout"])).toBe(true);
19
+ expect(demoFrameOk(CHANT_DEMO_READS.own, false, REPO, ["demo-fanout"])).toBe(false);
20
+ });
21
+ it("not before /api/project has said which", () => {
22
+ expect(demoFrameOk(CHANT_DEMO_READS.own, null, REPO, null)).toBe(false);
23
+ });
24
+ it("terragucci's loop keeps its own gate (its answer's project, or the served repo by name)", () => {
25
+ expect(demoFrameOk(TERRAGUCCI_READS.own, true, REPO, null)).toBe(false);
26
+ });
27
+ });
@@ -10,17 +10,20 @@
10
10
  // Inspect and by the caption in Watch; a chip, pointed at or clicked,
11
11
  // shows its tip and its lights again;
12
12
  // - a critical event (a wave held, a wave failed, the cycle applied) opens
13
- // web/event-help-modal.js, narrated (or replayed on a tool's page).
13
+ // web/event-help-modal.js, narrated (or replayed on a tool's page);
14
+ // - behold#757: a step whose driver wrote a `highlight` (what is special about
15
+ // it) opens it in Watch as a modal of its own, off the cards, when the step
16
+ // arrives, for HIGHLIGHT_MS or until the step goes.
14
17
  //
15
18
  // The Tips switch, on by default and kept per viewer, turns the tips, the
16
19
  // lights, the glows and the modals off; the trail stays, since it is the
17
20
  // record.
18
21
 
19
- import { EH_STORE, LATE_ORDER, TIP_MS, cycleFacts, ehSnapshot, ehStore, ehStored, modalQueue, newEvents, storyTrail, tipsQueue } from "./kiosk-event-help.js";
22
+ import { EH_STORE, HIGHLIGHT_MS, LATE_ORDER, TIP_MS, cycleFacts, storyKey, ehSnapshot, ehStore, ehStored, highlightOpens, highlightShown, highlightTurn, modalQueue, modalShownElsewhere, newEvents, storyTrail, tipsQueue, tipsShown } from "./kiosk-event-help.js";
20
23
 
21
24
  /** How long after the page opens (or the cycle turns) what arrives is the story so far, not news: the reads land one by one. */
22
25
  export const SETTLE_MS = 8_000;
23
- import { modalStyle, openEventModal } from "./event-help-modal.js";
26
+ import { FIX_VERBS, modalStyle, openEventModal } from "./event-help-modal.js";
24
27
 
25
28
  /** The switch's label, and its title. */
26
29
  export const TIPS_WORDS = "Tips";
@@ -65,6 +68,8 @@ body.k-watch #eh-trail { position: fixed; z-index: 7; left: 5px; right: 5px; pad
65
68
  @media (prefers-reduced-motion: reduce) { .eh-tip.eh-out { opacity: 0; } }
66
69
  @keyframes eh-pop { from { opacity: 0; transform: var(--eh-at) translateY(6px) scale(0.92); } to { opacity: 1; transform: var(--eh-at); } }
67
70
  @keyframes eh-pulse { 0%, 100% { outline-color: color-mix(in srgb, var(--eh-glow, var(--focus)) 35%, transparent); } 50% { outline-color: var(--eh-glow, var(--focus)); } }
71
+ /* behold#631: a chant kiosk's strip fades in at its left edge, so a chip scrolled past it never reads as a word cut short. */
72
+ #eh-trail.eh-trail-fade { -webkit-mask-image: linear-gradient(to right, transparent 0, #000 72px); mask-image: linear-gradient(to right, transparent 0, #000 72px); }
68
73
  @media (max-width: 600px) { #eh-trail { padding: 0.2em 16px; } body.k-watch #eh-trail { position: static; background: transparent; border: 0; } .eh-tip { max-width: 18em; } }
69
74
  `;
70
75
 
@@ -122,7 +127,7 @@ export function tipSpot(rect, size, win, labels = []) {
122
127
 
123
128
  /** A fact's tone, for its chip, its tip and its modal: the state colours the bars use. */
124
129
  export function toneOf(kind) {
125
- if (kind === "held") return "wait";
130
+ if (kind === "held" || kind === "blocked") return "wait";
126
131
  if (kind === "failed" || kind === "refused") return "bad";
127
132
  if (kind === "applied" || kind === "applied-wave" || kind === "approved" || kind === "known") return "ok";
128
133
  return "busy";
@@ -202,6 +207,19 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
202
207
  const right = Math.min(r.left + r.width, F.right);
203
208
  return bottom - top > 8 && right - left > 8 ? { left, top, width: right - left, height: bottom - top, right, bottom } : null;
204
209
  };
210
+ /** behold#744: the read pills the frame shows now (its `labels`, read fresh at each placement), which a modal keeps off. */
211
+ const pillRects = (h) => {
212
+ const now = (get && get()) || h;
213
+ return ((now && now.boxes && now.boxes.labels) || []).map((l) => fromFrame(now, l)).filter(Boolean);
214
+ };
215
+ /** behold#631: the graph's area above the bottom band (the track or trail, and the caption): where a chant modal may go. */
216
+ const graphArea = (h) => {
217
+ const F = frameRect(h);
218
+ if (!F) return null;
219
+ const band = [doc.getElementById ? doc.getElementById("k-track") : null, trailHost, h.caption].filter((n) => n && !n.hidden && n.getBoundingClientRect).map((n) => n.getBoundingClientRect()).filter((r) => r.height > 0);
220
+ const bottom = Math.min(F.bottom, ...band.map((r) => r.top)) - 8;
221
+ return { left: F.left, top: F.top, width: F.width, height: Math.max(0, bottom - F.top) };
222
+ };
205
223
  const q = (sel) => [...doc.querySelectorAll(sel)].find((n) => visible(n.getBoundingClientRect()) && !n.closest("[hidden]"));
206
224
  /** The things an event is about, the one its tip points at first. */
207
225
  const anchorsOf = (ev, h) => {
@@ -248,15 +266,31 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
248
266
  node.style.transform = at;
249
267
  };
250
268
  const trailChip = (id) => trailHost && trailHost.querySelector(`.eh-chip[data-eh-id="${CSS.escape(id)}"]`);
251
- const showTips = (h) => {
269
+ const showTips = (h, { asked = false } = {}) => {
270
+ // A held small stage in Watch: no bubble over the graph (its cards say it), but a chip the viewer clicks still shows.
271
+ if (asked) st.asked = true;
272
+ if (!st.asked && h && !tipsShown({ watch: !!h.watch, held: !!h.held })) {
273
+ for (const n of st.nodes.values()) n.remove();
274
+ st.nodes.clear();
275
+ st.tips = null;
276
+ return;
277
+ }
252
278
  const t = now();
253
279
  const prev = st.tips;
254
- st.tips = tipsQueue(st.tips, { now: t });
280
+ st.tips = tipsQueue(st.tips, { now: t, ...(st.tipsMax ? { max: st.tipsMax } : {}) });
281
+ // The tip a viewer asked for has had its time: the held stage's rule holds again.
282
+ if (!st.tips.shown.length && !st.tips.waiting.length) st.asked = false;
255
283
  const up = new Set(st.tips.shown.map((x) => x.event.id));
256
284
  // Each tip whose time is up shrinks toward its chip on the trail, then goes.
257
285
  for (const [id, node] of st.nodes) {
258
286
  if (up.has(id)) continue;
259
287
  st.nodes.delete(id);
288
+ // behold#631: on a chant kiosk a tip that goes leaves at once: no shrinking ghost under the next wave.
289
+ // behold#741: so on a terragucci kiosk telling a chapter-carrying scenario (st.story).
290
+ if (st.story) {
291
+ node.remove();
292
+ continue;
293
+ }
260
294
  const chip = trailChip(id) || (trailHost && trailHost.querySelector(".eh-chip:last-of-type"));
261
295
  if (chip && !reduced()) {
262
296
  const c = chip.getBoundingClientRect();
@@ -330,9 +364,11 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
330
364
  let trailKey = "";
331
365
  const drawTrail = (h) => {
332
366
  if (!trailHost) return;
367
+ if (trailHost.classList) trailHost.classList.toggle("eh-trail-fade", !!(h.chant || h.story));
333
368
  const facts = [...st.trail.values()].sort((a, b) => a.order - b.order);
334
369
  const key = facts.map((f) => `${f.id}=${f.text}`).join(",");
335
- trailHost.hidden = !facts.length;
370
+ // behold#631: a chant kiosk's projected track stands in its place.
371
+ trailHost.hidden = !facts.length || !!h.hideTrail;
336
372
  if (h.watch && h.caption && trailHost.style) {
337
373
  const c = h.caption.getBoundingClientRect();
338
374
  trailHost.style.bottom = c.height ? `${Math.round((doc.defaultView ? doc.defaultView.innerHeight : 0) - c.top)}px` : "";
@@ -341,7 +377,11 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
341
377
  trailKey = key;
342
378
  trailHost.replaceChildren(el("span", "eh-trail-label", TRAIL_WORDS));
343
379
  facts.forEach((f, i) => {
344
- if (i) trailHost.appendChild(el("span", "eh-sep", "›"));
380
+ // behold#631: a chant cycle's next pull request (the fix) starts its own run of chips, after a label that says so.
381
+ const prev = i ? facts[i - 1] : null;
382
+ if (prev && Number.isInteger(f.pull) && Number.isInteger(prev.pull) && f.pull !== prev.pull) {
383
+ trailHost.appendChild(el("span", "eh-sep eh-sep-pr", ` | then pull request #${f.pull}:`));
384
+ } else if (i) trailHost.appendChild(el("span", "eh-sep", "›"));
345
385
  const chip = el("button", "eh-chip", f.text);
346
386
  chip.type = "button";
347
387
  chip.dataset.ehId = f.id;
@@ -359,7 +399,7 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
359
399
  for (const n of st.nodes.values()) n.remove();
360
400
  st.nodes.clear();
361
401
  st.tips = { shown: [], waiting: [f] };
362
- showTips(get());
402
+ showTips(get(), { asked: true });
363
403
  };
364
404
 
365
405
  // ---- modals --------------------------------------------------------------
@@ -372,14 +412,83 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
372
412
  if (event.kind === "held") {
373
413
  data = { title: Number.isInteger(event.subjects.wave) ? `Wave ${event.subjects.wave} waits for an approval` : "The plan waits for an approval", lines: [{ text: event.text }], panel: panel("held"), command: h.approveLine || null, at: d && d.step === "waiting" && /approve/.test((d.next && d.next.action) || "") ? nextAt : null, from: t, replayAt: t };
374
414
  } else if (event.kind === "failed" || event.kind === "refused") {
375
- data = { title: `Wave ${event.subjects.wave} failed`, lines: [{ text: event.text, lit: true }, ...(h.label ? [{ text: h.label }] : [])], action: d && d.next ? d.next.action : null, at: nextAt, from: t, replayAt: t };
415
+ // behold#631: a chant failure's own line is the error chant printed. When the step's label already says why, the label is the line and
416
+ // the error goes in its tooltip; otherwise the error's most specific part, with the whole of it in the tooltip.
417
+ const lines = event.chant
418
+ ? h.label
419
+ ? [{ text: h.label, ...(event.raw || event.text ? { title: event.raw || event.text } : {}) }]
420
+ : [{ text: event.text, lit: true, ...(event.raw ? { title: event.raw } : {}) }]
421
+ : [{ text: event.text, lit: true }, ...(h.label ? [{ text: h.label }] : [])];
422
+ // A chant failure is the component's: half of its wave went ahead.
423
+ data = { title: event.chant && event.subjects.roots && event.subjects.roots[0] ? `${event.subjects.roots[0]} failed` : `Wave ${event.subjects.wave} failed`, lines, action: d && d.next ? d.next.action : null, at: nextAt, from: t, replayAt: t };
424
+ // What follows a chant failure is a fix's pull request, not a re-run.
425
+ if (event.chant) Object.assign(data, { fix: true, verbs: FIX_VERBS });
376
426
  } else {
377
427
  const r = h.result;
378
428
  data = { title: "Applied", lines: [...(h.label ? [{ text: h.label }] : []), ...(r ? r.counts.map((c) => ({ text: c })) : [])], replayAt: t };
379
429
  }
380
430
  const kind = event.kind === "refused" ? "failed" : event.kind;
381
- const api = openEventModal(modalHost, { mode, kind, data, doc, now: shown, reduced: reduced(), onClose: () => (st.modal = null) });
382
- st.modal = { api, event, kind, step: d ? d.step : null, cycle: d ? d.cycle : null };
431
+ // behold#631: a chant failure's modal keeps clear of the failed card and the cards it blocked.
432
+ // It must leave the failed wave and the wave after it in view (`avoid`), and covers as few other cards as it can.
433
+ // behold#741: a terragucci story's modals do the same: off the cards they are about (a held wave's, a failed one's),
434
+ // covering as few others as they can, above the bottom band.
435
+ if (event.chant || (st.story && !st.chant)) {
436
+ const box = (r) => fromFrame(h, h.boxes && h.boxes.roots ? h.boxes.roots[r] : null);
437
+ const wave = Number.isInteger(event.subjects.wave) ? (h.waves || []).find((w) => w.wave === event.subjects.wave) : null;
438
+ const must = event.avoid || (event.subjects.roots && event.subjects.roots.length ? event.subjects.roots : wave && Array.isArray(wave.roots) ? wave.roots : []);
439
+ data.avoid = () => [...must.map(box).filter(Boolean), ...pillRects(h)];
440
+ data.prefer = () => Object.keys((h.boxes && h.boxes.roots) || {}).filter((r) => !must.includes(r)).map(box).filter(Boolean);
441
+ data.bounds = () => graphArea(h);
442
+ }
443
+ // A chant kiosk counts down on the clock its track and caption use, so all three say the same second.
444
+ const api = openEventModal(modalHost, { mode, kind, data, doc, now: event.chant ? now : shown, reduced: reduced(), onClose: () => (st.modal = null) });
445
+ st.modal = { api, event, kind, step: d ? d.step : null, cycle: d ? d.cycle : null, pull: d ? d.pull : null };
446
+ };
447
+ /** behold#631: the "Waiting on…" modal's words: what is waited on, why it matters, and how long it usually takes. */
448
+ const waitingData = (w, h) => ({
449
+ title: `Waiting on ${w.what}`,
450
+ lines: w.why ? [{ text: w.why }] : [],
451
+ progress: { fraction: w.fraction, words: w.words },
452
+ ...offCards(h),
453
+ });
454
+ /**
455
+ * Where a modal about no one card goes (the "Waiting on…" one, a step's highlight): never over a card, since any
456
+ * card of the graph is to stay in view. Then, where it can, off the graph altogether (its wave boxes and the space
457
+ * between them, where a reach is drawn): the space beside it first. behold#744: nor over a read pill the frame
458
+ * shows; behold#748's outside mark sits in the pills' layer, so it is kept clear of the same way.
459
+ * behold#757: each read of the cards is of what the frame says now: a highlight opens with its step, often
460
+ * before the frame has said where its cards are.
461
+ */
462
+ const offCards = (at) => ({
463
+ avoid: () => {
464
+ const h = (get && get()) || at;
465
+ return [...Object.keys((h.boxes && h.boxes.roots) || {}).map((r) => fromFrame(h, h.boxes.roots[r])).filter(Boolean), ...pillRects(h)];
466
+ },
467
+ prefer: () => {
468
+ const h = (get && get()) || at;
469
+ const waves = Object.values((h.boxes && h.boxes.waves) || {}).map((b) => fromFrame(h, b)).filter(Boolean);
470
+ if (!waves.length) return [];
471
+ const left = Math.min(...waves.map((b) => b.left));
472
+ const top = Math.min(...waves.map((b) => b.top));
473
+ const right = Math.max(...waves.map((b) => b.left + b.width));
474
+ const bottom = Math.max(...waves.map((b) => b.top + b.height));
475
+ return [{ left, top, width: right - left, height: bottom - top }];
476
+ },
477
+ bounds: () => graphArea((get && get()) || at),
478
+ });
479
+ const openWaiting = (w, h) => {
480
+ const d = h.demo;
481
+ const api = openEventModal(modalHost, { mode: "narrated", kind: "waiting", data: waitingData(w, h), doc, now, reduced: reduced(), onClose: () => (st.modal = null) });
482
+ st.modal = { api, event: { kind: "waiting", subjects: { roots: [], wave: null } }, kind: "waiting", key: w.key, step: d ? d.step : null, cycle: d ? d.cycle : null, pull: d ? d.pull : null };
483
+ if (st.story) for (const n of st.nodes.values()) n.style.visibility = "hidden";
484
+ };
485
+ /** behold#757: a step's highlight, as a modal off the cards: up HIGHLIGHT_MS (longer while hovered), or until its step goes. */
486
+ const openHighlight = (hl, h) => {
487
+ const d = h.demo;
488
+ const data = { title: hl.title, lines: [{ text: hl.body }], closeAfter: HIGHLIGHT_MS, ...offCards(h) };
489
+ const api = openEventModal(modalHost, { mode: h.replay ? "replay" : "narrated", kind: "highlight", data, doc, now, reduced: reduced(), onClose: () => (st.modal = null) });
490
+ st.modal = { api, event: { kind: "highlight", subjects: { roots: [], wave: null } }, kind: "highlight", key: hl.key, step: d ? d.step : null, cycle: d ? d.cycle : null, pull: d ? d.pull : null };
491
+ for (const n of st.nodes.values()) n.style.visibility = "hidden";
383
492
  };
384
493
  /** The modal's real event: the approval landed, the waves ran again, the cycle moved on. */
385
494
  const settleModal = (h, facts) => {
@@ -392,6 +501,9 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
392
501
  else if (d && (d.cycle !== m.cycle || !["waiting", "approved"].includes(d.step))) m.api.resolve(d.cycle === m.cycle ? "approved; the waves run again" : null);
393
502
  } else if (m.kind === "failed") {
394
503
  if (d && (d.cycle !== m.cycle || ["resumed", "applying", "waiting", "applied"].includes(d.step))) m.api.resolve(d.cycle === m.cycle ? "the waves run again" : null);
504
+ // behold#631: a chant failure's modal goes once the cycle moves on, to a new pull request or a new step (the fix's plan, its wait).
505
+ // behold#736: a terragucci story's too (#741's look): on fan-out-choudoufu it stayed over the fix's cone plan.
506
+ if ((m.event.chant || st.story) && d && (d.cycle !== m.cycle || d.pull !== m.pull || d.step !== m.step)) m.api.close();
395
507
  }
396
508
  };
397
509
 
@@ -407,13 +519,15 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
407
519
  st.stripKey = stripKey;
408
520
  st.trail.clear();
409
521
  }
410
- const facts = cycleFacts(ehSnapshot({ demo: h.demo, answer: h.answer, progress: h.progress, runDoc: h.runDoc, runDocs: h.runDocs || [], approval: h.approval, metrics: h.metrics, waveTraces: h.waveTraces || {}, strip: h.strip || null, waves: h.waves || [], failed: [...st.failed] }));
411
- if (h.demo.cycle !== st.cycle) {
522
+ const facts = cycleFacts(ehSnapshot({ demo: h.demo, answer: h.answer, progress: h.progress, runDoc: h.runDoc, runDocs: h.runDocs || [], approval: h.approval, metrics: h.metrics, waveTraces: h.waveTraces || {}, strip: h.strip || null, waves: h.waves || [], failed: [...st.failed], chant: !!h.chant }));
523
+ // A new cycle, or a new beat of one (web/kiosk-event-help.js storyKey): a new story.
524
+ const story = storyKey({ cycle: h.demo.cycle, beat: h.demo.beat || null });
525
+ if (story !== st.cycle) {
412
526
  // A new cycle: a new story. Its first look is the trail so far, not news.
413
527
  // The first look at a page sees a cycle already under way: no news. A cycle that turns while the page is open is all news.
414
528
  if (st.cycle !== null) st.seen = new Set();
415
529
  else st.seen = null;
416
- st.cycle = h.demo.cycle;
530
+ st.cycle = story;
417
531
  st.maxOrder = -Infinity;
418
532
  st.trail.clear();
419
533
  st.failed.clear();
@@ -431,19 +545,71 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
431
545
  for (const f of storyTrail(facts)) st.trail.set(f.id, f);
432
546
  drawTrail(h);
433
547
  settleModal(h, facts);
548
+ // A modal Inspect opened goes when the viewer turns to Watch on a held small stage, where nothing overlays the graph.
549
+ if (st.modal && modalShownElsewhere(st.modal.event, { watch: !!h.watch, held: !!h.held })) st.modal.api.close();
550
+ // behold#757: a step's highlight is read on every look (Tips off or not, so turning them on mid-step still shows it,
551
+ // and one the driver adds partway through a step shows when it appears); its modal goes with its step, or when the
552
+ // viewer turns to Inspect: it is Watch's.
553
+ st.hl = highlightTurn(st.hl, h.demo);
554
+ if (st.modal && st.modal.kind === "highlight" && (st.modal.key !== st.hl.step || !h.watch)) st.modal.api.close();
434
555
  if (!st.on) return;
435
- if (news.length) st.tips = tipsQueue(st.tips, { add: news, now: now() });
556
+ // behold#631: a new pull request of a chant cycle (the fix) starts with no tip of the one before.
557
+ if (h.chant && st.tipsPull !== undefined && st.tipsPull !== h.demo.pull) {
558
+ for (const n of st.nodes.values()) n.remove();
559
+ st.nodes.clear();
560
+ st.tips = null;
561
+ }
562
+ st.tipsPull = h.demo.pull;
563
+ // A chant wave's start is history once the wave has settled, outcome tip or not: its tip goes, so the tags follow the paced graph.
564
+ if (h.chant && st.tips) {
565
+ const done = new Set(facts.filter((f) => ["failed", "applied-wave", "blocked"].includes(f.kind) && Number.isInteger(f.subjects.wave)).map((f) => f.subjects.wave));
566
+ if (done.size) st.tips = { shown: st.tips.shown.filter((x) => !(x.event.kind === "started" && done.has(x.event.subjects.wave))), waiting: st.tips.waiting.filter((e) => !(e.kind === "started" && done.has(e.subjects.wave))) };
567
+ }
568
+ // A chant kiosk shows one tip at a time: two placed on one wave box land on each other.
569
+ // behold#741: so does a terragucci kiosk telling a chapter-carrying scenario (`h.story`); its story order stays its own.
570
+ st.tipsMax = h.chant || h.story ? 1 : undefined;
571
+ st.chant = !!h.chant;
572
+ st.story = !!(h.chant || h.story);
573
+ if (news.length) st.tips = tipsQueue(st.tips, { add: news, now: now(), ...(st.tipsMax ? { max: st.tipsMax } : {}) });
436
574
  // While a modal is up, the tips wait their turn behind it.
437
- if (!st.modal) showTips(h);
575
+ if (!st.modal && tipsShown({ watch: !!h.watch, held: !!h.held })) showTips(h);
576
+ // behold#631: on a chant kiosk no tip shows at all while a modal is open, not even one already up.
577
+ else if (st.story) for (const n of st.nodes.values()) n.style.visibility = "hidden";
438
578
  ageGlows();
439
- st.modals = modalQueue(st.modals, { add: news, now: now(), lastInput: st.lastInput, open: !!st.modal });
579
+ // behold#631: the "Waiting on…" modal goes the moment anything new arrives, or what it waits on changes;
580
+ // a critical modal (the failure) always wins over it.
581
+ if (st.modal && st.modal.kind === "waiting" && (news.length || !h.waiting || h.waiting.key !== st.modal.key)) {
582
+ // News closed it: the same wait does not come straight back over the news.
583
+ if (news.length && h.waiting) st.waitingHold = { key: h.waiting.key, until: now() + 4_000 };
584
+ st.modal.api.close();
585
+ }
586
+ // behold#757: the step's highlight, once per cycle, step and title, before the critical modals: one due now waits
587
+ // behind it in the queue, and opens when it closes if its step is still the step.
588
+ if (highlightOpens({ pending: st.hl.pending, on: st.on, watch: !!h.watch, held: !!h.held, modal: st.modal ? st.modal.kind : null })) {
589
+ if (st.modal) st.modal.api.close();
590
+ openHighlight(st.hl.pending, h);
591
+ st.hl = highlightShown(st.hl);
592
+ }
593
+ // behold#631: a chant repo's approval is the card beside the graph; a modal over it would hide it, so its hold opens none.
594
+ // Its result is the Applied card beside the graph; a modal would say it twice, over the cards.
595
+ // On a held small stage in Watch no modal opens: nothing overlays the graph there, and the caption says each step.
596
+ const told = (e) => modalShownElsewhere(e, { watch: !!h.watch, held: !!h.held });
597
+ st.modals = modalQueue(st.modals, { add: (h.chant ? news.filter((f) => f.kind !== "held" && f.kind !== "applied") : news).filter((e) => !told(e)), now: now(), lastInput: st.lastInput, open: !!st.modal });
440
598
  // A modal opens only while its event is still the step's: one that waited out a viewer at the page and went by is history.
441
- if (st.modals.next && stillNow(st.modals.next, h.demo)) openModal(st.modals.next, h);
599
+ if (st.modals.next && stillNow(st.modals.next, h.demo)) {
600
+ openModal(st.modals.next, h);
601
+ // The tip put up this same tick goes under too.
602
+ if (st.story) for (const n of st.nodes.values()) n.style.visibility = "hidden";
603
+ }
604
+ // behold#631: a quiet stretch on a chant kiosk: "Waiting on …", when no other modal is up or due.
605
+ const held = st.waitingHold && h.waiting && st.waitingHold.key === h.waiting.key && now() < st.waitingHold.until;
606
+ if (h.waiting && st.on && !held && !st.modal && !(st.modals && st.modals.next)) openWaiting(h.waiting, h);
607
+ else if (h.waiting && st.modal && st.modal.kind === "waiting") st.modal.api.update(waitingData(h.waiting, h));
442
608
  };
443
609
  const stillNow = (e, d) => (e.kind === "held" ? d.step === "waiting" : e.kind === "failed" || e.kind === "refused" ? d.step === "failed" : e.kind === "applied" ? d.step === "applied" : false);
444
610
  /** Keep the tips on their things while the graph moves (a shot, a pan). */
445
611
  const follow = () => {
446
- if (st.on && st.tips && st.tips.shown.length) showTips(get());
612
+ if (st.on && st.tips && st.tips.shown.length && !(st.story && st.modal)) showTips(get());
447
613
  };
448
614
  return { tick, follow, state: st, store: EH_STORE };
449
615
  }