@intentius/behold 0.29.40 → 0.29.42
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.
- package/AGENTS.md +180 -10
- package/README.md +6 -2
- package/dist/cli.js +16121 -13141
- package/example-writes/README.md +1 -1
- package/example-writes/chant.config.ts +0 -6
- package/package.json +5 -2
- package/web/app.js +327 -21
- package/web/carve-export.js +142 -0
- package/web/carve-narration.js +294 -0
- package/web/carve-narration.test.js +48 -0
- package/web/change-set-overlay.js +147 -0
- package/web/change-set-overlay.test.js +83 -0
- package/web/dots-border.js +66 -0
- package/web/dots-border.test.js +27 -0
- package/web/dots-kiosk.js +279 -0
- package/web/dots-kiosk.test.js +60 -0
- package/web/dots-layout.d.ts +10 -0
- package/web/dots-layout.js +201 -0
- package/web/dots-live.js +316 -0
- package/web/dots-live.test.js +220 -0
- package/web/dots-lod.js +122 -0
- package/web/dots-lod.test.js +78 -0
- package/web/dots-recording.d.ts +7 -0
- package/web/dots-recording.js +247 -0
- package/web/dots-recording.test.js +71 -0
- package/web/dots-scene.js +294 -0
- package/web/dots-scene.test.js +118 -0
- package/web/dots-timeline.js +128 -0
- package/web/dots-timeline.test.js +83 -0
- package/web/dots-tour.js +153 -0
- package/web/dots.js +2124 -0
- package/web/dots.test.js +15 -0
- package/web/event-help-modal.js +1 -1
- package/web/index.html +215 -121
- package/web/kiosk-carve.js +225 -0
- package/web/kiosk-carve.test.js +26 -0
- package/web/kiosk-event-help-ui.js +7 -1
- package/web/kiosk-link.js +68 -0
- package/web/kiosk-link.test.js +69 -0
- package/web/kiosk-metrics.js +2 -2
- package/web/kiosk-trace.js +1 -1
- package/web/kiosk.html +186 -135
- package/web/kiosk.js +65 -7
- package/web/motion.js +42 -0
- package/web/motion.test.js +64 -0
- package/web/operator.js +1 -1
- package/web/run-playhead.js +102 -19
- package/web/run-playhead.test.js +81 -11
- package/web/terralith.html +2 -2
- package/web/theme.js +99 -26
- package/web/theme.test.js +70 -6
- package/web/tooltip.js +212 -0
- package/web/tooltip.test.js +193 -0
- package/web/tour-player.js +204 -0
- package/web/tour-player.test.js +115 -0
- package/web/tours/behold.tour.v1.schema.json +182 -0
- package/web/tours/terralith.json +330 -0
- package/web/trunk-lane.js +406 -0
- package/web/trunk-lane.test.js +224 -0
- package/web/workspace-gates.js +29 -4
- package/web/workspace-gates.test.js +23 -2
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
import { describe, expect, it } from "vitest";
|
|
2
|
+
import { HOVER_MS, TIP_ID, addId, dropId, installTooltips, isBadge, ownTitle, placeTip, reachBadges, tipHost } from "./tooltip.js";
|
|
3
|
+
|
|
4
|
+
// behold#725: a stand-in DOM, enough for the tooltip: elements with
|
|
5
|
+
// attributes, children, text and a rect, and a document with listeners.
|
|
6
|
+
class El {
|
|
7
|
+
constructor(tag, attrs = {}, kids = []) {
|
|
8
|
+
this.nodeType = 1;
|
|
9
|
+
this.localName = tag;
|
|
10
|
+
this.attrs = new Map(Object.entries(attrs));
|
|
11
|
+
this.children = [];
|
|
12
|
+
this.parentNode = null;
|
|
13
|
+
this._text = "";
|
|
14
|
+
this.hidden = false;
|
|
15
|
+
this.style = {};
|
|
16
|
+
this.rect = { left: 100, top: 100, right: 140, bottom: 120, width: 40, height: 20 };
|
|
17
|
+
this.focusVisible = true;
|
|
18
|
+
for (const k of kids) this.appendChild(typeof k === "string" ? Object.assign(new El("#text"), { _text: k }) : k);
|
|
19
|
+
}
|
|
20
|
+
get id() { return this.getAttribute("id") || ""; }
|
|
21
|
+
set id(v) { this.setAttribute("id", v); }
|
|
22
|
+
getAttribute(k) { return this.attrs.has(k) ? this.attrs.get(k) : null; }
|
|
23
|
+
setAttribute(k, v) { this.attrs.set(k, String(v)); }
|
|
24
|
+
hasAttribute(k) { return this.attrs.has(k); }
|
|
25
|
+
removeAttribute(k) { this.attrs.delete(k); }
|
|
26
|
+
appendChild(c) { c.parentNode = this; this.children.push(c); return c; }
|
|
27
|
+
get textContent() { return this.localName === "#text" ? this._text : this._text + this.children.map((c) => c.textContent).join(""); }
|
|
28
|
+
set textContent(v) { this.children = []; this._text = String(v); }
|
|
29
|
+
getBoundingClientRect() { return this.rect; }
|
|
30
|
+
matches(q) { return q === ":focus-visible" ? this.focusVisible : false; }
|
|
31
|
+
*walk() { for (const c of this.children) { yield c; yield* c.walk(); } }
|
|
32
|
+
querySelectorAll(q) {
|
|
33
|
+
if (q !== "svg title") return [];
|
|
34
|
+
const out = [];
|
|
35
|
+
for (const n of this.walk()) {
|
|
36
|
+
if (n.localName !== "title") continue;
|
|
37
|
+
for (let p = n.parentNode; p; p = p.parentNode) if (p.localName === "svg") { out.push(n); break; }
|
|
38
|
+
}
|
|
39
|
+
return out;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
const fakeDoc = (body, { bare = false } = {}) => {
|
|
43
|
+
const listeners = new Map();
|
|
44
|
+
const html = new El("html", {}, [body]);
|
|
45
|
+
html.classList = { contains: (c) => c === "bare" && bare };
|
|
46
|
+
html.clientWidth = 800;
|
|
47
|
+
html.clientHeight = 600;
|
|
48
|
+
const doc = {
|
|
49
|
+
documentElement: html,
|
|
50
|
+
body,
|
|
51
|
+
defaultView: { innerWidth: 800, innerHeight: 600 },
|
|
52
|
+
createElement: (tag) => new El(tag),
|
|
53
|
+
getElementById: (id) => [...html.walk()].find((n) => n.getAttribute && n.getAttribute("id") === id) || null,
|
|
54
|
+
querySelector: () => null,
|
|
55
|
+
addEventListener: (type, fn) => listeners.set(type, fn),
|
|
56
|
+
removeEventListener: (type) => listeners.delete(type),
|
|
57
|
+
fire: (type, e) => listeners.get(type) && listeners.get(type)(e),
|
|
58
|
+
};
|
|
59
|
+
html.parentNode = null;
|
|
60
|
+
return doc;
|
|
61
|
+
};
|
|
62
|
+
const graph = () => {
|
|
63
|
+
const badgeTitle = new El("title", {}, ["wave 2 · waiting\n(from terragucci's reports, not live)"]);
|
|
64
|
+
const badgeRect = new El("rect");
|
|
65
|
+
const badge = new El("g", { "data-tg-root": "badge" }, [badgeTitle, badgeRect]);
|
|
66
|
+
const cardTitle = new El("title", {}, ["still reading this member"]);
|
|
67
|
+
const card = new El("g", { "data-node-id": "a/b" }, [cardTitle, new El("rect"), badge]);
|
|
68
|
+
const edge = new El("g", { "data-edge-from": "a/b" }, [new El("title", {}, ["data dependency"])]);
|
|
69
|
+
const svg = new El("svg", {}, [card, edge]);
|
|
70
|
+
const body = new El("body", {}, [svg]);
|
|
71
|
+
return { body, svg, card, cardTitle, badge, badgeTitle, badgeRect, edge };
|
|
72
|
+
};
|
|
73
|
+
const timers = () => {
|
|
74
|
+
const queue = [];
|
|
75
|
+
return { setTimer: (fn, ms) => { queue.push({ fn, ms }); return queue.length; }, clearTimer: (i) => { if (queue[i - 1]) queue[i - 1].fn = () => {}; }, run: () => queue.splice(0).forEach((t) => t.fn()), queue };
|
|
76
|
+
};
|
|
77
|
+
|
|
78
|
+
describe("placeTip (behold#725)", () => {
|
|
79
|
+
const view = { width: 800, height: 600 };
|
|
80
|
+
it("centres the tooltip under its target", () => {
|
|
81
|
+
expect(placeTip({ left: 100, right: 140, top: 100, bottom: 120 }, { width: 60, height: 30 }, view)).toEqual({ left: 90, top: 128, side: "below" });
|
|
82
|
+
});
|
|
83
|
+
it("goes above when there is no room below", () => {
|
|
84
|
+
expect(placeTip({ left: 100, right: 140, top: 560, bottom: 580 }, { width: 60, height: 30 }, view)).toEqual({ left: 90, top: 522, side: "above" });
|
|
85
|
+
});
|
|
86
|
+
it("stays inside the window's sides", () => {
|
|
87
|
+
expect(placeTip({ left: 0, right: 10, top: 10, bottom: 20 }, { width: 200, height: 30 }, view).left).toBe(8);
|
|
88
|
+
expect(placeTip({ left: 790, right: 800, top: 10, bottom: 20 }, { width: 200, height: 30 }, view).left).toBe(592);
|
|
89
|
+
});
|
|
90
|
+
});
|
|
91
|
+
|
|
92
|
+
describe("the id list (behold#725)", () => {
|
|
93
|
+
it("adds the tooltip's id once and takes it out again, keeping the others", () => {
|
|
94
|
+
expect(addId("", TIP_ID)).toBe(TIP_ID);
|
|
95
|
+
expect(addId(`x ${TIP_ID}`, TIP_ID)).toBe(`x ${TIP_ID}`);
|
|
96
|
+
expect(addId("x", TIP_ID)).toBe(`x ${TIP_ID}`);
|
|
97
|
+
expect(dropId(`x ${TIP_ID}`, TIP_ID)).toBe("x");
|
|
98
|
+
expect(dropId(null, TIP_ID)).toBe("");
|
|
99
|
+
});
|
|
100
|
+
});
|
|
101
|
+
|
|
102
|
+
describe("the graph's badges (behold#725)", () => {
|
|
103
|
+
it("finds a mark's own <title> and the element whose words a tooltip shows", () => {
|
|
104
|
+
const g = graph();
|
|
105
|
+
expect(ownTitle(g.badge)).toBe(g.badgeTitle);
|
|
106
|
+
expect(tipHost(g.badgeRect)).toBe(g.badge);
|
|
107
|
+
expect(tipHost(g.card.children[1])).toBe(g.card);
|
|
108
|
+
expect(tipHost(g.svg)).toBe(null);
|
|
109
|
+
});
|
|
110
|
+
|
|
111
|
+
it("counts a mark on a card as a badge, and the card, an edge and the drawing as not", () => {
|
|
112
|
+
const g = graph();
|
|
113
|
+
expect(isBadge(g.badge)).toBe(true);
|
|
114
|
+
expect(isBadge(g.card)).toBe(false);
|
|
115
|
+
expect(isBadge(g.edge)).toBe(false);
|
|
116
|
+
expect(isBadge(g.svg)).toBe(false);
|
|
117
|
+
});
|
|
118
|
+
|
|
119
|
+
it("gives each badge with words a tab stop, once", () => {
|
|
120
|
+
const g = graph();
|
|
121
|
+
expect(reachBadges(g.body)).toBe(1);
|
|
122
|
+
expect(g.badge.getAttribute("tabindex")).toBe("0");
|
|
123
|
+
expect(g.card.hasAttribute("tabindex")).toBe(false);
|
|
124
|
+
expect(reachBadges(g.body)).toBe(0);
|
|
125
|
+
});
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
describe("installTooltips (behold#725)", () => {
|
|
129
|
+
it("opens on a resting pointer with the <title>'s words, which leave the <title> while it shows and come back after", () => {
|
|
130
|
+
const g = graph();
|
|
131
|
+
const doc = fakeDoc(g.body);
|
|
132
|
+
const t = timers();
|
|
133
|
+
installTooltips(doc, t);
|
|
134
|
+
doc.fire("pointerover", { target: g.badgeRect });
|
|
135
|
+
// Emptied at once, so the browser's own tooltip has nothing to show.
|
|
136
|
+
expect(g.badgeTitle.textContent).toBe("");
|
|
137
|
+
expect(t.queue[0].ms).toBe(HOVER_MS);
|
|
138
|
+
t.run();
|
|
139
|
+
const tip = doc.getElementById(TIP_ID);
|
|
140
|
+
expect(tip.getAttribute("role")).toBe("tooltip");
|
|
141
|
+
expect(tip.hidden).toBe(false);
|
|
142
|
+
expect(tip.textContent).toContain("wave 2 · waiting");
|
|
143
|
+
expect(g.badge.getAttribute("aria-describedby")).toBe(TIP_ID);
|
|
144
|
+
doc.fire("pointerout", { target: g.badgeRect, relatedTarget: g.svg });
|
|
145
|
+
expect(tip.hidden).toBe(true);
|
|
146
|
+
expect(g.badgeTitle.textContent).toContain("wave 2 · waiting");
|
|
147
|
+
expect(g.badge.hasAttribute("aria-describedby")).toBe(false);
|
|
148
|
+
});
|
|
149
|
+
|
|
150
|
+
it("opens at once on keyboard focus, closes on Escape, and keeps the <title> empty until the focus leaves", () => {
|
|
151
|
+
const g = graph();
|
|
152
|
+
const doc = fakeDoc(g.body);
|
|
153
|
+
const t = timers();
|
|
154
|
+
installTooltips(doc, t);
|
|
155
|
+
doc.fire("focusin", { target: g.badge });
|
|
156
|
+
const tip = doc.getElementById(TIP_ID);
|
|
157
|
+
expect(tip.hidden).toBe(false);
|
|
158
|
+
doc.fire("keydown", { key: "Escape" });
|
|
159
|
+
expect(tip.hidden).toBe(true);
|
|
160
|
+
expect(g.badgeTitle.textContent).toBe("");
|
|
161
|
+
doc.fire("focusout", { target: g.badge });
|
|
162
|
+
expect(g.badgeTitle.textContent).toContain("wave 2 · waiting");
|
|
163
|
+
});
|
|
164
|
+
|
|
165
|
+
it("stays shut on a click's focus", () => {
|
|
166
|
+
const g = graph();
|
|
167
|
+
g.badge.focusVisible = false;
|
|
168
|
+
const doc = fakeDoc(g.body);
|
|
169
|
+
installTooltips(doc, timers());
|
|
170
|
+
doc.fire("focusin", { target: g.badge });
|
|
171
|
+
expect(doc.getElementById(TIP_ID)).toBe(null);
|
|
172
|
+
expect(g.badgeTitle.textContent).toContain("wave 2");
|
|
173
|
+
});
|
|
174
|
+
|
|
175
|
+
it("is placed fixed under its target", () => {
|
|
176
|
+
const g = graph();
|
|
177
|
+
const doc = fakeDoc(g.body);
|
|
178
|
+
installTooltips(doc, timers());
|
|
179
|
+
doc.fire("focusin", { target: g.badge });
|
|
180
|
+
const tip = doc.getElementById(TIP_ID);
|
|
181
|
+
expect(tip.style.top).toBe("128px");
|
|
182
|
+
});
|
|
183
|
+
|
|
184
|
+
it("does nothing in a kiosk frame, which has its own popover", () => {
|
|
185
|
+
const g = graph();
|
|
186
|
+
const doc = fakeDoc(g.body, { bare: true });
|
|
187
|
+
const t = timers();
|
|
188
|
+
installTooltips(doc, t);
|
|
189
|
+
doc.fire("pointerover", { target: g.badgeRect });
|
|
190
|
+
expect(t.queue.length).toBe(0);
|
|
191
|
+
expect(g.badgeTitle.textContent).toContain("wave 2");
|
|
192
|
+
});
|
|
193
|
+
});
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
// The tour player (behold.tour/v1): which chapter of a tour a cycle is in,
|
|
2
|
+
// and which of its visuals are on, from the events that have happened. Pure:
|
|
3
|
+
// the tour and an event stream in, plain data out, so the live carve and a
|
|
4
|
+
// recorded cycle or bundle can feed it the same way.
|
|
5
|
+
//
|
|
6
|
+
// An event is one of:
|
|
7
|
+
// { kind: "beat", beat, step, at } demo.json's beat and step
|
|
8
|
+
// { kind: "line", migration, line, at } a migration's first or last progress line
|
|
9
|
+
// { kind: "wave", wave, edge, at } a wave's job starting or ending
|
|
10
|
+
// `at` is a time in ms. A trigger matches an event of its kind whose fields
|
|
11
|
+
// equal the trigger's; `after_at` (a named run's finish, which the server
|
|
12
|
+
// resolves) keeps out an event at or before it, and `blocked` (the named run
|
|
13
|
+
// does not exist yet) matches nothing.
|
|
14
|
+
//
|
|
15
|
+
// The current chapter is the last chapter, in the file's order, whose trigger
|
|
16
|
+
// has fired by `t`: a cycle's beats only go forward, so a later chapter that
|
|
17
|
+
// fired wins over an earlier one that fired since.
|
|
18
|
+
|
|
19
|
+
const has = (o, k) => o && Object.prototype.hasOwnProperty.call(o, k);
|
|
20
|
+
|
|
21
|
+
/** The first event at or before `t` that `trigger` matches, or null. */
|
|
22
|
+
export function firedBy(trigger, events, t = Infinity) {
|
|
23
|
+
if (!trigger || trigger.blocked) return null;
|
|
24
|
+
if (Array.isArray(trigger.any)) {
|
|
25
|
+
let best = null;
|
|
26
|
+
for (const tr of trigger.any) {
|
|
27
|
+
const e = firedBy(tr, events, t);
|
|
28
|
+
if (e && (!best || e.at < best.at)) best = e;
|
|
29
|
+
}
|
|
30
|
+
return best;
|
|
31
|
+
}
|
|
32
|
+
let best = null;
|
|
33
|
+
for (const e of events || []) {
|
|
34
|
+
if (!(e.at <= t)) continue;
|
|
35
|
+
if (!matches(trigger, e)) continue;
|
|
36
|
+
if (!best || e.at < best.at) best = e;
|
|
37
|
+
}
|
|
38
|
+
return best;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
function matches(tr, e) {
|
|
42
|
+
if (has(tr, "migration")) {
|
|
43
|
+
if (e.kind !== "line" || e.migration !== tr.migration || e.line !== tr.line) return false;
|
|
44
|
+
} else if (has(tr, "wave")) {
|
|
45
|
+
if (e.kind !== "wave" || e.wave !== tr.wave || e.edge !== tr.edge) return false;
|
|
46
|
+
} else {
|
|
47
|
+
if (e.kind !== "beat") return false;
|
|
48
|
+
if (has(tr, "beat") && e.beat !== tr.beat) return false;
|
|
49
|
+
if (has(tr, "step") && e.step !== tr.step) return false;
|
|
50
|
+
}
|
|
51
|
+
if (typeof tr.after_at === "number" && !(e.at > tr.after_at)) return false;
|
|
52
|
+
return true;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* The chapter at `t`: `{ index, chapter, at, progress }`, or null before the
|
|
57
|
+
* first chapter's trigger. `step`: demo.json's step now, for how far a chapter
|
|
58
|
+
* that a beat started has got along the tour's `steps`.
|
|
59
|
+
*/
|
|
60
|
+
export function chapterAt(tour, events, t = Infinity, step = null) {
|
|
61
|
+
const chapters = (tour && tour.chapters) || [];
|
|
62
|
+
for (let i = chapters.length - 1; i >= 0; i--) {
|
|
63
|
+
const e = firedBy(chapters[i].trigger, events, t);
|
|
64
|
+
if (e) return { index: i, chapter: chapters[i], at: e.at, progress: progressOf(tour, i, step) };
|
|
65
|
+
}
|
|
66
|
+
return null;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** How far chapter `i` has got, 0..1: the step's place in the tour's steps; the last chapter is whole once reached. */
|
|
70
|
+
export function progressOf(tour, i, step) {
|
|
71
|
+
const chapters = (tour && tour.chapters) || [];
|
|
72
|
+
if (i >= chapters.length - 1) return 1;
|
|
73
|
+
const steps = (tour && tour.steps) || [];
|
|
74
|
+
const k = step ? steps.indexOf(step) : -1;
|
|
75
|
+
if (k < 0 || steps.length < 2) return 0;
|
|
76
|
+
return k / (steps.length - 1);
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** Each chapter's place on the rail: done, current (with its progress) or ahead. */
|
|
80
|
+
export function railOf(tour, at) {
|
|
81
|
+
return ((tour && tour.chapters) || []).map((c, i) => ({
|
|
82
|
+
n: i + 1,
|
|
83
|
+
id: c.id,
|
|
84
|
+
title: c.title,
|
|
85
|
+
state: !at ? "ahead" : i < at.index ? "done" : i === at.index ? "current" : "ahead",
|
|
86
|
+
progress: !at ? 0 : i < at.index ? 1 : i === at.index ? at.progress : 0,
|
|
87
|
+
}));
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** A chapter's visuals that are on at `t`: those with no `when`, and those whose `when` has fired. Each with `at`, when it fired. */
|
|
91
|
+
export function shownAt(chapter, events, t = Infinity) {
|
|
92
|
+
const out = [];
|
|
93
|
+
for (const s of (chapter && chapter.show) || []) {
|
|
94
|
+
if (!s.when) {
|
|
95
|
+
out.push({ ...s, at: null });
|
|
96
|
+
continue;
|
|
97
|
+
}
|
|
98
|
+
const e = firedBy(s.when, events, t);
|
|
99
|
+
if (e) out.push({ ...s, at: e.at });
|
|
100
|
+
}
|
|
101
|
+
return out;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* A line of text with its facts filled in, or null when a fact it names has
|
|
106
|
+
* no value: a fact with no record behind it is left out, never shown as 0.
|
|
107
|
+
*/
|
|
108
|
+
export function fill(text, facts) {
|
|
109
|
+
if (typeof text !== "string") return null;
|
|
110
|
+
let missing = false;
|
|
111
|
+
const out = text.replace(/\{([A-Za-z][A-Za-z0-9]*)\}/g, (_, k) => {
|
|
112
|
+
const v = facts ? facts[k] : undefined;
|
|
113
|
+
if (v === undefined || v === null || v === "") {
|
|
114
|
+
missing = true;
|
|
115
|
+
return "";
|
|
116
|
+
}
|
|
117
|
+
return typeof v === "number" ? v.toLocaleString("en-US") : String(v);
|
|
118
|
+
});
|
|
119
|
+
return missing ? null : out;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/** A chapter's lines, filled; a line naming a fact with no record is dropped. */
|
|
123
|
+
export function chapterLines(chapter, facts) {
|
|
124
|
+
return ((chapter && chapter.text) || []).map((l) => fill(l, facts)).filter((l) => l !== null);
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** The card's rows, filled; a row with no record is dropped. */
|
|
128
|
+
export function cardRows(card, facts) {
|
|
129
|
+
return (card || []).map((r) => ({ label: r.label, text: fill(r.text, facts) })).filter((r) => r.text !== null);
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
// --- the live badge's lag (faithfulness 3) -----------------------------------
|
|
133
|
+
|
|
134
|
+
/** After this long with no write while a migration runs, the badge says it is waiting for the job. */
|
|
135
|
+
export const LAG_WAIT_MS = 60_000;
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* The words beside LIVE: "last write N s ago", from the newest progress
|
|
139
|
+
* line's `at` and the page's clock; "waiting for the job" once the gap passes
|
|
140
|
+
* a minute while a migration runs; null with no write to measure from.
|
|
141
|
+
*/
|
|
142
|
+
export function lagText(newestAt, now, running) {
|
|
143
|
+
const at = typeof newestAt === "number" ? newestAt : Date.parse(newestAt || "");
|
|
144
|
+
if (!Number.isFinite(at)) return null;
|
|
145
|
+
const gap = Math.max(0, now - at);
|
|
146
|
+
if (running && gap > LAG_WAIT_MS) return "waiting for the job";
|
|
147
|
+
const s = Math.floor(gap / 1000);
|
|
148
|
+
if (s < 60) return `last write ${s} s ago`;
|
|
149
|
+
const m = Math.floor(s / 60);
|
|
150
|
+
if (m < 60) return `last write ${m} min ago`;
|
|
151
|
+
return `last write ${Math.floor(m / 60)} h ago`;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
// --- a landed dot's provenance (faithfulness 2) --------------------------------
|
|
155
|
+
|
|
156
|
+
/** A line's time as a reader reads it: UTC, to the millisecond. */
|
|
157
|
+
export function clockOf(at) {
|
|
158
|
+
const d = new Date(typeof at === "number" ? at : Date.parse(at || ""));
|
|
159
|
+
if (Number.isNaN(d.getTime())) return null;
|
|
160
|
+
return `${d.toISOString().slice(11, 23)} UTC`;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/**
|
|
164
|
+
* What happened to a landed dot, from its progress line and the migration
|
|
165
|
+
* that wrote it: "live-mv retagged aws_iam_role.x from tl1-terralith to
|
|
166
|
+
* tl1-team-a at 16:57:49.668 UTC · job #3655". `w`: { outcome, address, from,
|
|
167
|
+
* to, at, tool, job, reason }.
|
|
168
|
+
*/
|
|
169
|
+
export function provenanceText(w) {
|
|
170
|
+
if (!w || !w.address) return null;
|
|
171
|
+
const when = clockOf(w.at);
|
|
172
|
+
const at = when ? ` at ${when}` : "";
|
|
173
|
+
const job = w.job ? ` · job #${w.job}` : "";
|
|
174
|
+
if (w.outcome === "stamped") return `${w.tool || "live-import"} stamped ${w.address} into ${w.to}${at}${job}`;
|
|
175
|
+
if (w.outcome === "refused") return `${w.tool || "live-mv"} refused to retag ${w.address} from ${w.from} to ${w.to}${w.reason ? `: ${w.reason}` : ""}${at}${job}`;
|
|
176
|
+
return `${w.tool || "live-mv"} retagged ${w.address} from ${w.from} to ${w.to}${at}${job}`;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/** The choudoufu command a migration ran, from its record's `change`: an adoption stamps with live-import, a retag moves with live-mv. */
|
|
180
|
+
export function migrationTool(change) {
|
|
181
|
+
return change === "adopt" ? "live-import" : "live-mv";
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/** The job number in a job's URL (Forgejo/GitHub `/actions/runs/<n>`, GitLab `/-/jobs/<n>`), or null. */
|
|
185
|
+
export function jobNumber(url) {
|
|
186
|
+
const m = typeof url === "string" ? /\/(?:actions\/runs|-\/jobs|jobs)\/(\d+)(?:[/?#]|$)/.exec(url) : null;
|
|
187
|
+
return m ? Number(m[1]) : null;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
// --- slowed playback (faithfulness 1) -------------------------------------------
|
|
191
|
+
|
|
192
|
+
/** The slowed control's choices: off is real time; each other is how far apart one read's lines are drawn. */
|
|
193
|
+
export const SLOWED = [
|
|
194
|
+
{ n: 1, words: "real time", stepMs: 0 },
|
|
195
|
+
{ n: 2, words: "slowed ×2", stepMs: 25 },
|
|
196
|
+
{ n: 4, words: "slowed ×4", stepMs: 50 },
|
|
197
|
+
{ n: 8, words: "slowed ×8", stepMs: 100 },
|
|
198
|
+
];
|
|
199
|
+
|
|
200
|
+
/** The pacing of one read's lines for a slowed factor: 0 (real time) unless a person chose to slow it. */
|
|
201
|
+
export function stepMsFor(n) {
|
|
202
|
+
const s = SLOWED.find((x) => x.n === n);
|
|
203
|
+
return s ? s.stepMs : 0;
|
|
204
|
+
}
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
// The tour player (behold.tour/v1): the chapter a cycle is in from its events,
|
|
2
|
+
// the facts filled into a chapter's lines (a fact with no record is left out),
|
|
3
|
+
// the live badge's lag, and a landed dot's provenance.
|
|
4
|
+
import { describe, it, expect } from "vitest";
|
|
5
|
+
import { readFileSync } from "node:fs";
|
|
6
|
+
import { chapterAt, firedBy, shownAt, railOf, fill, chapterLines, cardRows, lagText, LAG_WAIT_MS, provenanceText, jobNumber, stepMsFor, SLOWED, migrationTool } from "./tour-player.js";
|
|
7
|
+
|
|
8
|
+
const tour = JSON.parse(readFileSync(new URL("./tours/terralith.json", import.meta.url), "utf8"));
|
|
9
|
+
const beat = (b, step = "applying", at = 1_000) => ({ kind: "beat", beat: b, step, at });
|
|
10
|
+
|
|
11
|
+
describe("the chapter from demo.json's beat", () => {
|
|
12
|
+
it("maps each beat to its chapter, in the tour's order", () => {
|
|
13
|
+
const ids = ["stock", "adopt", "split", "team", "cross"].map((b) => chapterAt(tour, [beat(b)]).chapter.id);
|
|
14
|
+
expect(ids).toEqual(["stock", "adopt", "split", "team", "cross"]);
|
|
15
|
+
});
|
|
16
|
+
|
|
17
|
+
it("is the epilogue once the cross beat applied, and through the reset", () => {
|
|
18
|
+
expect(chapterAt(tour, [beat("cross", "applied")]).chapter.id).toBe("epilogue");
|
|
19
|
+
expect(chapterAt(tour, [{ kind: "beat", beat: null, step: "reset", at: 5 }]).chapter.id).toBe("epilogue");
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
it("is no chapter before any trigger fires", () => {
|
|
23
|
+
expect(chapterAt(tour, [])).toBeNull();
|
|
24
|
+
expect(chapterAt(tour, [beat("stock", "applying", 50)], 10)).toBeNull();
|
|
25
|
+
});
|
|
26
|
+
|
|
27
|
+
it("says how far a chapter has got from the step, and the rail marks done, current and ahead", () => {
|
|
28
|
+
const at = chapterAt(tour, [beat("split", "applied")], Infinity, "applied");
|
|
29
|
+
expect(at.progress).toBe(1);
|
|
30
|
+
expect(chapterAt(tour, [beat("split", "planned")], Infinity, "planned").progress).toBeCloseTo(1 / 7);
|
|
31
|
+
expect(railOf(tour, at).map((c) => c.state)).toEqual(["done", "done", "current", "ahead", "ahead", "ahead"]);
|
|
32
|
+
});
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
describe("triggers on lines and waves", () => {
|
|
36
|
+
it("fires on a migration's last line, and on a wave only after the named run's finish", () => {
|
|
37
|
+
const events = [
|
|
38
|
+
{ kind: "line", migration: "split", line: "first", at: 10 },
|
|
39
|
+
{ kind: "wave", wave: 1, edge: "start", at: 20 },
|
|
40
|
+
{ kind: "wave", wave: 1, edge: "start", at: 40 },
|
|
41
|
+
];
|
|
42
|
+
expect(firedBy({ migration: "split", line: "last" }, events)).toBeNull();
|
|
43
|
+
expect(firedBy({ migration: "split", line: "first" }, events).at).toBe(10);
|
|
44
|
+
expect(firedBy({ wave: 1, edge: "start", after_at: 30 }, events).at).toBe(40);
|
|
45
|
+
expect(firedBy({ wave: 1, edge: "start", blocked: true }, events)).toBeNull();
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
it("shows a visual with no `when` at once, and one with a `when` once it fires", () => {
|
|
49
|
+
const ch = { show: [{ kind: "light" }, { kind: "checks", when: { migration: "split", line: "last" } }] };
|
|
50
|
+
expect(shownAt(ch, []).map((s) => s.kind)).toEqual(["light"]);
|
|
51
|
+
expect(shownAt(ch, [{ kind: "line", migration: "split", line: "last", at: 7 }]).map((s) => s.kind)).toEqual(["light", "checks"]);
|
|
52
|
+
});
|
|
53
|
+
});
|
|
54
|
+
|
|
55
|
+
describe("facts in a chapter's lines", () => {
|
|
56
|
+
const team = tour.chapters.find((c) => c.id === "team");
|
|
57
|
+
|
|
58
|
+
it("fills the contrast from both plans' numbers", () => {
|
|
59
|
+
expect(chapterLines(team, { teamPlanned: 3, planned: 82, of: 82 })).toEqual(["Team B changes one policy, and only team B is planned.", "Planned 3 of 82 · chapter 1: 82 of 82"]);
|
|
60
|
+
});
|
|
61
|
+
|
|
62
|
+
it("leaves a line out when a fact it names has no record, never showing 0", () => {
|
|
63
|
+
expect(chapterLines(team, { planned: 82, of: 82 })).toEqual(["Team B changes one policy, and only team B is planned."]);
|
|
64
|
+
expect(fill("{n} moved", {})).toBeNull();
|
|
65
|
+
expect(fill("{n} refused", { n: 0 })).toBe("0 refused");
|
|
66
|
+
});
|
|
67
|
+
|
|
68
|
+
it("drops an epilogue row whose record is missing", () => {
|
|
69
|
+
const rows = cardRows([{ label: "tag writes", text: "{writes}" }, { label: "recreated", text: "{recreated}" }], { writes: 86 });
|
|
70
|
+
expect(rows).toEqual([{ label: "tag writes", text: "86" }]);
|
|
71
|
+
});
|
|
72
|
+
});
|
|
73
|
+
|
|
74
|
+
describe("the live badge's lag", () => {
|
|
75
|
+
const now = Date.parse("2026-10-17T17:00:00Z");
|
|
76
|
+
it("counts from the newest line's time", () => {
|
|
77
|
+
expect(lagText("2026-10-17T16:59:48Z", now, true)).toBe("last write 12 s ago");
|
|
78
|
+
expect(lagText(now - 5 * 60_000, now, false)).toBe("last write 5 min ago");
|
|
79
|
+
});
|
|
80
|
+
it("says it waits for the job once the gap passes a minute while a migration runs", () => {
|
|
81
|
+
expect(lagText(now - LAG_WAIT_MS - 1, now, true)).toBe("waiting for the job");
|
|
82
|
+
expect(lagText(now - LAG_WAIT_MS - 1, now, false)).toBe("last write 1 min ago");
|
|
83
|
+
});
|
|
84
|
+
it("says nothing with no write to count from", () => {
|
|
85
|
+
expect(lagText(null, now, true)).toBeNull();
|
|
86
|
+
});
|
|
87
|
+
});
|
|
88
|
+
|
|
89
|
+
describe("a landed dot's provenance", () => {
|
|
90
|
+
it("names the write, its time and its job", () => {
|
|
91
|
+
expect(provenanceText({ outcome: "moved", tool: "live-mv", address: "aws_iam_role.team_0000_role", from: "tl54-terralith", to: "tl54-team-a", at: "2026-10-17T16:57:49.66896996Z", job: 3655 })).toBe(
|
|
92
|
+
"live-mv retagged aws_iam_role.team_0000_role from tl54-terralith to tl54-team-a at 16:57:49.668 UTC · job #3655",
|
|
93
|
+
);
|
|
94
|
+
});
|
|
95
|
+
it("names a stamp and a refusal in their own words, and leaves out a job no run names", () => {
|
|
96
|
+
expect(provenanceText({ outcome: "stamped", tool: "live-import", address: "aws_ecs_cluster.main", to: "tl54-terralith", at: "2026-10-17T16:54:06.283Z" })).toBe("live-import stamped aws_ecs_cluster.main into tl54-terralith at 16:54:06.283 UTC");
|
|
97
|
+
expect(provenanceText({ outcome: "refused", address: "aws_ecs_service.a", from: "x", to: "y", reason: "marker rewrite", at: "bad" })).toBe("live-mv refused to retag aws_ecs_service.a from x to y: marker rewrite");
|
|
98
|
+
});
|
|
99
|
+
it("reads the job number from a run's URL, and the tool from the record's change", () => {
|
|
100
|
+
expect(jobNumber("http://forgejo:3000/a/b/actions/runs/3655")).toBe(3655);
|
|
101
|
+
expect(jobNumber("https://gitlab.example/a/-/jobs/12")).toBe(12);
|
|
102
|
+
expect(jobNumber(null)).toBeNull();
|
|
103
|
+
expect(migrationTool("adopt")).toBe("live-import");
|
|
104
|
+
expect(migrationTool("retag")).toBe("live-mv");
|
|
105
|
+
});
|
|
106
|
+
});
|
|
107
|
+
|
|
108
|
+
describe("slowed playback", () => {
|
|
109
|
+
it("is real time unless a person picks a slowed factor", () => {
|
|
110
|
+
expect(SLOWED[0]).toEqual({ n: 1, words: "real time", stepMs: 0 });
|
|
111
|
+
expect(stepMsFor(1)).toBe(0);
|
|
112
|
+
expect(stepMsFor(4)).toBe(50);
|
|
113
|
+
expect(SLOWED.slice(1).every((s) => s.words.startsWith("slowed ×"))).toBe(true);
|
|
114
|
+
});
|
|
115
|
+
});
|