@intentius/behold 0.29.44 → 0.29.46

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,85 @@
1
+ // behold#764: where a floating dialog goes, kept inside what can be seen.
2
+ // On the fan-out kiosks wave 3's cards sit at the very top of the graph, and
3
+ // a dialog put above (or levelled with) one of them, or one taller than the
4
+ // space left, ran off the top of its window. Every floating thing of the
5
+ // kiosk (the frame's card popover, the job box and its log drawer, the
6
+ // approval callout, the event-help tips, the tooltip) places itself with
7
+ // these: beside its anchor on the first side it fits, else on the side with
8
+ // the most room, never past the view's edges less a margin; taller than the
9
+ // view, it gets a max height and its body scrolls.
10
+ //
11
+ // Pure: rects in, a position out. All boxes are `{ left, top, width, height }`
12
+ // in one window's pixels; the view is the part of that window that shows (a
13
+ // frame's window, or the kiosk's graph above its caption).
14
+
15
+ /** The room kept between a dialog and the view's edge, in px. */
16
+ export const FLOAT_MARGIN = 8;
17
+
18
+ const clamp = (v, lo, hi) => Math.max(lo, Math.min(v, Math.max(lo, hi)));
19
+
20
+ /**
21
+ * The smallest move `{ dx, dy }` that puts `rect` inside `view` less `margin`.
22
+ * A rect bigger than the view keeps its top (or left) edge in: what a dialog
23
+ * starts with is what is read first.
24
+ */
25
+ export function shiftInto(rect, view, margin = FLOAT_MARGIN) {
26
+ const x0 = view.left + margin;
27
+ const y0 = view.top + margin;
28
+ const x1 = view.left + view.width - margin;
29
+ const y1 = view.top + view.height - margin;
30
+ const left = clamp(rect.left, x0, x1 - rect.width);
31
+ const top = clamp(rect.top, y0, y1 - rect.height);
32
+ return { dx: left - rect.left, dy: top - rect.top };
33
+ }
34
+
35
+ /** Whether `rect` lies inside `view` less `margin` (half a pixel's slack for rounding). */
36
+ export function fitsIn(rect, view, margin = FLOAT_MARGIN) {
37
+ return rect.left >= view.left + margin - 0.5 && rect.top >= view.top + margin - 0.5 && rect.left + rect.width <= view.left + view.width - margin + 0.5 && rect.top + rect.height <= view.top + view.height - margin + 0.5;
38
+ }
39
+
40
+ /**
41
+ * Where a dialog of `size` (`{ width, height }`) goes beside `anchor` inside
42
+ * `view`. `sides` is the order to try ("right", "left", "below", "above"):
43
+ * the first side with room for the whole dialog wins. With none, the side
44
+ * with the most room for it, as a share of its size. Along its side the
45
+ * dialog starts level with the anchor's top (beside) or left (above, below),
46
+ * slid as little as keeps it in the view. A dialog taller than the view
47
+ * less its margins gets `maxHeight` (else null): the caller caps it there and
48
+ * lets its body scroll. `arrow` is how far along the dialog's near edge the
49
+ * anchor's middle is (its notch or leader points there), kept 12px off its
50
+ * corners. Returns `{ left, top, side, maxHeight, arrow }`.
51
+ */
52
+ export function placeFloat(anchor, size, view, { sides = ["right", "left", "below", "above"], gap = 12, margin = FLOAT_MARGIN } = {}) {
53
+ const vx0 = view.left + margin;
54
+ const vy0 = view.top + margin;
55
+ const vx1 = view.left + view.width - margin;
56
+ const vy1 = view.top + view.height - margin;
57
+ const maxH = Math.max(0, vy1 - vy0);
58
+ const maxW = Math.max(0, vx1 - vx0);
59
+ const h = Math.min(size.height, maxH);
60
+ const w = Math.min(size.width, maxW);
61
+ const right = anchor.left + anchor.width;
62
+ const bottom = anchor.top + anchor.height;
63
+ const room = {
64
+ right: vx1 - (right + gap),
65
+ left: anchor.left - gap - vx0,
66
+ below: vy1 - (bottom + gap),
67
+ above: anchor.top - gap - vy0,
68
+ };
69
+ const need = (side) => (side === "right" || side === "left" ? w : h);
70
+ const at = (side) => {
71
+ if (side === "right") return { left: right + gap, top: clamp(anchor.top, vy0, vy1 - h) };
72
+ if (side === "left") return { left: anchor.left - gap - w, top: clamp(anchor.top, vy0, vy1 - h) };
73
+ if (side === "below") return { left: clamp(anchor.left, vx0, vx1 - w), top: bottom + gap };
74
+ return { left: clamp(anchor.left, vx0, vx1 - w), top: anchor.top - gap - h };
75
+ };
76
+ let side = sides.find((s) => room[s] >= need(s));
77
+ if (!side) side = [...sides].sort((a, b) => room[b] / need(b) - room[a] / need(a))[0];
78
+ const p = at(side);
79
+ const left = clamp(p.left, vx0, vx1 - w);
80
+ const top = clamp(p.top, vy0, vy1 - h);
81
+ const beside = side === "right" || side === "left";
82
+ const mid = beside ? anchor.top + anchor.height / 2 - top : anchor.left + anchor.width / 2 - left;
83
+ const arrow = Math.max(12, Math.min((beside ? h : w) - 12, mid));
84
+ return { left, top, side, maxHeight: size.height > maxH ? maxH : null, arrow };
85
+ }
@@ -0,0 +1,117 @@
1
+ // behold#764: every floating dialog of the kiosk stays inside what can be seen.
2
+ import { describe, expect, it } from "vitest";
3
+ import { FLOAT_MARGIN, fitsIn, placeFloat, shiftInto } from "./float-place.js";
4
+ import { placePopover } from "./kiosk-popover.js";
5
+ import { placeBeside } from "./kiosk-watch.js";
6
+ import { placeTip } from "./tooltip.js";
7
+ import { tipSpot } from "./kiosk-event-help-ui.js";
8
+
9
+ const box = (left, top, width, height) => ({ left, top, width, height });
10
+ const overlaps = (a, b) => a.left < b.left + b.width && a.left + a.width > b.left && a.top < b.top + b.height && a.top + a.height > b.top;
11
+
12
+ describe("shiftInto", () => {
13
+ const view = box(0, 0, 1000, 600);
14
+ it("leaves a rect inside alone, and moves one outside by as little as brings it in", () => {
15
+ expect(shiftInto(box(100, 100, 200, 100), view)).toEqual({ dx: 0, dy: 0 });
16
+ expect(shiftInto(box(100, -331, 262, 31), view)).toEqual({ dx: 0, dy: 339 });
17
+ expect(shiftInto(box(-105, 373, 390, 46), view)).toEqual({ dx: 113, dy: 0 });
18
+ expect(shiftInto(box(900, 580, 200, 40), view)).toEqual({ dx: -108, dy: -28 });
19
+ });
20
+ it("keeps the top and left edges in for a rect bigger than the view", () => {
21
+ expect(shiftInto(box(50, -94, 2000, 900), view)).toEqual({ dx: -42, dy: 102 });
22
+ });
23
+ it("works in a view that does not start at 0", () => {
24
+ expect(shiftInto(box(0, 0, 50, 50), box(100, 80, 400, 300), 4)).toEqual({ dx: 104, dy: 84 });
25
+ });
26
+ });
27
+
28
+ describe("placeFloat", () => {
29
+ const view = box(0, 0, 1356, 686); // the kiosk's graph frame at 1366x768
30
+ const size = { width: 412, height: 141 };
31
+ const sides = [["right"], ["left"], ["below"], ["above"]];
32
+
33
+ it("a wave 3 card at the very top of the view: no side puts the dialog past the top", () => {
34
+ const card = box(574, 8, 110, 50);
35
+ for (const [s] of sides) {
36
+ const p = placeFloat(card, size, view, { sides: [s, "below"] });
37
+ expect(fitsIn({ ...p, ...size }, view)).toBe(true);
38
+ }
39
+ // Asked for above first, with no room there, it goes below.
40
+ expect(placeFloat(card, size, view, { sides: ["above", "below"] }).side).toBe("below");
41
+ });
42
+
43
+ it("flips to the side with room: below when there is none above, beside when that fits better", () => {
44
+ expect(placeFloat(box(500, 20, 300, 60), { width: 300, height: 200 }, box(0, 0, 1000, 700), { sides: ["above", "below"] })).toMatchObject({ side: "below", top: 92 });
45
+ // A card as wide as the view, at its top: no room above or below for a tall dialog; to its side when that has room.
46
+ const p = placeFloat(box(20, 10, 600, 650), { width: 300, height: 400 }, box(0, 0, 1000, 700), { sides: ["above", "below", "right"] });
47
+ expect(p.side).toBe("right");
48
+ expect(fitsIn({ ...p, width: 300, height: 400 }, box(0, 0, 1000, 700))).toBe(true);
49
+ });
50
+
51
+ it("never covers its anchor when a side has room, and keeps its leader's end on the anchor", () => {
52
+ const card = box(574, 84, 110, 50);
53
+ const p = placeFloat(card, size, view);
54
+ expect(overlaps({ ...p, ...size }, card)).toBe(false);
55
+ expect(p.side).toBe("right");
56
+ // The notch points at the card's middle, along the dialog's near edge.
57
+ expect(p.top + p.arrow).toBe(card.top + card.height / 2);
58
+ });
59
+
60
+ it("a dialog taller than the view is capped there, its top inside the view", () => {
61
+ const p = placeFloat(box(400, 300, 300, 80), { width: 442, height: 900 }, view);
62
+ expect(p.maxHeight).toBe(686 - 2 * FLOAT_MARGIN);
63
+ expect(p.top).toBe(FLOAT_MARGIN);
64
+ expect(fitsIn({ left: p.left, top: p.top, width: 442, height: p.maxHeight }, view)).toBe(true);
65
+ expect(placeFloat(box(400, 300, 300, 80), size, view).maxHeight).toBeNull();
66
+ });
67
+
68
+ it("stays inside the view for any anchor, at both kiosk sizes", () => {
69
+ for (const v of [box(0, 0, 1910, 981), box(0, 0, 1356, 686), box(5, 77, 1356, 400)]) {
70
+ for (let x = -200; x < v.width + 200; x += 97) {
71
+ for (let y = -200; y < v.height + 200; y += 89) {
72
+ for (const s of [size, { width: 535, height: 771 }, { width: 30, height: 20 }]) {
73
+ const p = placeFloat(box(x, y, 110, 50), s, v);
74
+ const h = p.maxHeight || s.height;
75
+ expect(fitsIn({ left: p.left, top: p.top, width: Math.min(s.width, v.width - 16), height: h }, v)).toBe(true);
76
+ }
77
+ }
78
+ }
79
+ }
80
+ });
81
+ });
82
+
83
+ describe("the dialogs that use it", () => {
84
+ it("the card popover: right of a top-row card, inside the frame, capped when taller", () => {
85
+ const frame = { width: 1356, height: 686 };
86
+ const p = placePopover(box(574, 84, 110, 50), { width: 412, height: 141 }, frame);
87
+ expect(p).toMatchObject({ side: "right", left: 696, top: 84, maxHeight: null });
88
+ const tall = placePopover(box(574, 0, 110, 50), { width: 412, height: 900 }, frame);
89
+ expect(tall.top).toBe(8);
90
+ expect(tall.maxHeight).toBe(670);
91
+ });
92
+
93
+ it("the job box's drawer, opened taller than the graph above the caption: kept below the view's top, capped (was 94px off it)", () => {
94
+ // 1366x768: the graph shows from 77px to the caption's top at 480px; the drawer opened is 569px tall.
95
+ const view = { x: 5, y: 77, w: 1356, h: 403 };
96
+ const p = placeBeside({ x: 120, y: 250, w: 920, h: 300 }, { w: 442, h: 569 }, view);
97
+ expect(p.y).toBeGreaterThanOrEqual(view.y + 8);
98
+ expect(p.maxHeight).toBe(403 - 16);
99
+ expect(p.y + p.maxHeight).toBeLessThanOrEqual(view.y + view.h - 8);
100
+ // Its old "below" spot was 18px under a wave box low in the view: now it never runs past the top for that either.
101
+ const low = placeBeside({ x: 0, y: 300, w: 1356, h: 160 }, { w: 442, h: 300 }, view);
102
+ expect(low.y).toBeGreaterThanOrEqual(view.y + 8);
103
+ expect(low.y + 300).toBeLessThanOrEqual(view.y + view.h - 8);
104
+ });
105
+
106
+ it("the tooltip: inside the window when it fits neither below nor above", () => {
107
+ const p = placeTip({ left: 100, right: 140, top: 300, bottom: 320 }, { width: 200, height: 500 }, { width: 800, height: 600 });
108
+ expect(p.top).toBeGreaterThanOrEqual(8);
109
+ expect(p.top + 500).toBeLessThanOrEqual(600 - 8 + 0.5);
110
+ });
111
+
112
+ it("an event-help tip under a card low in the window stays inside its bottom", () => {
113
+ const p = tipSpot({ left: 400, top: 10, width: 300, height: 700 }, { w: 240, h: 30 }, { w: 1440, h: 760 });
114
+ expect(p.below).toBe(true);
115
+ expect(p.y + 30).toBeLessThanOrEqual(760 - 8);
116
+ });
117
+ });
package/web/index.html CHANGED
@@ -523,8 +523,12 @@
523
523
  /* behold#571: the marks drawn over a card let the pointer through to it, so pointing anywhere on the card opens its popover. */
