@celestia-island/hikari 0.55.264 → 0.55.266

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.264",
+  "version": "0.55.266",
   "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/HkMenu.rail.test.tsx

@@ -7,6 +7,7 @@ import { createApp, h, nextTick, ref, type Ref } from "vue";
 import { Home, Settings } from "lucide-vue-next";
 
 import HkMenu, { type HkMenuItem } from "./HkMenu";
+import { RAIL_FLIP_ICON_ATTR } from "../composables/useRailIconFlight";
 
 /**
  * HkMenu sidebar-variant ICON-RAIL mode (collapsed prop, 2026-10-30):
@@ -418,6 +419,53 @@ describe("HkMenu sidebar icon rail", () => {
     expect(glyph.textContent).toBe("D");
   });
 
+  it("stamps every icon cell with data-flip-icon = the row key, in BOTH densities", () => {
+    // The rail flip's icon flight (useRailIconFlight) pairs the leaving
+    // and entering copies of ONE destination by this attribute; a cell
+    // missing it (or carrying the wrong key) silently drops that row out
+    // of the continuity choreography. All four render sites — expanded
+    // leaf + group toggle, rail leaf + rail group header — must stamp it.
+    // The selector is built from the composable's exported constant — the
+      // welding that turns a literal drift in HkMenu's JSX (or the JS
+      // pairing vocabulary) into a red test instead of a silently dead
+      // flight chain (2026-11-02 review).
+      const iconKeys = (root: ParentNode): string[] =>
+        [...root.querySelectorAll<HTMLElement>(`.hk-menu-item-icon[${RAIL_FLIP_ICON_ATTR}]`)].map((el) =>
+          el.getAttribute(RAIL_FLIP_ICON_ATTR) ?? "",
+        );
+
+    // An icon on the group exercises the group-toggle sites; the
+    // icon-less leaf exercises the asymmetry the flight tolerates: the
+    // rail renders a fallback cell for it (keyed!) while the expanded
+    // sidebar renders no cell at all — pairing needs BOTH ends, so that
+    // row dissolves instead of flying.
+    const FULL: HkMenuItem[] = [
+      { key: "home", label: "Home", icon: Home },
+      { key: "plain", label: "Docs" },
+      {
+        key: "admin",
+        label: "Administration",
+        icon: Settings,
+        children: [{ key: "users", label: "Users", icon: Home }],
+      },
+    ];
+
+    const expanded = mountMenu(FULL, { defaultExpandGroups: true });
+    expect(iconKeys(expanded), "expanded leaf + group toggle icons").toEqual([
+      "home",
+      "admin",
+      "users",
+    ]);
+
+    const collapsed = mountMenu(FULL, { collapsed: true, defaultExpandGroups: true });
+    expect(iconKeys(collapsed), "rail leaves + rail group header icons").toEqual([
+      "home",
+      "plain",
+      "admin",
+      "users",
+    ]);
+  });
+
   it("still selects from the rail (and stays disabled-aware)", () => {
     const selected: string[] = [];
     const container = document.createElement("div");

package/src/components/HkMenu.tsx

@@ -861,7 +861,12 @@ export default defineComponent({
             </span>
           )}
           {item.icon && (
-            <span class="hk-menu-item-icon">{h(item.icon, { size: 16 })}</span>
+            // data-flip-icon: the row key opts this cell into the rail
+            // flip's icon flight (useRailIconFlight) — the flight pairs
+            // the leaving and entering copies of ONE destination by it.
+            <span class="hk-menu-item-icon" data-flip-icon={item.key}>
+              {h(item.icon, { size: 16 })}
+            </span>
           )}
           {item.flag && <span class="hk-menu-flag">{item.flag}</span>}
           <span class="hk-menu-label">{item.label}</span>
@@ -890,8 +895,14 @@ export default defineComponent({
               toggleGroup(item.key);
             }}
           >
+            {/* The group toggle's glyph flies too — same key, same
+                pairing (the rail header centers the same group icon).
+                Still conditional: an icon-less group renders no cell
+                here, exactly as before. */}
             {item.icon && (
-              <span class="hk-menu-item-icon">{h(item.icon, { size: 16 })}</span>
+              <span class="hk-menu-item-icon" data-flip-icon={item.key}>
+                {h(item.icon, { size: 16 })}
+              </span>
             )}
             <span class="hk-menu-label">{item.label}</span>
             {item.badge && <span class="hk-menu-sidebar-badge">{item.badge}</span>}
