@celestia-island/hikari 0.55.232 → 0.55.234

package/package.json

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

package/src/components/HkAboutBody.test.tsx

@@ -16,6 +16,9 @@ import { HkAboutBody } from "./HkAboutModal";
  * - the default slot appends host content after the copyright footer
  * - without a backdrop factory no backdrop layer renders (a body host may
  *   not want the decorative canvas at all)
+ * - a version row's `metaTone: "danger"` reaches the pill as
+ *   `data-tone="danger"`, and an EMPTY `value` drops the mono number cell
+ *   entirely (the "component not wired up" row shows only its red label)
  *
  * (Repo test convention: raw createApp + document queries, no
  * @vue/test-utils dependency.)
@@ -121,4 +124,36 @@ describe("HkAboutBody extraction", () => {
 
     expect(document.body.querySelector(".s-about-modal-backdrop")).toBeNull();
   });
+
+  it("tints a version row's meta pill with the danger tone", async () => {
+    mountBody({
+      componentVersions: [
+        { label: "Edge engine", value: "1.4.0", meta: "Not connected", metaTone: "danger" },
+      ],
+    });
+    await flush();
+
+    const pill = query(".s-about-modal-row-meta");
+    expect(pill.getAttribute("data-tone")).toBe("danger");
+    expect(pill.textContent).toBe("Not connected");
+  });
+
+  it("drops the mono number cell when a row's value is empty", async () => {
+    mountBody({
+      componentVersions: [
+        // A host with nothing to report names the state in `meta` and leaves
+        // `value` empty (the "not wired up" row).
+        { label: "Edge engine", value: "", meta: "Not connected", metaTone: "danger" },
+      ],
+    });
+    await flush();
+
+    // No blank tabular slot: the mono cell is absent, not just empty.
+    expect(document.body.querySelector(".s-about-modal-row-number")).toBeNull();
+    // The label and the pill still carry the row.
+    expect(query(".s-about-modal-row-label").textContent).toContain("Edge engine");
+    const pill = query(".s-about-modal-row-meta");
+    expect(pill.textContent).toBe("Not connected");
+    expect(pill.getAttribute("data-tone")).toBe("danger");
+  });
 });

package/src/components/HkAboutModal.scss

@@ -228,6 +228,14 @@
   color: rgb(var(--color-warning));
 }
 