524
524
  .bare #graph text[data-tg-root], .bare #graph g[data-tg-root] { pointer-events: none; }
525
525
  /* behold#571: the kiosk frame's popover, beside the card it describes. */
526
- #k-pop { position: fixed; z-index: 50; max-width: min(30em, 46vw); padding: 0.7em 0.9em 0.6em; background: var(--panel); color: var(--fg);
527
- border: 1px solid var(--rule); border-radius: 8px; box-shadow: 0 6px 22px color-mix(in srgb, var(--shadow) 70%, transparent);
526
+ /* behold#764: capped to the frame's view by placePopover (max-height), its body scrolls. */
527
+ /* behold#764: on the kiosk's raised surface (its modals' and callouts'), not --panel: in Batman --panel is within a
528
+ few steps of the cards and wave boxes under it, so the popover read as see-through over the graph. A focus-tinted
529
+ border and a deeper shadow set it apart in every theme. */
530
+ #k-pop { position: fixed; z-index: 50; max-width: min(30em, 46vw); overflow-y: auto; overscroll-behavior: contain; padding: 0.7em 0.9em 0.6em; background: var(--surface-pane-b, var(--panel)); color: var(--fg);
531
+ border: 1.5px solid color-mix(in srgb, var(--focus) 70%, var(--rule)); border-radius: 8px; box-shadow: 0 10px 34px color-mix(in srgb, var(--shadow) 80%, transparent);
528
532
  font: 14px/1.4 var(--font-ui); pointer-events: auto; }
