@intentius/behold 0.29.39 → 0.29.41

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 (49) hide show
  1. package/AGENTS.md +148 -10
  2. package/README.md +6 -2
  3. package/dist/cli.js +15965 -13076
  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 +268 -0
  10. package/web/carve-narration.test.js +18 -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/index.html +29 -0
  34. package/web/kiosk-carve.js +219 -0
  35. package/web/kiosk-carve.test.js +26 -0
  36. package/web/kiosk-event-help-ui.js +6 -0
  37. package/web/kiosk.html +2 -1
  38. package/web/kiosk.js +21 -6
  39. package/web/operator.js +1 -1
  40. package/web/run-playhead.js +102 -19
  41. package/web/run-playhead.test.js +81 -11
  42. package/web/tour-player.js +204 -0
  43. package/web/tour-player.test.js +115 -0
  44. package/web/tours/behold.tour.v1.schema.json +182 -0
  45. package/web/tours/terralith.json +330 -0
  46. package/web/trunk-lane.js +254 -0
  47. package/web/trunk-lane.test.js +117 -0
  48. package/web/workspace-gates.js +29 -4
  49. package/web/workspace-gates.test.js +23 -2
@@ -0,0 +1,294 @@
1
+ // The dots layer's scene (#712, #715): where every dot and every estate box is at
2
+ // any moment of a replay, and the choreography of the carve.
3
+ //
4
+ // Each estate has its own box at the dot level. A dot's slot is its unit's
5
+ // place inside its estate's box (web/dots-layout.js), so a carved dot leaves
6
+ // the terralith's box and lands in its estate's. The boxes have stable slots:
7
+ // the source estate keeps the place its cards had on the page, and the new
8
+ // estates sit in a grid beside it in name order, each cell sized for what the
9
+ // estate holds at the end of the recording. A reset or a replay lays out the
10
+ // same way.
11
+ //
12
+ // The choreography: a carve recording plays on its own clock (#711): each move
13
+ // flies when the recording says it was written, and an idle stretch plays as a
14
+ // break the timeline names (web/dots-timeline.js). A show without its own
15
+ // clock (the walkthrough) is flown by unit, the order #457 recommends, so one
16
+ // team's cluster lifts off together as a flock; what moves, where to, and
17
+ // whether it landed are its records', and the order and timing the replay's. Pure: show in, plain data out. Units are in
18
+ // pitches (one dot spacing); the page scales them into the viewBox.
19
+
20
+ import { unitsOf, unitOf, packBlock, blockWidth, shelfPack } from "./dots-layout.js";
21
+
22
+ export const CHOREO = { duration: 90_000, flight: 1_300, stagger: 28, lead: 2_500, tail: 3_000 };
23
+ export const BOX = { pad: 1.5, title: 3, gap: 5 };
24
+
25
+ /** A show's own time -> replay ms, linear over [t0, t1]. */
26
+ export function replayClock(show, duration = CHOREO.duration) {
27
+ // #715: a live carve's clock is the show's own, one to one; its length grows as the page runs.
28
+ if (show.kind === "live") return { length: Math.max(1, show.t1 - show.t0), at: (t) => t - show.t0, live: true };
29
+ // A recording of a real event stream plays on its own clock: wall-clock time, with its idle stretches drawn as breaks (web/dots-timeline.js).
30
+ if (show.timeline) return { length: show.timeline.length, at: (t) => show.timeline.toReplay(t), real: (p) => show.timeline.toReal(p), recorded: true };
31
+ const span = Math.max(1, show.t1 - show.t0);
32
+ return { length: duration, at: (t) => ((t - show.t0) / span) * duration };
33
+ }
34
+
35
+ /**
36
+ * The flights: one per landed or refused move, plus one per follower and per
37
+ * untaggable child that moves with its parent. Sorted by start.
38
+ * Each is { address, from, to, ok, refusal?, start, end, flock, parent? }.
39
+ */
40
+ export function choreograph(show, opts = {}) {
41
+ const o = { ...CHOREO, ...opts };
42
+ const clock = replayClock(show, o.duration);
43
+ const writes = show.events.filter((e) => e.kind === "write");
44
+ if (!writes.length) return [];
45
+ // The window the flights fill: the whole replay for a carve recording, the
46
+ // split phase's stretch of it for the walkthrough.
47
+ let a = o.lead;
48
+ let b = o.duration - o.tail - o.flight;
49
+ if (show.kind !== "carve") {
50
+ a = clock.at(Math.min(...writes.map((e) => e.start)));
51
+ b = Math.max(a + o.flight, clock.at(Math.max(...writes.map((e) => e.t))) - o.flight);
52
+ }
53
+ // Children that move with a parent but that no follower record names.
54
+ const kidsOf = new Map();
55
+ for (const [child, parent] of show.parents ?? []) {
56
+ if (!kidsOf.has(parent)) kidsOf.set(parent, []);
57
+ kidsOf.get(parent).push(child);
58
+ }
59
+ // #715: a live carve flies each write when it was seen, in the show's own
60
+ // time (its clock is one to one), never regrouped: the order and the timing
61
+ // are the job's.
62
+ // A recording with its own clock flies each write when the recording says it was written, the same way.
63
+ if (show.kind === "live" || show.timeline) {
64
+ const out = [];
65
+ for (const w of writes) {
66
+ const start = show.kind === "live" ? w.start - show.t0 : Math.max(0, clock.at(w.t) - o.flight);
67
+ const base = { from: w.from, to: w.to, ok: w.ok, flock: 0, start, end: start + o.flight, at: w.at ?? w.t };
68
+ out.push({ ...base, address: w.address, ...(w.refusal ? { refusal: w.refusal } : {}), ...(w.refusalSummary ? { refusalSummary: w.refusalSummary } : {}) });
69
+ const followers = new Set(w.followers ?? []);
70
+ if (w.ok) for (const c of kidsOf.get(w.address) ?? []) followers.add(c);
71
+ [...followers].forEach((f, m) => {
72
+ const s = start + (m % 3) * 8;
73
+ out.push({ ...base, start: s, end: s + o.flight, address: f, parent: w.address });
74
+ });
75
+ }
76
+ // A resource may move twice (adopted into one estate, then split into another); the same write read twice flies once.
77
+ // A recording's follower named by two moves goes with the first, as the flocks do.
78
+ const seen = new Set();
79
+ const keyOf = (f) => (show.kind === "live" ? `${f.address}@${f.start}` : f.address);
80
+ return out.sort((x, y) => x.start - y.start).filter((f) => !seen.has(keyOf(f)) && seen.add(keyOf(f)));
81
+ }
82
+ const typeOf = new Map(show.roster.map((r) => [r.address, r.type]));
83
+ const order = new Map(show.roster.map((r, i) => [r.address, i]));
84
+ const unitKey = (addr) => unitOf(addr, typeOf.get(addr));
85
+ const flocks = new Map();
86
+ for (const w of writes) {
87
+ const k = unitKey(w.address);
88
+ if (!flocks.has(k)) flocks.set(k, []);
89
+ flocks.get(k).push(w);
90
+ }
91
+ const keys = [...flocks.keys()].sort();
92
+ // Children that move with a parent but that no follower record names.
93
+ const kids = new Map();
94
+ for (const [child, parent] of show.parents ?? []) {
95
+ if (!kids.has(parent)) kids.set(parent, []);
96
+ kids.get(parent).push(child);
97
+ }
98
+ const flights = [];
99
+ // Each unit lifts off as one flock: its dots a short stagger apart, the
100
+ // flocks evenly spaced, so one team's cluster leaves together.
101
+ const gap = (b - a) / Math.max(1, keys.length);
102
+ keys.forEach((k, fi) => {
103
+ const ws = flocks.get(k).sort((x, y) => (order.get(x.address) ?? 0) - (order.get(y.address) ?? 0));
104
+ const t = a + gap * fi;
105
+ ws.forEach((w, j) => {
106
+ const start = t + j * o.stagger;
107
+ // `at`: when the recording says the move happened, for a viewer who asks.
108
+ const base = { from: w.from, to: w.to, ok: w.ok, flock: fi, start, end: start + o.flight, at: w.t };
109
+ flights.push({ ...base, address: w.address, ...(w.refusal ? { refusal: w.refusal } : {}), ...(w.refusalSummary ? { refusalSummary: w.refusalSummary } : {}) });
110
+ const followers = new Set(w.followers ?? []);
111
+ if (w.ok) for (const c of kids.get(w.address) ?? []) followers.add(c);
112
+ [...followers].forEach((f, m) => {
113
+ const s = start + (m % 3) * 8;
114
+ flights.push({ ...base, start: s, end: s + o.flight, address: f, parent: w.address });
115
+ });
116
+ });
117
+ });
118
+ // A resource flies once: a follower named by two moves goes with the first.
119
+ const seen = new Set();
120
+ const once = flights.sort((x, y) => x.start - y.start).filter((f) => !seen.has(f.address) && seen.add(f.address));
121
+ return once;
122
+ }
123
+
124
+ /**
125
+ * The scene: the flights, and the layout after every takeoff, in pitches.
126
+ * `layoutAt(k)` is the layout once the first k landing flights have taken off
127
+ * (a dot in flight already holds its slot in the box it is flying to).
128
+ */
129
+ export function buildScene(show, opts = {}) {
130
+ const o = { ...opts };
131
+ const flights = choreograph(show, opts);
132
+ const landing = flights.filter((f) => f.ok);
133
+ landing.forEach((f, i) => (f.k = i + 1));
134
+ const source = show.source;
135
+ const rosterBy = new Map(show.roster.map((r) => [r.address, r]));
136
+ const end = show.ownersEnd;
137
+ const estates = [...new Set([source, ...show.estates, ...end.values()])];
138
+ const membersOf = (owners, e) => show.roster.filter((r) => owners.get(r.address) === e);
139
+ // Fixed widths: the source's from its first members, each estate's from its last.
140
+ const width = new Map();
141
+ const finalSize = new Map();
142
+ for (const e of estates) {
143
+ const first = e === source ? membersOf(show.owners0, e) : membersOf(end, e);
144
+ if (!first.length && e !== source) continue;
145
+ const us = unitsOf(first);
146
+ // The source's box takes its cards' shape on the page, so a card's dot has a short way to go.
147
+ width.set(e, blockWidth(us, e === source && o.sourceAspect ? o.sourceAspect : 1.3));
148
+ const p = packBlock(us, { width: width.get(e), fromEnd: e === source });
149
+ finalSize.set(e, { w: p.w + 2 * BOX.pad, h: p.h + 2 * BOX.pad + BOX.title });
150
+ }
151
+ const src = finalSize.get(source) ?? { w: 10, h: 10 };
152
+ const dests = estates.filter((e) => e !== source && finalSize.has(e)).sort();
153
+ const area = dests.reduce((s, e) => s + finalSize.get(e).w * finalSize.get(e).h, 0);
154
+ // A box's label sits over its outline and may be wider than the box: each cell leaves room for it, so two labels
155
+ // never touch. `labelPx(e)` is the label's width on screen and `avail` the screen area the boxes are framed in; the
156
+ // pitch on screen follows from the extent, so it is found in a few passes.
157
+ const labelRoom = (ppp) => (e) => (o.labelPx && ppp ? o.labelPx(e) / ppp + 1 : 0);
158
+ const pack = (ppp) => {
159
+ const room = labelRoom(ppp);
160
+ const ws = dests.map((e) => Math.max(finalSize.get(e).w, room(e)));
161
+ const gridW = Math.max(Math.sqrt(area) * 1.25, ...ws);
162
+ // A row's labels sit in the gap above it.
163
+ const gap = Math.max(BOX.gap, o.labelPx && ppp ? (o.labelH ?? 18) / ppp + 1 : 0);
164
+ const cells = shelfPack(
165
+ dests.map((e, i) => ({ key: e, w: ws[i], h: finalSize.get(e).h })),
166
+ { width: gridW, gap },
167
+ );
168
+ let h = src.h;
169
+ for (const e of dests) h = Math.max(h, cells.get(e).y + finalSize.get(e).h);
170
+ return { gridW, cells, w: src.w + BOX.gap * 3 + gridW, h };
171
+ };
172
+ let packed = pack(null);
173
+ if (o.labelPx && o.avail && o.avail.w > 0 && o.avail.h > 0) {
174
+ for (let i = 0; i < 3; i++) {
175
+ // The director's widest shot frames the whole extent, with its padding: the smallest pitch a label must fit.
176
+ const ppp = Math.min(o.avail.w / (packed.w + 7), o.avail.h / (packed.h + 7));
177
+ packed = pack(ppp);
178
+ }
179
+ }
180
+ const { gridW, cells } = packed;
181
+ const destX = src.w + BOX.gap * 3;
182
+ const origin = new Map([[source, { x: 0, y: 0 }]]);
183
+ for (const e of dests) origin.set(e, { x: destX + cells.get(e).x, y: cells.get(e).y });
184
+ let extentW = destX + gridW;
185
+ let extentH = src.h;
186
+ for (const e of dests) extentH = Math.max(extentH, cells.get(e).y + finalSize.get(e).h);
187
+ if (!dests.length) extentW = src.w;
188
+
189
+ const cache = new Map();
190
+ const layoutAt = (k) => {
191
+ const kk = Math.max(0, Math.min(k, landing.length));
192
+ if (cache.has(kk)) return cache.get(kk);
193
+ const owners = new Map(show.owners0);
194
+ for (let i = 0; i < kk; i++) owners.set(landing[i].address, landing[i].to);
195
+ const slots = new Map();
196
+ const boxes = new Map();
197
+ for (const e of estates) {
198
+ if (!width.has(e)) continue;
199
+ const ms = show.roster.filter((r) => owners.get(r.address) === e);
200
+ if (!ms.length && e !== source) continue;
201
+ const fromEnd = e === source;
202
+ const p = packBlock(unitsOf(ms), { width: width.get(e), fromEnd });
203
+ const o = origin.get(e);
204
+ let bx;
205
+ let by;
206
+ if (fromEnd) {
207
+ // Bottom edge fixed: the source loses its top rows as units leave.
208
+ bx = o.x;
209
+ by = o.y + src.h - (p.h + 2 * BOX.pad + BOX.title);
210
+ } else {
211
+ bx = o.x;
212
+ by = o.y;
213
+ }
214
+ const ix = bx + BOX.pad;
215
+ const iy = by + BOX.pad + BOX.title + (fromEnd ? p.h : 0);
216
+ for (const [addr, s] of p.slots) slots.set(addr, { x: ix + s.x, y: iy + s.y, ...(s.parent ? { parent: s.parent } : {}) });
217
+ // The source's box narrows to the dots it still holds once its last row is partial.
218
+ let x0 = bx;
219
+ let w = Math.max(p.w, ms.length ? 0 : 4) + 2 * BOX.pad;
220
+ if (fromEnd && ms.length) {
221
+ let lo = Infinity;
222
+ for (const [, sl] of p.slots) lo = Math.min(lo, sl.x);
223
+ const cellHalf = 1.5;
224
+ const left = Math.max(0, Math.min(p.w, lo - cellHalf));
225
+ x0 = bx + left;
226
+ w = p.w - left + 2 * BOX.pad;
227
+ }
228
+ boxes.set(e, { x: x0, y: by, w, h: p.h + 2 * BOX.pad + BOX.title, members: ms.length });
229
+ }
230
+ const out = { k: kk, slots, boxes, owners };
231
+ if (cache.size > 2000) cache.clear();
232
+ cache.set(kk, out);
233
+ return out;
234
+ };
235
+ return { show, flights, landing, estates, source, layoutAt, extent: { w: extentW, h: extentH }, sourceBox: src, finalSize, rosterBy };
236
+ }
237
+
238
+ /** How many landing flights have taken off by replay time `t` (binary search). */
239
+ export function takeoffsBy(scene, t) {
240
+ const l = scene.landing;
241
+ let lo = 0;
242
+ let hi = l.length;
243
+ while (lo < hi) {
244
+ const mid = (lo + hi) >> 1;
245
+ if (l[mid].start <= t) lo = mid + 1;
246
+ else hi = mid;
247
+ }
248
+ return lo;
249
+ }
250
+
251
+ /** Each estate's resource count at `t`: a dot counts where it is until it lands. */
252
+ export function countsAt(scene, t) {
253
+ const c = new Map();
254
+ for (const [, e] of scene.show.owners0) c.set(e, (c.get(e) ?? 0) + 1);
255
+ for (const f of scene.landing) {
256
+ if (f.end > t) continue;
257
+ c.set(f.from, (c.get(f.from) ?? 0) - 1);
258
+ c.set(f.to, (c.get(f.to) ?? 0) + 1);
259
+ }
260
+ return c;
261
+ }
262
+
263
+ /** The first landing in each estate (when its box draws in). */
264
+ export function firstLandings(scene) {
265
+ const out = new Map();
266
+ for (const f of scene.landing) if (!out.has(f.to) || f.end < out.get(f.to)) out.set(f.to, f.end);
267
+ return out;
268
+ }
269
+
270
+ /** Ease in and out. */
271
+ export function easeInOut(t) {
272
+ const x = Math.max(0, Math.min(1, t));
273
+ return x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2;
274
+ }
275
+
276
+ /**
277
+ * A point on a flight at progress u in [0, 1]: a gentle arc from a to b,
278
+ * bowed to the left of travel by `bow` of the distance. A refused flight goes
279
+ * out `reach` of the way and comes back to a.
280
+ */
281
+ export function flightPoint(a, b, u, { ok = true, bow = 0.18, reach = 0.32 } = {}) {
282
+ const e = easeInOut(u);
283
+ let p = e;
284
+ let tx = b.x;
285
+ let ty = b.y;
286
+ if (!ok) {
287
+ // Out and back: progress rises to `reach` at mid-flight and returns to 0.
288
+ p = Math.sin(Math.PI * e) * reach;
289
+ }
290
+ const dx = tx - a.x;
291
+ const dy = ty - a.y;
292
+ const lift = (ok ? Math.sin(Math.PI * e) : Math.sin(Math.PI * e) * reach) * bow;
293
+ return { x: a.x + dx * p - dy * lift, y: a.y + dy * p + dx * lift };
294
+ }
@@ -0,0 +1,118 @@
1
+ import { describe, it, expect } from "vitest";
2
+ import { readFileSync } from "node:fs";
3
+ import { gunzipSync } from "node:zlib";
4
+ import { fileURLToPath } from "node:url";
5
+ import { readCarve, carveShow } from "./dots-recording.js";
6
+ import { parentsOf, unitsOf, unitOf, packBlock, ringsOf } from "./dots-layout.js";
7
+ import { choreograph, buildScene, takeoffsBy, countsAt, flightPoint, CHOREO } from "./dots-scene.js";
8
+
9
+ const text = gunzipSync(readFileSync(fileURLToPath(new URL("../scripts/dot-bench/carve-terralith-14.jsonl.gz", import.meta.url)))).toString("utf8");
10
+ const rec = readCarve(text);
11
+ const show = carveShow(rec, parentsOf(rec.roster));
12
+
13
+ describe("the dots layout (#712)", () => {
14
+ it("groups a unit by module, block stem and count index", () => {
15
+ expect(unitOf("aws_iam_role.team_0003_role", "aws_iam_role")).toBe(unitOf("aws_iam_instance_profile.team_0003_profile", "aws_iam_instance_profile"));
16
+ expect(unitOf("aws_cloudwatch_log_group.team_a_0")).toBe(unitOf("aws_cloudwatch_log_group.team_a_2"));
17
+ expect(unitOf("aws_ecs_service.svc_0001")).not.toBe(unitOf("aws_ecs_service.svc_0002"));
18
+ expect(unitOf('aws_route53_record.records["www"]', "aws_route53_record")).toBe("|dns");
19
+ });
20
+ it("packs a large ring into concentric rings", () => {
21
+ const rs = ringsOf(141);
22
+ expect(rs.reduce((s, r) => s + r.n, 0)).toBe(141);
23
+ expect(rs.length).toBeGreaterThan(3);
24
+ });
25
+ it("keeps every slot when units leave from the front of a box packed from the end", () => {
26
+ const us = unitsOf(rec.roster);
27
+ const width = 60;
28
+ const all = packBlock(us, { width, fromEnd: true });
29
+ const rest = packBlock(us.slice(5), { width, fromEnd: true });
30
+ for (const [a, s] of rest.slots) expect(all.slots.get(a)).toEqual(s);
31
+ });
32
+ });
33
+
34
+ describe("the carve choreography (#712)", () => {
35
+ const flights = choreograph(show);
36
+ it("flies every resource that changes estate exactly once, and lands it where the recording ends", () => {
37
+ const seen = new Set(flights.map((f) => f.address));
38
+ expect(seen.size).toBe(flights.length);
39
+ const owners = new Map(show.owners0);
40
+ for (const f of flights) if (f.ok) owners.set(f.address, f.to);
41
+ for (const r of rec.roster) expect(owners.get(r.address)).toBe(show.ownersEnd.get(r.address));
42
+ expect(flights.filter((f) => !f.ok && !f.parent)).toHaveLength(14);
43
+ });
44
+ it("flies each move when the recording says it was written, on the recording's own clock", () => {
45
+ const clock = show.timeline;
46
+ const byAddr = new Map(show.events.map((e) => [e.address, e]));
47
+ for (const f of flights.filter((x) => !x.parent)) {
48
+ const w = byAddr.get(f.address);
49
+ expect(f.start).toBeCloseTo(Math.max(0, clock.toReplay(w.t) - CHOREO.flight), 6);
50
+ }
51
+ expect(Math.min(...flights.map((f) => f.start))).toBeGreaterThanOrEqual(0);
52
+ expect(Math.max(...flights.map((f) => f.start))).toBeLessThanOrEqual(clock.length);
53
+ });
54
+ it("carries a child with its parent", () => {
55
+ const child = flights.find((f) => f.parent);
56
+ const parent = flights.find((f) => f.address === child.parent);
57
+ expect(child.to).toBe(parent.to);
58
+ expect(child.start - parent.start).toBeLessThan(60);
59
+ });
60
+ });
61
+
62
+ describe("the scene (#712)", () => {
63
+ const scene = buildScene(show, { sourceAspect: 2.5 });
64
+ it("is the same every time it is built", () => {
65
+ const again = buildScene(show, { sourceAspect: 2.5 });
66
+ const a = scene.layoutAt(200);
67
+ const b = again.layoutAt(200);
68
+ expect([...a.slots]).toEqual([...b.slots]);
69
+ });
70
+ it("puts every dot inside its estate's box, at the start and at the end", () => {
71
+ for (const k of [0, scene.landing.length]) {
72
+ const L = scene.layoutAt(k);
73
+ for (const [addr, s] of L.slots) {
74
+ const b = L.boxes.get(L.owners.get(addr));
75
+ expect(s.x).toBeGreaterThanOrEqual(b.x - 1e-9);
76
+ expect(s.x).toBeLessThanOrEqual(b.x + b.w + 1e-9);
77
+ expect(s.y).toBeGreaterThanOrEqual(b.y - 1e-9);
78
+ expect(s.y).toBeLessThanOrEqual(b.y + b.h + 1e-9);
79
+ }
80
+ }
81
+ expect(scene.layoutAt(0).boxes.size).toBe(1);
82
+ expect(scene.layoutAt(scene.landing.length).boxes.size).toBe(9);
83
+ });
84
+ it("never overlaps two estates' final boxes", () => {
85
+ const bs = [...scene.layoutAt(scene.landing.length).boxes.values()];
86
+ for (let i = 0; i < bs.length; i++)
87
+ for (let j = i + 1; j < bs.length; j++) {
88
+ const a = bs[i];
89
+ const b = bs[j];
90
+ expect(a.x + a.w <= b.x || b.x + b.w <= a.x || a.y + a.h <= b.y || b.y + b.h <= a.y).toBe(true);
91
+ }
92
+ });
93
+ it("counts a dot where it is until it lands", () => {
94
+ const f = scene.landing[10];
95
+ const before = countsAt(scene, f.end - 1);
96
+ const after = countsAt(scene, f.end);
97
+ expect(after.get(f.to) - (before.get(f.to) ?? 0)).toBeGreaterThanOrEqual(1);
98
+ expect(takeoffsBy(scene, f.start)).toBeGreaterThanOrEqual(f.k);
99
+ });
100
+ });
101
+
102
+ describe("a flight's path (#712)", () => {
103
+ const a = { x: 0, y: 0 };
104
+ const b = { x: 100, y: 0 };
105
+ it("leaves its old slot, arcs, and lands in its new one", () => {
106
+ expect(flightPoint(a, b, 0)).toEqual({ x: 0, y: 0 });
107
+ const end = flightPoint(a, b, 1);
108
+ expect(end.x).toBeCloseTo(100, 9);
109
+ expect(end.y).toBeCloseTo(0, 9);
110
+ expect(Math.abs(flightPoint(a, b, 0.5).y)).toBeGreaterThan(5);
111
+ });
112
+ it("comes back to its slot when the move was refused", () => {
113
+ const back = flightPoint(a, b, 1, { ok: false });
114
+ expect(back.x).toBeCloseTo(0, 9);
115
+ expect(back.y).toBeCloseTo(0, 9);
116
+ expect(flightPoint(a, b, 0.5, { ok: false }).x).toBeGreaterThan(10);
117
+ });
118
+ });
@@ -0,0 +1,128 @@
1
+ // The timeline of a recorded replay: a recording of a real event stream,
2
+ // played on the recording's own clock. Pure: the recording's times in, the
3
+ // mapping between replay time and wall-clock time, the ticks, the marks and
4
+ // the label out.
5
+ //
6
+ // Replay time is wall-clock time, one to one, except across an idle stretch
7
+ // longer than `maxGap`: that stretch plays as `keep` ms, and the timeline
8
+ // draws a break there with the real gap's length ("+48 s skipped"). Nothing is
9
+ // compressed without a break to say so. The ticks are the recording's
10
+ // wall-clock times, and every mark is a line of the recording (its file and
11
+ // line, and its time).
12
+
13
+ export const GAPS = { maxGap: 10_000, keep: 2_000 };
14
+
15
+ /**
16
+ * The replay's clock over a recording whose events happened at `times` (ms),
17
+ * from `t0` to `t1`: { length, toReplay(real), toReal(p), breaks, t0, t1 }.
18
+ * Each break is { p, real0, real1, skipped } in replay ms and wall-clock ms.
19
+ */
20
+ export function recordedClock(times, t0, t1, { maxGap = GAPS.maxGap, keep = GAPS.keep } = {}) {
21
+ const ts = [...new Set([t0, ...times.filter((x) => Number.isFinite(x) && x >= t0 && x <= t1), t1])].sort((a, b) => a - b);
22
+ const segs = []; // { r0, r1, p0 }: wall-clock [r0, r1] plays from replay p0, one to one
23
+ const breaks = [];
24
+ let p = 0;
25
+ let r0 = ts[0];
26
+ for (let i = 1; i < ts.length; i++) {
27
+ const a = ts[i - 1];
28
+ const b = ts[i];
29
+ if (b - a > maxGap) {
30
+ // Play up to a, then the gap as `keep` ms, the first half before the break and the second after.
31
+ segs.push({ r0, r1: a + keep / 2, p0: p });
32
+ p += a + keep / 2 - r0;
33
+ breaks.push({ p, real0: a + keep / 2, real1: b - keep / 2, skipped: b - a - keep });
34
+ r0 = b - keep / 2;
35
+ }
36
+ }
37
+ segs.push({ r0, r1: ts[ts.length - 1], p0: p });
38
+ p += ts[ts.length - 1] - r0;
39
+ const length = Math.max(1, p);
40
+ const toReplay = (real) => {
41
+ if (real <= segs[0].r0) return 0;
42
+ for (const s of segs) {
43
+ if (real <= s.r1) return real < s.r0 ? s.p0 : s.p0 + (real - s.r0);
44
+ }
45
+ return length;
46
+ };
47
+ const toReal = (q) => {
48
+ let s = segs[0];
49
+ for (const x of segs) if (x.p0 <= q) s = x;
50
+ return Math.min(s.r1, s.r0 + Math.max(0, q - s.p0));
51
+ };
52
+ return { length, toReplay, toReal, breaks, segs, t0: ts[0], t1: ts[ts.length - 1] };
53
+ }
54
+
55
+ const pad = (n) => String(n).padStart(2, "0");
56
+ /** A wall-clock time as the timeline shows it, in UTC: "16:37" or, with seconds, "16:37:26". */
57
+ export function clockWords(ms, seconds = false) {
58
+ const d = new Date(ms);
59
+ return `${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}${seconds ? `:${pad(d.getUTCSeconds())}` : ""}`;
60
+ }
61
+
62
+ const STEPS = [1, 2, 5, 10, 15, 30, 60, 120, 300, 600, 900, 1800, 3600].map((s) => s * 1000);
63
+
64
+ /** The wall-clock ticks: round times inside the played stretches, about `want` of them, each { p, real, label }. */
65
+ export function wallTicks(clock, want = 7) {
66
+ const played = clock.segs.reduce((s, x) => s + (x.r1 - x.r0), 0);
67
+ const step = STEPS.find((s) => played / s <= want) ?? STEPS[STEPS.length - 1];
68
+ const out = [];
69
+ for (const s of clock.segs) {
70
+ for (let r = Math.ceil(s.r0 / step) * step; r <= s.r1; r += step) out.push({ p: s.p0 + (r - s.r0), real: r, label: clockWords(r, step < 60_000) });
71
+ }
72
+ return out;
73
+ }
74
+
75
+ const DAY = new Intl.DateTimeFormat("en-GB", { day: "numeric", month: "short", year: "numeric", timeZone: "UTC" });
76
+
77
+ /**
78
+ * The timeline's label: "Recorded 22 Sep 2026, 16:37:26–17:13:00 UTC from
79
+ * behold-terralith-14 · plan domains", from the recording's own header and
80
+ * times. A source the records do not name is left out. `short`: the phone's
81
+ * "Recorded 16:37–17:13 UTC".
82
+ */
83
+ export function recordedLabel({ t0, t1, source = null, plan = null }, { short = false } = {}) {
84
+ if (short) return `Recorded ${clockWords(t0)}–${clockWords(t1)} UTC`;
85
+ const from = [source, plan ? `plan ${plan}` : null].filter(Boolean).join(" · ");
86
+ return `Recorded ${DAY.format(new Date(t0))}, ${clockWords(t0, true)}–${clockWords(t1, true)} UTC${from ? ` from ${from}` : ""}`;
87
+ }
88
+
89
+ /** The speed control's words, always its state: "1x real time", "slowed ×10", "sped up ×4". */
90
+ export function speedWords(speed) {
91
+ if (speed === 1) return "1x real time";
92
+ if (speed < 1) return `slowed ×${Math.round(1 / speed)}`;
93
+ return `sped up ×${speed}`;
94
+ }
95
+
96
+ /** The speeds a recorded replay offers, real time first. */
97
+ export const RECORDED_SPEEDS = [1, 4, 16, 0.5, 0.1];
98
+
99
+ /** A gap's length in words: "+48 s skipped", "+2 min 5 s skipped". */
100
+ export function skippedWords(ms) {
101
+ const s = Math.round(ms / 1000);
102
+ return s < 60 ? `+${s} s skipped` : `+${Math.floor(s / 60)} min${s % 60 ? ` ${s % 60} s` : ""} skipped`;
103
+ }
104
+
105
+ /**
106
+ * The marks on the timeline, each a line of the recording: the first and
107
+ * last move, each keyframe (an estate listing), and the end. Each is
108
+ * { p, real, kind, words, record } where `record` names the file, line and time.
109
+ */
110
+ export function recordedMarks(show, clock, file = "the recording") {
111
+ const r = show && show.records;
112
+ if (!r) return [];
113
+ const out = [];
114
+ const add = (real, kind, words, line) => {
115
+ if (!Number.isFinite(real)) return;
116
+ out.push({ p: clock.toReplay(real), real, kind, words, record: `${file}${line ? ` line ${line}` : ""} · ${new Date(real).toISOString()}` });
117
+ };
118
+ const moves = show.events.filter((e) => e.kind === "write");
119
+ if (moves.length) {
120
+ const first = moves.reduce((a, e) => (e.t < a.t ? e : a));
121
+ const last = moves.reduce((a, e) => (e.t > a.t ? e : a));
122
+ add(first.t, "first", `first move: ${first.address}`, first.line);
123
+ add(last.t, "last", `last move: ${last.address}`, last.line);
124
+ }
125
+ for (const k of r.keyframes || []) add(k.t, "keyframe", "keyframe: each estate listed (live-ls)", k.line);
126
+ if (r.end) add(r.end.t, "end", "the recording's end", r.end.line);
127
+ return out.sort((a, b) => a.p - b.p);
128
+ }
@@ -0,0 +1,83 @@
1
+ // A recorded replay's timeline: wall-clock time one to one, an idle stretch
2
+ // played as a break that says how long it really was, ticks at the
3
+ // recording's own times, marks that name their line, and a label and a speed
4
+ // that always say this is a recording.
5
+ import { describe, it, expect } from "vitest";
6
+ import { readFileSync } from "node:fs";
7
+ import { gunzipSync } from "node:zlib";
8
+ import { fileURLToPath } from "node:url";
9
+ import { recordedClock, wallTicks, recordedLabel, speedWords, skippedWords, recordedMarks, clockWords, GAPS, RECORDED_SPEEDS } from "./dots-timeline.js";
10
+ import { readCarve, carveShow } from "./dots-recording.js";
11
+ import { parentsOf } from "./dots-layout.js";
12
+ import { replayClock } from "./dots-scene.js";
13
+
14
+ const T = Date.parse("2026-09-22T16:38:15Z");
15
+
16
+ describe("the recorded clock", () => {
17
+ it("plays wall-clock time one to one", () => {
18
+ const c = recordedClock([T + 1_000, T + 4_000], T, T + 6_000);
19
+ expect(c.length).toBe(6_000);
20
+ expect(c.toReplay(T + 4_000)).toBe(4_000);
21
+ expect(c.toReal(2_500)).toBe(T + 2_500);
22
+ expect(c.breaks).toEqual([]);
23
+ });
24
+
25
+ it("plays an idle stretch as a break that keeps the real gap's length", () => {
26
+ const c = recordedClock([T + 1_000, T + 61_000], T, T + 62_000);
27
+ expect(c.breaks).toHaveLength(1);
28
+ expect(c.breaks[0].skipped).toBe(60_000 - GAPS.keep);
29
+ expect(c.length).toBe(62_000 - c.breaks[0].skipped);
30
+ // Before the gap and after it, one to one.
31
+ expect(c.toReplay(T + 61_000) - c.toReplay(T + 61_000 - 500)).toBe(500);
32
+ expect(c.toReal(c.toReplay(T + 61_500))).toBe(T + 61_500);
33
+ expect(skippedWords(c.breaks[0].skipped)).toBe("+58 s skipped");
34
+ expect(skippedWords(125_000)).toBe("+2 min 5 s skipped");
35
+ });
36
+
37
+ it("ticks at the recording's own wall-clock times, never 0:00", () => {
38
+ // A write every 5 s for ten minutes: no stretch is idle, so none is skipped.
39
+ const c = recordedClock(Array.from({ length: 120 }, (_, i) => T + i * 5_000), T, T + 10 * 60_000);
40
+ expect(c.breaks).toEqual([]);
41
+ const ticks = wallTicks(c, 6);
42
+ expect(ticks.length).toBeGreaterThan(2);
43
+ expect(ticks[0].label).toMatch(/^16:\d\d$/);
44
+ for (const t of ticks) expect(clockWords(t.real)).toBe(t.label);
45
+ });
46
+ });
47
+
48
+ describe("what the timeline says", () => {
49
+ it("says it is a recording, when and from what, and shortens on a phone", () => {
50
+ const facts = { t0: T, t1: T + 34 * 60_000 + 44_000, source: "behold-terralith-14", plan: "domains" };
51
+ expect(recordedLabel(facts)).toMatch(/^Recorded 22 Sept? 2026, 16:38:15–17:12:59 UTC from behold-terralith-14 · plan domains$/);
52
+ expect(recordedLabel({ t0: T, t1: T + 60_000 })).not.toMatch(/from/);
53
+ expect(recordedLabel(facts, { short: true })).toBe("Recorded 16:38–17:12 UTC");
54
+ });
55
+
56
+ it("always says the speed in words", () => {
57
+ expect(speedWords(1)).toBe("1x real time");
58
+ expect(speedWords(0.1)).toBe("slowed ×10");
59
+ expect(speedWords(4)).toBe("sped up ×4");
60
+ expect(RECORDED_SPEEDS[0]).toBe(1);
61
+ });
62
+ });
63
+
64
+ describe("the committed recording on its own clock", () => {
65
+ const text = gunzipSync(readFileSync(fileURLToPath(new URL("../scripts/dot-bench/carve-terralith-14.jsonl.gz", import.meta.url)))).toString("utf8");
66
+ const rec = readCarve(text);
67
+ const show = carveShow(rec, parentsOf(rec.roster));
68
+
69
+ it("replays on the recording's clock, with a break for each listing pause", () => {
70
+ const clock = replayClock(show);
71
+ expect(clock.recorded).toBe(true);
72
+ expect(clock.length).toBe(show.timeline.length);
73
+ expect(show.timeline.breaks.length).toBeGreaterThan(0);
74
+ for (const b of show.timeline.breaks) expect(b.skipped).toBeGreaterThan(0);
75
+ });
76
+
77
+ it("marks the first and last move and each keyframe, each naming its line and time", () => {
78
+ const marks = recordedMarks(show, show.timeline, "carve-terralith-14.jsonl");
79
+ expect(marks.find((m) => m.kind === "first").record).toMatch(/^carve-terralith-14\.jsonl line \d+ · 2026-09-22T/);
80
+ expect(marks.filter((m) => m.kind === "keyframe")).toHaveLength(rec.keyframes.length);
81
+ for (const m of marks) expect(m.p).toBeGreaterThanOrEqual(0);
82
+ });
83
+ });