+// Red state: the component is not wired up / unreachable. The row then
+// carries no version at all, so this pill is the whole value cell.
+.s-about-modal-row-meta[data-tone="danger"] {
+  border-color: rgb(var(--color-error) / 32%);
+  background: rgb(var(--color-error) / 10%);
+  color: rgb(var(--color-error));
+}
+
 /* ── Links: licenses, external links, credits names and filings ───────── */
 
 .s-about-modal-chips {

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

@@ -29,6 +29,36 @@ function classesFrom(source: string): Set<string> {
   return found;
 }
 
+/**
+ * Body of one compiled rule, by exact selector (Sass drops the quotes around
+ * an attribute value: `[data-face=plain]`).
+ *
+ * The selector must compile exactly once: a second copy — say inside a media
+ * query, or a later override — would otherwise stay invisible here while
+ * still winning the cascade.
+ */
+function ruleBody(sheet: string, selector: string): string {
+  const escaped = selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const matches = [...sheet.matchAll(new RegExp(`${escaped}\\s*\\{([^}]*)\\}`, "g"))];
+  expect(matches, `${selector} compiles exactly once`).toHaveLength(1);
+  return matches[0]?.[1] ?? "";
+}
+
+/**
+ * One declaration's value inside a rule body.
+ *
+ * A property declared twice is a failure rather than a coincidence: CSS
+ * resolves a repeat last-wins, so a first-match reader would report the stale
+ * value and happily accept the override.
+ */
+function declaration(body: string, property: string): string {
+  const values = [
+    ...body.matchAll(new RegExp(`(?:^|;)\\s*${property}\\s*:([^;]*)`, "g")),
+  ].map((match) => match[1]!.trim());
+  expect(values.length, `${property} is declared at most once`).toBeLessThanOrEqual(1);
+  return values[0] ?? "";
+}
+
 describe("HkAboutModal stylesheet contract", () => {
   const tsx = readFileSync(resolve(componentDir, "HkAboutModal.tsx"), "utf8");
   const scss = readFileSync(resolve(componentDir, "HkAboutModal.scss"), "utf8");
@@ -67,36 +97,6 @@ describe("HkAboutModal stylesheet contract", () => {
    * into chips. These assertions read the compiled declarations instead.
    */
   describe("link faces", () => {
-    /**
-     * Body of one compiled rule, by exact selector (Sass drops the quotes
-     * around an attribute value: `[data-face=plain]`).
-     *
-     * The selector must compile exactly once: a second copy — say inside a
-     * media query, or a later override — would otherwise stay invisible here
-     * while still winning the cascade.
-     */
-    function ruleBody(sheet: string, selector: string): string {
-      const escaped = selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      const matches = [...sheet.matchAll(new RegExp(`${escaped}\\s*\\{([^}]*)\\}`, "g"))];
-      expect(matches, `${selector} compiles exactly once`).toHaveLength(1);
-      return matches[0]?.[1] ?? "";
-    }
-
-    /**
-     * One declaration's value inside a rule body.
-     *
-     * A property declared twice is a failure rather than a coincidence: CSS
-     * resolves a repeat last-wins, so a first-match reader would report the
-     * stale value and happily accept the override.
-     */
-    function declaration(body: string, property: string): string {
-      const values = [
-        ...body.matchAll(new RegExp(`(?:^|;)\\s*${property}\\s*:([^;]*)`, "g")),
-      ].map((match) => match[1]!.trim());
-      expect(values.length, `${property} is declared at most once`).toBeLessThanOrEqual(1);
-      return values[0] ?? "";
-    }
-
     const PLAIN = ".s-about-modal-link[data-face=plain]";
 
     it("keeps the plain face a bare text link", () => {
@@ -229,4 +229,32 @@ describe("HkAboutModal stylesheet contract", () => {
       expect(iconAt).toBeGreaterThan(plainAt);
     });
   });
+
+  /**
+   * Row-meta tones are self-contained rules, so the class-name checks above
+   * cannot see them: reverting a tone to `neutral` (or dropping its rule)
+   * leaves the `data-tone` attribute intact and the runtime suite green while
+   * the pill silently loses its colour — the whole point of the tone.
+   */
+  describe("row meta tones", () => {
+    const TONE = (tone: string) => `.s-about-modal-row-meta[data-tone=${tone}]`;
+
+    it("paints the danger tone in the theme's error colour", () => {
+      const danger = ruleBody(css, TONE("danger"));
+      expect(danger, "the danger-tone rule must survive compilation").not.toBe("");
+      expect({
+        borderColor: declaration(danger, "border-color"),
+        background: declaration(danger, "background"),
+        color: declaration(danger, "color"),
+      }).toEqual({
+        // Same geometry as the positive / caution tones, only the channel
+        // differs — `--color-error` is the theme's existing danger token.
+        // (Dart Sass compiles the seed-relative form without spaces around
+        // the slash.)
+        borderColor: "rgb(var(--color-error)/32%)",
+        background: "rgb(var(--color-error)/10%)",
+        color: "rgb(var(--color-error))",
+      });
+    });
+  });
 });

package/src/components/HkAboutModal.tsx

@@ -73,12 +73,19 @@ export interface HAboutCredit {
  * rendered as a separate muted pill so it never melts into the version
  * string. `metaTone` tints that pill when the tag carries a status
  * meaning (e.g. a production environment).
+ *
+ * `danger` is the red "not wired up / unreachable" state: a host whose
+ * component (e.g. an edge master node engine) has no version to report
+ * passes an EMPTY `value` and names the state in `meta` with
+ * `metaTone: "danger"`. The empty value then renders the pill alone —
+ * the mono number cell is dropped rather than leaving a blank tabular
+ * slot — so the row reads as one red label instead of `unknown`.
  */
 export interface HAboutComponentVersion {
   label: string;
   value: string;
   meta?: string;
-  metaTone?: "neutral" | "positive" | "caution";
+  metaTone?: "neutral" | "positive" | "caution" | "danger";
 }
 
 /**
@@ -288,7 +295,14 @@ export const HkAboutBody = defineComponent({
                 <div class="s-about-modal-row" key={component.label}>
                   <span class="s-about-modal-row-label">{component.label}</span>
                   <span class="s-about-modal-row-value">
-                    <span class="s-about-modal-row-number">{component.value}</span>
+                    {/* An empty value means the host has no version to
+                        report (e.g. the component is not wired up) and
+                        carries the state in `meta` instead — skip the mono
+                        cell so the row does not open with a blank tabular
+                        slot and a stray gap. */}
+                    {component.value && (
+                      <span class="s-about-modal-row-number">{component.value}</span>
+                    )}
                     {component.meta && (
                       <span
                         class="s-about-modal-row-meta"

package/src/components/HkAdminShell.tsx

@@ -39,8 +39,10 @@ export const HkAdminShell = defineComponent({
     sidebarWidth: { type: String, default: "224px" },
     /** Desktop icon-rail capability, forwarded to HkFaceShell (see its
      *  prop doc): opt in here and the admin sidebar gains the circular
-     *  hover-reveal toggle, the one-icon rail and the overlay peek
-     *  drawer. Declared on the wrapper on purpose — the same
+     *  hover-reveal toggle STRADDLING the sidebar's content-facing border,
+     *  the one-icon rail and the overlay peek drawer (with the peek
+     *  suppressed while the pointer rests on the toggle, and a pinned
+     *  panel on expand). Declared on the wrapper on purpose — the same
      *  honest-forwarding rule as contentMode (a stray attr must not
      *  reach the inner shell's declared prop through fallthrough). */
     sidebarCollapsible: { type: Boolean, default: false },

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

@@ -368,3 +368,211 @@ describe("HkAdminShell forwarding (source pin)", () => {
     expect(container.querySelector(".hk-sidebar-rail-toggle button")).toBeTruthy();
   });
 });
+/** A pointermove with explicit viewport coordinates (the suppression
+ *  wiring is purely geometric — see HkSidebarRailToggle's helper). */
+function pointerMove(x: number, y: number): MouseEvent {
+  const e = new MouseEvent("pointermove", { bubbles: true });
+  Object.defineProperty(e, "clientX", { value: x });
+  Object.defineProperty(e, "clientY", { value: y });
+  return e;
+}
+
+/** A pointerenter carrying viewport coordinates — the host evaluates the
+ *  toggle containment on ENTER, before it arms the dwell. */
+function pointerEnterAt(x: number, y: number): MouseEvent {
+  const e = new MouseEvent("pointerenter", { bubbles: true });
+  Object.defineProperty(e, "clientX", { value: x });
+  Object.defineProperty(e, "clientY", { value: y });
+  return e;
+}
+
+/** A transitionend carrying the property name (happy-dom has no
+ *  TransitionEvent; the host handler filters on `width`). */
+function widthTransitionEnd(): Event {
+  const e = new Event("transitionend");
+  Object.defineProperty(e, "propertyName", { value: "width" });
+  return e;
+}
+
+/** Pin the toggle wrapper's box — happy-dom lays nothing out. */
+function stubToggleRect(container: HTMLElement, left: number, top: number, size = 24) {
+  const el = container.querySelector(".hk-sidebar-rail-toggle") as HTMLElement;
+  el.getBoundingClientRect = () =>
+    ({
+      left,
+      top,
+      right: left + size,
+      bottom: top + size,
+      width: size,
+      height: size,
+      x: left,
+      y: top,
+      toJSON: () => ({}),
+    }) as DOMRect;
+}
+
+describe("HkFaceShell rail chrome: toggle placement and the clip wrapper", () => {
+  it("keeps the toggle a DIRECT child of the panel and the slot inside the clip", () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    const panel = c.panel();
+    const clip = panel.querySelector(":scope > .hk-sidebar-rail-clip") as HTMLElement | null;
+    const toggle = panel.querySelector(":scope > .hk-sidebar-rail-toggle") as HTMLElement | null;
+
+    expect(clip, "the slot's content clips inside the wrapper").toBeTruthy();
+    expect(toggle, "the toggle is a direct child of the panel").toBeTruthy();
+    expect(clip!.contains(toggle!), "the toggle is never inside the clip").toBe(false);
+    expect(clip!.querySelector(".sidebar-mock"), "the sidebar slot renders in the clip").toBeTruthy();
+  });
+
+  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();
+    expect(c.container.querySelector(".hk-sidebar-rail-panel")).toBeFalsy();
+    expect(c.container.querySelector(".sidebar-mock")).toBeTruthy();
+  });
+});
+
+describe("HkFaceShell pin window: expand must not replay the slide", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  it("pins on a rail -> expanded flip and clears on the host width transition", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-pinning"), "collapsing never pins").toBe(false);
+
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-pinning"), "the expand window is pinned").toBe(true);
+    // The panel is already at its final width — only the host animates.
+    expect(c.panel().style.width).toBe("224px");
+    expect(c.aside().style.width).toBe("224px");
+
+    c.aside().dispatchEvent(widthTransitionEnd());
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-pinning")).toBe(false);
+  });
+
+  it("clears the pin window by the fallback when no transition fires", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-pinning")).toBe(true);
+
+    await vi.advanceTimersByTimeAsync(400);
+    expect(c.aside().hasAttribute("data-pinning")).toBe(false);
+  });
+
+  it("collapsing closes an open pin window immediately", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-pinning")).toBe(true);
+
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-pinning")).toBe(false);
+    expect(c.aside().style.width).toBe("56px");
+  });
+
+  it("a child transitionend never ends the window (filtered to the host's width)", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+
+    c.panel().dispatchEvent(widthTransitionEnd());
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-pinning")).toBe(true);
+  });
+});
+
+describe("HkFaceShell hover suppression: a pointer on the toggle never peeks", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  it("suppresses the dwell while the pointer rests on the toggle, re-arms when it moves off", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    stubToggleRect(c.container, 100, 200);
+
+    c.aside().dispatchEvent(POINTER_ENTER());
+    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.slotParams[c.slotParams.length - 1]!.collapsed).toBe(true);
+
+    c.aside().dispatchEvent(pointerMove(400, 500));
+    await vi.advanceTimersByTimeAsync(400);
+    expect(c.aside().hasAttribute("data-peeking"), "off the toggle the peek arms normally").toBe(true);
+    expect(c.slotParams[c.slotParams.length - 1]!.peeking).toBe(true);
+  });
+
+  it("evaluates suppression on ENTER: crossing the boundary onto the toggle arms nothing", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    stubToggleRect(c.container, 100, 200);
+
+    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.slotParams[c.slotParams.length - 1]!.collapsed).toBe(true);
+  });
+
+  it("evaluates suppression on ENTER: entering elsewhere on the rail still peeks", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    stubToggleRect(c.container, 100, 200);
+
+    c.aside().dispatchEvent(pointerEnterAt(400, 500));
+    await vi.advanceTimersByTimeAsync(399);
+    expect(c.aside().hasAttribute("data-peeking"), "one tick before the dwell").toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(c.aside().hasAttribute("data-peeking"), "off the toggle the enter arms the dwell").toBe(true);
+  });
+
+  it("ignores a pointerleave whose relatedTarget is still inside the host", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    c.aside().dispatchEvent(POINTER_ENTER());
+    await vi.advanceTimersByTimeAsync(400);
+    expect(c.aside().hasAttribute("data-peeking")).toBe(true);
+
+    const churn = POINTER_LEAVE();
+    Object.defineProperty(churn, "relatedTarget", { value: c.container.querySelector(".sidebar-mock") });
+    c.aside().dispatchEvent(churn);
+    await vi.advanceTimersByTimeAsync(150 * 4);
+    expect(c.aside().hasAttribute("data-peeking"), "DOM churn is not a leave").toBe(true);
+
+    c.aside().dispatchEvent(POINTER_LEAVE());
+    await vi.advanceTimersByTimeAsync(150);
+    expect(c.aside().hasAttribute("data-peeking")).toBe(false);
+  });
+
+  it("clicking the toggle during an open peek still pins the sidebar expanded", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    c.aside().dispatchEvent(POINTER_ENTER());
+    await vi.advanceTimersByTimeAsync(400);
+    expect(c.aside().hasAttribute("data-peeking")).toBe(true);
+
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-peeking")).toBe(false);
+    expect(c.aside().style.width).toBe("224px");
+    expect(c.aside().hasAttribute("data-pinning"), "the peek pin is a rail -> expanded flip").toBe(true);
+  });
+});