529
533
  #k-pop[hidden] { display: none; }
530
534
  /* behold#571: on a phone the popover takes the frame's width, less a margin. */
@@ -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,13 +10,16 @@
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, storyKey, ehSnapshot, ehStore, ehStored, modalQueue, modalShownElsewhere, newEvents, storyTrail, tipsQueue, tipsShown } from "./kiosk-event-help.js";
22
+ import { EH_STORE, HIGHLIGHT_MS, LATE_ORDER, TIP_MS, createDismissals, cycleFacts, dismissKey, stepWrittenAt, storyKey, ehSnapshot, ehStore, ehStored, highlightOpens, highlightShown, highlightTurn, modalQueue, modalShownElsewhere, newEvents, storyTrail, tipsQueue, tipsShown, waitingOpens } 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;
@@ -111,7 +114,11 @@ export function tipSpot(rect, size, win, labels = []) {
111
114
  if (y >= 8) spots.push({ x: spots[0].x, y, below: false });
112
115
  }
113
116
  }
114
- spots.push(...along(rect.top + rect.height + 12, true));
117
+ // behold#764: below, kept inside the window's bottom when its height is known (a tip under a card low in the view).
118
+ const belowY = win.h ? Math.max(8, Math.min(rect.top + rect.height + 12, win.h - h - 8)) : rect.top + rect.height + 12;
119
+ spots.push(...along(belowY, true));
120
+ // An anchor too narrow for any spot along it to reach: the centred spot, still inside the window.
121
+ if (!spots.length) spots.push({ x: clampX(mid - w / 2), y: aboveY >= 8 ? aboveY : belowY, below: aboveY < 8 });
115
122
  let best = null;
