@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.
Files changed (61) hide show
  1. package/AGENTS.md +180 -10
  2. package/README.md +6 -2
  3. package/dist/cli.js +16121 -13141
  4. package/example-writes/README.md +1 -1
  5. package/example-writes/chant.config.ts +0 -6
  6. package/package.json +5 -2
  7. package/web/app.js +327 -21
  8. package/web/carve-export.js +142 -0
  9. package/web/carve-narration.js +294 -0
  10. package/web/carve-narration.test.js +48 -0
  11. package/web/change-set-overlay.js +147 -0
  12. package/web/change-set-overlay.test.js +83 -0
  13. package/web/dots-border.js +66 -0
  14. package/web/dots-border.test.js +27 -0
  15. package/web/dots-kiosk.js +279 -0
  16. package/web/dots-kiosk.test.js +60 -0
  17. package/web/dots-layout.d.ts +10 -0
  18. package/web/dots-layout.js +201 -0
  19. package/web/dots-live.js +316 -0
  20. package/web/dots-live.test.js +220 -0
  21. package/web/dots-lod.js +122 -0
  22. package/web/dots-lod.test.js +78 -0
  23. package/web/dots-recording.d.ts +7 -0
  24. package/web/dots-recording.js +247 -0
  25. package/web/dots-recording.test.js +71 -0
  26. package/web/dots-scene.js +294 -0
  27. package/web/dots-scene.test.js +118 -0
  28. package/web/dots-timeline.js +128 -0
  29. package/web/dots-timeline.test.js +83 -0
  30. package/web/dots-tour.js +153 -0
  31. package/web/dots.js +2124 -0
  32. package/web/dots.test.js +15 -0
  33. package/web/event-help-modal.js +1 -1
  34. package/web/index.html +215 -121
  35. package/web/kiosk-carve.js +225 -0
  36. package/web/kiosk-carve.test.js +26 -0
  37. package/web/kiosk-event-help-ui.js +7 -1
  38. package/web/kiosk-link.js +68 -0
  39. package/web/kiosk-link.test.js +69 -0
  40. package/web/kiosk-metrics.js +2 -2
  41. package/web/kiosk-trace.js +1 -1
  42. package/web/kiosk.html +186 -135
  43. package/web/kiosk.js +65 -7
  44. package/web/motion.js +42 -0
  45. package/web/motion.test.js +64 -0
  46. package/web/operator.js +1 -1
  47. package/web/run-playhead.js +102 -19
  48. package/web/run-playhead.test.js +81 -11
  49. package/web/terralith.html +2 -2
  50. package/web/theme.js +99 -26
  51. package/web/theme.test.js +70 -6
  52. package/web/tooltip.js +212 -0
  53. package/web/tooltip.test.js +193 -0
  54. package/web/tour-player.js +204 -0
  55. package/web/tour-player.test.js +115 -0
  56. package/web/tours/behold.tour.v1.schema.json +182 -0
  57. package/web/tours/terralith.json +330 -0
  58. package/web/trunk-lane.js +406 -0
  59. package/web/trunk-lane.test.js +224 -0
  60. package/web/workspace-gates.js +29 -4
  61. package/web/workspace-gates.test.js +23 -2