package/src/components/HkFaceShell.tsx

@@ -2,7 +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 HkSidebarRailToggle from "./HkSidebarRailToggle";
+import HkSidebarRailToggle, { isPointerOverRailToggle } from "./HkSidebarRailToggle";
 
 /** CSS-wide keywords. A shorthand rebuilt from one of them is NOT a
  * padding (`inherit 0 inherit` is rejected by every engine, measured in
@@ -171,13 +171,22 @@ export const HkFaceShell = defineComponent({
     sidebarCollapsed: { type: Boolean, default: false },
     sidebarWidth: { type: String, default: "224px" },
     /** OPT-IN icon-rail capability for the desktop sidebar (2026-10-30):
-     *  mounts the hover-reveal circular chevron toggle on the sidebar's
-     *  content-facing edge, lets a click collapse the sidebar to a one-
-     *  icon rail, and — while collapsed — opens a hover-peek drawer that
-     *  slides the full sidebar OVER the content as an overlay (the
-     *  layout keeps the rail width; the content area never shifts).
-     *  Timing lives in useSidebarRail (dwell, grace, Escape); geometry in
-     *  HkSidebarRail.scss (.hk-sidebar-rail-host/-panel/-toggle).
+     *  mounts the hover-reveal circular chevron toggle STRADDLING the
+     *  sidebar's content-facing border (its center on the border line,
+     *  half the circle over the content), lets a click collapse the
+     *  sidebar to a one-icon rail, and — while collapsed — opens a
+     *  hover-peek drawer that slides the full sidebar OVER the content as
+     *  an overlay (the layout keeps the rail width; the content area never
+     *  shifts).
+     *
+     *  Two behaviors ride the same opt-in: a pointer resting on the toggle
+     *  SUPPRESSES the peek dwell (it sits on the rail's hover surface and
+     *  would otherwise open the drawer out from under the cursor), and a
+     *  rail -> expanded flip PINNS the panel at its final width for the
+     *  transition window, so only the content area animates instead of the
+     *  sidebar re-sliding. Timing lives in useSidebarRail (dwell, grace,
+     *  suppression, Escape, pinning); geometry in HkSidebarRail.scss
+     *  (.hk-sidebar-rail-host/-panel/-clip/-toggle).
      *  False (default) renders the sidebar exactly as before. Below
      *  mobileBreakpoint nothing changes — the mobile drawer stays the
      *  only nav surface. */