116
123
  for (const p of spots) {
117
124
  const c = covered(p);
@@ -135,7 +142,7 @@ export function toneOf(kind) {
135
142
  * lights them across the panes as a hover does (null puts them out);
136
143
  * `panel(kind)` builds the real panel the modal shows (the approval panel).
137
144
  */
138
- export function startEventHelp({ doc = document, store = null, switchHost = null, trailHost, tipsHost, modalHost, get, light = () => {}, panel = () => null, openTrace = () => {}, now = () => Date.now(), shown = now, reduced = () => typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches }) {
145
+ export function startEventHelp({ doc = document, store = null, session = null, switchHost = null, trailHost, tipsHost, modalHost, get, light = () => {}, panel = () => null, openTrace = () => {}, now = () => Date.now(), shown = now, reduced = () => typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches }) {
139
146
  if (doc.head && !doc.getElementById("eh-style")) {
140
147
  const style = doc.createElement("style");
141
148
  style.id = "eh-style";
@@ -144,6 +151,13 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
144
151
  }
145
152
  modalStyle(doc);
146
153
  const st = { bootAt: now(), maxOrder: -Infinity, appliedAt: new Map(), on: ehStored(store), cycle: null, seen: null, trail: new Map(), failed: new Set(), tips: null, modals: null, modal: null, lastInput: -Infinity, lit: null, litUntil: 0, nodes: new Map(), glows: [] };
154
+ // behold#764: the story modals the viewer closed this visit (sessionStorage, `session`), which do not open again for the same thing.
155
+ st.closed = createDismissals(session);
156
+ /** The onClose of a story modal about `key` of `kind`: a close by the viewer is kept, so the same thing never reopens it. */
157
+ const closedBy = (kind, d, key) => (ms) => {
158
+ st.modal = null;
159
+ if (ms && ms.closedBy === "viewer") st.closed.add(dismissKey(kind, d, key));
160
+ };
147
161
  const el = (tag, cls, text) => {
148
162
  const n = doc.createElement(tag);
149
163
  if (cls) n.className = cls;
@@ -209,6 +223,11 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
209
223
  const now = (get && get()) || h;
210
224
  return ((now && now.boxes && now.boxes.labels) || []).map((l) => fromFrame(now, l)).filter(Boolean);
211
225
  };
226
+ /** behold#764: the card's details popover the frame has open (its `pop`, read fresh), in the window's coordinates, or null. */
227
+ const popRect = (at) => {
228
+ const h = (get && get()) || at;
229
+ return h && h.pop ? fromFrame(h, h.pop) : null;
230
+ };
212
231
  /** behold#631: the graph's area above the bottom band (the track or trail, and the caption): where a chant modal may go. */
213
232
  const graphArea = (h) => {
214
233
  const F = frameRect(h);
@@ -251,7 +270,7 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
251
270
 
252
271
  // ---- tips ----------------------------------------------------------------
253
272
  const place = (node, rect, h) => {
254
- const win = { w: doc.defaultView ? doc.defaultView.innerWidth : 1600 };
273
+ const win = { w: doc.defaultView ? doc.defaultView.innerWidth : 1600, h: doc.defaultView ? doc.defaultView.innerHeight : 0 };
255
274
  // The frame's edge labels, in the window's coordinates (behold#695).
256
275
  const F = h ? frameRect(h) : null;
257
276
  const labels = F && h.boxes && Array.isArray(h.boxes.labels) ? h.boxes.labels.map((l) => ({ x: F.left + l.x, y: F.top + l.y, w: l.w, h: l.h })) : [];
@@ -425,6 +444,8 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
425
444
  data = { title: "Applied", lines: [...(h.label ? [{ text: h.label }] : []), ...(r ? r.counts.map((c) => ({ text: c })) : [])], replayAt: t };
426
445
  }
427
446
  const kind = event.kind === "refused" ? "failed" : event.kind;
447
+ // behold#764: never over the card's details popover a viewer has open.
448
+ data.keepClear = () => popRect(h);
428
449
  // behold#631: a chant failure's modal keeps clear of the failed card and the cards it blocked.
429
450
  // It must leave the failed wave and the wave after it in view (`avoid`), and covers as few other cards as it can.
430
451
  // behold#741: a terragucci story's modals do the same: off the cards they are about (a held wave's, a failed one's),
@@ -438,7 +459,7 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
438
459
  data.bounds = () => graphArea(h);
439
460
  }
440
461
  // A chant kiosk counts down on the clock its track and caption use, so all three say the same second.
441
- const api = openEventModal(modalHost, { mode, kind, data, doc, now: event.chant ? now : shown, reduced: reduced(), onClose: () => (st.modal = null) });
462
+ const api = openEventModal(modalHost, { mode, kind, data, doc, now: event.chant ? now : shown, reduced: reduced(), onClose: closedBy(kind, d, event.id) });
442
463
  st.modal = { api, event, kind, step: d ? d.step : null, cycle: d ? d.cycle : null, pull: d ? d.pull : null };
443
464
  };
444
465
  /** behold#631: the "Waiting on…" modal's words: what is waited on, why it matters, and how long it usually takes. */
@@ -446,11 +467,26 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
446
467
  title: `Waiting on ${w.what}`,
447
468
  lines: w.why ? [{ text: w.why }] : [],
448
469
  progress: { fraction: w.fraction, words: w.words },
449
- // Never over a card: any card of the graph is to stay in view. Then, where it can, off the graph altogether
450
- // (its wave boxes and the space between them, where a reach is drawn): the space beside it first.
451
- // behold#744: nor over a read pill the frame shows.
452
- avoid: () => [...Object.keys((h.boxes && h.boxes.roots) || {}).map((r) => fromFrame(h, h.boxes.roots[r])).filter(Boolean), ...pillRects(h)],
470
+ ...offCards(h),
471
+ keepClear: () => popRect(h),
472
+ });
473
+ /**
474
+ * Where a modal about no one card goes (the "Waiting on…" one, a step's highlight): never over a card, since any
475
+ * card of the graph is to stay in view. Then, where it can, off the graph altogether (its wave boxes and the space
476
+ * between them, where a reach is drawn): the space beside it first. behold#744: nor over a read pill the frame
477
+ * shows; behold#748's outside mark sits in the pills' layer, so it is kept clear of the same way.
478
+ * behold#757: each read of the cards is of what the frame says now: a highlight opens with its step, often
479
+ * before the frame has said where its cards are.
480
+ */
481
+ const offCards = (at) => ({
482
+ avoid: () => {
483
+ const h = (get && get()) || at;
484
+ // behold#764: nor over the job box (the log drawer) or the approval callout beside a wave.
485
+ const overs = doc.querySelectorAll ? [...doc.querySelectorAll("#k-drawer.k-placed, #k-callout.k-placed")].filter((n) => !n.hidden && n.getBoundingClientRect).map((n) => n.getBoundingClientRect()).filter((r) => r.width > 0) : [];
486
+ return [...Object.keys((h.boxes && h.boxes.roots) || {}).map((r) => fromFrame(h, h.boxes.roots[r])).filter(Boolean), ...pillRects(h), ...overs];
487
+ },
453
488
  prefer: () => {
489
+ const h = (get && get()) || at;
454
490
  const waves = Object.values((h.boxes && h.boxes.waves) || {}).map((b) => fromFrame(h, b)).filter(Boolean);
455
491
  if (!waves.length) return [];
456
492
  const left = Math.min(...waves.map((b) => b.left));
@@ -459,14 +495,24 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
459
495
  const bottom = Math.max(...waves.map((b) => b.top + b.height));
460
496
  return [{ left, top, width: right - left, height: bottom - top }];
461
497
  },
462
- bounds: () => graphArea(h),
498
+ bounds: () => graphArea((get && get()) || at),
463
499
  });
464
500
  const openWaiting = (w, h) => {
465
501
  const d = h.demo;
466
- const api = openEventModal(modalHost, { mode: "narrated", kind: "waiting", data: waitingData(w, h), doc, now, reduced: reduced(), onClose: () => (st.modal = null) });
502
+ const api = openEventModal(modalHost, { mode: "narrated", kind: "waiting", data: waitingData(w, h), doc, now, reduced: reduced(), onClose: closedBy("waiting", d, w.key) });
467
503
  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 };
468
504
  if (st.story) for (const n of st.nodes.values()) n.style.visibility = "hidden";
469
505
  };