@@ -0,0 +1,142 @@
1
+ // The static carve export's page (#712): `npm run export:carve` bundles this
2
+ // with the dots layer and the theme into one HTML file, with the card SVG and
3
+ // the recording inlined, so it opens from a web host or straight from disk
4
+ // with no behold server behind it.
5
+ //
6
+ // It replays the recording by itself and loops, holding on the result. The
7
+ // camera follows the flock until a person takes it (pinch, scroll, drag);
8
+ // zooming works as in the app's preview: cards, then dots, then discs.
9
+
10
+ import { initTheme, mountThemePicker, KIOSK_THEME } from "./theme.js";
11
+ import { mountDots, dotsCamera, dotsZoomOutFactor } from "./dots.js";
12
+ import { createNarration } from "./carve-narration.js";
13
+
14
+ async function gunzipBase64(b64) {
15
+ const bytes = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
16
+ const stream = new Blob([bytes]).stream().pipeThrough(new DecompressionStream("gzip"));
17
+ return new Response(stream).text();
18
+ }
19
+
20
+ async function main() {
21
+ initTheme(KIOSK_THEME);
22
+ mountThemePicker(document.getElementById("cx-theme"));
23
+ const data = JSON.parse(document.getElementById("cx-data").textContent);
24
+ const source = data.kind === "carve" ? { kind: "carve", name: data.name, text: await gunzipBase64(data.gz) } : { kind: "walkthrough", name: data.name, model: data.model };
25
+
26
+ const host = document.getElementById("graph");
27
+ const svg = host.querySelector("svg");
28
+ svg.removeAttribute("width");
29
+ svg.removeAttribute("height");
30
+ svg.setAttribute("preserveAspectRatio", "xMidYMid meet");
31
+ const vbInit = svg.getAttribute("viewBox").split(/\s+/).map(Number);
32
+ // The fit: the whole card graph, at the pane's own aspect, so the pane maps to the viewBox at one scale.
33
+ const fitted = () => {
34
+ const r = host.getBoundingClientRect();
35
+ const s = Math.min(r.width / vbInit[2], r.height / vbInit[3]);
36
+ const w = r.width / s;
37
+ const h = r.height / s;
38
+ return [vbInit[0] - (w - vbInit[2]) / 2, vbInit[1] - (h - vbInit[3]) / 2, w, h];
39
+ };
40
+ let vb = fitted();
41
+ const apply = () => {
42
+ svg.setAttribute("viewBox", vb.join(" "));
43
+ dotsCamera();
44
+ };
45
+ apply();
46
+
47
+ // The camera by hand: scroll or pinch zooms at the pointer, a drag pans.
48
+ // The SVG may be out of layout at the dot level; it always fills the host.
49
+ const zoomAt = (cx, cy, f) => {
50
+ const r = host.getBoundingClientRect();
51
+ const px = vb[0] + ((cx - r.left) / r.width) * vb[2];
52
+ const py = vb[1] + ((cy - r.top) / r.height) * vb[3];
53
+ const nw = Math.min(vbInit[2] * (dotsZoomOutFactor() ?? 3), Math.max(vbInit[2] / 60, vb[2] * f));
54
+ const nh = nw * (vb[3] / vb[2]);
55
+ vb = [px - ((px - vb[0]) * nw) / vb[2], py - ((py - vb[1]) * nh) / vb[3], nw, nh];
56
+ apply();
57
+ };
58
+ host.addEventListener(
59
+ "wheel",
60
+ (e) => {
61
+ e.preventDefault();
62
+ zoomAt(e.clientX, e.clientY, Math.exp(e.deltaY * (e.ctrlKey ? 0.01 : 0.0025)));
63
+ },
64
+ { passive: false },
65
+ );
66
+ let drag = null;
67
+ host.addEventListener("mousedown", (e) => {
68
+ if (e.target.closest && e.target.closest("button, select, input")) return;
69
+ drag = { x: e.clientX, y: e.clientY };
70
+ });
71
+ window.addEventListener("mousemove", (e) => {
72
+ if (!drag) return;
73
+ const r = host.getBoundingClientRect();
74
+ vb[0] -= ((e.clientX - drag.x) / r.width) * vb[2];
75
+ vb[1] -= ((e.clientY - drag.y) / r.height) * vb[3];
76
+ drag = { x: e.clientX, y: e.clientY };
77
+ apply();
78
+ });
79
+ window.addEventListener("mouseup", () => (drag = null));
80
+ let touch = null;
81
+ const pts = (e) => [...e.touches].map((t) => ({ x: t.clientX, y: t.clientY }));
82
+ host.addEventListener("touchstart", (e) => (touch = pts(e)), { passive: true });
83
+ host.addEventListener(
84
+ "touchmove",
85
+ (e) => {
86
+ if (!touch) return;
87
+ e.preventDefault();
88
+ const p = pts(e);
89
+ const r = host.getBoundingClientRect();
90
+ if (p.length >= 2 && touch.length >= 2) {
91
+ const d = (q) => Math.hypot(q[0].x - q[1].x, q[0].y - q[1].y) || 1;
92
+ zoomAt((p[0].x + p[1].x) / 2, (p[0].y + p[1].y) / 2, d(touch) / d(p));
93
+ } else if (p.length === 1 && touch.length === 1) {
94
+ vb[0] -= ((p[0].x - touch[0].x) / r.width) * vb[2];
95
+ vb[1] -= ((p[0].y - touch[0].y) / r.height) * vb[3];
96
+ apply();
97
+ }
98
+ touch = p;
99
+ },
100
+ { passive: false },
101
+ );
102
+ host.addEventListener("touchend", (e) => (touch = e.touches.length ? pts(e) : null));
103
+
104
+ const caption = document.getElementById("cx-caption");
105
+ const narration = createNarration({
106
+ bar: document.getElementById("cx-bar"),
107
+ caption,
108
+ tipsHost: document.getElementById("eh-tips"),
109
+ modalHost: document.getElementById("eh-modals"),
110
+ origin: () => host.getBoundingClientRect(),
111
+ });
112
+ await mountDots({
113
+ host,
114
+ svg,
115
+ meta: { dots: { source: data.name } },
116
+ vbInit,
117
+ getVB: () => vb,
118
+ setVB: (a) => {
119
+ vb = a.slice();
120
+ apply();
121
+ },
122
+ source,
123
+ auto: { narrate: (msg) => narration.update(msg), bar: true },
124
+ });
125
+ // The director keeps the boxes clear of the caption over the graph's foot.
126
+ const insets = () => {
127
+ const g = host.getBoundingClientRect();
128
+ const c = caption.getBoundingClientRect();
129
+ const over = c.height && c.top < g.bottom && c.bottom > g.top ? g.bottom - c.top : 0;
130
+ if (window.__dots) window.__dots.setInsets({ top: 0, bottom: Math.max(0, Math.round(over)) });
131
+ };
132
+ insets();
133
+ if (typeof ResizeObserver === "function") new ResizeObserver(insets).observe(caption);
134
+ window.addEventListener("resize", insets);
135
+ }
136
+
137
+ main().catch((err) => {
138
+ const p = document.createElement("p");
139
+ p.className = "cx-error";
140
+ p.textContent = `This page could not start: ${err && err.message ? err.message : err}`;
141
+ document.body.appendChild(p);
142
+ });
@@ -0,0 +1,294 @@
1
+ // The narration around a carve (#712, #715): the header, the Watch-style
2
+ // caption with its next line and progress bar, and the Tips bubbles on the
3
+ // boxes. The static export narrates a recording with it, under a "recorded"
4
+ // badge; the kiosk narrates the live carve with it (web/kiosk-carve.js), under
5
+ // a "live" badge. The dots layer (web/dots.js, in its `auto` mode)
6
+ // replays the recording, directs the camera, and hands this a state twice a
7
+ // second: the beat (web/dots-kiosk.js), the counts, and where each estate's
8
+ // box is on the page. A click on a bubble opens it in Tips' replay modal.
9
+
10
+ import { tipSpot, tipsStyle, TIPS_STYLE_ID } from "./kiosk-event-help-ui.js";
11
+ import { openEventModal } from "./event-help-modal.js";
12
+ import { TIP } from "./dots-kiosk.js";
13
+ import { lagText } from "./tour-player.js";
14
+ import { onLinkChange, pageStaleness } from "./kiosk-link.js";
15
+
16
+ /** behold#725: the stale badge's tooltip. */
17
+ export const STALE_WORDS = "The kiosk is not reading from behold right now, so this may be out of date. It keeps retrying.";
18
+
19
+ const fmt = (n) => Number(n).toLocaleString("en-US");
20
+
21
+ function el(tag, cls, text) {
22
+ const n = document.createElement(tag);
23
+ if (cls) n.className = cls;
24
+ if (text !== undefined && text !== null) n.textContent = text;
25
+ return n;
26
+ }
27
+
28
+ const STOPS = [
29
+ { id: "start", words: "one estate" },
30
+ { id: "carve", words: "carving" },
31
+ { id: "settled", words: "carved" },
32
+ ];
33
+
34
+ /** The badge: "live" over a carve being written (#715), "recorded" over a replay. */
35
+ export function badgeText(state) {
36
+ return state.recording && state.recording.kind === "live" ? "live" : "recorded";
37
+ }
38
+
39
+ /**
40
+ * behold#725: the live badge and its lag while the kiosk's link may be down.
41
+ * Live and reading: "live", the lag counting from now. While the kiosk can't
42
+ * read (`staleness` from web/kiosk-link.js): "stale", and the lag frozen at
43
+ * the last good read, so the screen never says "live" beside "not updating".
44
+ * Anything else: the badge as badgeText has it, and no lag.
45
+ */
46
+ export function liveBadge(state, staleness = { stale: false, since: null }, now = Date.now()) {
47
+ const word = badgeText(state);
48
+ if (word !== "live") return { word, cls: `cx-badge-${word}`, lag: null };
49
+ if (staleness.stale) {
50
+ const at = staleness.since ? staleness.since.getTime() : null;
51
+ return { word: "stale", cls: "cx-badge-stale", lag: at === null ? null : lagText(state.lastWriteAt, at, state.running) };
52
+ }
53
+ return { word, cls: "cx-badge-live", lag: lagText(state.lastWriteAt, now, state.running) };
54
+ }
55
+
56
+ /** The badge's tooltip: what the recording is, or where the live carve is read from. */
57
+ export function recordedWords(state) {
58
+ const r = state.recording || {};
59
+ if (r.kind === "live") {
60
+ const n = r.resources ? `, ${fmt(r.resources)} resources` : "";
61
+ const m = r.migration ? `; migration ${r.migration}` : "";
62
+ return `live carve of ${state.src}${n}, drawn from the estate rosters and the migration's progress as terragucci writes them${r.from ? ` to ${r.from}` : ""}${m}`;
63
+ }
64
+ const what = r.kind === "walkthrough" ? "recorded walkthrough" : "recorded carve";
65
+ const n = r.resources ? `, ${fmt(r.resources)} resources` : "";
66
+ const when = r.recordedAt ? `, recorded ${new Date(r.recordedAt).toISOString().slice(0, 10)}` : "";
67
+ return `${what} of ${state.src}${n}${when}, replayed`;
68
+ }
69
+
70
+ /** First landings that queue up together become one bubble, on the newest box. */
71
+ export function mergeLandings(tips, names = {}) {
72
+ if (tips.length < 2) return tips[0] || null;
73
+ const list = tips.map((x) => names[x.estate] || x.estate);
74
+ const last = tips[tips.length - 1];
75
+ return { ...last, text: `${list.slice(0, -1).join(", ")} and ${list[list.length - 1]}: their first resources land. live-mv rewrote the ownership tags; nothing was recreated.` };
76
+ }
77
+
78
+ /**
79
+ * bar, caption: elements to draw into; tipsHost, modalHost: where bubbles and
80
+ * modals go; origin(): the page offset of the layer the state's box rects are in.
81
+ */
82
+ export function createNarration({ bar, caption, tipsHost, modalHost, origin }) {
83
+ if (!document.getElementById(TIPS_STYLE_ID)) {
84
+ const st = el("style");
85
+ st.id = TIPS_STYLE_ID;
86
+ st.textContent = tipsStyle();
87
+ document.head.appendChild(st);
88
+ }
89
+ const queue = [];
90
+ const shown = new Set();
91
+ let tip = null;
92
+ let lastTipAt = 0;
93
+ let last = null;
94
+
95
+ const anchorOf = (t, state) => {
96
+ const o = origin();
97
+ const r = t.estate && state.rects[t.estate];
98
+ if (r) return { left: o.left + r.left, top: o.top + r.top, width: r.width, height: r.height };
99
+ return { left: o.left + o.width / 2 - 60, top: o.top + o.height * 0.35, width: 120, height: 10 };
100
+ };
101
+ const placeTip = (state) => {
102
+ if (!tip) return;
103
+ const size = { w: tip.node.offsetWidth, h: tip.node.offsetHeight };
104
+ const win = { w: window.innerWidth, h: window.innerHeight };
105
+ let p;
106
+ // The other boxes are what the bubble keeps off: it points at one estate, never sits on another's box or the source's.
107
+ const o = origin();
108
+ const others = Object.entries(state.rects || {})
109
+ .filter(([e]) => e !== tip.t.estate)
110
+ .map(([, r]) => ({ x: o.left + r.left, y: o.top + r.top, w: r.width, h: r.height }));
111
+ try {
112
+ p = tipSpot(anchorOf(tip.t, state), size, win, others);
113
+ } catch {
114
+ // A box off the page has no spot beside it: the bubble goes over the middle.
115
+ p = tipSpot({ left: o.left + o.width / 2 - 60, top: o.top + o.height / 2, width: 120, height: 10 }, size, win);
116
+ }
117
+ tip.node.style.setProperty("--eh-at", `translate(${p.x}px, ${p.y}px)`);
118
+ tip.node.style.transform = `translate(${p.x}px, ${p.y}px)`;
119
+ tip.node.style.setProperty("--eh-arrow", `${p.arrow}px`);
120
+ tip.node.classList.toggle("eh-below", p.below);
121
+ };
122
+ const tickTips = (state) => {
123
+ const now = Date.now();
124
+ if (tip && now - tip.at > TIP.showMs) {
125
+ const n = tip.node;
126
+ n.classList.add("eh-out");
127
+ setTimeout(() => n.remove(), 700);
128
+ tip = null;
129
+ lastTipAt = now;
130
+ }
131
+ // A bubble about something long past, or not yet reached after a seek back, is dropped.
132
+ while (queue.length && (queue[0].at > state.t || state.t - queue[0].at > TIP.staleMs)) queue.shift();
133
+ if (!tip && queue.length && now - lastTipAt > TIP.gapMs && tipsHost) {
134
+ let t = queue.shift();
135
+ if (t.key.startsWith("land:")) {
136
+ const group = [t];
137
+ while (queue.length && queue[0].key.startsWith("land:")) group.push(queue.shift());
138
+ t = mergeLandings(group, state.names);
139
+ }
140
+ const node = el("div", "eh-tip eh-tip-go", t.text);
141
+ node.dataset.ehTone = t.tone;
142
+ node.setAttribute("role", "status");
143
+ node.title = "Open it";
144
+ node.addEventListener("click", () => {
145
+ if (!modalHost) return;
146
+ openEventModal(modalHost, {
147
+ mode: "replay",
148
+ kind: t.tone === "bad" ? "failed" : "applied",
149
+ data: { title: t.title || "The carve", lines: [{ text: t.text, lit: true }, { text: recordedWords(last || state) }], ...(t.recordedAt ? { replayAt: t.recordedAt } : {}) },
150
+ });
151
+ });
152
+ tipsHost.appendChild(node);
153
+ tip = { t, node, at: now };
154
+ }
155
+ placeTip(state);
156
+ };
157
+
158
+ let lastChapter = null;
159
+ const draw = (state) => {
160
+ if (caption && state.tour) return drawTour(state);
161
+ if (caption) caption.classList.remove("cx-tour");
162
+ const b = state.beat;
163
+ if (bar) {
164
+ bar.replaceChildren();
165
+ const place = el("div", "cx-place");
166
+ const rec = el("span", `cx-rec cx-badge-${badgeText(state)}`, badgeText(state));
167
+ rec.title = recordedWords(state);
168
+ place.append(rec, el("span", "cx-src", state.src));
169
+ bar.appendChild(place);
170
+ const strip = el("ol", "cx-strip");
171
+ const at = STOPS.findIndex((s) => s.id === b.phase);
172
+ STOPS.forEach((s, i) => strip.appendChild(el("li", `cx-stop cx-${i < at ? "done" : i === at ? "current" : "ahead"}`, s.words)));
173
+ bar.appendChild(strip);
174
+ }
175
+ if (caption) {
176
+ caption.replaceChildren();
177
+ const top = el("div", "cx-top");
178
+ const h = el("h1", "cx-title");
179
+ const badge = liveBadge(state, pageStaleness());
180
+ const rec = el("span", `cx-rec ${badge.cls}`, badge.word);
181
+ rec.title = badge.word === "stale" ? STALE_WORDS : recordedWords(state);
182
+ h.append(rec);
183
+ const lag = badge.lag;
184
+ if (lag) h.append(el("span", `cx-lag${lag === "waiting for the job" ? " cx-lag-wait" : ""}`, lag));
185
+ h.append(el("span", null, b.title));
186
+ top.appendChild(h);
187
+ const hold = state.holdLeft !== null && state.holdLeft !== undefined;
188
+ const nx = el("p", "cx-next");
189
+ if (!b.next) b.next = { text: "", fraction: 0 };
190
+ nx.append(el("span", null, hold ? `starting again in ${state.holdLeft} s` : b.next.text));
191
+ const nbar = el("span", `cx-nbar cx-tone-${hold ? "idle" : b.phase === "settled" ? "ok" : "busy"}`);
192
+ const fill = el("span", "cx-nbar-in");
193
+ fill.style.width = `${Math.round((hold ? 1 - state.holdLeft / 10 : b.next.fraction) * 1000) / 10}%`;
194
+ nbar.appendChild(fill);
195
+ nx.appendChild(nbar);
196
+ top.appendChild(nx);
197
+ caption.appendChild(top);
198
+ const line = el("p", `cx-row cx-tone-${b.line.tone}`);
199
+ line.append(el("span", "cx-label", b.line.label), el("span", "cx-text cx-lead", b.line.text));
200
+ caption.appendChild(line);
201
+ const tot = state.totals;
202
+ const tally = el("p", "cx-row cx-tone-idle");
203
+ const estatesN = Object.values(state.counts).filter((n) => n > 0).length;
204
+ const estatesW = `${estatesN} estate${estatesN === 1 ? "" : "s"}`;
205
+ const tallyText =
206
+ state.recording && state.recording.kind === "live" && tot.moved !== undefined
207
+ ? `${fmt(tot.moved)} moved · ${fmt(tot.stamped)} stamped · ${tot.refused} refused${tot.skipped ? ` · ${tot.skipped} skipped` : ""} · ${estatesW}`
208
+ : `${fmt(tot.done)} of ${fmt(tot.moves)} flown · ${tot.refused} refused · ${estatesW}`;
209
+ tally.append(el("span", "cx-label", "moves"), el("span", "cx-text", tallyText));
210
+ caption.appendChild(tally);
211
+ }
212
+ };
213
+
214
+ /** The tour's caption: the live badge and its lag, the chapter rail, the chapter's card, what each visual stands on, the links. */
215
+ const drawTour = (state) => {
216
+ const tr = state.tour;
217
+ caption.replaceChildren();
218
+ caption.classList.add("cx-tour");
219
+ const top = el("div", "cx-top cx-tour-top");
220
+ const badge = liveBadge({ ...state, recording: { ...(state.recording || {}), kind: "live" } }, pageStaleness());
221
+ const rec = el("span", `cx-rec ${badge.cls}`, badge.word);
222
+ rec.title = badge.word === "stale" ? STALE_WORDS : recordedWords(state);
223
+ top.appendChild(rec);
224
+ const lag = badge.lag;
225
+ if (lag) top.appendChild(el("span", `cx-lag${lag === "waiting for the job" ? " cx-lag-wait" : ""}`, lag));
226
+ const rail = el("ol", "cx-rail");
227
+ rail.setAttribute("aria-label", `${tr.title || "The tour"}: chapter ${tr.n} of ${tr.of}`);
228
+ for (const c of tr.rail) {
229
+ const li = el("li", `cx-ch cx-ch-${c.state}`);
230
+ li.title = `${c.n}. ${c.title}`;
231
+ li.appendChild(el("span", "cx-ch-n", String(c.n)));
232
+ if (c.state === "current") li.appendChild(el("span", "cx-ch-name", c.title));
233
+ const bar = el("i", "cx-ch-bar");
234
+ bar.style.setProperty("--p", String(c.progress));
235
+ li.appendChild(bar);
236
+ if (c.state === "current") li.setAttribute("aria-current", "step");
237
+ rail.appendChild(li);
238
+ }
239
+ top.appendChild(rail);
240
+ const links = el("p", "cx-follow");
241
+ const l = tr.links || {};
242
+ if (l.pull || l.job) {
243
+ links.appendChild(el("span", "cx-follow-label", "follow along"));
244
+ if (l.pull) links.appendChild(Object.assign(el("a", null, `pull request #${l.pull.n}`), { href: l.pull.url, target: "_blank", rel: "noopener" }));
245
+ if (l.job) links.appendChild(Object.assign(el("a", null, `job #${l.job.n}`), { href: l.job.url, target: "_blank", rel: "noopener" }));
246
+ top.appendChild(links);
247
+ }
248
+ caption.appendChild(top);
249
+ // The chapter's card, docked in the caption: it slides in when the chapter changes.
250
+ const card = el("div", `cx-card${lastChapter !== tr.id ? " cx-enter" : ""}`);
251
+ lastChapter = tr.id;
252
+ const h = el("h1", "cx-title cx-card-title");
253
+ h.append(el("span", "cx-ch-kicker", `${tr.n} of ${tr.of}`), el("span", null, tr.heading));
254
+ card.appendChild(h);
255
+ for (const line of tr.lines) card.appendChild(el("p", "cx-card-line", line));
256
+ caption.appendChild(card);
257
+ if (tr.card && tr.card.length) {
258
+ const grid = el("dl", "cx-numbers");
259
+ for (const r of tr.card) {
260
+ const d = el("div", "cx-num");
261
+ d.append(el("dt", null, r.label), el("dd", null, r.text));
262
+ grid.appendChild(d);
263
+ }
264
+ caption.appendChild(grid);
265
+ }
266
+ if (tr.notes.length) {
267
+ const notes = el("p", "cx-notes");
268
+ notes.textContent = tr.notes.join(" · ");
269
+ caption.appendChild(notes);
270
+ }
271
+ };
272
+
273
+ // behold#725: the badge follows the kiosk's link at once, not at the next state from the frame.
274
+ onLinkChange(() => { if (last) draw(last); });
275
+
276
+ return {
277
+ update(state) {
278
+ if (state.type !== "behold:dots-state") {
279
+ if (state.type === "behold:dots-ready") shown.clear();
280
+ return;
281
+ }
282
+ // A new loop shows its Tips again.
283
+ if (last && state.t < last.t) shown.clear();
284
+ for (const t of state.tips || []) {
285
+ if (shown.has(t.key)) continue;
286
+ shown.add(t.key);
287
+ queue.push(t);
288
+ }
289
+ last = state;
290
+ draw(state);
291
+ tickTips(state);
292
+ },
293
+ };
294
+ }
@@ -0,0 +1,48 @@
1
+ import { describe, it, expect } from "vitest";
2
+ import { recordedWords, mergeLandings, liveBadge } from "./carve-narration.js";
3
+
4
+ describe("the carve export's narration (#712)", () => {
5
+ it("says what the recording is", () => {
6
+ expect(recordedWords({ src: "behold-terralith-14", recording: { kind: "carve", resources: 1041, recordedAt: Date.parse("2026-09-22T16:37:26Z") } })).toBe(
7
+ "recorded carve of behold-terralith-14, 1,041 resources, recorded 2026-09-22, replayed",
8
+ );
9
+ expect(recordedWords({ src: "terralith", recording: { kind: "walkthrough" } })).toBe("recorded walkthrough of terralith, replayed");
10
+ });
11
+ it("puts first landings that queue together in one bubble, on the newest box", () => {
12
+ const t = (e, at) => ({ key: `land:${e}`, estate: e, at, text: e });
13
+ expect(mergeLandings([t("a", 1)])).toEqual(t("a", 1));
14
+ const m = mergeLandings([t("x-a", 1), t("x-b", 2), t("x-c", 3)], { "x-a": "a", "x-b": "b", "x-c": "c" });
15
+ expect(m.estate).toBe("x-c");
16
+ expect(m.text).toMatch(/^a, b and c: their first resources land/);
17
+ });
18
+ });
19
+
20
+ // behold#725: the live badge never says "live" beside the kiosk's "not updating" cue.
21
+ describe("the live badge while the kiosk can't read (behold#725)", () => {
22
+ const live = { recording: { kind: "live" }, lastWriteAt: "2026-10-17T12:00:00.000Z", running: false };
23
+ const t = (iso) => new Date(iso).getTime();
24
+
25
+ it("says live, with the lag counting from now, while reads come back", () => {
26
+ const b = liveBadge(live, { stale: false, since: null }, t("2026-10-17T12:00:30.000Z"));
27
+ expect(b).toEqual({ word: "live", cls: "cx-badge-live", lag: "last write 30 s ago" });
28
+ });
29
+
30
+ it("says stale while the cue is up, its lag frozen at the last good read", () => {
31
+ const since = new Date("2026-10-17T12:00:12.000Z");
32
+ const b = liveBadge(live, { stale: true, since }, t("2026-10-17T12:05:00.000Z"));
33
+ expect(b.word).toBe("stale");
34
+ expect(b.cls).toBe("cx-badge-stale");
35
+ expect(b.lag).toBe("last write 12 s ago");
36
+ // Later still, the same words: frozen, not counting.
37
+ expect(liveBadge(live, { stale: true, since }, t("2026-10-17T12:09:00.000Z")).lag).toBe("last write 12 s ago");
38
+ });
39
+
40
+ it("drops the lag when nothing was ever read, and goes back to live on recovery", () => {
41
+ expect(liveBadge(live, { stale: true, since: null }).lag).toBe(null);
42
+ expect(liveBadge(live, { stale: false, since: null }, t("2026-10-17T12:00:05.000Z")).word).toBe("live");
43
+ });
44
+
45
+ it("leaves a recording's badge alone", () => {
46
+ expect(liveBadge({ recording: { kind: "carve" } }, { stale: true, since: null })).toEqual({ word: "recorded", cls: "cx-badge-recorded", lag: null });
47
+ });
48
+ });
@@ -0,0 +1,147 @@
1
+ // #681: a waiting gate's change set, drawn on the graph as a preview. Pure
2
+ // words and colours from /api/workspace/change-set; app.js draws them.
3
+ //
4
+ // The colours are the graph's own (the drift legend's tokens): a card the
5
+ // change set creates is outlined in the managed green, one it updates or
6
+ // replaces in the foreign yellow, one it deletes or forgets in the degraded
7
+ // red. A card with entries of several kinds takes the one that destroys most.
8
+ // The outline and a tag above the card are the marks; the fill stays the
9
+ // live-status channel, so a preview never reads as what is live.
10
+
11
+ /** The legend's buckets, in order, with the token each is drawn in. */
12
+ export const BUCKETS = [
13
+ { bucket: "create", color: "var(--managed)", label: "create", title: "The change set creates these." },
14
+ { bucket: "change", color: "var(--foreign)", label: "update or replace", title: "The change set updates these in place, or replaces them (a new object for the old one)." },
15
+ { bucket: "delete", color: "var(--degraded)", label: "delete or forget", title: "The change set deletes these, or forgets them (chant stops managing the object and leaves it standing)." },
16
+ ];
17
+ const COLOR = Object.fromEntries(BUCKETS.map((b) => [b.bucket, b.color]));
18
+
19
+ /** The colour a bucket is drawn in. */
20
+ export const bucketColor = (bucket) => COLOR[bucket] || "var(--muted)";
21
+
22
+ const short = (s) => (s ? String(s).replace(/^(jcs1-)?sha256:/, "").slice(0, 12) : "");
23
+ const sha7 = (s) => (s ? String(s).slice(0, 7) : "");
24
+ const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
25
+
26
+ /** The note under the overlay's legend: it is a preview. */
27
+ export const PREVIEW_NOTE = "A preview of what approving this gate lets chant apply. Nothing on the graph has changed yet.";
28
+
29
+ /** The overlay's first lines: the change set, the gate and commit it belongs to, or why it wasn't read. */
30
+ export function overlayHeader(a) {
31
+ if (!a || a.error) return { lines: [`change set not read${a && a.error ? `: ${a.error}` : ""}`], tone: "refusal", title: "" };
32
+ if (a.refusal) return { lines: [`change set not read: ${a.refusal.error}`], tone: "refusal", title: a.refusal.remedy || "" };
33
+ const g = a.gate;
34
+ const lines = [`change set ${short(a.digest)} · gate ${g.key}${g.env ? ` in ${g.env}` : ""}`];
35
+ const facts = [];
36
+ const commit = g.gitSha || (a.graph && a.graph.at);
37
+ facts.push(commit ? `commit ${sha7(commit)}` : "commit unknown");
38
+ if (g.runId) facts.push(`run ${g.runId}`);
39
+ if (a.planned) facts.push(`release ${short(a.planned.releaseDigest)} planned for ${a.planned.environment}`);
40
+ lines.push(facts.join(" · "));
41
+ const title = [
42
+ `change set ${a.digest}`,
43
+ commit ? `commit ${commit}${g.gitSha ? "" : " (the commit chant read the graph at)"}` : "",
44
+ a.planned ? `release ${a.planned.releaseDigest}` : "",
45
+ a.graph ? `nodes from the graph of ${a.graph.member || "the project"}${a.graph.at ? ` at ${sha7(a.graph.at)}` : ""}` : "chant read no graph, so no entry has a node",
46
+ g.approve,
47
+ ]
48
+ .filter(Boolean)
49
+ .join("\n");
50
+ return { lines, tone: "quiet", title };
51
+ }
52
+
53
+ /** The legend: one row per bucket with its colour and how many entries it holds, and the entries that change nothing. */
54
+ export function overlayLegend(a) {
55
+ if (!a || a.error || a.refusal) return [];
56
+ const rows = BUCKETS.map((b) => ({ bucket: b.bucket, color: b.color, label: b.label, count: (a.counts && a.counts[b.bucket]) || 0, title: b.title }));
57
+ if (a.unchanged) rows.push({ bucket: "unchanged", color: "var(--muted)", label: "no change (not drawn)", count: a.unchanged, title: "Entries the plan reads or leaves as they are." });
58
+ return rows;
59
+ }
60
+
61
+ /** The tag above a card: its actions in words, "update", "2 create, delete". */
62
+ export function actionWords(actions) {
63
+ const order = ["create", "update", "replace", "delete", "forget"];
64
+ return order.filter((k) => actions && actions[k]).map((k) => (actions[k] === 1 ? k : `${actions[k]} ${k}`)).join(", ");
65
+ }
66
+
67
+ /** The marks to draw: per node id, its colour, its tag and its tooltip. */
68
+ export function nodeMarks(a) {
69
+ const out = {};
70
+ if (!a || a.error || a.refusal || !a.nodes) return out;
71
+ for (const [id, n] of Object.entries(a.nodes)) {
72
+ const entries = a.entries.filter((e) => e.node === id);
73
+ out[id] = {
74
+ bucket: n.bucket,
75
+ color: bucketColor(n.bucket),
76
+ tag: actionWords(n.actions),
77
+ title: [`change set ${short(a.digest)} (preview, not applied):`, ...entries.map((e) => `${e.action} ${e.address}`)].join("\n"),
78
+ };
79
+ }
80
+ return out;
81
+ }
82
+
83
+ const MAX_VALUE = 80;
84
+ /** One value as JSON, cut to a line. */
85
+ export function valueWords(v) {
86
+ let s;
87
+ try {
88
+ s = JSON.stringify(v);
89
+ } catch {
90
+ s = String(v);
91
+ }
92
+ if (s === undefined) s = String(v);
93
+ return s.length > MAX_VALUE ? `${s.slice(0, MAX_VALUE - 3)}...` : s;
94
+ }
95
+
96
+ /** One attribute in words: "Versioning: before {...}, after {...}". */
97
+ export function attributeWords(t) {
98
+ let what;
99
+ if (t.sensitive) what = "sensitive, not shown";
100
+ else {
101
+ const parts = [];
102
+ if ("before" in t) parts.push(`before ${valueWords(t.before)}`);
103
+ if (t.unknown) parts.push("after: known after apply");
104
+ else if ("after" in t) parts.push(`after ${valueWords(t.after)}`);
105
+ what = parts.join(", ") || "changes";
106
+ }
107
+ return `${t.path}: ${what}${t.forcesReplacement ? " (forces replacement)" : ""}`;
108
+ }
109
+
110
+ /** One entry as lines: its action and address, then its type, disruption and fields where present. */
111
+ export function entryLines(e) {
112
+ const facts = [e.type, e.disruption ? `disruption ${e.disruption}` : "", e.deposed ? `deposed ${e.deposed}` : ""].filter(Boolean).join(" · ");
113
+ return { head: `${e.action} ${e.address}`, bucket: e.bucket, color: bucketColor(e.bucket), facts, fields: (e.attributes || []).map(attributeWords) };
114
+ }
115
+
116
+ /** The entries on one card, for the inspect pane. */
117
+ export function entriesFor(a, id) {
118
+ if (!a || a.error || a.refusal || !a.entries) return [];
119
+ return a.entries.filter((e) => e.node === id).map(entryLines);
120
+ }
121
+
122
+ /**
123
+ * The entries a reader would not see on the graph: those chant mapped to no
124
+ * node, and those whose node this view does not draw (another lens, or a
125
+ * member not on screen). `drawn` is the set of node ids on the canvas.
126
+ */
127
+ export function offGraph(a, drawn) {
128
+ if (!a || a.error || a.refusal || !a.entries) return { noNode: [], notDrawn: [] };
129
+ return {
130
+ noNode: a.entries.filter((e) => !e.node).map(entryLines),
131
+ notDrawn: a.entries.filter((e) => e.node && drawn && !drawn.has(e.node)).map((e) => ({ ...entryLines(e), node: e.node })),
132
+ };
133
+ }
134
+
135
+ /** What the change set leaves out: members that failed to plan, and holes. */
136
+ export function gapLines(a) {
137
+ if (!a || a.error || a.refusal || !a.gaps) return [];
138
+ return a.gaps.map((m) => {
139
+ if (m.status !== "planned") return { text: `${m.member} did not plan${m.error ? `: ${m.error}` : ""}, so its changes are not drawn`, title: "" };
140
+ return { text: `${m.member}: ${plural(m.holes.length, "address", "addresses")} the plan could not read`, title: m.holes.map((h) => `${h.address}: ${h.reason}`).join("\n") };
141
+ });
142
+ }
143
+
144
+ /** The heading over a card's entries in the inspect pane. */
145
+ export function inspectHeading(a) {
146
+ return `change set ${short(a.digest)} (preview, not applied)`;
147
+ }