@@ -291,10 +300,15 @@ export const HkFaceShell = defineComponent({
         emit("update:sidebarRailStyle", v ? "rail" : "expanded");
       },
     });
+    // The host REGION element (the rail <aside>) — the machine uses it to
+    // tell a real pointerleave from DOM churn during the peek/width
+    // transitions.
+    const railHostRef = ref<HTMLElement>();
     const rail = useSidebarRail({
       collapsed: railCollapsed,
       peekDelay: () => props.sidebarPeekDelay,
       peekGrace: () => props.sidebarPeekGrace,
+      host: () => railHostRef.value,
     });
     const railActive = computed(() => props.sidebarCollapsible && railCollapsed.value);
     // The LAYOUT width — the core contract of the peek: rail width while
@@ -327,6 +341,33 @@ export const HkFaceShell = defineComponent({
       if (rail.onKeydown(e)) e.stopPropagation();
     };
 
+    /** A pointer parked on the toggle must NOT arm the peek dwell — the
+     *  toggle straddles the rail's hover surface, so the drawer would open
+     *  under the resting cursor and jump the button away from it (the
+     *  reported twitch). Containment is GEOMETRIC: before the reveal the
+     *  toggle is opacity:0 / pointer-events:none, so event.target cannot
+     *  report it.
+     *
+     *  ENTER evaluates it too, and BEFORE the arm: a pointer that crosses
+     *  the boundary and stops exactly on the toggle (or a synthetic enter
+     *  with no following move) must not arm the dwell. */
+    const onSidebarHostPointerEnter = (e: PointerEvent) => {
+      rail.setPeekSuppressed(isPointerOverRailToggle(railHostRef.value, e.clientX, e.clientY));
+      rail.onPointerEnter();
+    };
+    const onSidebarHostPointerMove = (e: PointerEvent) => {
+      rail.setPeekSuppressed(isPointerOverRailToggle(railHostRef.value, e.clientX, e.clientY));
+    };
+
+    /** The pin window ends with the HOST's own width transition; child
+     *  transitionend events (the panel, a nested HkSidebar) bubble here
+     *  too, so filter to this element's width. */
+    const onSidebarHostTransitionEnd = (e: TransitionEvent) => {
+      if (e.target !== e.currentTarget) return;
+      if (e.propertyName !== "width") return;
+      rail.endPinning();
+    };
+
     const contentStyle = computed(() => ({
       padding: isDesktop.value || !props.contentBleedOnMobile
         ? props.contentPadding
@@ -392,12 +433,20 @@ export const HkFaceShell = defineComponent({
           {isDesktop.value && !props.sidebarCollapsed && slots.sidebar && (
             props.sidebarCollapsible ? (
               <aside
+                ref={railHostRef}
                 class="hk-sidebar-rail-host"
                 data-rail={railActive.value || undefined}
                 data-peeking={rail.peeking.value || undefined}
+                // Transient rail -> expanded window (useSidebarRail.pinning):
+                // the panel and any nested sidebar snap to their final width
+                // 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 }}
-                onPointerenter={rail.onPointerEnter}
+                onPointerenter={onSidebarHostPointerEnter}
                 onPointerleave={rail.onPointerLeave}
+                onPointermove={onSidebarHostPointerMove}
+                onTransitionend={onSidebarHostTransitionEnd}
                 onKeydown={onSidebarHostKeydown}
               >
                 {/* The visual panel — absolutely positioned over the host
@@ -413,11 +462,18 @@ export const HkFaceShell = defineComponent({
                     background: "rgb(var(--color-surface))",
                   }}
                 >
-                  {slots.sidebar({
-                    collapsed: railActive.value && !rail.peeking.value,
-                    onNavigate: onSidebarNavigate,
-                    peeking: rail.peeking.value,
-                  })}
+                  {/* The panel no longer clips (the toggle straddles its
+                      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. */}
+                  <div class="hk-sidebar-rail-clip">
+                    {slots.sidebar({
+                      collapsed: railActive.value && !rail.peeking.value,
+                      onNavigate: onSidebarNavigate,
+                      peeking: rail.peeking.value,
+                    })}
+                  </div>
                   <HkSidebarRailToggle expanded={!railActive.value} onToggle={rail.toggle} />
                 </div>
               </aside>