@celestia-island/hikari 0.55.263 → 0.55.265

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,537 @@
1
+ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
2
+ import { createApp, defineComponent, h, nextTick, ref, type App } from "vue";
3
+
4
+ import {
5
+ enterDelayMs,
6
+ RAIL_FLIGHT_MS,
7
+ RAIL_FLIGHT_SWEEP_MS,
8
+ RAIL_FLIP_ACTIVE_ATTR,
9
+ RAIL_FLIP_FLYING_ATTR,
10
+ RAIL_FLIP_ICON_ATTR,
11
+ RAIL_FLIP_ITEM_ATTR,
12
+ } from "./useRailIconFlight";
13
+ import { __teardownMediaQueries } from "../runtime/useMediaQuery";
14
+ import HkSidebarRailSwap from "../components/HkSidebarRailSwap";
15
+
16
+ /**
17
+ * useRailIconFlight — the rail flip's icon continuity layer (2026-11-02).
18
+ *
19
+ * The tests mount the REAL HkSidebarRailSwap with keyed icon cells in the
20
+ * slot and drive a genuine density flip. What is stubbed is only what
21
+ * happy-dom cannot do: layout (getBoundingClientRect), WAAPI (a
22
+ * recording stub whose listeners the tests can fire) and — implicitly —
23
+ * zoom (no ancestor zoom in happy-dom, so drawnScale is 1 and the
24
+ * written offsets equal the measured deltas). Timing is fake-timer
25
+ * driven, and that is load-bearing twice over:
26
+ *
27
+ * - the choreographer's arm macrotask (setTimeout 0) fires on
28
+ * `advanceTimersByTimeAsync(0)` — while happy-dom's rAF-driven
29
+ * dissolve (a ~16ms timer) has NOT run yet, so both generations are
30
+ * still mounted exactly as in a real browser mid-CSS-dissolve;
31
+ * - advancing past the sweep budget exercises the cleanup path.
32
+ *
33
+ * The assertions pin the choreography DECISIONS:
34
+ * 1. A flip with moving keyed icons arms the flight: `data-flipping` on
35
+ * the swap host, a flight layer on the ENTERING item with one clone
36
+ * per PAIRED key, each clone painted at the leaving rect (logical
37
+ * insets relative to the stage) and animated by the signed delta.
38
+ * 2. The pairing contract is visible: matched leaving cells carry the
39
+ * `data-flip-flying` mark (they are substituted), UNMATCHED opted-in
40
+ * cells are never marked (they dissolve — a rail fallback with no
41
+ * expanded counterpart must not vanish un-substituted).
42
+ * 3. The guards: no movement → no flight; a missing WAAPI, reduced
43
+ * motion, or a dissolved-away leaving generation → no flight.
44
+ * 4. The lifecycle: the WAAPI `finish` sweeps the layer; the sweep timer
45
+ * backstops it; a fresh flip replaces (never stacks) the previous
46
+ * flight; unmount cleans up.
47
+ */
48
+
49
+ const mounts: App[] = [];
50
+ const containers: HTMLElement[] = [];
51
+
52
+ interface RecordedAnimation {
53
+ el: HTMLElement;
54
+ keyframes: Keyframe[];
55
+ options: KeyframeAnimationOptions;
56
+ fire(type: "finish" | "cancel"): void;
57
+ }
58
+ let animations: RecordedAnimation[] = [];
59
+
60
+ function rect(x: number, y: number, width = 16, height = 16): DOMRect {
61
+ return {
62
+ x,
63
+ y,
64
+ width,
65
+ height,
66
+ top: y,
67
+ left: x,
68
+ right: x + width,
69
+ bottom: y + height,
70
+ toJSON: () => ({}),
71
+ } as DOMRect;
72
+ }
73
+
74
+ /** Stub layout for one element. */
75
+ function stubRect(el: Element, r: DOMRect): void {
76
+ vi.spyOn(el, "getBoundingClientRect").mockReturnValue(r);
77
+ }
78
+
79
+ interface Harness {
80
+ container: HTMLElement;
81
+ swap(): HTMLElement;
82
+ generations(): HTMLElement[];
83
+ set(rail: boolean): Promise<void>;
84
+ }
85
+
86
+ function mountSwap(): Harness {
87
+ const container = document.createElement("div");
88
+ document.body.appendChild(container);
89
+ containers.push(container);
90
+ const rail = ref(false);
91
+ const Wrapper = defineComponent({
92
+ name: "FlightHarness",
93
+ setup() {
94
+ return () =>
95
+ h(
96
+ HkSidebarRailSwap,
97
+ { rail: rail.value, railWidth: "56px", expandedWidth: "240px" },
98
+ {
99
+ default: (p: { rail: boolean }) =>
100
+ h("div", { class: "rows" }, [
101
+ h("span", { class: "hk-menu-item-icon", [RAIL_FLIP_ICON_ATTR]: "home" }, "H"),
102
+ h("span", { class: "hk-menu-item-icon", [RAIL_FLIP_ICON_ATTR]: "inbox" }, "I"),
103
+ // The rail-only fallback cell: an opted-in row with NO
104
+ // expanded counterpart (the icon-less leaf's rail form).
105
+ p.rail
106
+ ? h(
107
+ "span",
108
+ { class: "hk-menu-item-icon", [RAIL_FLIP_ICON_ATTR]: "rail-only" },
109
+ "R",
110
+ )
111
+ : null,
112
+ // …and its full-only twin: a cell that exists ONLY in the
113
+ // expanded generation (a rich expanded row's icon).
114
+ p.rail
115
+ ? null
116
+ : h(
117
+ "span",
118
+ { class: "hk-menu-item-icon", [RAIL_FLIP_ICON_ATTR]: "full-only" },
119
+ "F",
120
+ ),
121
+ ]),
122
+ },
123
+ );
124
+ },
125
+ });
126
+ const app = createApp(Wrapper);
127
+ mounts.push(app);
128
+ app.mount(container);
129
+ return {
130
+ container,
131
+ swap: () => container.querySelector(".hk-sidebar-rail-swap") as HTMLElement,
132
+ generations: () =>
133
+ Array.from(container.querySelectorAll<HTMLElement>(".hk-sidebar-rail-generation")),
134
+ set: async (v: boolean) => {
135
+ rail.value = v;
136
+ await nextTick();
137
+ },
138
+ };
139
+ }
140
+
141
+ /** Split the mid-swap items by HkCrossfade's semantic key — the same
142
+ * anchor the choreographer itself pairs through. */
143
+ function dissolvePair(
144
+ h: Harness,
145
+ enteringRail: boolean,
146
+ ): { leaving: HTMLElement; entering: HTMLElement } {
147
+ const enteringKey = enteringRail ? "rail" : "full";
148
+ const items = Array.from(h.swap().querySelectorAll<HTMLElement>(":scope > .hk-crossfade-item"));
149
+ const entering = items.find((el) => el.getAttribute(RAIL_FLIP_ITEM_ATTR) === enteringKey);
150
+ const leaving = items.find((el) => el.getAttribute(RAIL_FLIP_ITEM_ATTR) !== enteringKey);
151
+ expect(entering, "the entering generation is mounted").toBeTruthy();
152
+ expect(leaving, "the leaving generation is still mounted").toBeTruthy();
153
+ return { leaving: leaving!, entering: entering! };
154
+ }
155
+
156
+ /** Stub the geometry of every keyed icon in a generation. */
157
+ function stubIcons(root: HTMLElement, fn: (key: string) => DOMRect): void {
158
+ for (const icon of root.querySelectorAll<HTMLElement>(`[${RAIL_FLIP_ICON_ATTR}]`)) {
159
+ stubRect(icon, fn(icon.getAttribute(RAIL_FLIP_ICON_ATTR)!));
160
+ }
161
+ }
162
+
163
+ const flightLayer = (h: Harness): HTMLElement | null =>
164
+ h.swap().querySelector<HTMLElement>(".hk-sidebar-rail-flight");
165
+
166
+ /** happy-dom ships no WAAPI: the prototype method is assigned by hand
167
+ * (spyOn requires an existing property) and restored in afterEach. The
168
+ * recording handle keeps its listeners fireable so the finish/cancel
169
+ * sweep paths are actually exercised. */
170
+ const animatable = HTMLElement.prototype as Omit<HTMLElement, "animate"> & {
171
+ animate?: unknown;
172
+ };
173
+ let originalAnimate: unknown;
174
+
175
+ beforeEach(() => {
176
+ vi.useFakeTimers();
177
+ animations = [];
178
+ originalAnimate = animatable.animate;
179
+ animatable.animate = function (
180
+ this: HTMLElement,
181
+ keyframes: Keyframe[],
182
+ options?: KeyframeAnimationOptions,
183
+ ) {
184
+ const listeners = new Map<string, EventListener>();
185
+ const handle = {
186
+ addEventListener: (type: string, listener: EventListener) => {
187
+ listeners.set(type, listener);
188
+ },
189
+ cancel: () => listeners.get("cancel")?.(new Event("cancel")),
190
+ fire(type: "finish" | "cancel") {
191
+ listeners.get(type)?.(new Event(type));
192
+ },
193
+ };
194
+ animations.push({ el: this, keyframes, options: options ?? ({} as KeyframeAnimationOptions), fire: handle.fire });
195
+ return handle as unknown as Animation;
196
+ } as typeof animatable.animate;
197
+ });
198
+
199
+ afterEach(() => {
200
+ if (originalAnimate === undefined) delete animatable.animate;
201
+ else animatable.animate = originalAnimate;
202
+ for (const app of mounts.splice(0)) app.unmount();
203
+ containers.splice(0).forEach((c) => c.remove());
204
+ document.body.innerHTML = "";
205
+ vi.unstubAllGlobals();
206
+ vi.useRealTimers();
207
+ __teardownMediaQueries();
208
+ });
209
+
210
+ describe("enterDelayMs", () => {
211
+ it("parses the enter-hold property shapes", () => {
212
+ expect(enterDelayMs("")).toBe(0);
213
+ expect(enterDelayMs("0ms")).toBe(0);
214
+ expect(enterDelayMs("150ms")).toBe(150);
215
+ expect(enterDelayMs("0.2s")).toBe(200);
216
+ expect(enterDelayMs("garbage")).toBe(0);
217
+ expect(enterDelayMs("-5ms")).toBe(0);
218
+ });
219
+ });
220
+
221
+ describe("useRailIconFlight", () => {
222
+ it("arms a flight on collapse: matched cells marked, layer on the entering item, clones at the leaving rects", async () => {
223
+ const h = mountSwap();
224
+ await h.set(true);
225
+ // Expanded geometry: icon cells at x=32 (the leading padding column).
226
+ const { leaving, entering } = dissolvePair(h, true);
227
+ stubRect(h.swap(), rect(0, 0, 240, 400));
228
+ stubIcons(leaving, (key) => rect(32, key === "home" ? 100 : 140));
229
+ // Rail geometry: the same cells centered in the 56px column (x=20).
230
+ stubIcons(entering, (key) =>
231
+ rect(20, key === "home" ? 100 : key === "inbox" ? 140 : 180),
232
+ );
233
+
234
+ await vi.advanceTimersByTimeAsync(0);
235
+
236
+ expect(h.swap().getAttribute(RAIL_FLIP_ACTIVE_ATTR), "the flight is armed").toBe("");
237
+ const layer = flightLayer(h);
238
+ expect(layer, "the flight layer lives on the swap host").toBeTruthy();
239
+ expect(
240
+ layer!.parentElement,
241
+ "the stage is the SWAP HOST — outside both dissolving items, so the clones never inherit the enter fade",
242
+ ).toBe(h.swap());
243
+ // Two MATCHED keys fly; "rail-only"/"full-only" have no partner and
244
+ // must dissolve instead of being invented a source.
245
+ expect(layer!.querySelectorAll(".hk-sidebar-rail-flight-clone")).toHaveLength(2);
246
+ // Each clone animates by the SIGNED delta (collapse: 12px leftward).
247
+ const home = animations.find((a) => a.el.textContent === "H");
248
+ expect(home, "the home clone animates").toBeTruthy();
249
+ expect(home!.options.duration).toBe(RAIL_FLIGHT_MS);
250
+ expect(home!.keyframes.at(-1)!.transform).toBe("translate(-12px, 0px)");
251
+ const inbox = animations.find((a) => a.el.textContent === "I");
252
+ expect(inbox!.keyframes.at(-1)!.transform).toBe("translate(-12px, 0px)");
253
+ // The clone is PAINTED at the leaving rect as a logical inset from
254
+ // the stage's stable inline-start edge…
255
+ const homeClone = layer!.querySelector<HTMLElement>(".hk-sidebar-rail-flight-clone")!;
256
+ expect(homeClone.style.insetInlineStart).toBe("32px");
257
+ expect(homeClone.style.insetBlockStart).toBe("100px");
258
+ // …and carries no flip identity of its own.
259
+ expect(homeClone.getAttribute(RAIL_FLIP_ICON_ATTR)).toBeNull();
260
+ // The pairing contract, visible: matched leaving cells are stamped
261
+ // for the hide rule; the partnerless LEAVING cell ("full-only" has
262
+ // no rail counterpart) is NOT (it must dissolve, not vanish
263
+ // un-substituted).
264
+ const leavingHome = leaving.querySelector(`[${RAIL_FLIP_ICON_ATTR}="home"]`)!;
265
+ expect(leavingHome.hasAttribute(RAIL_FLIP_FLYING_ATTR), "matched cell marked").toBe(true);
266
+ const solo = leaving.querySelector(`[${RAIL_FLIP_ICON_ATTR}="full-only"]`)!;
267
+ expect(solo.hasAttribute(RAIL_FLIP_FLYING_ATTR), "unmatched cell never marked").toBe(false);
268
+ });
269
+
270
+ it("divides the written geometry by the ancestor draw scale (root zoom)", async () => {
271
+ // drawnScale = drawn rect / laid size: stubbing the stage's laid
272
+ // size to HALF its drawn box puts the flight at scale 2 — every
273
+ // written px (insets, size, travel) must halve, or a root-level
274
+ // `html { zoom }` renders the flight k times too far (the deletion
275
+ // mutation ran 91 tests green before this pin existed).
276
+ const h = mountSwap();
277
+ await h.set(true);
278
+ const { leaving, entering } = dissolvePair(h, true);
279
+ const host = h.swap();
280
+ stubRect(host, rect(0, 0, 240, 400));
281
+ // The stage reads the HOST's laid size: 240/120 = 400/200 = 2.
282
+ Object.defineProperty(host, "offsetWidth", { configurable: true, get: () => 120 });
283
+ Object.defineProperty(host, "offsetHeight", { configurable: true, get: () => 200 });
284
+ stubIcons(leaving, (key) => rect(32, key === "home" ? 100 : 140));
285
+ stubIcons(entering, (key) => rect(20, key === "home" ? 100 : 140));
286
+
287
+ await vi.advanceTimersByTimeAsync(0);
288
+
289
+ const homeClone = flightLayer(h)!.querySelector<HTMLElement>(".hk-sidebar-rail-flight-clone")!;
290
+ expect(homeClone.style.insetInlineStart, "inset halves at zoom 2").toBe("16px");
291
+ expect(homeClone.style.insetBlockStart, "block inset halves at zoom 2").toBe("50px");
292
+ expect(homeClone.style.width).toBe("8px");
293
+ const home = animations.find((a) => a.el.textContent === "H")!;
294
+ expect(home.keyframes.at(-1)!.transform, "travel halves at zoom 2").toBe(
295
+ "translate(-6px, 0px)",
296
+ );
297
+ });
298
+
299
+ it("measures the RTL inline offset INWARD from the docked right edge", async () => {
300
+ // inset-inline-start in RTL maps to `right`, and a right inset grows
301
+ // INWARD (leftward): the value is the icon's right edge measured
302
+ // from the host's right edge. The sign the other way round wrote a
303
+ // NEGATIVE inset — every clone landed outside the docked edge and
304
+ // the clip ate the whole flight (the review's S1, RTL had zero
305
+ // coverage before this test).
306
+ const h = mountSwap();
307
+ const realGCS = window.getComputedStyle.bind(window);
308
+ vi.spyOn(window, "getComputedStyle").mockImplementation((el: Element) => {
309
+ const declared = realGCS(el as HTMLElement);
310
+ if (el !== h.swap()) return declared;
311
+ // The host reads direction: rtl; everything else passes through.
312
+ return new Proxy(declared, {
313
+ get(target, prop) {
314
+ if (prop === "direction") return "rtl";
315
+ const value = Reflect.get(target, prop, target);
316
+ return typeof value === "function" ? value.bind(target) : value;
317
+ },
318
+ }) as CSSStyleDeclaration;
319
+ });
320
+ await h.set(true);
321
+ const { leaving, entering } = dissolvePair(h, true);
322
+ stubRect(h.swap(), rect(0, 0, 240, 400));
323
+ stubIcons(leaving, (key) => rect(32, key === "home" ? 100 : 140));
324
+ stubIcons(entering, (key) => rect(20, key === "home" ? 100 : 140));
325
+
326
+ await vi.advanceTimersByTimeAsync(0);
327
+
328
+ const homeClone = flightLayer(h)!.querySelector<HTMLElement>(".hk-sidebar-rail-flight-clone")!;
329
+ // origin.right = 240, icon right = 48 → 192px inward from the right.
330
+ expect(homeClone.style.insetInlineStart, "RTL inset measured inward from right").toBe(
331
+ "192px",
332
+ );
333
+ // The travel stays PHYSICAL: the icon moves 12px left, same as LTR.
334
+ const home = animations.find((a) => a.el.textContent === "H")!;
335
+ expect(home.keyframes.at(-1)!.transform).toBe("translate(-12px, 0px)");
336
+ vi.mocked(window.getComputedStyle).mockRestore();
337
+ });
338
+
339
+ it("flies the opposite way on expand (the delta is signed, per key)", async () => {
340
+ const h = mountSwap();
341
+ await h.set(true);
342
+ // Let the first flight arm AND settle (sweep budget), so the second
343
+ // flip starts from a clean host.
344
+ await vi.advanceTimersByTimeAsync(RAIL_FLIGHT_SWEEP_MS + 50);
345
+ expect(flightLayer(h)).toBeNull();
346
+ animations.length = 0;
347
+
348
+ await h.set(false);
349
+ const { leaving, entering } = dissolvePair(h, false);
350
+ stubRect(h.swap(), rect(0, 0, 240, 400));
351
+ // Distinct tracks per key so a mixed-up pairing cannot pass: home at
352
+ // y=100, inbox at y=160 — leaving (rail) at x=20, entering (full) at
353
+ // x=32 → +12px rightward on BOTH keys.
354
+ stubIcons(leaving, (key) => rect(20, key === "home" ? 100 : 160));
355
+ stubIcons(entering, (key) => rect(32, key === "home" ? 100 : 160));
356
+
357
+ await vi.advanceTimersByTimeAsync(0);
358
+ expect(h.swap().getAttribute(RAIL_FLIP_ACTIVE_ATTR)).toBe("");
359
+ for (const a of animations) {
360
+ expect(a.keyframes.at(-1)!.transform, `${a.el.textContent} flies right`).toBe(
361
+ "translate(12px, 0px)",
362
+ );
363
+ }
364
+ expect(animations).toHaveLength(2);
365
+ // The expand direction hides by the same pairing rule: the rail's
366
+ // fallback cell ("rail-only" — no expanded counterpart) stays
367
+ // unmarked and dissolves.
368
+ const solo = leaving.querySelector(`[${RAIL_FLIP_ICON_ATTR}="rail-only"]`)!;
369
+ expect(solo.hasAttribute(RAIL_FLIP_FLYING_ATTR), "unmatched cell never marked").toBe(false);
370
+ });
371
+
372
+ it("skips the flight when nothing moves (positions already coincide)", async () => {
373
+ const h = mountSwap();
374
+ await h.set(true);
375
+ const { leaving, entering } = dissolvePair(h, true);
376
+ stubRect(h.swap(), rect(0, 0, 240, 400));
377
+ stubIcons(leaving, () => rect(28, 100));
378
+ stubIcons(entering, () => rect(28, 100));
379
+
380
+ await vi.advanceTimersByTimeAsync(0);
381
+ expect(h.swap().hasAttribute(RAIL_FLIP_ACTIVE_ATTR)).toBe(false);
382
+ expect(flightLayer(h)).toBeNull();
383
+ expect(animations).toHaveLength(0);
384
+ });
385
+
386
+ it("skips the flight when WAAPI is unavailable", async () => {
387
+ delete animatable.animate;
388
+ const h = mountSwap();
389
+ await h.set(true);
390
+ const { leaving, entering } = dissolvePair(h, true);
391
+ stubRect(h.swap(), rect(0, 0, 240, 400));
392
+ stubIcons(leaving, () => rect(32, 100));
393
+ stubIcons(entering, () => rect(20, 100));
394
+
395
+ await vi.advanceTimersByTimeAsync(0);
396
+ expect(h.swap().hasAttribute(RAIL_FLIP_ACTIVE_ATTR)).toBe(false);
397
+ expect(flightLayer(h)).toBeNull();
398
+ });
399
+
400
+ it("skips the flight under reduced motion", async () => {
401
+ // Minimal MediaQueryList fake — spread of a live list loses the
402
+ // accessor. `matches: true` must be readable at SETUP time: the
403
+ // composable subscribes once and reads its ref in flightCapable().
404
+ const fakeList = {
405
+ matches: true,
406
+ media: "(prefers-reduced-motion: reduce)",
407
+ onchange: null,
408
+ addEventListener: () => {},
409
+ removeEventListener: () => {},
410
+ addListener: () => {},
411
+ removeListener: () => {},
412
+ dispatchEvent: () => false,
413
+ } as unknown as MediaQueryList;
414
+ vi.spyOn(window, "matchMedia").mockReturnValue(fakeList);
415
+ const h = mountSwap();
416
+ await h.set(true);
417
+ const { leaving, entering } = dissolvePair(h, true);
418
+ stubRect(h.swap(), rect(0, 0, 240, 400));
419
+ stubIcons(leaving, () => rect(32, 100));
420
+ stubIcons(entering, () => rect(20, 100));
421
+
422
+ await vi.advanceTimersByTimeAsync(0);
423
+ expect(h.swap().hasAttribute(RAIL_FLIP_ACTIVE_ATTR)).toBe(false);
424
+ expect(flightLayer(h)).toBeNull();
425
+ vi.mocked(window.matchMedia).mockRestore();
426
+ });
427
+
428
+ it("skips the flight when the leaving generation is gone (watchdog-degraded swap)", async () => {
429
+ const h = mountSwap();
430
+ await h.set(true);
431
+ // HkCrossfade's stall sweep removes the stale item outright; the
432
+ // choreographer must stay dormant with no dissolve to fly over.
433
+ h.swap()
434
+ .querySelector(`:scope > .hk-crossfade-item[${RAIL_FLIP_ITEM_ATTR}="full"]`)
435
+ ?.remove();
436
+ stubRect(h.swap(), rect(0, 0, 240, 400));
437
+
438
+ await vi.advanceTimersByTimeAsync(0);
439
+ expect(h.swap().hasAttribute(RAIL_FLIP_ACTIVE_ATTR)).toBe(false);
440
+ expect(flightLayer(h)).toBeNull();
441
+ expect(animations).toHaveLength(0);
442
+ });
443
+
444
+ it("the WAAPI finish sweeps the layer before the fallback budget", async () => {
445
+ const h = mountSwap();
446
+ await h.set(true);
447
+ const { leaving, entering } = dissolvePair(h, true);
448
+ stubRect(h.swap(), rect(0, 0, 240, 400));
449
+ stubIcons(leaving, () => rect(32, 100));
450
+ stubIcons(entering, () => rect(20, 100));
451
+
452
+ await vi.advanceTimersByTimeAsync(0);
453
+ expect(flightLayer(h)).toBeTruthy();
454
+ // The real browser's healthy path: the animation finishes at ~300ms.
455
+ animations[0]!.fire("finish");
456
+ expect(flightLayer(h), "the finish listener sweeps immediately").toBeNull();
457
+ expect(h.swap().hasAttribute(RAIL_FLIP_ACTIVE_ATTR)).toBe(false);
458
+ // The marks ride along: a swept flight unhides its cells.
459
+ expect(
460
+ leaving.querySelector(`[${RAIL_FLIP_ICON_ATTR}="home"]`)!.hasAttribute(RAIL_FLIP_FLYING_ATTR),
461
+ ).toBe(false);
462
+ });
463
+
464
+ it("sweeps the layer and the attribute when the fallback budget expires", async () => {
465
+ const h = mountSwap();
466
+ await h.set(true);
467
+ const { leaving, entering } = dissolvePair(h, true);
468
+ stubRect(h.swap(), rect(0, 0, 240, 400));
469
+ stubIcons(leaving, () => rect(32, 100));
470
+ stubIcons(entering, () => rect(20, 100));
471
+
472
+ await vi.advanceTimersByTimeAsync(0);
473
+ expect(flightLayer(h)).toBeTruthy();
474
+ await vi.advanceTimersByTimeAsync(RAIL_FLIGHT_SWEEP_MS + 10);
475
+ expect(flightLayer(h), "the sweep timer removes the layer").toBeNull();
476
+ expect(h.swap().hasAttribute(RAIL_FLIP_ACTIVE_ATTR)).toBe(false);
477
+ });
478
+
479
+ it("a replaced flight's late finish never sweeps its successor (stale-finish race)", async () => {
480
+ // The 2026-11-02 review's scratch probe: flight #1's WAAPI animation
481
+ // keeps ticking after a fresh flip swept the stage — its finish
482
+ // listener must not act on flight #2's layer, marks or attribute.
483
+ const h = mountSwap();
484
+ await h.set(true);
485
+ let pair = dissolvePair(h, true);
486
+ stubRect(h.swap(), rect(0, 0, 240, 400));
487
+ stubIcons(pair.leaving, () => rect(32, 100));
488
+ stubIcons(pair.entering, () => rect(20, 100));
489
+ await vi.advanceTimersByTimeAsync(0);
490
+ expect(flightLayer(h)).toBeTruthy();
491
+ const firstFlightCount = animations.length;
492
+
493
+ // Flip #2 BEFORE flight #1 finishes: the replacement sweeps the stage…
494
+ await h.set(false);
495
+ pair = dissolvePair(h, false);
496
+ stubIcons(pair.leaving, () => rect(20, 100));
497
+ stubIcons(pair.entering, () => rect(32, 100));
498
+ await vi.advanceTimersByTimeAsync(0);
499
+ expect(flightLayer(h), "flight #2 is on stage").toBeTruthy();
500
+ const secondFlightAnims = animations.slice(firstFlightCount);
501
+
502
+ // …then flight #1's finish fires late: a no-op for the successor.
503
+ animations[0]!.fire("finish");
504
+ expect(flightLayer(h), "the successor's layer survives a stale finish").toBeTruthy();
505
+ expect(h.swap().hasAttribute(RAIL_FLIP_ACTIVE_ATTR), "the successor stays armed").toBe(true);
506
+ expect(
507
+ pair.leaving
508
+ .querySelector(`[${RAIL_FLIP_ICON_ATTR}="home"]`)!
509
+ .hasAttribute(RAIL_FLIP_FLYING_ATTR),
510
+ "the successor's hide marks survive",
511
+ ).toBe(true);
512
+ // …and flight #2's own finish still sweeps normally.
513
+ secondFlightAnims[0]!.fire("finish");
514
+ expect(flightLayer(h)).toBeNull();
515
+ expect(h.swap().hasAttribute(RAIL_FLIP_ACTIVE_ATTR)).toBe(false);
516
+ });
517
+
518
+ it("a fresh flip replaces the previous flight instead of stacking layers", async () => {
519
+ const h = mountSwap();
520
+ await h.set(true);
521
+ let pair = dissolvePair(h, true);
522
+ stubRect(h.swap(), rect(0, 0, 240, 400));
523
+ stubIcons(pair.leaving, () => rect(32, 100));
524
+ stubIcons(pair.entering, () => rect(20, 100));
525
+ await vi.advanceTimersByTimeAsync(0);
526
+ expect(flightLayer(h)).toBeTruthy();
527
+
528
+ await h.set(false);
529
+ pair = dissolvePair(h, false);
530
+ stubIcons(pair.leaving, () => rect(20, 100));
531
+ stubIcons(pair.entering, () => rect(32, 100));
532
+ await vi.advanceTimersByTimeAsync(0);
533
+ const layers = h.swap().querySelectorAll(".hk-sidebar-rail-flight");
534
+ expect(layers, "exactly one flight layer").toHaveLength(1);
535
+ expect(h.swap().hasAttribute(RAIL_FLIP_ACTIVE_ATTR)).toBe(true);
536
+ });
537
+ });