506
+ /** behold#757: a step's highlight, as a modal off the cards: up HIGHLIGHT_MS (longer while hovered), or until its step goes. */
507
+ const openHighlight = (hl, h) => {
508
+ const d = h.demo;
509
+ const data = { title: hl.title, lines: [{ text: hl.body }], closeAfter: HIGHLIGHT_MS, ...offCards(h), keepClear: () => popRect(h) };
510
+ // behold#764: once per cycle, step and title for the visit, a reload included: kept as it opens.
511
+ st.closed.add(dismissKey("highlight", d, hl.id));
512
+ const api = openEventModal(modalHost, { mode: h.replay ? "replay" : "narrated", kind: "highlight", data, doc, now, reduced: reduced(), onClose: () => (st.modal = null) });
513
+ 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 };
514
+ for (const n of st.nodes.values()) n.style.visibility = "hidden";
515
+ };
470
516
  /** The modal's real event: the approval landed, the waves ran again, the cycle moved on. */
471
517
  const settleModal = (h, facts) => {
472
518
  const m = st.modal;
@@ -509,6 +555,10 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
509
555
  st.trail.clear();
510
556
  st.failed.clear();
511
557
  }
558
+ // behold#764: a replay looping round to its start (its step's time goes back) is a new telling: what the viewer closed opens again.
559
+ const at = stepWrittenAt(h.demo);
560
+ if (at !== null && st.writtenAt !== undefined && st.writtenAt !== null && at < st.writtenAt) st.closed.clear();
561
+ st.writtenAt = at;
512
562
  for (const f of facts) if ((f.kind === "failed" || f.kind === "refused") && Number.isInteger(f.subjects.wave)) st.failed.add(f.subjects.wave);
