@celestia-island/hikari 0.55.266 → 0.55.268

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.266",
+  "version": "0.55.268",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/components/HkSidebarRail.scss

@@ -206,22 +206,22 @@
   will-change: transform;
 }
 
-/* During a flight the leaving generation's MATCHED icons hide: the clone
- * paints in their place at the same geometry, full opacity — a
- * substitution, not a fade, so the icon reads as ONE object that
- * travels. Scoped four ways on purpose: only while a flight runs
- * ([data-flipping] on the swap host), only on the dissolving copy (the
- * leave item class), only on opted-in icons ([data-flip-icon]), and
- * only on the cells the choreographer actually PAIRED AND CLONED
- * ([data-flip-flying] — stamped per flight, swept after). That last
- * scope is the pairing contract made visible: an opted-in cell without
- * a partner (a rail fallback letter with no expanded counterpart) is
- * never stamped, so it dissolves instead of vanishing without a
- * substitute (2026-11-02 review). Identity blocks, carets, badges
- * and every other icon keep the plain dissolve. */
-.hk-sidebar-rail-swap[data-flipping]
-  .hk-crossfade-item.hk-crossfade-leave-active
-  .hk-menu-item-icon[data-flip-flying] {
+/* THE SINGLE-GLYPH CONTRACT (2026-11-02 user direction: the flight
+ * used to double-expose — the clone crossed paths with the entering
+ * icon dissolving in at the destination). While a flight runs, BOTH
+ * ends of every matched pair hide ([data-flip-flying], stamped on the
+ * leaving AND the entering cell by the choreographer, swept with the
+ * layer): the clone is the one visible glyph of that destination from
+ * arm to landing, and the entering icon only resurfaces — via the same
+ * sweep, in the same task — once the clone has landed on it. Scoped
+ * deliberately WITHOUT the items' dissolve classes: those are
+ * transient engine state, and the mark alone already names exactly the
+ * substituted cells. An opted-in cell without a partner (a rail
+ * fallback letter with no expanded counterpart) is never stamped, so
+ * it dissolves instead of vanishing without a substitute — the pairing
+ * contract. Identity blocks, carets, badges and every other icon keep
+ * the plain dissolve. */
+.hk-sidebar-rail-swap[data-flipping] .hk-menu-item-icon[data-flip-flying] {
   visibility: hidden;
 }
 

package/src/components/HkSidebarRail.styles.test.ts

@@ -246,7 +246,7 @@ describe("HkSidebarRail geometry contract", () => {
     expect(btn).toContain("--hi-icon-button-radius: 9999px");
   });
 
-  it("hosts the rail flip's icon flight: paint-only layer, dead clones, triply-scoped hide", () => {
+  it("hosts the rail flip's icon flight: paint-only layer, dead clones, single-glyph hide", () => {
     // useRailIconFlight clones the flipping icons onto a layer ABOVE the
     // dissolve. The layer is chrome: it must never intercept a pointer
     // (the leaving generation is pointer-dead for the dissolve and the
@@ -264,30 +264,41 @@ describe("HkSidebarRail geometry contract", () => {
     expect(clone).toContain("position: absolute");
     expect(clone).toContain("pointer-events: none");
 
-    // The hide rule is scoped FOUR ways — only while a flight is armed
-    // ([data-flipping] on the swap host), only on the DISSOLVING copy
-    // (the leave item class), only on opted-in icons ([data-flip-icon]),
-    // and only on the cells the choreographer actually PAIRED AND CLONED
-    // ([data-flip-flying]): identity blocks, carets, badges, unmatched
-    // fallbacks and every other icon keep the plain dissolve. The
-    // selector is composed from the composable's EXPORTED CONSTANTS —
-    // the welding that keeps the JSX/SCSS literals and the JS pairings
-    // one vocabulary (a literal drift anywhere turns this red instead of
-    // silently double-exposing the glyph).
+    // The hide rule enforces the SINGLE-GLYPH CONTRACT (2026-11-02 user
+    // direction: the clone and the dissolving-in entering icon used to
+    // double-expose mid-flight): while a flight is armed
+    // ([data-flipping] on the swap host), every cell the choreographer
+    // marked ([data-flip-flying] — stamped on BOTH ends of a matched
+    // pair, swept with the layer) hides, so the clone is the one
+    // visible glyph from arm to landing. Deliberately NOT scoped to the
+    // items' dissolve classes — those are transient engine state (the
+    // happy-dom lesson), and the mark alone already names exactly the
+    // substituted cells. The selector is composed from the composable's
+    // EXPORTED CONSTANTS — the welding that keeps the JSX/SCSS literals
+    // and the JS pairings one vocabulary (a literal drift anywhere turns
+    // this red instead of silently double-exposing the glyph).
     const hideSelector =
       `.hk-sidebar-rail-swap[${RAIL_FLIP_ACTIVE_ATTR}] ` +
-      `.hk-crossfade-item.hk-crossfade-leave-active ` +
       `.hk-menu-item-icon[${RAIL_FLIP_FLYING_ATTR}]`;
-    const hide = ruleBody(css, hideSelector);
-    expect(hide, "the flight hide rule exists (all four scopes)").not.toBeNull();
-    expect(hide).toContain("visibility: hidden");
-    // …and the sheet must not hide on the OPT-IN attribute alone — that
+    // Rule-boundary anchored: ruleBody's plain match is a SUBSTRING
+    // lookup, so a longer selector that merely CONTAINS the welded form
+    // (a namespaced prefix, a malformed double selector) would pass.
+    // Demanding a rule edge (start of stylesheet or a closing brace)
+    // before the selector closes that hole.
+    const hide = css.match(
+      new RegExp(
+        "(^|})\\s*" + hideSelector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "\\s*\\{([^}]*)\\}",
+      ),
+    );
+    expect(hide, "the single-glyph hide rule exists as ITS OWN rule").not.toBeNull();
+    // Group 2 is the rule body (group 1 is the boundary anchor).
+    expect(hide![2]).toContain("visibility: hidden");
+    // The sheet must not hide on the OPT-IN attribute alone — that
     // spelling would vanish unmatched fallbacks without a substitute.
     expect(
       ruleBody(
         css,
         `.hk-sidebar-rail-swap[${RAIL_FLIP_ACTIVE_ATTR}] ` +
-          `.hk-crossfade-item.hk-crossfade-leave-active ` +
           `.hk-menu-item-icon[${RAIL_FLIP_ICON_ATTR}]`,
       ),
       "hiding keyed to the opt-in attribute alone is the S1-1 regression",

package/src/components/HkSidebarRailSwap.tsx

@@ -84,9 +84,11 @@ import "./HkSidebarRail.scss";
  * icon slides slightly left as it collapses"). This component hands the
  * flip to the flight choreographer: icons opted in by HkMenu
  * (`data-flip-icon`) are cloned into a flight layer on THIS host and
- * animated from the leaving rect to the entering one, while the leaving
- * copies hide (`data-flipping` + the leave class) and the rest of the
- * content keeps the plain dissolve. Skipped under reduced motion / the
+ * animated from the leaving rect to the entering one, while BOTH ends
+ * of each matched pair hide (`data-flipping` + the per-cell
+ * `data-flip-flying` mark — the single-glyph contract: the clone is the
+ * one visible glyph from arm to landing) and the rest of the content
+ * keeps the plain dissolve. Skipped under reduced motion / the
  * animation switch / no WAAPI / no matching pair — every such case
  * degrades to today's dissolve.
  *

package/src/composables/useRailIconFlight.test.ts

@@ -2,9 +2,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createApp, defineComponent, h, nextTick, ref, type App } from "vue";
 
 import {
-  enterDelayMs,
+  cssDurationMs,
   RAIL_FLIGHT_MS,
-  RAIL_FLIGHT_SWEEP_MS,
+  RAIL_FLIGHT_SWEEP_MARGIN_MS,
   RAIL_FLIP_ACTIVE_ATTR,
   RAIL_FLIP_FLYING_ATTR,
   RAIL_FLIP_ICON_ATTR,
@@ -43,7 +43,8 @@ import HkSidebarRailSwap from "../components/HkSidebarRailSwap";
  *    motion, or a dissolved-away leaving generation → no flight.
  * 4. The lifecycle: the WAAPI `finish` sweeps the layer; the sweep timer
  *    backstops it; a fresh flip replaces (never stacks) the previous
- *    flight; unmount cleans up.
+ *    flight; scope disposal tears a live flight down (the afterEach
+ *    unmount walks the same path).
  */
 
 const mounts: App[] = [];
@@ -54,6 +55,7 @@ interface RecordedAnimation {
   keyframes: Keyframe[];
   options: KeyframeAnimationOptions;
   fire(type: "finish" | "cancel"): void;
+  cancelCount(): number;
 }
 let animations: RecordedAnimation[] = [];
 
@@ -182,16 +184,26 @@ beforeEach(() => {
     options?: KeyframeAnimationOptions,
   ) {
     const listeners = new Map<string, EventListener>();
+    let cancels = 0;
     const handle = {
       addEventListener: (type: string, listener: EventListener) => {
         listeners.set(type, listener);
       },
-      cancel: () => listeners.get("cancel")?.(new Event("cancel")),
+      cancel: () => {
+        cancels++;
+        listeners.get("cancel")?.(new Event("cancel"));
+      },
       fire(type: "finish" | "cancel") {
         listeners.get(type)?.(new Event(type));
       },
     };
-    animations.push({ el: this, keyframes, options: options ?? ({} as KeyframeAnimationOptions), fire: handle.fire });
+    animations.push({
+      el: this,
+      keyframes,
+      options: options ?? ({} as KeyframeAnimationOptions),
+      fire: handle.fire,
+      cancelCount: () => cancels,
+    });
     return handle as unknown as Animation;
   } as typeof animatable.animate;
 });
@@ -212,14 +224,17 @@ afterEach(() => {
   __teardownMediaQueries();
 });
 
-describe("enterDelayMs", () => {
-  it("parses the enter-hold property shapes", () => {
-    expect(enterDelayMs("")).toBe(0);
-    expect(enterDelayMs("0ms")).toBe(0);
-    expect(enterDelayMs("150ms")).toBe(150);
-    expect(enterDelayMs("0.2s")).toBe(200);
-    expect(enterDelayMs("garbage")).toBe(0);
-    expect(enterDelayMs("-5ms")).toBe(0);
+describe("cssDurationMs", () => {
+  it("parses the CSS time property shapes", () => {
+    expect(cssDurationMs("")).toBe(0);
+    expect(cssDurationMs("0ms")).toBe(0);
+    expect(cssDurationMs("150ms")).toBe(150);
+    expect(cssDurationMs("0.2s")).toBe(200);
+    expect(cssDurationMs("300ms")).toBe(300);
+    expect(cssDurationMs("0.3S"), "CSS units are case-insensitive").toBe(300);
+    expect(cssDurationMs("150MS")).toBe(150);
+    expect(cssDurationMs("garbage")).toBe(0);
+    expect(cssDurationMs("-5ms")).toBe(0);
   });
 });
 
@@ -248,13 +263,23 @@ describe("useRailIconFlight", () => {
     // Two MATCHED keys fly; "rail-only"/"full-only" have no partner and
     // must dissolve instead of being invented a source.
     expect(layer!.querySelectorAll(".hk-sidebar-rail-flight-clone")).toHaveLength(2);
-    // Each clone animates by the SIGNED delta (collapse: 12px leftward).
+    // Each clone animates by the SIGNED delta (collapse: 12px leftward)
+    // at the FALLBACK window (the test DOM resolves no custom
+    // properties, so --duration-normal reads empty).
     const home = animations.find((a) => a.el.textContent === "H");
     expect(home, "the home clone animates").toBeTruthy();
     expect(home!.options.duration).toBe(RAIL_FLIGHT_MS);
     expect(home!.keyframes.at(-1)!.transform).toBe("translate(-12px, 0px)");
     const inbox = animations.find((a) => a.el.textContent === "I");
     expect(inbox!.keyframes.at(-1)!.transform).toBe("translate(-12px, 0px)");
+    // SINGLE GLYPH: pure travel — no opacity keyframe anywhere, the
+    // clone holds full opacity to the landing (the old end-fade is what
+    // double-exposed it against the dissolving-in entering icon).
+    for (const a of animations) {
+      expect(a.keyframes.some((f) => "opacity" in (f as PropertyIndexedKeyframes)), "no fade in the flight").toBe(false);
+    }
+    expect(home!.keyframes).toHaveLength(2);
+    expect(home!.options.fill, "a slipped frame parks the clone at the landing rect").toBe("forwards");
     // The clone is PAINTED at the leaving rect as a logical inset from
     // the stage's stable inline-start edge…
     const homeClone = layer!.querySelector<HTMLElement>(".hk-sidebar-rail-flight-clone")!;
@@ -262,14 +287,59 @@ describe("useRailIconFlight", () => {
     expect(homeClone.style.insetBlockStart).toBe("100px");
     // …and carries no flip identity of its own.
     expect(homeClone.getAttribute(RAIL_FLIP_ICON_ATTR)).toBeNull();
-    // The pairing contract, visible: matched leaving cells are stamped
-    // for the hide rule; the partnerless LEAVING cell ("full-only" has
-    // no rail counterpart) is NOT (it must dissolve, not vanish
-    // un-substituted).
+    expect(homeClone.hasAttribute(RAIL_FLIP_FLYING_ATTR), "the clone never hides itself").toBe(false);
+    // The pairing contract, visible: BOTH ends of a matched pair are
+    // stamped for the hide rule (the clone is the one glyph from arm to
+    // landing — the entering cell hides too); the partnerless cells on
+    // either side ("full-only" leaving, "rail-only" entering) are NOT
+    // (they must dissolve, not vanish un-substituted).
     const leavingHome = leaving.querySelector(`[${RAIL_FLIP_ICON_ATTR}="home"]`)!;
-    expect(leavingHome.hasAttribute(RAIL_FLIP_FLYING_ATTR), "matched cell marked").toBe(true);
+    expect(leavingHome.hasAttribute(RAIL_FLIP_FLYING_ATTR), "matched leaving cell marked").toBe(true);
+    const enteringHome = entering.querySelector(`[${RAIL_FLIP_ICON_ATTR}="home"]`)!;
+    expect(enteringHome.hasAttribute(RAIL_FLIP_FLYING_ATTR), "matched ENTERING cell marked too — single glyph").toBe(true);
     const solo = leaving.querySelector(`[${RAIL_FLIP_ICON_ATTR}="full-only"]`)!;
-    expect(solo.hasAttribute(RAIL_FLIP_FLYING_ATTR), "unmatched cell never marked").toBe(false);
+    expect(solo.hasAttribute(RAIL_FLIP_FLYING_ATTR), "unmatched leaving cell never marked").toBe(false);
+    const soloIn = entering.querySelector(`[${RAIL_FLIP_ICON_ATTR}="rail-only"]`)!;
+    expect(soloIn.hasAttribute(RAIL_FLIP_FLYING_ATTR), "unmatched entering cell never marked").toBe(false);
+  });
+
+  it("derives the flight window from the theme's --duration-normal (no hardcoded mirror)", async () => {
+    // The window must READ the token the dissolve consumes: a theme
+    // retuned to 600ms retunes the flight with it, and the sweep budget
+    // stretches past the longer window (arm at 600, sweep at 900).
+    const h = mountSwap();
+    const realGCS = window.getComputedStyle.bind(window);
+    vi.spyOn(window, "getComputedStyle").mockImplementation((el: Element) => {
+      const declared = realGCS(el as HTMLElement);
+      if (el !== h.swap()) return declared;
+      return new Proxy(declared, {
+        get(target, prop) {
+          if (prop === "getPropertyValue") {
+            return (name: string) =>
+              name === "--duration-normal" ? "600ms" : (target.getPropertyValue(name) ?? "");
+          }
+          const value = Reflect.get(target, prop, target);
+          return typeof value === "function" ? value.bind(target) : value;
+        },
+      }) as CSSStyleDeclaration;
+    });
+    await h.set(true);
+    const { leaving, entering } = dissolvePair(h, true);
+    stubRect(h.swap(), rect(0, 0, 240, 400));
+    stubIcons(leaving, (key) => rect(32, key === "home" ? 100 : 140));
+    stubIcons(entering, (key) => rect(20, key === "home" ? 100 : 140));
+
+    await vi.advanceTimersByTimeAsync(0);
+    expect(h.swap().getAttribute(RAIL_FLIP_ACTIVE_ATTR)).toBe("");
+    const home = animations.find((a) => a.el.textContent === "H")!;
+    expect(home.options.duration, "the flight window follows the theme token").toBe(600);
+    // The sweep is the DERIVED window plus margin: at 700ms the flight
+    // is still on stage; past 900ms the fallback collects it.
+    await vi.advanceTimersByTimeAsync(700);
+    expect(flightLayer(h), "still flying inside the token-derived window").toBeTruthy();
+    await vi.advanceTimersByTimeAsync(RAIL_FLIGHT_SWEEP_MARGIN_MS + 20);
+    expect(flightLayer(h), "the sweep follows the stretched window").toBeNull();
+    vi.mocked(window.getComputedStyle).mockRestore();
   });
 
   it("divides the written geometry by the ancestor draw scale (root zoom)", async () => {
@@ -346,7 +416,7 @@ describe("useRailIconFlight", () => {
     await h.set(true);
     // Let the first flight arm AND settle (sweep budget), so the second
     // flip starts from a clean host.
-    await vi.advanceTimersByTimeAsync(RAIL_FLIGHT_SWEEP_MS + 50);
+    await vi.advanceTimersByTimeAsync(RAIL_FLIGHT_MS + RAIL_FLIGHT_SWEEP_MARGIN_MS + 50);
     expect(flightLayer(h)).toBeNull();
     animations.length = 0;
 
@@ -386,6 +456,14 @@ describe("useRailIconFlight", () => {
     expect(h.swap().hasAttribute(RAIL_FLIP_ACTIVE_ATTR)).toBe(false);
     expect(flightLayer(h)).toBeNull();
     expect(animations).toHaveLength(0);
+    // Skip paths never STAMP either: no cell anywhere may carry the hide
+    // mark (the skip tests used to assert only the host attribute and
+    // the layer — a future reorder stamping before a veto would have
+    // stayed green — 2026-11-02 review F5).
+    expect(
+      h.swap().querySelectorAll(`[${RAIL_FLIP_FLYING_ATTR}]`),
+      "a skipped flight marks nothing",
+    ).toHaveLength(0);
   });
 
   it("skips the flight when WAAPI is unavailable", async () => {
@@ -460,9 +538,27 @@ describe("useRailIconFlight", () => {
     animations[0]!.fire("finish");
     expect(flightLayer(h), "the finish listener sweeps immediately").toBeNull();
     expect(h.swap().hasAttribute(RAIL_FLIP_ACTIVE_ATTR)).toBe(false);
-    // The marks ride along: a swept flight unhides its cells.
+    // LEAK PIN: the sweep CANCELS the clone animations, not just drops
+    // the layer — under the spec's replace-only auto-removal a finished
+    // fill:forwards animation on a never-again-animated element would
+    // strand Animation→effect→clone forever (2026-11-02 reviews: one
+    // reading says leak, a real-Chromium probe says element removal
+    // already clears getAnimations(); the cancel makes BOTH readings
+    // true and costs nothing).
+    for (const a of animations) {
+      expect(a.cancelCount(), "sweep cancels every clone animation").toBeGreaterThan(0);
+    }
+    // The marks ride along: a swept flight unhides BOTH ends — the
+    // leaving cell it substituted AND the entering cell it covered
+    // (deleting the unmark loop once stayed green on this side; the pin
+    // closes that hole — 2026-11-02 review S3-1).
     expect(
       leaving.querySelector(`[${RAIL_FLIP_ICON_ATTR}="home"]`)!.hasAttribute(RAIL_FLIP_FLYING_ATTR),
+      "leaving mark cleared",
+    ).toBe(false);
+    expect(
+      entering.querySelector(`[${RAIL_FLIP_ICON_ATTR}="home"]`)!.hasAttribute(RAIL_FLIP_FLYING_ATTR),
+      "ENTERING mark cleared",
     ).toBe(false);
   });
 
@@ -476,7 +572,7 @@ describe("useRailIconFlight", () => {
 
     await vi.advanceTimersByTimeAsync(0);
     expect(flightLayer(h)).toBeTruthy();
-    await vi.advanceTimersByTimeAsync(RAIL_FLIGHT_SWEEP_MS + 10);
+    await vi.advanceTimersByTimeAsync(RAIL_FLIGHT_MS + RAIL_FLIGHT_SWEEP_MARGIN_MS + 10);
     expect(flightLayer(h), "the sweep timer removes the layer").toBeNull();
     expect(h.swap().hasAttribute(RAIL_FLIP_ACTIVE_ATTR)).toBe(false);
   });

package/src/composables/useRailIconFlight.ts

@@ -51,22 +51,38 @@ import { releaseMediaQuery, useMediaQuery } from "../runtime/useMediaQuery";
  *    (`drawnScale` — a root-level `html { zoom }` multiplies every
  *    measured viewport px by k; values written back in local px would
  *    render k times too far).
- * 3. While the flight runs, the leaving generation's MATCHED icons hide
- *    (CSS keyed on the host's `data-flipping` + the leave item's
- *    dissolve class + the per-cell `data-flip-flying` mark this
- *    composable stamps on exactly the cells it cloned): the clone
- *    substitutes them at the same geometry, full opacity — nothing
- *    blinks. UNMATCHED keyed cells (a rail fallback letter with no
- *    expanded counterpart, say) are never marked, never hidden — they
- *    plain dissolve, exactly as the pairing contract promises. The
- *    ENTERING icons keep the normal dissolve, so by the time the clone
- *    lands and fades (last ~20% of the window) the real icon underneath
- *    is nearly fully dissolved in and occupies the identical rect — the
- *    handoff tax is a sub-frame dip well under the double-exposure
- *    artifact this replaces.
+ * 3. THE SINGLE-GLYPH CONTRACT (2026-11-02 user direction: the flight
+ *    used to double-expose — the flying clone crossed paths with the
+ *    entering icon dissolving in at the destination, two glyphs on
+ *    screen at once). Both ends of every matched pair are marked
+ *    `data-flip-flying` and hidden for the flight's whole window (the
+ *    rule keys on the host's `data-flipping` + the mark — item-local
+ *    dissolve classes are deliberately NOT part of the selector: they
+ *    are transient engine state, and the mark itself already names
+ *    exactly the substituted cells): the clone is therefore the ONE
+ *    visible glyph of that destination, from arm to landing. The clone
+ *    holds full opacity the entire way (no end fade — the fade was the
+ *    old handoff, and it is what showed two glyphs); it lands exactly
+ *    as the entering dissolve reaches 100%, because both windows read
+ *    the same theme duration. The sweep then removes the clone and
+ *    unmarks the entering icon in one task — one paint shows the real
+ *    icon alone. Even a slipped frame is benign: two identical opaque
+ *    glyphs at the SAME rect read as one (the old artifact was two
+ *    glyphs at DIFFERENT rects mid-crossing). UNMATCHED keyed cells (a
+ *    rail fallback letter with no expanded counterpart) are never
+ *    marked, never hidden — they plain dissolve, as the pairing
+ *    contract promises.
  * 4. Non-participating icons (identity blocks, group carets, badge
  *    dots), the pills, and the labels crossfade exactly as before.
  *
+ * TIMING IS TOKEN-DERIVED, NOT HARDCODED (2026-11-02 user direction):
+ * the flight window reads the theme's `--duration-normal` off the swap
+ * host's computed style — the very variable HkCrossfade's dissolve
+ * consumes — so a retuned theme retunes the flight with it.
+ * `RAIL_FLIGHT_MS` survives only as the fallback for environments
+ * where custom properties cannot be read (the test DOM); the sweep
+ * budget is the derived window plus a fixed margin.
+ *
  * GUARDS: skipped entirely under reduced motion, the global animation
  * switch (`html[data-css-animations="0"]`), a missing WAAPI, or when no
  * pair actually moves (identical positions — the dissolve alone is then
@@ -75,12 +91,19 @@ import { releaseMediaQuery, useMediaQuery } from "../runtime/useMediaQuery";
  * even where `finish` never fires (rAF-starved tabs); a fresh flip
  * sweeps any previous flight first, so flip-flopping can't stack layers.
  *
- * KNOWN LIMIT (documented, accepted): the window constants assume the
- * dissolve runs at its default timing. A host that sets HkCrossfade's
- * `--hk-crossfade-enter-delay` holds the entering fade back; the flight
- * reads the property off the swap host and widens its window and sweep
- * by the same amount, so the handoff lands after the icon has actually
- * faded in. No shipped rail host sets it today.
+ * The same read covers HkCrossfade's `--hk-crossfade-enter-delay`: a
+ * host that holds the entering fade back gets a widened window and
+ * sweep, and the single-glyph contract makes the alignment exact — the
+ * clone covers the destination until the real icon is fully faded in.
+ * No shipped rail host sets it today.
+ *
+ * KNOWN CEILING (2026-11-02 review, pre-existing): HkCrossfade's own
+ * stall watchdog is a fixed 450ms (CROSSFADE_WATCHDOG_MS). A theme that
+ * raises `--duration-normal` past it gets its healthy dissolve swept by
+ * the watchdog before the CSS completes — the flight follows the token
+ * faithfully, but the dissolve it mirrors is cut short. Tokenizing that
+ * watchdog is its own change; until then the practical retune ceiling
+ * is 450ms.
  */
 
 /** Row-key attribute on an icon cell that flies across a rail flip. */
@@ -94,24 +117,33 @@ export const RAIL_FLIP_ACTIVE_ATTR = "data-flipping";
 export const RAIL_FLIP_FLYING_ATTR = "data-flip-flying";
 /** HkCrossfade's per-item identity — the semantic pairing anchor. */
 export const RAIL_FLIP_ITEM_ATTR = "data-crossfade-key";
-/** Total flight window — parity with the dissolve's --duration-normal. */
+/** Flight-window FALLBACK for when `--duration-normal` yields no
+ *  parsable time: environments that resolve no custom properties (the
+ *  test DOM), or a value cssDurationMs cannot read (`calc(…)`, `0s` —
+ *  a 0s theme means an instant dissolve; the fallback flight covers
+ *  the swap's settle frames and stays single-glyph). A real browser
+ *  reads the theme token — see TIMING above. */
 export const RAIL_FLIGHT_MS = 300;
-/** The clone holds full opacity until this fraction of the window, then
- *  fades over the rest — landing INTO the entering icon's own fade. */
-const FLIGHT_HANDOFF_RATIO = 0.78;
-/** Sweep fallback: above any healthy flight (HkCrossfade watchdog
- *  parity — 450ms budget + margin) so a stalled clone can never linger. */
-export const RAIL_FLIGHT_SWEEP_MS = 600;
+/** Sweep margin on top of the (token-derived) flight window: above any
+ *  healthy completion (HkCrossfade watchdog parity) so a stalled clone
+ *  can never linger, however long the theme draws the dissolve. */
+export const RAIL_FLIGHT_SWEEP_MARGIN_MS = 300;
 
-/** Parse HkCrossfade's enter-hold custom property (`"120ms"`, `"0.15s"`,
- *  `""`) into milliseconds. Anything unparsable is no hold at all. */
-export function enterDelayMs(value: string): number {
+/** Parse a CSS time custom property (`"120ms"`, `"0.15s"`, `""`) into
+ *  milliseconds. Anything unparsable or non-positive is 0 — the caller
+ *  decides what 0 means (no hold, or the fallback window). Units are
+ *  case-insensitive in CSS (`"0.3S"` is legal): the check lowercases
+ *  first, or an uppercase second would slip through as 0.3ms — 2026-11-02
+ *  review F3. */
+export function cssDurationMs(value: string): number {
   if (!value) return 0;
   const n = parseFloat(value);
   if (!Number.isFinite(n) || n <= 0) return 0;
-  return value.trim().endsWith("s") && !value.trim().endsWith("ms") ? n * 1000 : n;
+  const unit = value.trim().toLowerCase();
+  return unit.endsWith("s") && !unit.endsWith("ms") ? n * 1000 : n;
 }
 
+
 /** One matched icon pair across the swap: live leaving geometry, entering
  *  geometry, the leaving icon's computed color (svg stroke = currentColor),
  *  and the entering cell to clone (its dress is the destination's). */
@@ -149,6 +181,18 @@ export function useRailIconFlight(
   let flightSeq = 0;
   let currentFlightId = -1;
   let layer: HTMLElement | null = null;
+  /** The current flight's clone animations. The sweep CANCELS them: a
+   *  finished `fill: forwards` animation is auto-removed by the engine
+   *  only when a LATER animation replaces it on the same target+property
+   *  (the spec's replaceable-animations rule) — and every flight targets
+   *  a brand-new clone, so nothing ever replaces it. Without the cancel,
+   *  each flip strands Animation → effect → clone subtree on the document
+   *  timeline forever (the spec itself warns the pattern accumulates
+   *  "hundreds, even thousands"; hover-peeks arm flights constantly) —
+   *  2026-11-02 review S1. cancel() on an already-idle animation is a
+   *  no-op, and the cancel listener routes through the idempotent
+   *  sweepIfCurrent, so re-entrancy is harmless. */
+  let flightAnims: Animation[] = [];
   /** The leaving cells this flight hid — unmarked on every sweep so a
    *  cancelled/dissolve-less path never leaves a stale hide mark. */
   let hidden: HTMLElement[] = [];
@@ -165,6 +209,12 @@ export function useRailIconFlight(
       clearTimeout(sweepTimer);
       sweepTimer = null;
     }
+    // Detach the ledger BEFORE cancelling: a synchronous cancel event
+    // (test stubs fire them inline; the browser queues them) re-enters
+    // sweep via the listener, and the emptied ledger breaks the cycle.
+    const anims = flightAnims;
+    flightAnims = [];
+    for (const anim of anims) anim.cancel();
     layer?.remove();
     layer = null;
     for (const el of hidden) el.removeAttribute(RAIL_FLIP_FLYING_ATTR);
@@ -247,28 +297,39 @@ export function useRailIconFlight(
     // column): the dissolve alone is already continuous — no layer.
     if (!pairs.some(({ from, to }) => from.left !== to.left || from.top !== to.top)) return;
 
-    // Timing: the flight mirrors the dissolve's window, widened by any
-    // enter hold the host choreographed (see KNOWN LIMIT above).
-    const delay = enterDelayMs(
-      getComputedStyle(host).getPropertyValue("--hk-crossfade-enter-delay"),
-    );
-    const flightMs = RAIL_FLIGHT_MS + delay;
+    // Timing is TOKEN-DERIVED: the flight window reads the theme's
+    // --duration-normal (the very variable the dissolve consumes), plus
+    // any enter hold the host choreographed. Both ends of the window
+    // therefore align with the entering fade without a single
+    // hard-coded mirror of the theme's number.
+    const vars = getComputedStyle(host);
+    const delay = cssDurationMs(vars.getPropertyValue("--hk-crossfade-enter-delay"));
+    const dissolveMs =
+      cssDurationMs(vars.getPropertyValue("--duration-normal")) || RAIL_FLIGHT_MS;
+    const flightMs = dissolveMs + delay;
+    const sweepMs = flightMs + RAIL_FLIGHT_SWEEP_MARGIN_MS;
 
     host.setAttribute(RAIL_FLIP_ACTIVE_ATTR, "");
     // The fallback sweep arms BEFORE any clone animates: a throwing
     // `animate` mid-loop must not strand the freshly hidden marks until
     // the next flip (2026-11-02 review).
-    // Stamp exactly the cells being substituted BEFORE any paint with the
-    // layer up: the hide rule reads this mark, so an opted-in cell
-    // without a clone partner keeps dissolving (2026-11-02 review S1-1).
+    // Stamp BOTH ends of every matched pair BEFORE any paint with the
+    // layer up — the single-glyph contract: the leaving cell hides
+    // because the clone substitutes it, and the ENTERING cell hides
+    // because the clone IS it until landing; two glyphs of one
+    // destination must never share a frame. Unmatched opted-in cells
+    // stay unmarked and dissolve (2026-11-02 review S1-1). The clone
+    // strips the mark again right after cloneNode, so the layer never
+    // hides its own citizens.
     for (const pair of pairs) {
       pair.fromEl.setAttribute(RAIL_FLIP_FLYING_ATTR, "");
-      hidden.push(pair.fromEl);
+      pair.template.setAttribute(RAIL_FLIP_FLYING_ATTR, "");
+      hidden.push(pair.fromEl, pair.template);
     }
     layer = document.createElement("div");
     layer.className = "hk-sidebar-rail-flight";
     layer.setAttribute("aria-hidden", "true");
-    sweepTimer = setTimeout(() => sweepIfCurrent(flightId), RAIL_FLIGHT_SWEEP_MS + delay);
+    sweepTimer = setTimeout(() => sweepIfCurrent(flightId), sweepMs);
     // The host's inline-start edge is the docked edge — a stable origin
     // in both directions (see the mechanism note above). Its draw scale
     // converts measured viewport px into the local px the layer's own
@@ -302,23 +363,27 @@ export function useRailIconFlight(
       clone.style.width = `${pair.from.width / scale.x}px`;
       clone.style.height = `${pair.from.height / scale.y}px`;
       clone.style.color = pair.color;
+      // Pure travel: full opacity the whole way, `fill: forwards` so a
+      // frame that slips past finish still shows the clone AT the
+      // landing rect (same-geometry overlap with the real icon reads
+      // as one glyph) instead of snapping back to the origin.
       const anim = clone.animate(
         [
-          { transform: "translate(0, 0)", opacity: "1" },
-          {
-            transform: `translate(${dx}px, ${dy}px)`,
-            opacity: "1",
-            offset: FLIGHT_HANDOFF_RATIO,
-          },
-          { transform: `translate(${dx}px, ${dy}px)`, opacity: "0" },
+          { transform: "translate(0, 0)" },
+          { transform: `translate(${dx}px, ${dy}px)` },
         ],
-        { duration: flightMs, easing: "cubic-bezier(0.22, 1, 0.36, 1)" },
+        {
+          duration: flightMs,
+          easing: "cubic-bezier(0.22, 1, 0.36, 1)",
+          fill: "forwards",
+        },
       );
       // Same duration on every clone: the first settle sweeps the
       // layer — but only while THIS flight is on stage (a replaced
       // flight's late finish is a no-op, never its successor's sweeper).
       anim.addEventListener("finish", () => sweepIfCurrent(flightId));
       anim.addEventListener("cancel", () => sweepIfCurrent(flightId));
+      flightAnims.push(anim);
       layer.appendChild(clone);
     }
     host.appendChild(layer);