@celestia-island/hikari 0.55.236 → 0.55.237

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.236",
+  "version": "0.55.237",
   "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

@@ -424,6 +424,41 @@ describe("HkFaceShell rail chrome: toggle placement and the clip wrapper", () =>
     expect(clip!.querySelector(".sidebar-mock"), "the sidebar slot renders in the clip").toBeTruthy();
   });
 
+  it("hands the sidebar slot to the rail/full generations through the SWAP", async () => {
+    // The density dress rides the swap's GENERATION, never the host root:
+    // a root-level data-rail would restyle the frozen leaving generation
+    // mid-dissolve and reintroduce the squeeze this wave fixes. The root
+    // keeps data-rail as a STATE MARKER only (hosts/tests read it).
+    vi.useFakeTimers();
+    vi.stubGlobal("requestAnimationFrame", () => 0 as unknown as number);
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+    const c = mountShell({ sidebarCollapsible: true });
+    const clip = () =>
+      c.panel().querySelector(":scope > .hk-sidebar-rail-clip") as HTMLElement;
+    const gens = () =>
+      Array.from(clip().querySelectorAll<HTMLElement>(".hk-sidebar-rail-generation"));
+
+    expect(clip().querySelector(".hk-sidebar-rail-swap"), "the swap mounts inside the clip").toBeTruthy();
+    expect(gens()).toHaveLength(1);
+    expect(gens()[0]!.hasAttribute("data-rail"), "expanded carries no rail density").toBe(false);
+    expect(gens()[0]!.style.width, "the generation pins the shell's sidebar width").toBe("224px");
+    expect(c.aside().hasAttribute("data-rail")).toBe(false);
+
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(100); // mid-dissolve
+    const mid = gens();
+    expect(mid.length, "both generations share the swap's cell").toBe(2);
+    expect(mid[0]!.hasAttribute("data-rail"), "the leaving copy keeps the full dress").toBe(false);
+    expect(mid[0]!.style.width).toBe("224px");
+    expect(mid[1]!.hasAttribute("data-rail"), "the entering copy takes the rail dress").toBe(true);
+    expect(mid[1]!.style.width, "the rail generation pins the collapsed width").toBe("56px");
+    // The slot ran for the entering generation at its density; the root
+    // marker reads rail while the DENSITY lives on the generation.
+    expect(c.slotParams[c.slotParams.length - 1]!.collapsed).toBe(true);
+    expect(c.aside().hasAttribute("data-rail"), "the root keeps the state marker").toBe(true);
+    vi.unstubAllGlobals();
+  });
+
   it("does not touch the legacy sidebar path (no clip wrapper, no rail classes)", () => {
     const c = mountShell();
     expect(c.container.querySelector(".hk-sidebar-rail-clip")).toBeFalsy();

package/src/components/HkFaceShell.tsx

@@ -2,6 +2,7 @@ import { computed, defineComponent, ref, watch, type PropType } from "vue";
 import { HkCrossfade, HDrawer, HScrollContainer, useBreakpoint } from "@celestia-island/hikari";
 import { useI18n } from "../i18n/context";
 import { useSidebarRail } from "../composables/useSidebarRail";
+import HkSidebarRailSwap from "./HkSidebarRailSwap";
 import HkSidebarRailToggle, { isPointerOverRailToggle } from "./HkSidebarRailToggle";
 
 /** CSS-wide keywords. A shorthand rebuilt from one of them is NOT a
@@ -435,6 +436,10 @@ export const HkFaceShell = defineComponent({
               <aside
                 ref={railHostRef}
                 class="hk-sidebar-rail-host"
+                // STATE marker only (hosts/tests read "the rail layout is
+                // active"): the rail DENSITY dress itself rides the swap's
+                // generation inside the clip, so it can freeze on the
+                // leaving generation during the dissolve.
                 data-rail={railActive.value || undefined}
                 data-peeking={rail.peeking.value || undefined}
                 // Transient rail -> expanded window (useSidebarRail.pinning):
@@ -466,13 +471,29 @@ export const HkFaceShell = defineComponent({
                       border), so the slot's content clips inside this
                       wrapper — full rows stay inside rail width while the
                       panel width animates. The toggle stays a DIRECT child
-                      of the panel: it must never be clipped. */}
+                      of the panel: it must never be clipped. Inside the
+                      clip, the crossfade handoff (HkSidebarRailSwap)
+                      exchanges the rail and full generations through the
+                      tab-panel dissolve at width-pinned boxes, so the
+                      slot's content never re-lays-out at the panel's
+                      transient width — each generation sees its own
+                      `collapsed` dress, and the leaving copy stays
+                      frozen (and unclickable) while it dissolves. */}
                   <div class="hk-sidebar-rail-clip">
-                    {slots.sidebar({
-                      collapsed: railActive.value && !rail.peeking.value,
-                      onNavigate: onSidebarNavigate,
-                      peeking: rail.peeking.value,
-                    })}
+                    <HkSidebarRailSwap
+                      rail={railActive.value && !rail.peeking.value}
+                      railWidth={props.sidebarCollapsedWidth}
+                      expandedWidth={props.sidebarWidth}
+                    >
+                      {/* NOT `rail` — the scoped param would shadow the
+                          useSidebarRail handle the outer bindings read. */}
+                      {({ rail: density }: { rail: boolean }) =>
+                        slots.sidebar?.({
+                          collapsed: density,
+                          onNavigate: onSidebarNavigate,
+                          peeking: rail.peeking.value,
+                        })}
+                    </HkSidebarRailSwap>
                   </div>
                   <HkSidebarRailToggle expanded={!railActive.value} onToggle={rail.toggle} />
                 </div>

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