513
563
  // While the page settles, everything is the story so far.
514
564
  const settling = now() - st.bootAt < SETTLE_MS;
@@ -524,6 +574,11 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
524
574
  settleModal(h, facts);
525
575
  // A modal Inspect opened goes when the viewer turns to Watch on a held small stage, where nothing overlays the graph.
526
576
  if (st.modal && modalShownElsewhere(st.modal.event, { watch: !!h.watch, held: !!h.held })) st.modal.api.close();
577
+ // behold#757: a step's highlight is read on every look (Tips off or not, so turning them on mid-step still shows it,
578
+ // and one the driver adds partway through a step shows when it appears); its modal goes with its step, or when the
579
+ // viewer turns to Inspect: it is Watch's.
580
+ st.hl = highlightTurn(st.hl, h.demo);
581
+ if (st.modal && st.modal.kind === "highlight" && (st.modal.key !== st.hl.step || !h.watch)) st.modal.api.close();
527
582
  if (!st.on) return;
528
583
  // behold#631: a new pull request of a chant cycle (the fix) starts with no tip of the one before.
529
584
  if (h.chant && st.tipsPull !== undefined && st.tipsPull !== h.demo.pull) {
@@ -555,11 +610,23 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
555
610
  if (news.length && h.waiting) st.waitingHold = { key: h.waiting.key, until: now() + 4_000 };
556
611
  st.modal.api.close();
557
612
  }
613
+ // behold#757: the step's highlight, once per cycle, step and title, before the critical modals: one due now waits
614
+ // behind it in the queue, and opens when it closes if its step is still the step.
615
+ // behold#764: a highlight this visit already showed (before a reload) is not shown again; none opens over a details popover.
616
+ const pop = popRect(h);
617
+ if (st.hl.pending && st.closed.has(dismissKey("highlight", h.demo, st.hl.pending.id))) st.hl = highlightShown(st.hl);
618
+ if (highlightOpens({ pending: st.hl.pending, on: st.on, watch: !!h.watch, held: !!h.held, modal: st.modal ? st.modal.kind : null, pop })) {
619
+ if (st.modal) st.modal.api.close();
620
+ openHighlight(st.hl.pending, h);
621
+ st.hl = highlightShown(st.hl);
622
+ }
558
623
  // 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.
559
624
  // Its result is the Applied card beside the graph; a modal would say it twice, over the cards.
560
625
  // On a held small stage in Watch no modal opens: nothing overlays the graph there, and the caption says each step.
561
626
  const told = (e) => modalShownElsewhere(e, { watch: !!h.watch, held: !!h.held });