@@ -956,8 +967,14 @@ export default defineComponent({
             }}
           >
             {/* Icon-less rows fall back to the label's initial — the rail
-                must never strand a destination behind a missing glyph. */}
-            <span class="hk-menu-item-icon" data-fallback={item.icon ? undefined : true}>
+                must never strand a destination behind a missing glyph.
+                data-flip-icon pairs this cell with the expanded row's
+                icon across the density flip (useRailIconFlight). */}
+            <span
+              class="hk-menu-item-icon"
+              data-flip-icon={item.key}
+              data-fallback={item.icon ? undefined : true}
+            >
               {item.icon ? h(item.icon, { size: 16 }) : item.label.trim().charAt(0).toUpperCase()}
             </span>
             {item.badge && (
@@ -1002,7 +1019,16 @@ export default defineComponent({
                 toggleGroup(item.key);
               }}
             >
-              <span class="hk-menu-item-icon" data-fallback={item.icon ? undefined : true}>
+              {/* The flight pairs the rail header's glyph with the
+                  expanded group toggle's icon by the group key. An
+                  icon-less group has no expanded cell to pair with, so
+                  its placeholder caret simply dissolves — pairing needs
+                  both ends, and the flight never invents one. */}
+              <span
+                class="hk-menu-item-icon"
+                data-flip-icon={item.key}
+                data-fallback={item.icon ? undefined : true}
+              >
                 {item.icon ? h(item.icon, { size: 16 }) : railCaret(expanded, 16)}
               </span>
               {item.icon && (

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

@@ -97,7 +97,23 @@
  * collapsed paddings used to lift the whole nav by up to two paddings'
  * worth on every flip; a band that needs a different vertical dress in
  * rail mode would have to move the base values for BOTH densities, never
- * add a per-density block padding. */
+ * add a per-density block padding.
+ *
+ * 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 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] {
   .hk-sidebar-header {
@@ -108,6 +124,10 @@
   .hk-sidebar-footer {
     padding: var(--space-16) var(--space-8);
   }
+
+  .hk-sidebar-body {
+    padding-inline: calc((var(--hk-sidebar-rail-w, 56px) - 34px) / 2);
+  }
 }
 
 .hk-sidebar[data-mobile] {

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

@@ -76,19 +76,25 @@ describe("HkSidebar scroll end-cap", () => {
 
   it("the density dress keeps every vertical metric at the expanded value", () => {
     // Vertical rhythm is density-invariant (2026-10-31 user direction:
-    // the collapse toggle must not move rows). The body therefore has no
-    // density rule AT ALL — the leading air AND the scroll tail ride the
-    // single base rule in both densities — and the header/footer dress
+    // the collapse toggle must not move rows). The body's ONLY density
+    // declaration is the rail row square's inline track (2026-11-02 user
+    // screenshot: the collapsed selected pill was a 32×34 oblong; the
+    // track narrows to 11px a side so the 100%-wide row fills exactly its
+    // 34px min-height square) — the leading air AND the scroll tail ride
+    // the single base rule in both densities, and the header/footer dress
     // rules keep the expanded BLOCK padding, narrowing only the inline
     // track for the rail column.
-    expect(css).not.toContain(".hk-sidebar[data-collapsed] .hk-sidebar-body");
-    expect(css).not.toContain(".hk-sidebar-rail-generation[data-rail] .hk-sidebar-body");
-    // The two carrier literals above are the compiled spellings; a brand
-    // NEW carrier (a third density hook) is a new dress and must re-run
-    // this contract — not mechanically foreseeable here.
     // ruleBody needs the arm its brace follows; the dress compiles to one
     // comma-grouped rule per band, so the generation arm is the one the
     // helper can read (the legacy arm shares its body).
+    const bodySquare = css.match(
+      /\.hk-sidebar\[data-collapsed\]\s*\.hk-sidebar-body[^{]*\{([^}]*)\}/,
+    );
+    expect(bodySquare, "the rail body inline-track rule exists").not.toBeNull();
+    expect(
+      bodySquare![1]!.trim(),
+      "the body dress is the row square's inline track ALONE — any block spelling here moves rows",
+    ).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)");
@@ -96,37 +102,84 @@ describe("HkSidebar scroll end-cap", () => {
     expect(footer, "the collapsed footer rule exists (grouped density carriers)").not.toBeNull();
     expect(footer).toContain("padding: var(--space-16) var(--space-8)");
     // The stronger, spelling-proof form (whole-dress scan): EVERY
-    // padding declaration in ANY dress rule must be EXACTLY the expanded
-    // two-track shorthand — 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 shorthand-only one; both
-    // green-holed earlier rounds. Physical `bottom` longhands are banned
-    // beside the logical ones. Horizontal-only tracks (padding-inline*)
-    // cannot match the value pin and are rejected the same way; a band
-    // that truly needs different block metrics must move the BASE rule
-    // for BOTH densities. Margins are banned outright — the bands
+    // 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 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
+    // shorthand-only one; both green-holed earlier rounds. Physical
+    // `bottom` longhands are banned beside the logical ones; an
+    // `padding-inline` on any NON-body rule is rejected the same way (a
+    // band that truly needs different block metrics must move the BASE
+    // rule for BOTH densities). Margins are banned outright — the bands
     // separate by their paddings alone — and so are the block-FLOW
     // metrics that move rows just the same (gap/row-gap/height/
     // min-height/max-height).
+    // Keyed on the carrier SUBSTRINGS, not their bracket spelling: a
+    // `[data-collapsed="true"]`-style variant of the same carrier must
+    // not slip the scan (2026-11-02 review: the exact-literal filter was
+    // a green hole). Boundary (restored): a brand-new carrier MECHANISM
+    // — a class-based hook or a third density attribute under a new
+    // name — is a new dress and must re-run this contract; not
+    // mechanically foreseeable here.
     const dressRules = css
       .split("}")
-      .filter((rule) => rule.includes("[data-collapsed]") || rule.includes("[data-rail]"));
+      .filter((rule) => rule.includes("data-collapsed") || rule.includes("data-rail"));
     expect(dressRules.length, "the density dress rules exist").toBeGreaterThan(1);
     for (const rule of dressRules) {
       for (const decl of rule.matchAll(
-        /\bpadding(?:-(?:top|bottom|block(?:-(?:start|end))?))?\s*:[^;}]*/g,
+        /\bpadding(?:-(?:top|bottom|block(?:-(?:start|end))?|inline(?:-(?:start|end))?))?\s*:[^;}]*/g,
       )) {
-        expect(
-          decl[0].trim(),
-          `a dress padding is not the expanded two-track shorthand: ${decl[0]}`,
-        ).toBe("padding: var(--space-16) var(--space-8)");
+        const text = decl[0].trim();
+        if (/^padding-inline/.test(text)) {
+          // Chunk-anchored, not chunk-containment: the chunk carries the
+          // rule's own selector before its "{" — requiring THE SELECTOR
+          // to be the body's is what actually confines the inline track
+          // to the body rule (a raw chunk toContain would pass on a
+          // neighbor's selector too — 2026-11-02 review).
+          const selector = rule.slice(0, rule.indexOf("{"));
+          expect(
+            selector,
+            `a dress inline track outside the body rule: ${rule}`,
+          ).toContain(".hk-sidebar-body");
+          expect(
+            text,
+            `a dress inline track drifted from the row square: ${text}`,
+          ).toBe("padding-inline: calc((var(--hk-sidebar-rail-w, 56px) - 34px) / 2)");
+        } else {
+          expect(
+            text,
+            `a dress padding is not the expanded two-track shorthand: ${text}`,
+          ).toBe("padding: var(--space-16) var(--space-8)");
+        }
       }
       expect(rule, `a margin crept into the dress: ${rule}`).not.toMatch(
         /\bmargin(?:-(?:top|bottom|block(?:-(?:start|end))?))?\s*:/,
       );
+      // block-FLOW metrics that move rows just the same (line-height
+      // already falls under the `height` alternative via the word
+      // boundary; the logical `block-size` family spelled out
+      // separately — "min-block-size" carries no "height" substring,
+      // 2026-11-02 review), plus the block-EDGE spellings a
+      // padding/margin scan cannot see (border-block-start-width and
+      // inset-block drifted rows while every padding check stayed
+      // green).
       expect(rule, `block-flow metric in the dress: ${rule}`).not.toMatch(
-        /\b(?:gap|row-gap|height|min-height|max-height)\s*:/,
+        /\b(?:gap|row-gap|height|min-height|max-height|(?:min-|max-)?block-size)\s*:/,
+      );
+      expect(rule, `block-edge border in the dress: ${rule}`).not.toMatch(/\bborder-block/);
+      expect(rule, `block-edge inset in the dress: ${rule}`).not.toMatch(/\binset-block/);
+      // The PHYSICAL block-edge borders: the lookbehind above deliberately
+      // spares "-top"/"-bottom" INSIDE longer words, which let
+      // `border-top-width: 6px` push every row below it down while every
+      // logical check stayed green (2026-11-02 review).
+      expect(rule, `physical block-edge border in the dress: ${rule}`).not.toMatch(
+        /\bborder-(?:top|bottom)\b/,
+      );
+      expect(rule, `physical block offset in the dress: ${rule}`).not.toMatch(
+        /(?<![-\w])(?:top|bottom)\s*:/,
       );
     }
   });

package/src/components/HkSidebar.tsx

@@ -29,7 +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. */
+     *  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 },
@@ -264,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

@@ -159,11 +159,70 @@
  * the host from STRETCHING, which would clip nothing but would invite
  * percentage-width content to follow the animation.) The generations
  * fill the swap's height so the bands' flex column (spacer, footer at
- * the bottom) behaves exactly as it did as a direct child of the clip. */
+ * the bottom) behaves exactly as it did as a direct child of the clip.
+ *
+ * position: relative makes the host the containing block for the rail
+ * flip's FLIGHT LAYER (useRailIconFlight). The host is the right stage
+ * for two reasons, each the inverse of the other's failure mode
+ * (2026-11-02 review): its inline-START edge is the docked edge
+ * `align-self: flex-start` pins — stable while only the inline-END edge
+ * tracks the animating clip width, in LTR and RTL alike (a physical
+ * left anchor would drift by the whole width increment in RTL); and it
+ * sits OUTSIDE both dissolving items, so the clones never inherit an
+ * item's enter fade (enter-from holds opacity 0 for the flight's first
+ * frames — an item-anchored clone blinks out exactly when it should
+ * substitute). Clone insets are written as LOGICAL offsets from the
+ * stable edge; see the composable. */
 .hk-sidebar-rail-clip > .hk-sidebar-rail-swap {
   flex: 1;
   min-height: 0;
   align-self: flex-start;
+  position: relative;
+}
+
+/* The flight layer + clones (see useRailIconFlight). The layer covers
+ * the host — the widest generation's footprint — so a clone never
+ * repositions relative to the animating panel; its own geometry is
+ * inline (the measured rects, written as LOGICAL insets from the
+ * stable inline-start edge). pointer-events stay dead: the layer is
+ * paint-only chrome above a pointer-dead dissolve. Clones keep
+ * inline-flex centering so the svg sits in the cell exactly as the real
+ * icon cell centers it. */
+.hk-sidebar-rail-flight {
+  position: absolute;
+  inset: 0;
+  z-index: 2;
+  display: block;
+  pointer-events: none;
+}
+
+.hk-sidebar-rail-flight-clone {
+  position: absolute;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin: 0;
+  pointer-events: none;
+  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] {
+  visibility: hidden;
 }
 
 .hk-sidebar-rail-swap .hk-sidebar-rail-generation {

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

@@ -5,6 +5,12 @@ import { fileURLToPath } from "node:url";
 import { compile } from "sass";
 import { describe, expect, it } from "vitest";
 
+import {
+  RAIL_FLIP_ACTIVE_ATTR,
+  RAIL_FLIP_FLYING_ATTR,
+  RAIL_FLIP_ICON_ATTR,
+} from "../composables/useRailIconFlight";
+
 /**
  * Sidebar rail + peek stylesheet contract (2026-10-30) — the shared
  * geometry behind HkFaceShell's sidebar, HkSidebar and bespoke hosts
@@ -145,6 +151,20 @@ describe("HkSidebarRail geometry contract", () => {
     expect(swap).toContain("flex: 1");
     expect(swap).toContain("min-height: 0");
     expect(swap).toContain("align-self: flex-start");
+    // The swap host IS the flight layer's containing block: its
+    // inline-start edge is the docked edge (stable in LTR and RTL while
+    // only the inline-END edge tracks the animating clip width), and it
+    // sits OUTSIDE both dissolving items — clones must not inherit an
+    // item's enter fade (enter-from holds opacity 0 for the flight's
+    // first frames; an item-anchored clone blinks out at arm time).
+    expect(swap).toContain("position: relative");
+    // The dissolving items must NOT become containing blocks: a
+    // relative item would put the clones inside the very opacity group
+    // the flight exists to bypass.
+    expect(
+      ruleBody(css, ".hk-sidebar-rail-swap .hk-crossfade-item"),
+      "the dissolve item must not become the clone's containing block",
+    ).toBeNull();
 
     // Each generation is the flex column the bands expect, filling the
     // swap's height (spacer + footer-at-bottom behave as they did as
@@ -226,6 +246,65 @@ 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", () => {
+    // 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
+    // layer rides above it) and it lives INSIDE the swap host, so the
+    // nobody-clips contract above is untouched.
+    const layer = ruleBody(css, ".hk-sidebar-rail-flight");
+    expect(layer, "the flight layer rule exists").not.toBeNull();
+    expect(layer).toContain("position: absolute");
+    expect(layer).toContain("inset: 0");
+    expect(layer).toContain("z-index: 2");
+    expect(layer).toContain("pointer-events: none");
+
+    const clone = ruleBody(css, ".hk-sidebar-rail-flight-clone");
+    expect(clone, "the clone rule exists").not.toBeNull();
+    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).
+    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
+    // 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",
+    ).toBeNull();
+  });
+
+  it("leaves no flight transition for reduced motion to kill (the flight is JS-driven)", () => {
+    // useRailIconFlight skips itself under prefers-reduced-motion, so the
+    // sheet must not grow CSS transitions for the layer/clone that the
+    // kit's reduced-motion block would then have to enumerate — a
+    // transition here would mean the choreography drifted into CSS.
+    const layer = ruleBody(css, ".hk-sidebar-rail-flight");
+    expect(layer).not.toContain("transition");
+    const clone = ruleBody(css, ".hk-sidebar-rail-flight-clone");
+    expect(clone).not.toContain("transition");
+  });
+
   it("kills every transition under reduced motion", () => {
     const reduceAt = css.indexOf("@media (prefers-reduced-motion: reduce)");
     expect(reduceAt, "the reduced-motion block exists").toBeGreaterThanOrEqual(0);

package/src/components/HkSidebarRailSwap.tsx

@@ -1,5 +1,6 @@
-import { defineComponent } from "vue";
+import { defineComponent, ref, type ComponentPublicInstance } from "vue";
 
+import { useRailIconFlight } from "../composables/useRailIconFlight";
 import HkCrossfade from "./HkCrossfade";
 
 import "./HkSidebarRail.scss";
@@ -77,6 +78,18 @@ import "./HkSidebarRail.scss";
  *   dissolve (HkCrossfade), so the frozen copy is neither tabbable nor
  *   announced while the live one fades in.
  *
+ * THE ICON FLIGHT (2026-11-02, useRailIconFlight): a pure dissolve
+ * cannot show the icons' small horizontal journey into the rail column —
+ * both copies fade, nothing moves (user direction: "I can't tell the
+ * 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
+ * animation switch / no WAAPI / no matching pair — every such case
+ * degrades to today's dissolve.
+ *
  * Reduced motion: HkCrossfade keeps a short opacity exchange (a fade
  * carries no movement) while the kit's sheets kill the width slides —
  * the handoff degrades to a quick dip, never a squeeze.
@@ -89,18 +102,28 @@ 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). */
+     *  `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. */
     expandedWidth: { type: String, default: "280px" },
   },
   setup(props, { slots }) {
+    // The swap host IS this component's root element — HkCrossfade's
+    // host div (class fallthrough). The component ref's $el reaches it
+    // without adding a wrapper (the clip's child combinator styles
+    // `.hk-sidebar-rail-clip > .hk-sidebar-rail-swap` directly).
+    const swapRef = ref<ComponentPublicInstance | null>(null);
+    const swapEl = (): HTMLElement | null => (swapRef.value?.$el as HTMLElement | null) ?? null;
+    useRailIconFlight(swapEl, () => props.rail, () => (props.rail ? "rail" : "full"));
     return () => (
       // The class rides HkCrossfade's host (Vue class fallthrough), so
       // HkSidebarRail.scss can size the swap INSIDE the clip without a
       // second wrapper element.
-      <HkCrossfade class="hk-sidebar-rail-swap" swapKey={props.rail ? "rail" : "full"} tag="div">
+      <HkCrossfade ref={swapRef} class="hk-sidebar-rail-swap" swapKey={props.rail ? "rail" : "full"} tag="div">
         <div
           class="hk-sidebar-rail-generation"
           data-rail={props.rail || undefined}