@@ -53,6 +53,11 @@ function mountSidebar(props: Record<string, unknown> = {}) {
     aside: () => container.querySelector("aside.hk-sidebar") as HTMLElement,
     panel: () => container.querySelector("nav.hk-sidebar-panel") as HTMLElement,
     toggle: () => container.querySelector(".hk-sidebar-rail-toggle button") as HTMLButtonElement,
+    // The ACTIVE (entering/settled) generation of the rail swap — the
+    // last-mounted one; during a dissolve there are two.
+    generation: () =>
+      container.querySelectorAll<HTMLElement>(".hk-sidebar-rail-generation"),
+    swap: () => container.querySelector(".hk-sidebar-rail-swap") as HTMLElement,
   };
 }
 
@@ -91,7 +96,13 @@ describe("HkSidebar rail capability", () => {
     await vi.advanceTimersByTimeAsync(0);
     expect(c.aside().style.width).toBe("64px");
     expect(c.panel().style.width).toBe("64px");
-    expect(c.aside().hasAttribute("data-collapsed")).toBe(true);
+    // The density moved OFF the root onto the swap's generation: a root
+    // attribute flips with the state and would restyle the frozen
+    // leaving generation mid-dissolve (the squeeze this wave fixes).
+    expect(c.aside().hasAttribute("data-collapsed"), "the rail-mode root never carries the density").toBe(false);
+    expect(c.generation().length).toBeGreaterThan(0);
+    expect(c.generation()[c.generation().length - 1]!.hasAttribute("data-rail"), "the generation carries the rail density").toBe(true);
+    expect(c.generation()[c.generation().length - 1]!.style.width).toBe("64px");
   });
 
   it("peeks as an overlay: the host width never moves", async () => {
@@ -117,13 +128,13 @@ describe("HkSidebar rail capability", () => {
     await vi.advanceTimersByTimeAsync(0);
     expect(c.slotParams[c.slotParams.length - 1]!.collapsed).toBe(true);
     expect(c.slotParams[c.slotParams.length - 1]!.peeking).toBe(false);
-    expect(c.aside().hasAttribute("data-collapsed"), "rail density while collapsed").toBe(true);
+    expect(c.generation()[c.generation().length - 1]!.hasAttribute("data-rail"), "rail density while collapsed").toBe(true);
 
     c.aside().dispatchEvent(new Event("pointerenter"));
     await vi.advanceTimersByTimeAsync(400);
     expect(c.slotParams[c.slotParams.length - 1]!.collapsed, "full rows during the peek").toBe(false);
     expect(c.slotParams[c.slotParams.length - 1]!.peeking).toBe(true);
-    expect(c.aside().hasAttribute("data-collapsed"), "no rail density on the peek panel").toBe(false);
+    expect(c.generation()[c.generation().length - 1]!.hasAttribute("data-rail"), "no rail density on the peek generation").toBe(false);
 
     // closePeek (the nav-row hook) closes the drawer.
     c.slotParams[c.slotParams.length - 1]!.closePeek();
@@ -198,11 +209,38 @@ describe("HkSidebar rail chrome: toggle placement and the clip wrapper", () => {
     expect(clip, "the content clip lives inside the panel").toBeTruthy();
     expect(toggle, "the toggle is a direct child of the panel").toBeTruthy();
     expect(clip!.contains(toggle!), "the toggle is NOT clipped by the wrapper").toBe(false);
-    // The bands (header/body/footer) are inside the clip.
+    // The bands (header/body/footer) are inside the clip — now inside the
+    // swap's generation, one per density.
     expect(clip!.querySelector(".hk-sidebar-body")).toBeTruthy();
+    expect(clip!.querySelector(".hk-sidebar-rail-swap")).toBeTruthy();
     expect(clip!.contains(c.aside())).toBe(false);
   });
 
+  it("collapses through the SWAP: both densities coexist, each pinned at its own width", async () => {
+    // Freeze rAF to hold the dissolve mid-flight (HkCrossfade.test's
+    // timing model): the leaving FULL generation stays frozen at its
+    // dress and width while the entering RAIL generation takes over —
+    // no generation ever renders at the panel's transient width.
+    vi.useFakeTimers();
+    vi.stubGlobal("requestAnimationFrame", () => 0 as unknown as number);
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+    const c = mountSidebar({ width: "240px", collapsible: true, collapsedWidth: "64px" });
+
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(100);
+
+    const gens = c.generation();
+    expect(gens.length, "both generations share the swap's cell mid-dissolve").toBe(2);
+    const [leaving, entering] = gens;
+    expect(leaving!.hasAttribute("data-rail"), "the leaving copy keeps the full dress").toBe(false);
+    expect(leaving!.style.width).toBe("240px");
+    expect(entering!.hasAttribute("data-rail"), "the entering copy takes the rail dress").toBe(true);
+    expect(entering!.style.width).toBe("64px");
+    // The band content lives inside the entering generation.
+    expect(entering!.querySelector(".hk-sidebar-body")).toBeTruthy();
+    vi.unstubAllGlobals();
+  });
+
   it("renders the legacy panel with NO clip wrapper (byte-identical non-rail path)", () => {
     const legacy = mountSidebar({ width: "240px" });
     expect(legacy.panel().querySelector(".hk-sidebar-rail-clip")).toBeFalsy();
@@ -293,7 +331,7 @@ describe("HkSidebar hover suppression: a pointer on the toggle never peeks", ()
     c.aside().dispatchEvent(pointerMove(110, 210));
     await vi.advanceTimersByTimeAsync(400 * 4);
     expect(c.aside().hasAttribute("data-peeking"), "parked on the toggle: no peek").toBe(false);
-    expect(c.aside().hasAttribute("data-collapsed")).toBe(true);
+    expect(c.generation()[c.generation().length - 1]!.hasAttribute("data-rail")).toBe(true);
 
     // Moving off the toggle (still on the rail) re-arms the normal dwell.
     c.aside().dispatchEvent(pointerMove(400, 500));
@@ -314,7 +352,7 @@ describe("HkSidebar hover suppression: a pointer on the toggle never peeks", ()
     c.aside().dispatchEvent(pointerEnterAt(110, 210));
     await vi.advanceTimersByTimeAsync(400 * 4);
     expect(c.aside().hasAttribute("data-peeking"), "enter on the toggle arms nothing").toBe(false);
-    expect(c.aside().hasAttribute("data-collapsed")).toBe(true);
+    expect(c.generation()[c.generation().length - 1]!.hasAttribute("data-rail")).toBe(true);
   });
 
   it("evaluates suppression on ENTER: entering elsewhere on the rail still peeks", async () => {

package/src/components/HkSidebar.scss

@@ -77,7 +77,15 @@
   flex-shrink: 0;
 }
 
-.hk-sidebar[data-collapsed] {
+/* The rail density dress, keyed off EITHER density carrier: the legacy
+ * presentational rail (no collapsible prop — the attr rides the root,
+ * instant, no animation to mask) or the swapped GENERATION of the rail
+ * kit (HkSidebarRailSwap) — the generation's [data-rail] flips with the
+ * swap key, so the leaving generation keeps its dress for the dissolve
+ * while the entering one takes the new one. A root-level attr cannot do
+ * that: it would restyle the frozen leaving copy mid-dissolve. */
+.hk-sidebar[data-collapsed],
+.hk-sidebar-rail-generation[data-rail] {
   .hk-sidebar-header {
     justify-content: center;
     padding: var(--space-12) var(--space-8);

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

@@ -75,8 +75,14 @@ describe("HkSidebar scroll end-cap", () => {
   });
 
   it("keeps the same tail on the collapsed body", () => {
-    const body = ruleBody(css, ".hk-sidebar[data-collapsed] .hk-sidebar-body");
-    expect(body, "the collapsed body rule exists").not.toBeNull();
+    // The density dress is keyed off EITHER carrier — the legacy root's
+    // [data-collapsed] or the rail swap generation's [data-rail] (the
+    // generation attr freezes on the leaving copy for the dissolve, a
+    // root attr cannot). ruleBody needs the arm its brace follows, so the
+    // legacy arm is asserted as text and the body read from the group.
+    expect(css).toContain(".hk-sidebar[data-collapsed] .hk-sidebar-body");
+    const body = ruleBody(css, ".hk-sidebar-rail-generation[data-rail] .hk-sidebar-body");
+    expect(body, "the collapsed body rule exists (grouped density carriers)").not.toBeNull();
     expect(body).toContain("padding-block: var(--space-12) var(--hk-sidebar-scroll-tail)");
   });
 

package/src/components/HkSidebar.tsx

@@ -3,6 +3,7 @@ import { computed, defineComponent, onBeforeUnmount, onMounted, ref, watch } fro
 import "./HkSidebar.scss";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { useSidebarRail } from "../composables/useSidebarRail";
+import HkSidebarRailSwap from "./HkSidebarRailSwap";
 import HkSidebarRailToggle, { isPointerOverRailToggle } from "./HkSidebarRailToggle";
 
 export default defineComponent({
@@ -76,6 +77,11 @@ export default defineComponent({
           : props.collapsed,
     );
     const peeking = computed(() => props.collapsible && !props.mobile && rail.peeking.value);
+    // The rail DENSITY (icon-only dress): collapsed layout, not peeking.
+    // In rail mode this is the swap key — the density rides the swapped
+    // GENERATION (frozen on the leaving copy for the dissolve), never the
+    // host root, so nothing re-lays-out at the panel's transient width.
+    const railDensity = computed(() => layoutCollapsed.value && !peeking.value);
     // The host's inline width IS the layout footprint — rail width while
     // collapsed OR peeking (the peek is an overlay; the layout must not
     // shift), full width while expanded.
@@ -88,21 +94,39 @@ export default defineComponent({
       props.mobile ? undefined : layoutCollapsed.value && !peeking.value ? props.collapsedWidth : props.width,
     );
 
-    // Persistent layout surface — attach the overlay scrollbar (shared
-    // chrome) once and detach on unmount.
+    // Persistent layout surface — the overlay scrollbar (shared chrome)
+    // attaches to the scrolling body band. The rail swap mounts each
+    // generation's body FRESH (the leaving copy is frozen and unmounts
+    // with the dissolve), so the attach is a re-attach. Mechanism
+    // notes (probed against Vue 3.5): a flip patches the refs
+    // old -> null -> new in sequence — the unmount of the leaving copy
+    // nulls the shared ref before the entering copy's mount re-points
+    // it — so the guard below swallows the transient null and the FINAL
+    // state always lands on the entering body. The element tracker keeps
+    // a same-element watcher fire a no-op (no track churn on plain
+    // re-renders); a flip hands the single handle to the new body, which
+    // leaves the fading copy without a track for the dissolve — it is
+    // pointer-dead and dissolving, so that is cosmetic.
     const bodyRef = ref<HTMLElement>();
     // Positioned wrapper containing ONLY the body — the rail host (the
     // panel also contains the header/footer bands).
     const bodyWrapRef = ref<HTMLElement>();
     let bodyScrollbar: OverlayScrollbarHandle | null = null;
+    let bodyScrollbarEl: HTMLElement | null = null;
 
-    onMounted(() => {
+    const attachBodyScrollbar = () => {
       if (!bodyRef.value) return;
+      if (bodyScrollbar && bodyScrollbarEl === bodyRef.value) return;
+      bodyScrollbar?.detach();
+      bodyScrollbarEl = bodyRef.value;
       bodyScrollbar = attachOverlayScrollbars(bodyRef.value, {
         axis: "vertical",
         host: bodyWrapRef.value,
       });
-    });
+    };
+
+    onMounted(attachBodyScrollbar);
+    watch([bodyRef, bodyWrapRef], attachBodyScrollbar);
 
     onBeforeUnmount(() => {
       bodyScrollbar?.detach();
@@ -142,27 +166,32 @@ export default defineComponent({
       rail.endPinning();
     };
 
-    /** The panel's inner bands. In rail mode they live inside
-     *  .hk-sidebar-rail-clip — the rail panel no longer clips (the toggle
-     *  straddles its content-facing border), so the wrapper is what keeps
-     *  full-width rows inside the 56px footprint while widths animate.
-     *  Without rail chrome they stay direct children of the panel, exactly
-     *  as before (and the toggle is a direct child of the panel in both
-     *  cases where it exists, so it can never be clipped). */
-    const renderBands = () => (
+    /** The panel's inner bands, parameterized by the density so the
+     *  rail swap can render each generation at its OWN dress: the swap
+     *  invokes this with the entering generation's flag while the leaving
+     *  copy stays frozen at its last render (per-generation density by
+     *  construction). In rail mode the bands live inside the swap, which
+     *  lives inside .hk-sidebar-rail-clip — the rail panel no longer
+     *  clips (the toggle straddles its content-facing border), so the
+     *  wrapper is what keeps full-width rows inside the 56px footprint
+     *  while widths animate. Without rail chrome they stay direct
+     *  children of the panel, exactly as before (and the toggle is a
+     *  direct child of the panel in both cases where it exists, so it
+     *  can never be clipped). */
+    const renderBands = (collapsed: boolean) => (
       <>
         {slots.header ? (
           <header class="hk-sidebar-header">{slots.header()}</header>
         ) : null}
         <div ref={bodyWrapRef} class="hk-sidebar-body-wrap">
           <div ref={bodyRef} class="hk-sidebar-body">
-            {/* Scoped params (ignored by plain slots): the LIVE rail
-                state so a host renders icon-only rows while collapsed
-                and full rows during a peek, plus the peek closer — a
-                nav row click should dismiss the peek like the shell's
-                onNavigate does. */}
+            {/* Scoped params (ignored by plain slots): the density that
+                owns THIS generation so a host renders icon-only rows
+                while collapsed and full rows during a peek, plus the
+                peek closer — a nav row click should dismiss the peek
+                like the shell's onNavigate does. */}
             {slots.default?.({
-              collapsed: layoutCollapsed.value && !peeking.value,
+              collapsed,
               peeking: peeking.value,
               closePeek: rail.closePeek,
             })}
@@ -179,10 +208,13 @@ export default defineComponent({
         ref={hostRef}
         class={railChrome.value ? "hk-sidebar hk-sidebar-rail-host" : "hk-sidebar"}
         data-mobile={props.mobile || undefined}
-        // NOT during a peek: [data-collapsed] carries the rail density
-        // (centered header, tight paddings) and the peek renders FULL
-        // rows at full width — the collapsed dress would mis-style it.
-        data-collapsed={layoutCollapsed.value && !peeking.value || undefined}
+        // LEGACY density carrier only (no rail chrome): [data-collapsed]
+        // styles the presentational 56px rail exactly as before. In rail
+        // mode the density moves onto the swap's GENERATION — a root-level
+        // attribute flips with the state and would restyle the frozen
+        // leaving generation mid-dissolve (the squeeze this wave fixes),
+        // and a peek renders full rows at full width anyway.
+        data-collapsed={!railChrome.value && railDensity.value || undefined}
         data-peeking={peeking.value || undefined}
         // Transient rail -> expanded window (useSidebarRail.pinning): the
         // panel and the panel's inner widths snap while THIS host's width
@@ -211,9 +243,23 @@ export default defineComponent({
           style={{ width: props.mobile ? undefined : panelWidth.value }}
         >
           {railChrome.value ? (
-            <div class="hk-sidebar-rail-clip">{renderBands()}</div>
+            /* The crossfade handoff (HkSidebarRailSwap): each generation
+             * renders the bands at its OWN dress and width while the clip
+             * windows the panel's animating width — no reflow, no wrap,
+             * a pure opacity exchange (the tab-panel dissolve). */
+            <div class="hk-sidebar-rail-clip">
+              <HkSidebarRailSwap
+                rail={railDensity.value}
+                railWidth={props.collapsedWidth}
+                expandedWidth={props.width}
+              >
+                {/* NOT `rail` — the scoped param would shadow the
+                    useSidebarRail handle the outer bindings read. */}
+                {({ rail: density }: { rail: boolean }) => renderBands(density)}
+              </HkSidebarRailSwap>
+            </div>
           ) : (
-            renderBands()
+            renderBands(railDensity.value)
           )}
           {railChrome.value && (
             <HkSidebarRailToggle

package/src/components/HkSidebarRail.scss

@@ -20,6 +20,16 @@
  *                           itself cannot clip any more (see below), so
  *                           this wrapper preserves the rail-width clip
  *                           during the width transitions.
+ *   .hk-sidebar-rail-swap   the rail/full handoff inside the clip
+ *                           (HkSidebarRailSwap): two width-pinned
+ *                           generations exchanged through HkCrossfade's
+ *                           opacity dissolve, so no content ever reflows
+ *                           at the panel's transient width.
+ *   .hk-sidebar-rail-generation  ONE density's content (rail or full),
+ *                           width-pinned inline by the component; the
+ *                           active density carries [data-rail] HERE (never
+ *                           on the host root — a root attr would restyle
+ *                           the frozen leaving generation mid-dissolve).
  *   .hk-sidebar-rail-toggle the hover-reveal circular chevron button
  *                           (HkSidebarRailToggle) STRADDLING the panel's
  *                           content-facing border — its center ON the
@@ -129,6 +139,40 @@
   overflow: hidden;
 }
 
+/* ── the swap: crossfade handoff between rail and full generations ────
+ * (HkSidebarRailSwap, user direction 2026-10-30.) The clip windows; the
+ * swap keeps every generation at its ORIGINAL width so nothing reflows
+ * while the panel's width animates; HkCrossfade (the tab-panel dissolve)
+ * exchanges the two generations through pure opacity. The leaving
+ * generation is frozen at its last render and drops pointer events for
+ * the dissolve (HkCrossfade's leave rule).
+ *
+ * The no-reflow pin, precisely: the generations carry their widths
+ * INLINE (the component), and the grid inside (HkCrossfade's one-cell
+ * stack) sizes its auto track to max-content — a track that NEVER
+ * shrinks below the widest mounted generation when the container runs
+ * narrower — so both generations lay out at their OWN widths however
+ * wide the clip currently is. (The swap host itself DOES track the
+ * animating clip width — a non-stretched flex child's fit-content is
+ * clamped by the available space — which is fine: the host box is not
+ * the layout reference for anything inside it. align-self simply keeps
+ * 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. */
+.hk-sidebar-rail-clip > .hk-sidebar-rail-swap {
+  flex: 1;
+  min-height: 0;
+  align-self: flex-start;
+}
+
+.hk-sidebar-rail-swap .hk-sidebar-rail-generation {
+  height: 100%;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+}
+
 /* The peek's only shadow: cast toward the content side. Offsets cannot
  * flip via logical properties — mirror the cast in RTL (the house
  * [dir="rtl"] override HkSidebar's mobile panel uses). */

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

@@ -131,6 +131,31 @@ describe("HkSidebarRail geometry contract", () => {
     expect(clip).toContain("flex-direction: column");
   });
 
+  it("the swap holds every generation at its OWN width (the no-reflow pin)", () => {
+    // The crossfade handoff (HkSidebarRailSwap): the generations carry
+    // their widths INLINE and HkCrossfade's auto track never shrinks
+    // below the widest mounted generation, so neither generation is ever
+    // laid out at the panel's transient width while it animates — the
+    // structural guarantee behind "content is never squeezed". The swap
+    // host itself only needs to not STRETCH with the animating clip
+    // (align-self): the host box is not the layout reference for the
+    // generations inside it.
+    const swap = ruleBody(css, ".hk-sidebar-rail-clip > .hk-sidebar-rail-swap");
+    expect(swap, "the swap sizing rule exists").not.toBeNull();
+    expect(swap).toContain("flex: 1");
+    expect(swap).toContain("min-height: 0");
+    expect(swap).toContain("align-self: flex-start");
+
+    // Each generation is the flex column the bands expect, filling the
+    // swap's height (spacer + footer-at-bottom behave as they did as
+    // direct children of the clip).
+    const gen = ruleBody(css, ".hk-sidebar-rail-swap .hk-sidebar-rail-generation");
+    expect(gen, "the generation rule exists").not.toBeNull();
+    expect(gen).toContain("height: 100%");
+    expect(gen).toContain("display: flex");
+    expect(gen).toContain("flex-direction: column");
+  });
+
   it("straddles the panel border: half the toggle outside, center on the border line", () => {
     const toggle = ruleBody(css, ".hk-sidebar-rail-toggle");
     expect(toggle, "the toggle rule exists").not.toBeNull();

package/src/components/HkSidebarRailSwap.test.tsx

@@ -0,0 +1,254 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref, type App } from "vue";
+
+import HkSidebarRailSwap from "./HkSidebarRailSwap";
+import { CROSSFADE_WATCHDOG_MS } from "./HkCrossfade";
+
+/**
+ * HkSidebarRailSwap contract (2026-10-30) — the rail/full content handoff.
+ *
+ * What this file pins:
+ *
+ * 1. WIDTH PINS: each generation renders at ITS density's width (the
+ *    rail/expanded props) with the density attribute (`data-rail`) on the
+ *    GENERATION — never the host root — so the leaving generation keeps
+ *    its dress while the entering one takes the new one.
+ * 2. THE DISSOLVE is HkCrossfade's simultaneous exchange (the tab-panel
+ *    mechanism): mid-swap both generations share the swap's single grid
+ *    cell, the leaving copy frozen at its last render and pointer-dead.
+ * 3. The scoped `{ rail }` slot param: the entering generation is invoked
+ *    with the new value; the leaving one keeps what it last rendered.
+ * 4. A healthy swap settles on exactly one generation.
+ *
+ * Timing model: identical to HkCrossfade.test — happy-dom resolves no CSS
+ * transition durations, so a working rAF completes the swap inside
+ * fake-timer advances, and freezing rAF holds both generations mounted.
+ */
+
+const mounts: App[] = [];
+const containers: HTMLElement[] = [];
+
+interface SwapSlotParams {
+  rail: boolean;
+}
+
+interface Harness {
+  container: HTMLElement;
+  swap(): HTMLElement;
+  generations(): HTMLElement[];
+  params: SwapSlotParams[];
+  set(rail: boolean): Promise<void>;
+}
+
+function mountSwap(opts: { rail?: boolean; railWidth?: string; expandedWidth?: string } = {}): Harness {
+  const params: SwapSlotParams[] = [];
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const rail = ref(opts.rail ?? false);
+  const Wrapper = defineComponent({
+    name: "RailSwapHarness",
+    setup() {
+      return () =>
+        h(
+          HkSidebarRailSwap,
+          {
+            rail: rail.value,
+            railWidth: opts.railWidth ?? "56px",
+            expandedWidth: opts.expandedWidth ?? "240px",
+          },
+          {
+            default: (p: SwapSlotParams) => {
+              params.push(p);
+              return h("p", { class: "body" }, p.rail ? "RAIL" : "FULL");
+            },
+          },
+        );
+    },
+  });
+  const app = createApp(Wrapper);
+  mounts.push(app);
+  app.mount(container);
+  return {
+    container,
+    swap: () => container.querySelector(".hk-sidebar-rail-swap") as HTMLElement,
+    generations: () =>
+      Array.from(container.querySelectorAll<HTMLElement>(".hk-sidebar-rail-generation")),
+    params,
+    set: async (v: boolean) => {
+      rail.value = v;
+      await nextTick();
+    },
+  };
+}
+
+function freezeRaf(): void {
+  vi.stubGlobal("requestAnimationFrame", (_cb: FrameRequestCallback) => 0 as unknown as number);
+  vi.stubGlobal("cancelAnimationFrame", () => {});
+}
+
+afterEach(() => {
+  for (const app of mounts) app.unmount();
+  mounts.length = 0;
+  document.body.innerHTML = "";
+  containers.length = 0;
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+describe("HkSidebarRailSwap — generation contract", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  it("renders the active generation silently on first paint, pinned at its width", () => {
+    const c = mountSwap({ railWidth: "56px", expandedWidth: "240px" });
+    // The swap host IS HkCrossfade's host — class fallthrough merges them.
+    expect(c.swap().classList.contains("hk-crossfade")).toBe(true);
+
+    const gens = c.generations();
+    expect(gens).toHaveLength(1);
+    expect(gens[0]!.style.width).toBe("240px");
+    expect(gens[0]!.hasAttribute("data-rail"), "expanded carries no rail density").toBe(false);
+    expect(c.params[c.params.length - 1]!.rail).toBe(false);
+    expect(gens[0]!.textContent).toContain("FULL");
+  });
+
+  it("the rail generation pins the rail width and carries the density", async () => {
+    const c = mountSwap({ railWidth: "64px" });
+    await c.set(true);
+    await vi.advanceTimersByTimeAsync(600);
+    const gens = c.generations();
+    expect(gens).toHaveLength(1);
+    expect(gens[0]!.style.width).toBe("64px");
+    expect(gens[0]!.hasAttribute("data-rail")).toBe(true);
+    expect(c.params[c.params.length - 1]!.rail).toBe(true);
+    expect(gens[0]!.textContent).toContain("RAIL");
+  });
+
+  it("applies the width props VERBATIM (a var() token must survive the passthrough)", async () => {
+    // happy-dom's CSSOM silently drops a var() width from the parsed
+    // inline style, so the token passthrough is pinned in SOURCE (the
+    // house source-pin style): the generation's width is the raw prop —
+    // no re-resolution, no fallback substitution — which is what lets a
+    // bespoke host pass its own var(--app-sidebar-w, 240px) token.
+    const { readFileSync } = await import("node:fs");
+    const { dirname, join } = await import("node:path");
+    const { fileURLToPath } = await import("node:url");
+    const src = readFileSync(
+      join(dirname(fileURLToPath(import.meta.url)), "HkSidebarRailSwap.tsx"),
+      "utf8",
+    );
+    expect(src).toContain("width: props.rail ? props.railWidth : props.expandedWidth");
+  });
+});
+
+describe("HkSidebarRailSwap — the dissolve (HkCrossfade's mechanism)", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  it("holds BOTH generations mid-swap: leaving FROZEN at its dress, entering at the new one", async () => {
+    freezeRaf();
+    const c = mountSwap({ railWidth: "56px", expandedWidth: "240px" });
+    await c.set(true);
+    await vi.advanceTimersByTimeAsync(200); // inside the dissolve window
+
+    const gens = c.generations();
+    expect(gens, "both generations share the cell mid-swap").toHaveLength(2);
+    // DOM order: leaving first, entering last.
+    const [leaving, entering] = gens;
+    expect(leaving!.hasAttribute("data-rail"), "the leaving copy keeps the EXPANDED dress").toBe(false);
+    expect(leaving!.style.width).toBe("240px");
+    expect(leaving!.textContent).toContain("FULL");
+    expect(entering!.hasAttribute("data-rail"), "the entering copy takes the rail dress").toBe(true);
+    expect(entering!.style.width).toBe("56px");
+    expect(entering!.textContent).toContain("RAIL");
+    // The leaving ITEM is pointer-dead for the dissolve (HkCrossfade's
+    // leave rule) — the frozen generation cannot intercept clicks.
+    const leavingItem = leaving!.parentElement!;
+    expect(leavingItem.classList.contains("hk-crossfade-leave-active")).toBe(true);
+  });
+
+  it("a healthy swap settles on the entering generation alone", async () => {
+    const c = mountSwap({ railWidth: "56px" });
+    await c.set(true);
+    await vi.advanceTimersByTimeAsync(600);
+    const gens = c.generations();
+    expect(gens).toHaveLength(1);
+    expect(gens[0]!.hasAttribute("data-rail")).toBe(true);
+  });
+
+  it("reversing mid-dissolve still lands on the live density — and settles", async () => {
+    freezeRaf();
+    const c = mountSwap({});
+    await c.set(true);
+    await vi.advanceTimersByTimeAsync(100);
+    await c.set(false); // flipped back before the first dissolve settled
+    await vi.advanceTimersByTimeAsync(100);
+    const last = c.generations()[c.generations().length - 1]!;
+    expect(last.hasAttribute("data-rail")).toBe(false);
+    expect(last.style.width).toBe("240px");
+
+    // Release rAF and let the choreography finish: whatever stale items
+    // the reversal stranded must sweep, settling on exactly one
+    // generation at the live density (the watchdog's degraded path
+    // would otherwise leave wedged copies mounted).
+    vi.unstubAllGlobals();
+    await vi.advanceTimersByTimeAsync(CROSSFADE_WATCHDOG_MS + 200);
+    const settled = c.generations();
+    expect(settled).toHaveLength(1);
+    expect(settled[0]!.hasAttribute("data-rail")).toBe(false);
+    expect(settled[0]!.style.width).toBe("240px");
+  });
+
+  it("FREEZES the leaving generation under a host re-render mid-dissolve", async () => {
+    // THE central guarantee: the leaving copy is not re-rendered while
+    // it dissolves — a host re-render (peek state, live store data) must
+    // not restyle or rewrite it, or the density handoff would reintroduce
+    // the squeeze this component exists to fix. The harness re-renders
+    // the whole slot with NEW live text mid-dissolve; the leaving copy
+    // must keep the OLD text while the entering copy shows the new one.
+    freezeRaf();
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+
+    const rail = ref(false);
+    const live = ref("v1");
+    const Wrapper = defineComponent({
+      name: "RailSwapFreezeHarness",
+      setup() {
+        return () =>
+          h(
+            HkSidebarRailSwap,
+            { rail: rail.value, railWidth: "56px", expandedWidth: "240px" },
+            {
+              default: ({ rail: r }: { rail: boolean }) =>
+                h("p", { class: "body" }, (r ? "RAIL:" : "FULL:") + live.value),
+            },
+          );
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+
+    rail.value = true; // start the FULL -> RAIL dissolve
+    await nextTick();
+    await vi.advanceTimersByTimeAsync(120);
+    live.value = "v2"; // the host re-renders mid-dissolve
+    await nextTick();
+    await vi.advanceTimersByTimeAsync(50);
+
+    const gens = Array.from(
+      container.querySelectorAll<HTMLElement>(".hk-sidebar-rail-generation"),
+    );
+    expect(gens).toHaveLength(2);
+    // The frozen leaving copy keeps its last-rendered text (FULL:v1);
+    // the entering copy re-renders live (RAIL:v2).
+    expect(gens[0]!.textContent).toBe("FULL:v1");
+    expect(gens[1]!.textContent).toBe("RAIL:v2");
+  });
+});

package/src/components/HkSidebarRailSwap.tsx

@@ -0,0 +1,102 @@
+import { defineComponent } from "vue";
+
+import HkCrossfade from "./HkCrossfade";
+
+import "./HkSidebarRail.scss";
+
+/**
+ * HkSidebarRailSwap — the rail/full CONTENT handoff (2026-10-30).
+ *
+ * THE DEFECT this closes: a rail <-> expanded flip animates the panel's
+ * `width` (the slide lever) while the density dress (`[data-rail]` /
+ * the slot's scoped state) flips INSTANTLY. The single mounted body is
+ * therefore re-laid-out at the ANIMATING panel width — expanding mounts
+ * full-width rows inside a still-56px panel (labels wrap and ellipsize,
+ * then relax as the panel grows: the reported "squeezed" content) and
+ * collapsing snaps rows to icon tiles that glide through the still-wide
+ * panel. Both read as the content being crushed for the transition's
+ * ~300ms, even though nothing is wrong before or after it.
+ *
+ * THE CONTRACT (user direction 2026-10-30): during the handoff the
+ * content keeps its ORIGINAL width and the clip does the windowing
+ * (`overflow: hidden` — `.hk-sidebar-rail-clip`, already in the kit),
+ * and the old and new generations exchange through an OPACITY dissolve —
+ * the SAME primitive tab panels swap through (HkCrossfade via
+ * HkTransitionContainer; the paneSwap contract's standard mechanism, so
+ * this component composes it rather than inventing a bespoke fade).
+ *
+ * Per generation:
+ * - the generation wrapper is PINNED at its own width (`railWidth` /
+ *   `expandedWidth` inline) and anchored at the docked inline-start
+ *   edge, so neither generation ever reflows while the panel animates;
+ * - the swap host itself NEVER stretches to the animating clip width
+ *   (HkSidebarRail.scss: shrink-to-fit at the widest generation) — the
+ *   "original content width" guarantee is structural, not per-frame;
+ * - the generation carries `data-rail` while the rail density is
+ *   active, so hosts scope their density dress to the GENERATION, never
+ *   to the host root (a root-level attribute flips with the state and
+ *   would restyle the frozen leaving generation mid-dissolve);
+ * - the leaving generation is FROZEN at its last render (Vue keeps the
+ *   keyed leaving item unpatched) and drops pointer events for the
+ *   dissolve (HkCrossfade's leave rule), so the dead copy can neither
+ *   update nor intercept clicks.
+ *
+ * Slot: the default slot receives `{ rail }` — render the body as a
+ * function of it. The ENTERING generation is invoked with the new value;
+ * the LEAVING one keeps whatever it last rendered (per-generation density
+ * by construction). Hosts that ignore the param and close over their own
+ * state get the same freeze for free — but the param is the sanctioned
+ * channel because it also drives per-generation branching (icon hints,
+ * aria labels) that CSS cannot express.
+ *
+ * Trade-offs (documented, accepted): each flip MOUNTS the entering
+ * generation fresh, exactly like a tab-panel swap —
+ * - a scrolled sidebar body starts the entering copy at the top, and
+ *   uncontrolled state inside the slot (an expanded nav group, hover)
+ *   does not carry over. Same-family precedent (HkTabs panels, admin
+ *   views); rail flips are rare, and preserving scroll across a width
+ *   change whose row heights differ would map positions, not restore
+ *   them. A peek OPEN also hands hover to the full row under the
+ *   resting pointer without user intent — inherent to any dissolve.
+ * - FOCUS: when the leaving generation unmounts at the end of the
+ *   dissolve, focus inside it (a nav row focused in an open peek)
+ *   drops to <body> — the sharpest edge is Escape-closing a peek from
+ *   a focused row, which also drops the host's :focus-within (the
+ *   toggle's keyboard reveal) until the next Tab. Hosts that need a
+ *   softer landing can refocus the toggle from the peek-closer path.
+ *
+ * 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.
+ */
+export default defineComponent({
+  name: "HkSidebarRailSwap",
+  props: {
+    /** Which generation is active: true = the icon rail (the collapsed
+     *  density), false = the full sidebar (including a peek). */
+    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). */
+    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 }) {
+    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">
+        <div
+          class="hk-sidebar-rail-generation"
+          data-rail={props.rail || undefined}
+          style={{ width: props.rail ? props.railWidth : props.expandedWidth }}
+        >
+          {slots.default?.({ rail: props.rail })}
+        </div>
+      </HkCrossfade>
+    );
+  },
+});

package/src/index.ts

@@ -104,6 +104,12 @@ export {
   RAIL_TOGGLE_SELECTOR,
   RAIL_TOGGLE_SUPPRESS_PAD,
 } from "./components/HkSidebarRailToggle";
+// The rail/full content handoff: two width-pinned generations exchanged
+// through HkCrossfade's opacity dissolve (the tab-panel mechanism), so
+// sidebar content never re-lays-out at the panel's transient width while
+// it collapses or expands. Bespoke hosts (wowsp's own Sidebar) mount it
+// inside their .hk-sidebar-rail-clip exactly like HkSidebar/HkFaceShell.
+export { default as HkSidebarRailSwap } from "./components/HkSidebarRailSwap";
 export { default as HSkeleton } from "./components/HkSkeleton";
 export { default as HSkeletonList } from "./components/HkSkeletonList";
 export { default as HSlider } from "./components/HkSlider";