562
- 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 });
627
+ // behold#764: one the viewer closed stays closed; one due while a details popover is open waits for it to close.
628
+ const closedOne = (e) => st.closed.has(dismissKey(e.kind === "refused" ? "failed" : e.kind, h.demo, e.id));
629
+ st.modals = modalQueue(st.modals, { add: (h.chant ? news.filter((f) => f.kind !== "held" && f.kind !== "applied") : news).filter((e) => !told(e) && !closedOne(e)), now: now(), lastInput: st.lastInput, open: !!st.modal || !!pop });
563
630
  // 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.
564
631
  if (st.modals.next && stillNow(st.modals.next, h.demo)) {
565
632
  openModal(st.modals.next, h);
@@ -568,7 +635,8 @@ export function startEventHelp({ doc = document, store = null, switchHost = null
568
635
  }
569
636
  // behold#631: a quiet stretch on a chant kiosk: "Waiting on …", when no other modal is up or due.
570
637
  const held = st.waitingHold && h.waiting && st.waitingHold.key === h.waiting.key && now() < st.waitingHold.until;
571
- if (h.waiting && st.on && !held && !st.modal && !(st.modals && st.modals.next)) openWaiting(h.waiting, h);
638
+ const closedWait = !!h.waiting && st.closed.has(dismissKey("waiting", h.demo, h.waiting.key));
639
+ if (waitingOpens({ waiting: h.waiting, on: st.on, held, modal: st.modal, due: !!(st.modals && st.modals.next), pop, closed: closedWait })) openWaiting(h.waiting, h);
572
640
  else if (h.waiting && st.modal && st.modal.kind === "waiting") st.modal.api.update(waitingData(h.waiting, h));
573
641
  };
574
642
  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);
