@celestia-island/hikari 0.55.265 → 0.55.267

package/package.json

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

package/src/components/HkFaceShell.rail.test.tsx

@@ -185,6 +185,10 @@ describe("HkFaceShell rail mode", () => {
 
     expect(c.aside().style.width).toBe("224px");
     expect(c.aside().getAttribute("data-rail")).toBeNull();
+    // The shell declares the rail width token for the rail row square's
+    // inline track (same contract as HkSidebar's collapsedWidth); the
+    // default rides the 56px fallback.
+    expect(c.aside().style.getPropertyValue("--hk-sidebar-rail-w")).toBe("56px");
     expect(c.toggle().getAttribute("aria-expanded")).toBe("true");
 
     c.toggle().click();
@@ -265,6 +269,10 @@ describe("HkFaceShell rail mode", () => {
 
   it("honors a configured rail width", async () => {
     const c = mountShell({ sidebarCollapsible: true, sidebarCollapsedWidth: "72px" });
+    expect(
+      c.aside().style.getPropertyValue("--hk-sidebar-rail-w"),
+      "a non-default collapsed width retunes the square track via the token",
+    ).toBe("72px");
     c.toggle().click();
     await vi.advanceTimersByTimeAsync(0);
     expect(c.aside().style.width).toBe("72px");

package/src/components/HkFaceShell.tsx

@@ -461,7 +461,14 @@ export const HkFaceShell = defineComponent({
                 // while THIS host's width transition plays — expanding must
                 // not replay the sidebar slide.
                 data-pinning={rail.pinning.value || undefined}
-                style={{ width: hostSidebarWidth.value, flexShrink: 0 }}
+                style={{
+                  width: hostSidebarWidth.value,
+                  flexShrink: 0,
+                  // The rail row square's inline track (HkSidebar.scss)
+                  // derives from this token, so a non-default
+                  // sidebarCollapsedWidth keeps producing exact squares.
+                  "--hk-sidebar-rail-w": props.sidebarCollapsedWidth,
+                }}
                 onPointerenter={onSidebarHostPointerEnter}
                 onPointerleave={rail.onPointerLeave}
                 onPointermove={onSidebarHostPointerMove}

package/src/components/HkSidebar.rail.test.tsx

@@ -95,6 +95,12 @@ describe("HkSidebar rail capability", () => {
     const c = mountSidebar({ width: "240px", collapsible: true, collapsedWidth: "64px" });
     expect(c.aside().className).toContain("hk-sidebar-rail-host");
     expect(c.aside().style.width).toBe("240px");
+    // The rail width travels to the sheet as a token: the rail row
+    // square's inline track (HkSidebar.scss) computes from it, so a
+    // non-default collapsedWidth keeps exact squares without a second
+    // edit. Deleting the declaration regresses non-56 hosts silently
+    // (the 56px fallback renders identically at the default).
+    expect(c.aside().style.getPropertyValue("--hk-sidebar-rail-w")).toBe("64px");
 
     c.toggle().click();
     await vi.advanceTimersByTimeAsync(0);

package/src/components/HkSidebar.scss

@@ -102,13 +102,17 @@
  * THE RAIL ROW SQUARE (2026-11-02 user screenshot: the collapsed
  * selected pill read as "not quite square — a bit squat"). The body's
  * inline track narrows so a rail row is EXACTLY its own min-height
- * square: the default 56px rail minus the menu-item grammar's 34px row
- * leaves 22px, 11px a side. The row spans its track (width: 100% in the
- * shared spec), so the hover/active pill fills 34×34 instead of the
- * 32×34 oblong a 12px track produced. INLINE ONLY: the block paddings —
- * the 20px leading air and the scroll tail — stay with the base rule, so
- * the vertical rhythm invariant above is untouched. The literal is
- * derived, not tunable: --hk-menu-item-min-h is declared ON each row (the
+ * square: the rail width minus the menu-item grammar's 34px row, half
+ * a side each. The row spans its track (width: 100% in the shared
+ * spec), so the hover/active pill fills 34×34 instead of the 32×34
+ * oblong a 12px track produced. INLINE ONLY: the block paddings — the
+ * 20px leading air and the scroll tail — stay with the base rule, so
+ * the vertical rhythm invariant above is untouched. The rail width
+ * travels as `--hk-sidebar-rail-w`, declared inline by both rail
+ * holders (HkSidebar's `collapsedWidth`, HkFaceShell's
+ * `sidebarCollapsedWidth`) — a host retuning the width keeps exact
+ * squares with no second edit. The 34px minuend stays a literal
+ * because --hk-menu-item-min-h is declared ON each row (the
  * custom-property trap), so this ancestor cannot compute from it. */
 .hk-sidebar[data-collapsed],
 .hk-sidebar-rail-generation[data-rail] {
@@ -122,7 +126,7 @@
   }
 
   .hk-sidebar-body {
-    padding-inline: 11px;
+    padding-inline: calc((var(--hk-sidebar-rail-w, 56px) - 34px) / 2);
   }
 }
 

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

@@ -94,7 +94,7 @@ describe("HkSidebar scroll end-cap", () => {
     expect(
       bodySquare![1]!.trim(),
       "the body dress is the row square's inline track ALONE — any block spelling here moves rows",
-    ).toBe("padding-inline: 11px;");
+    ).toBe("padding-inline: calc((var(--hk-sidebar-rail-w, 56px) - 34px) / 2);");
     const header = ruleBody(css, ".hk-sidebar-rail-generation[data-rail] .hk-sidebar-header");
     expect(header, "the collapsed header rule exists (grouped density carriers)").not.toBeNull();
     expect(header).toContain("padding: var(--space-16) var(--space-8)");
@@ -104,7 +104,8 @@ describe("HkSidebar scroll end-cap", () => {
     // The stronger, spelling-proof form (whole-dress scan): EVERY
     // padding declaration in ANY dress rule must be EXACTLY one of the
     // two sanctioned values — the expanded two-track shorthand (header/
-    // footer bands) or the body's square track — exact, not a prefix: a
+    // footer bands) or the body's token-derived square track — exact,
+    // not a prefix: a
     // three-track spelling (`padding: var(--space-16) var(--space-8)
     // var(--space-12)`) drifts the block END past a block-start-only
     // check, and a longhand (`padding-block-start:`) hides from a
@@ -146,7 +147,7 @@ describe("HkSidebar scroll end-cap", () => {
           expect(
             text,
             `a dress inline track drifted from the row square: ${text}`,
-          ).toBe("padding-inline: 11px");
+          ).toBe("padding-inline: calc((var(--hk-sidebar-rail-w, 56px) - 34px) / 2)");
         } else {
           expect(
             text,

package/src/components/HkSidebar.tsx

@@ -29,11 +29,10 @@ export default defineComponent({
      *  no peek, `collapsed` stays the plain presentational 56px rail. */
     collapsible: { type: Boolean, default: false },
     /** Layout width of the icon rail (the one-icon column). Mirrors the
-     *  56px this component always used for its collapsed mode.
-     *  COUPLING (2026-11-02): the rail row square in HkSidebar.scss
-     *  derives its body inline track from the DEFAULT — 56px rail − 34px
-     *  menu row = 11px a side. A non-56 rail re-flattens the selected
-     *  pill unless that track is retuned alongside. */
+     *  56px this component always used for its collapsed mode. Declared
+     *  to the sheet as `--hk-sidebar-rail-w` on this aside, so the rail
+     *  row square (HkSidebar.scss's body inline track) retunes with it —
+     *  any width yields exact 34px squares. */
     collapsedWidth: { type: String, default: "56px" },
     /** Hover dwell on the rail before the peek drawer opens, ms. */
     peekDelay: { type: Number, default: 400 },
@@ -268,7 +267,17 @@ export default defineComponent({
         // panel and the panel's inner widths snap while THIS host's width
         // transition plays — expanding must not replay the sidebar slide.
         data-pinning={rail.pinning.value || undefined}
-        style={props.mobile ? undefined : { width: hostWidth.value }}
+        style={
+          props.mobile
+            ? undefined
+            : {
+                width: hostWidth.value,
+                // The rail row square's inline track (HkSidebar.scss)
+                // derives from this token, so a non-default
+                // collapsedWidth keeps producing exact squares.
+                "--hk-sidebar-rail-w": props.collapsedWidth,
+              }
+        }
         onPointerenter={railChrome.value ? onHostPointerEnter : undefined}
         onPointerleave={railChrome.value ? rail.onPointerLeave : undefined}
         onPointermove={railChrome.value ? onHostPointerMove : undefined}

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

@@ -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

@@ -102,9 +102,10 @@ export default defineComponent({
     rail: { type: Boolean, default: false },
     /** Pinned width of the RAIL generation. The host's collapsed-width
      *  token (HkSidebar's `collapsedWidth`, the shell's
-     *  `sidebarCollapsedWidth`, wowsp's 56px). COUPLING (2026-11-02): the
-     *  rail row square in HkSidebar.scss derives from the 56px default —
-     *  a non-56 rail needs its body inline track retuned alongside. */
+     *  `sidebarCollapsedWidth`, wowsp's 56px). The rail row square's
+     *  body inline track reads the same width as
+     *  `--hk-sidebar-rail-w` — declared by the rail holder (HkSidebar /
+     *  HkFaceShell), so a non-default width keeps exact squares. */
     railWidth: { type: String, default: "56px" },
     /** Pinned width of the EXPANDED generation. The host's full sidebar
      *  width token — a CSS length or a var() reference. */

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,
@@ -32,7 +32,7 @@ import HkSidebarRailSwap from "../components/HkSidebarRailSwap";
  *
  * The assertions pin the choreography DECISIONS:
  * 1. A flip with moving keyed icons arms the flight: `data-flipping` on
- *    the swap host, a flight layer on the ENTERING item with one clone
+ *    the swap host, a flight layer ON THE HOST with one clone
  *    per PAIRED key, each clone painted at the leaving rect (logical
  *    insets relative to the stage) and animated by the signed delta.
  * 2. The pairing contract is visible: matched leaving cells carry the
@@ -202,24 +202,30 @@ afterEach(() => {
   for (const app of mounts.splice(0)) app.unmount();
   containers.splice(0).forEach((c) => c.remove());
   document.body.innerHTML = "";
+  // Restores every vi.spyOn (getComputedStyle / matchMedia / rect
+  // stubs) even when a test failed before its own inline restore —
+  // the probes recorded the leak as harmless, but the class is free
+  // to close.
+  vi.restoreAllMocks();
   vi.unstubAllGlobals();
   vi.useRealTimers();
   __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("garbage")).toBe(0);
+    expect(cssDurationMs("-5ms")).toBe(0);
   });
 });
 
 describe("useRailIconFlight", () => {
-  it("arms a flight on collapse: matched cells marked, layer on the entering item, clones at the leaving rects", async () => {
+  it("arms a flight on collapse: matched cells marked, layer on the swap host, clones at the leaving rects", async () => {
     const h = mountSwap();
     await h.set(true);
     // Expanded geometry: icon cells at x=32 (the leading padding column).
@@ -243,13 +249,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")!;
@@ -257,14 +273,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 () => {
@@ -341,7 +402,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;
 
@@ -455,9 +516,17 @@ 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.
+    // 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);
   });
 
@@ -471,7 +540,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,11 @@ 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.
  */
 
 /** Row-key attribute on an icon cell that flies across a rail flip. */
@@ -94,24 +109,31 @@ 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). */
+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;
 }
 
+/** Back-compat alias: HkCrossfade's enter hold parses like any duration. */
+export const enterDelayMs = cssDurationMs;
+
 /** 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). */
@@ -247,28 +269,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,17 +335,20 @@ 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