@@ -340,3 +340,149 @@ export function modalQueue(state, { add = [], now = 0, lastInput = -Infinity, qu
340
340
  if (open || !queue.length || now - lastInput < quietMs) return { next: null, waiting: queue };
341
341
  return { next: queue[0], waiting: queue.slice(1) };
342
342
  }
343
+
344
+ // ---------------------------------------------------------------------------
345
+ // behold#757: a step's highlight. The scenario's driver says what is special
346
+ // about a step (demo.json's or demo-step/v1's `highlight: { title, body }`,
347
+ // terragucci#1176, chant#4106) on the step where it happens; Watch opens it as
348
+ // a modal once per cycle, step and title. The driver writes a step more than
349
+ // once (an apply, its holds) with the same highlight, which opens once; a step
350
+ // can gain one partway through (choudoufu's operator, on one write of the
351
+ // applying step), which opens when it first appears; and a replay that loops
352
+ // round to its step opens it again.
353
+
354
+ /** How long a highlight stays up, longer than a tip: it is a paragraph to read. It goes sooner when its step does. */
355
+ export const HIGHLIGHT_MS = 12_000;
356
+
357
+ /** A demo step's highlight, `{ title, body }`, or null unless both are non-empty strings (the server's floor, again). */
358
+ export function stepHighlight(demo) {
359
+ const h = demo && demo.highlight;
360
+ if (!h || typeof h !== "object" || Array.isArray(h)) return null;
361
+ const title = typeof h.title === "string" ? h.title.trim() : "";
362
+ const body = typeof h.body === "string" ? h.body.trim() : "";
363
+ return title && body ? { title, body } : null;
364
+ }
365
+
366
+ /** The step a highlight's modal stays with: its cycle, beat, pull request and step. It closes when the step moves on. */
367
+ export function highlightStepKey(demo) {
368
+ if (!demo) return null;
369
+ return [demo.cycle, demo.beat || "", demo.pull === null || demo.pull === undefined ? "" : demo.pull, demo.step].join("|");
370
+ }
371
+
372
+ /** What a highlight opens once for: its cycle (and beat), its step and its title (terragucci#1176). */
373
+ export const highlightId = (demo, h) => [demo.cycle, demo.beat || "", demo.step, h.title].join("|");
374
+
375
+ /** When a step was written: a replay's step its `at`, a live one its `started_at`. A time that goes back is a replay looping round. */
376
+ const writtenAt = (demo) => {
377
+ const t = Date.parse((demo && (demo.at || demo.started_at)) || "");
378
+ return Number.isFinite(t) ? t : null;
379
+ };
380
+
381
+ /**
382
+ * The highlight's state after a look at `demo`: `{ step, seen, at, pending }`.
383
+ * `pending` is the step's highlight while it has not opened (`{ id, key,
384
+ * title, body }`), to open once nothing stops it; `seen` the ids opened this
385
+ * pass of the cycle, so a highlight written again is not opened again. A step
386
+ * that goes takes a pending highlight with it; a replay looping round (its
387
+ * step's time going back) starts a new pass.
388
+ */
389
+ export function highlightTurn(state, demo) {
390
+ const at = writtenAt(demo);
391
+ const looped = !!state && state.at !== null && at !== null && at < state.at;
392
+ const seen = !state || looped ? new Set() : state.seen;
393
+ const step = highlightStepKey(demo);
394
+ const h = stepHighlight(demo);
395
+ const id = h ? highlightId(demo, h) : null;
396
+ const kept = state && !looped && state.pending && state.pending.id === id && state.step === step ? state.pending : null;
397
+ const pending = h && !seen.has(id) ? kept || { id, key: step, ...h } : null;
398
+ if (state && !looped && state.step === step && state.pending === pending && state.at === at) return state;
399
+ return { step, seen, at, pending };
400
+ }
401
+
402
+ /** The state once its pending highlight has opened: seen for the rest of the pass. */
403
+ export function highlightShown(state) {
404
+ if (!state || !state.pending) return state;
405
+ return { ...state, seen: new Set([...state.seen, state.pending.id]), pending: null };
406
+ }
407
+
408
+ /**
409
+ * Whether a pending highlight opens now: Tips on, in Watch, not on a held
410
+ * small stage (nothing overlays the graph there), and no modal up but a
411
+ * "Waiting on…" one, which it replaces. A critical modal up keeps it waiting.
412
+ */
413
+ export function highlightOpens({ pending = null, on = true, watch = false, held = false, modal = null, pop = null } = {}) {
414
+ // behold#764: nor over the card's details popover a viewer has open (`pop`): it waits until that closes.
415
+ return !!pending && !!on && !!watch && !held && !pop && (!modal || modal === "waiting");
416
+ }
417
+
418
+ // ---------------------------------------------------------------------------
419
+ // behold#764: a story modal a viewer closes stays closed. "Waiting on the
420
+ // pipeline…" came straight back on the next look after its ×: the tick opens
421
+ // one whenever a wait is up and no modal is. A close by the viewer (×, Escape,
422
+ // a click on the sheet) is kept for what the modal was about: its kind, the
423
+ // cycle (and beat), the pull request, the step, and its own key (the wait's
424
+ // chapter, segment and what it waits on; a fact's id; a highlight's id). A new
425
+ // wait (a later step, a new pull request, a new cycle) opens again. Kept for
426
+ // the visit in sessionStorage, so a reload does not bring it back either; a
427
+ // replay that loops round to its start forgets them, as it does a highlight.
428
+ // A step's highlight is kept here once it has opened, so it is once per
429
+ // cycle, step and title across a reload too.
430
+
431
+ /** Where the visit's closed modals are kept (sessionStorage). */
432
+ export const DISMISS_STORE = "behold.eventHelp.closed";
433
+ /** At most this many are kept: the newest. */
434
+ export const DISMISS_MAX = 64;
435
+
436
+ /** What a story modal is about, as one key: kind, cycle, beat, pull request, step and its own key. */
437
+ export function dismissKey(kind, demo, key) {
438
+ const d = demo || {};
439
+ return [kind, d.cycle ?? "", d.beat || "", d.pull ?? "", d.step || "", key ?? ""].join("|");
440
+ }
441
+
442
+ /** When a step was written, in ms (a replay's `at`, a live step's `started_at`), or null. */
443
+ export const stepWrittenAt = (demo) => writtenAt(demo);
444
+
445
+ /**
446
+ * The visit's closed modals: `{ has(key), add(key), clear(), keys() }`, kept
447
+ * in `store` (sessionStorage) where it lets them be, in memory where it
448
+ * throws or is missing. Never localStorage: a closed modal is this visit's.
449
+ */
450
+ export function createDismissals(store = null) {
451
+ let keys = [];
452
+ try {
453
+ const raw = store ? JSON.parse(store.getItem(DISMISS_STORE) || "[]") : [];
454
+ if (Array.isArray(raw)) keys = raw.filter((k) => typeof k === "string").slice(-DISMISS_MAX);
455
+ } catch {
456
+ keys = [];
457
+ }
458
+ const save = () => {
459
+ try {
460
+ if (store) store.setItem(DISMISS_STORE, JSON.stringify(keys));
461
+ } catch {
462
+ /* kept for this page only */
463
+ }
464
+ };
465
+ return {
466
+ has: (key) => keys.includes(key),
467
+ add(key) {
468
+ if (keys.includes(key)) return;
469
+ keys = [...keys, key].slice(-DISMISS_MAX);
470
+ save();
471
+ },
472
+ clear() {
473
+ if (!keys.length) return;
474
+ keys = [];
475
+ save();
476
+ },
477
+ keys: () => [...keys],
478
+ };
479
+ }
480
+
481
+ /**
482
+ * behold#764: whether the "Waiting on…" modal opens now: a wait is up, Tips
483
+ * on, no other modal up or due, the wait not just closed by news (`held`),
484
+ * no details popover open (`pop`), and the viewer has not closed this wait.
485
+ */
486
+ export function waitingOpens({ waiting = null, on = true, held = false, modal = null, due = false, pop = null, closed = false } = {}) {
487
+ return !!waiting && !!on && !held && !modal && !due && !pop && !closed;
488
+ }