@celestia-island/hikari 0.55.229 → 0.55.231

package/package.json

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

package/src/components/HkAdminShell.tsx

@@ -37,6 +37,25 @@ export const HkAdminShell = defineComponent({
   props: {
     sidebarCollapsed: { type: Boolean, default: false },
     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
+     *  honest-forwarding rule as contentMode (a stray attr must not
+     *  reach the inner shell's declared prop through fallthrough). */
+    sidebarCollapsible: { type: Boolean, default: false },
+    /** Layout width of the icon rail (default 56px), forwarded. */
+    sidebarCollapsedWidth: { type: String, default: "56px" },
+    /** Rail state channel, `v-model:sidebar-rail-style` ("expanded" |
+     *  "rail"), forwarded — session-only unless the host persists it. */
+    sidebarRailStyle: {
+      type: String as PropType<"expanded" | "rail">,
+      default: "expanded",
+    },
+    /** Hover dwell before the peek opens, ms, forwarded. */
+    sidebarPeekDelay: { type: Number, default: 400 },
+    /** Grace after pointerleave before the peek closes, ms, forwarded. */
+    sidebarPeekGrace: { type: Number, default: 150 },
     /** Viewport width at which the desktop layout takes over (below it
      *  the nav collapses into the mobile drawer). Defaults to the shared
      *  1024px "lg" breakpoint; lower it (e.g. 768) for tablet-friendly
@@ -106,6 +125,15 @@ export const HkAdminShell = defineComponent({
       h(HkFaceShell, {
         sidebarCollapsed: props.sidebarCollapsed,
         sidebarWidth: props.sidebarWidth,
+        sidebarCollapsible: props.sidebarCollapsible,
+        sidebarCollapsedWidth: props.sidebarCollapsedWidth,
+        sidebarRailStyle: props.sidebarRailStyle,
+        sidebarPeekDelay: props.sidebarPeekDelay,
+        sidebarPeekGrace: props.sidebarPeekGrace,
+        // The v-model channel rides the inner shell's event straight
+        // through this wrapper's listeners (attrs fallthrough carries
+        // onUpdate:sidebarRailStyle to HkFaceShell — inheritAttrs stays
+        // on, the default), so the host binding is one wire end-to-end.
         mobileBreakpoint: props.mobileBreakpoint,
         footerHeight: props.footerHeight,
         navTitle: props.navTitle,

package/src/components/HkAvatarButton.test.tsx

@@ -1,5 +1,8 @@
 import { afterEach, describe, expect, it } from "vitest";
 import { createApp, defineComponent, h, nextTick, ref } from "vue";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { HkAvatarButton } from "./HkAvatarButton";
 import { HkAdminHeader } from "./HkAdminHeader";
@@ -107,6 +110,61 @@ describe("HkAvatarButton", () => {
   });
 });
 
+describe("HkAvatarButton sheet contract", () => {
+  // happy-dom has no layout engine, so the geometry is pinned at the
+  // source level — the same approach the downstream chest tripwire
+  // (headerAvatarGeometry.test.ts) takes against the INSTALLED sheet.
+  const sheet = readFileSync(
+    join(dirname(fileURLToPath(import.meta.url)), "..", "styles", "admin-tokens.scss"),
+    "utf8",
+  );
+
+  /** Declarations of the rule whose whole prelude IS `selector`
+   *  (a compound/descendant spelling is a different rule and does not
+   *  match), comments stripped; null when no such rule exists — every
+   *  assertion treats null as a failure, never as "no objection". */
+  function ruleDeclarations(selector: string): Array<[string, string]> | null {
+    const code = sheet
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/(^|[^:])\/\/[^\n]*/gm, "$1");
+    for (let at = code.indexOf(selector); at >= 0; at = code.indexOf(selector, at + 1)) {
+      const open = code.indexOf("{", at + selector.length);
+      if (open < 0) continue;
+      if (code.slice(at + selector.length, open).trim() !== "") continue;
+      let boundary = at - 1;
+      while (boundary >= 0 && !"}{;".includes(code[boundary])) boundary -= 1;
+      if (code.slice(boundary + 1, at).replace(/\s+/g, " ").trim() !== "") continue;
+      const body = code.slice(open + 1, code.indexOf("}", open));
+      const out: Array<[string, string]> = [];
+      for (const part of body.split(";")) {
+        const m = /^\s*([-a-zA-Z]+)\s*:\s*([\s\S]+?)\s*$/.exec(part);
+        if (m) out.push([m[1], m[2].replace(/\s+/g, " ")]);
+      }
+      return out;
+    }
+    return null;
+  }
+
+  it("the trigger is a BLOCK — hosts may nest it in a plain wrapper div", () => {
+    // The chat face wraps HeaderLeft's trigger in a menu-anchor <div>:
+    // an inline-block button there joins a line box and the strut's
+    // descender space lands BELOW it, riding the avatar ~4px high inside
+    // a perfectly centred wrapper (2026-10-30 user report). Removing
+    // this declaration is the mutation this test must catch.
+    const rule = ruleDeclarations(".s-admin-header-avatar");
+    expect(rule, "admin-tokens must declare .s-admin-header-avatar").not.toBeNull();
+    // Positive control for the extractor itself: the geometry pair the
+    // downstream tripwire also reads. If these stop matching, the parser
+    // above is broken — fix it, not the assertion below.
+    expect(rule).toContainEqual(["width", "var(--space-28)"]);
+    expect(rule).toContainEqual(["height", "var(--space-28)"]);
+    expect(rule, "the trigger must not re-enter inline formatting").toContainEqual([
+      "display",
+      "block",
+    ]);
+  });
+});
+
 describe("HkAdminHeader × HkAvatarButton / identity slot", () => {
   it("never renders aria-expanded when no expanded prop is given (drawer-mode contract)", () => {
     // R2 S3-2: menu engines read this pair; a drawer-mode trigger has no

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

@@ -0,0 +1,370 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, ref } from "vue";
+
+// Same stub shape as HkFaceShell.test.tsx: HDrawer teleports and
+// animates; the desktop rail contract is testable without the overlay
+// runtime.
+vi.mock("@celestia-island/hikari", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@celestia-island/hikari")>();
+  const { defineComponent, h } = await import("vue");
+  const HDrawerStub = defineComponent({
+    name: "HDrawer",
+    props: {
+      modelValue: { type: Boolean, default: false },
+      side: { type: String, default: "left" },
+      size: { type: String, default: "280px" },
+      title: { type: String, default: undefined },
+      panelClass: { type: String, default: undefined },
+    },
+    setup(props, { slots }) {
+      return () =>
+        props.modelValue
+          ? h("div", { class: ["drawer-stub", props.panelClass] }, [
+              h("div", { class: "drawer-stub-body" }, slots.default?.()),
+              slots.footer
+                ? h("div", { class: "drawer-stub-footer" }, slots.footer())
+                : null,
+            ])
+          : null;
+    },
+  });
+  return { ...actual, HDrawer: HDrawerStub };
+});
+
+import { HkFaceShell } from "./HkFaceShell";
+import { HkAdminShell } from "./HkAdminShell";
+
+/**
+ * HkFaceShell desktop rail + peek integration (2026-10-30). What this
+ * file pins:
+ *
+ * 1. OPT-IN: without sidebarCollapsible the sidebar renders the legacy
+ *    aside — no rail classes, no toggle, slot collapsed stays false and
+ *    carries no peeking param.
+ * 2. The rail channel: the toggle drives v-model:sidebar-rail-style, the
+ *    host width collapses to sidebarCollapsedWidth, the slot receives
+ *    collapsed: true.
+ * 3. The PEEK overlay: after the dwell (pointerenter + 400ms) the panel
+ *    grows to the full width while the HOST width — the only layout
+ *    lever over the content — STAYS at the rail width (the "content
+ *    never shifts" core contract), and the slot flips back to full rows
+ *    (collapsed: false, peeking: true).
+ * 4. Grace + flicker: leave closes only after the grace; re-entry inside
+ *    the grace keeps the peek open.
+ * 5. Escape closes; a nav click (the slot's onNavigate) closes.
+ * 6. HkAdminShell forwards the whole prop family (source pin, the same
+ *    honest-forwarding rule as contentMode) and mounts the rail.
+ *
+ * The harness closes the v-model loop with a stateful wrapper — exactly
+ * what a real host's v-model:sidebar-rail-style does.
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+interface SlotParams {
+  collapsed: boolean;
+  onNavigate: () => void;
+  peeking?: boolean;
+  [key: string]: unknown;
+}
+
+interface RailMount {
+  container: HTMLElement;
+  aside(): HTMLElement;
+  panel(): HTMLElement;
+  main(): HTMLElement;
+  toggle(): HTMLButtonElement;
+  slotParams: SlotParams[];
+  emitted: string[];
+}
+
+function mountShell(props: Record<string, unknown> = {}): RailMount {
+  const slotParams: SlotParams[] = [];
+  const emitted: string[] = [];
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+
+  const Wrapper = defineComponent({
+    name: "RailShellHarness",
+    setup() {
+      const railStyle = ref<"expanded" | "rail">(
+        (props.sidebarRailStyle as "expanded" | "rail") ?? "expanded",
+      );
+      return () =>
+        h(HkFaceShell, {
+          navTitle: "Navigation",
+          ...props,
+          sidebarRailStyle: railStyle.value,
+          "onUpdate:sidebarRailStyle": (v: string) => {
+            emitted.push(v);
+            railStyle.value = v as "expanded" | "rail";
+          },
+        }, {
+          header: () => null,
+          sidebar: (params: SlotParams) => {
+            slotParams.push(params);
+            return h("div", { class: "sidebar-mock" }, "NAV");
+          },
+          content: () => h("div", { class: "content-mock" }, "CONTENT"),
+        });
+    },
+  });
+
+  const app = createApp(Wrapper);
+  app.mount(container);
+  mounts.push({ app, container });
+  return {
+    container,
+    aside: () => container.querySelector(".hk-sidebar-rail-host") as HTMLElement,
+    panel: () => container.querySelector(".hk-sidebar-rail-panel") as HTMLElement,
+    main: () => container.querySelector(".s-admin-shell-main") as HTMLElement,
+    toggle: () =>
+      container.querySelector(".hk-sidebar-rail-toggle button") as HTMLButtonElement,
+    slotParams,
+    emitted,
+  };
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+  vi.useRealTimers();
+});
+
+const POINTER_ENTER = () => new Event("pointerenter");
+const POINTER_LEAVE = () => new Event("pointerleave");
+
+describe("HkFaceShell desktop sidebar rail (opt-in)", () => {
+  it("renders the LEGACY aside untouched when not collapsible", () => {
+    const c = mountShell();
+    expect(c.aside(), "no rail host class").toBeFalsy();
+    expect(c.toggle(), "no toggle button").toBeFalsy();
+    // The slot keeps its legacy param shape.
+    const last = c.slotParams[c.slotParams.length - 1]!;
+    expect(last.collapsed).toBe(false);
+    expect(typeof last.onNavigate).toBe("function");
+    expect("peeking" in last).toBe(false);
+  });
+
+  it("keeps removing the sidebar entirely under the legacy sidebarCollapsed prop", () => {
+    const c = mountShell({ sidebarCollapsible: true, sidebarCollapsed: true });
+    expect(c.container.querySelector("aside")).toBeFalsy();
+    expect(c.container.querySelector(".content-mock")).toBeTruthy();
+  });
+});
+
+describe("HkFaceShell rail mode", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  it("collapses through the toggle and the v-model channel", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+
+    expect(c.aside().style.width).toBe("224px");
+    expect(c.aside().getAttribute("data-rail")).toBeNull();
+    expect(c.toggle().getAttribute("aria-expanded")).toBe("true");
+
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+
+    expect(c.emitted, "the model channel emits rail").toEqual(["rail"]);
+    expect(c.aside().style.width).toBe("56px");
+    expect(c.aside().hasAttribute("data-rail")).toBe(true);
+    expect(c.toggle().getAttribute("aria-expanded")).toBe("false");
+    expect(c.slotParams[c.slotParams.length - 1]!.collapsed).toBe(true);
+  });
+
+  it("collapses with NO channel bound — the session-only default (R1 defect pin)", async () => {
+    // Semi-controlled state: a host that never binds
+    // v-model:sidebar-rail-style still gets a working toggle; the emit
+    // just lands unheard. (The pure-delegate version left the click
+    // inert — found by the R1 verifier.)
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(HkFaceShell, { navTitle: "Navigation", sidebarCollapsible: true }, {
+          header: () => null,
+          sidebar: () => h("div", "NAV"),
+          content: () => h("div", "CONTENT"),
+        }),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+
+    const aside = container.querySelector(".hk-sidebar-rail-host") as HTMLElement;
+    const toggle = container.querySelector(".hk-sidebar-rail-toggle button") as HTMLButtonElement;
+    expect(aside.style.width).toBe("224px");
+
+    toggle.click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(aside.style.width, "the unbound toggle still collapses").toBe("56px");
+
+    toggle.click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(aside.style.width, "and expands again").toBe("224px");
+  });
+
+  it("the bound prop WINS on the way back in — external channel drives both directions", async () => {
+    // The other half of the semi-controlled contract (R2 pin): a host
+    // that treats sidebarRailStyle as ITS state (store-driven, no echo)
+    // must see the sidebar follow. Deleting the prop-sync watch leaves
+    // every other test green — this is the one that goes red.
+    const railStyle = ref<"expanded" | "rail">("expanded");
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      setup: () => () =>
+        h(HkFaceShell, {
+          navTitle: "Navigation",
+          sidebarCollapsible: true,
+          // Deliberately NO onUpdate:sidebarRailStyle echo — the prop is
+          // the external authority here.
+          sidebarRailStyle: railStyle.value,
+        }, {
+          header: () => null,
+          sidebar: () => h("div", "NAV"),
+          content: () => h("div", "CONTENT"),
+        }),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+    const aside = () => container.querySelector(".hk-sidebar-rail-host") as HTMLElement;
+
+    railStyle.value = "rail";
+    await vi.advanceTimersByTimeAsync(0);
+    expect(aside().style.width, "an external rail value collapses").toBe("56px");
+
+    railStyle.value = "expanded";
+    await vi.advanceTimersByTimeAsync(0);
+    expect(aside().style.width, "and an external expanded value restores").toBe("224px");
+  });
+
+  it("honors a configured rail width", async () => {
+    const c = mountShell({ sidebarCollapsible: true, sidebarCollapsedWidth: "72px" });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().style.width).toBe("72px");
+  });
+
+  it("peeks after the dwell as an OVERLAY — the host width never moves", async () => {
+    const c = mountShell({ sidebarCollapsible: true });
+    c.toggle().click();
+    await vi.advanceTimersByTimeAsync(0);
+
+    c.aside().dispatchEvent(POINTER_ENTER());
+    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")).toBe(true);
+    // THE core contract: the layout footprint (host width) stays at the
+    // rail width while the panel overlays at the full width — the
+    // content <main> cannot shift because nothing in flow changed.
+    expect(c.aside().style.width).toBe("56px");
+    expect(c.panel().style.width).toBe("224px");
+    expect(c.main(), "the content host still renders").toBeTruthy();
+    // The slot renders FULL rows again inside the peek.
+    expect(c.slotParams[c.slotParams.length - 1]!.collapsed).toBe(false);
+    expect(c.slotParams[c.slotParams.length - 1]!.peeking).toBe(true);
+  });
+
+  it("closes on leave only after the grace; re-entry cancels the close", 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);
+
+    // Diagonal move: out, back inside the grace — no flicker.
+    c.aside().dispatchEvent(POINTER_LEAVE());
+    await vi.advanceTimersByTimeAsync(100);
+    c.aside().dispatchEvent(POINTER_ENTER());
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(c.aside().hasAttribute("data-peeking"), "re-entry keeps the peek open").toBe(true);
+
+    // A full grace outside finally closes.
+    c.aside().dispatchEvent(POINTER_LEAVE());
+    await vi.advanceTimersByTimeAsync(149);
+    expect(c.aside().hasAttribute("data-peeking"), "inside the grace it stays open").toBe(true);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(c.aside().hasAttribute("data-peeking")).toBe(false);
+    expect(c.panel().style.width).toBe("56px");
+    expect(c.aside().style.width).toBe("56px");
+  });
+
+  it("Escape closes an open peek", 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.aside().dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-peeking")).toBe(false);
+  });
+
+  it("a nav row click inside the peek closes it (onNavigate)", 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 nav = c.slotParams[c.slotParams.length - 1]!.onNavigate;
+    nav();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(c.aside().hasAttribute("data-peeking"), "navigate + close, like the drawer").toBe(false);
+  });
+});
+
+describe("HkAdminShell forwarding (source pin)", () => {
+  it("declares and forwards the rail prop family", async () => {
+    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)), "HkAdminShell.tsx"),
+      "utf8",
+    ).replace(/\r\n/g, "\n");
+    // Declared on the wrapper (the honest-forwarding rule)…
+    for (const decl of [
+      "sidebarCollapsible: { type: Boolean, default: false }",
+      'sidebarCollapsedWidth: { type: String, default: "56px" }',
+      "sidebarPeekDelay: { type: Number, default: 400 }",
+      "sidebarPeekGrace: { type: Number, default: 150 }",
+    ]) {
+      expect(src, decl).toContain(decl);
+    }
+    // …and forwarded to the inner shell.
+    expect(src).toContain("sidebarCollapsible: props.sidebarCollapsible,");
+    expect(src).toContain("sidebarCollapsedWidth: props.sidebarCollapsedWidth,");
+    expect(src).toContain("sidebarRailStyle: props.sidebarRailStyle,");
+    expect(src).toContain("sidebarPeekDelay: props.sidebarPeekDelay,");
+    expect(src).toContain("sidebarPeekGrace: props.sidebarPeekGrace,");
+  });
+
+  it("mounts the rail through the wrapper (behavior spot-check)", () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h(HkAdminShell, { sidebarCollapsible: true }, {
+          header: () => null,
+          sidebar: () => h("div", "NAV"),
+          content: () => h("div", "CONTENT"),
+        }),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+    expect(container.querySelector(".hk-sidebar-rail-host")).toBeTruthy();
+    expect(container.querySelector(".hk-sidebar-rail-toggle button")).toBeTruthy();
+  });
+});

package/src/components/HkFaceShell.tsx

@@ -1,6 +1,8 @@
-import { computed, defineComponent, ref, type PropType } from "vue";
+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";
 
 /** CSS-wide keywords. A shorthand rebuilt from one of them is NOT a
  * padding (`inherit 0 inherit` is rejected by every engine, measured in
@@ -168,6 +170,35 @@ export const HkFaceShell = defineComponent({
   props: {
     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).
+     *  False (default) renders the sidebar exactly as before. Below
+     *  mobileBreakpoint nothing changes — the mobile drawer stays the
+     *  only nav surface. */
+    sidebarCollapsible: { type: Boolean, default: false },
+    /** Layout width of the icon rail (the one-icon column). Default 56px,
+     *  the rail width HkSidebar's collapsed mode has always used. */
+    sidebarCollapsedWidth: { type: String, default: "56px" },
+    /** Rail state channel, `v-model:sidebar-rail-style`: "expanded" (the
+     *  default) or "rail". The library itself NEVER persists this — the
+     *  collapse is session-only by design; a host that wants persistence
+     *  (or a shared store) binds the channel and stores the value
+     *  itself. */
+    sidebarRailStyle: {
+      type: String as PropType<"expanded" | "rail">,
+      default: "expanded",
+    },
+    /** Hover dwell on the rail before the peek drawer opens, ms. */
+    sidebarPeekDelay: { type: Number, default: 400 },
+    /** Grace after pointerleave before the peek drawer closes, ms — a
+     *  diagonal pointer move within the window does not flicker it shut. */
+    sidebarPeekGrace: { type: Number, default: 150 },
     /** Viewport width at which the desktop layout takes over (below it
      *  the nav collapses into the mobile drawer). Defaults to the shared
      *  1024px "lg" breakpoint; lower it (e.g. 768) for tablet-friendly
@@ -230,12 +261,72 @@ export const HkFaceShell = defineComponent({
      *  Default false: the padding reads the same at every width. */
     contentBleedOnMobile: { type: Boolean, default: false },
   },
-  setup(props, { slots }) {
+  emits: {
+    "update:sidebarRailStyle": (v: string) => true,
+  },
+  setup(props, { slots, emit }) {
     const { t } = useI18n();
     const { width: viewportWidth } = useBreakpoint();
     const isDesktop = computed(() => viewportWidth.value >= props.mobileBreakpoint);
     const sidebarOpen = ref(false);
 
+    // ── desktop icon rail + hover peek (sidebarCollapsible) ──────────
+    // SEMI-CONTROLLED rail state: a local session-only ref is the live
+    // state, so the toggle works with NO channel bound at all (the
+    // session-only default); a host that binds v-model:sidebar-rail-style
+    // hears every flip through update:sidebarRailStyle and its prop then
+    // wins on the way back in (the watch below). Same shape as
+    // HkSidebar's collapsed handling.
+    const railCollapsedLocal = ref(props.sidebarRailStyle === "rail");
+    watch(
+      () => props.sidebarRailStyle,
+      (v) => {
+        railCollapsedLocal.value = v === "rail";
+      },
+    );
+    const railCollapsed = computed({
+      get: () => railCollapsedLocal.value,
+      set: (v: boolean) => {
+        railCollapsedLocal.value = v;
+        emit("update:sidebarRailStyle", v ? "rail" : "expanded");
+      },
+    });
+    const rail = useSidebarRail({
+      collapsed: railCollapsed,
+      peekDelay: () => props.sidebarPeekDelay,
+      peekGrace: () => props.sidebarPeekGrace,
+    });
+    const railActive = computed(() => props.sidebarCollapsible && railCollapsed.value);
+    // The LAYOUT width — the core contract of the peek: rail width while
+    // collapsed OR peeking (the peek overlays; it never reflows content),
+    // full width while expanded.
+    const hostSidebarWidth = computed(() =>
+      railActive.value ? props.sidebarCollapsedWidth : props.sidebarWidth,
+    );
+    // The PANEL width — full while expanded or peeking (the slide-out
+    // lever), rail width otherwise.
+    const peekPanelWidth = computed(() =>
+      railActive.value && !rail.peeking.value ? props.sidebarCollapsedWidth : props.sidebarWidth,
+    );
+    // Crossing under the breakpoint unmounts the desktop sidebar — the
+    // peek must not survive into the mobile drawer era (or reappear when
+    // the viewport grows back).
+    watch(isDesktop, (desktop) => {
+      if (!desktop) rail.closePeek();
+    });
+
+    /** Nav rows close the mobile drawer (their existing onNavigate
+     *  contract) AND an open peek — mirroring the drawer's
+     *  navigate-and-dismiss behavior on desktop hover. */
+    const onSidebarNavigate = () => {
+      rail.closePeek();
+      closeSidebar();
+    };
+
+    const onSidebarHostKeydown = (e: KeyboardEvent) => {
+      if (rail.onKeydown(e)) e.stopPropagation();
+    };
+
     const contentStyle = computed(() => ({
       padding: isDesktop.value || !props.contentBleedOnMobile
         ? props.contentPadding
@@ -299,17 +390,50 @@ export const HkFaceShell = defineComponent({
 
         <div class="s-admin-shell-body" style={{ paddingBottom: footerPad() }}>
           {isDesktop.value && !props.sidebarCollapsed && slots.sidebar && (
-            <aside
-              style={{
-                width: props.sidebarWidth,
-                flexShrink: 0,
-                borderRight: "1px solid var(--border-faint, rgb(var(--color-border) / 10%))",
-                background: "rgb(var(--color-surface))",
-                overflow: "hidden",
-              }}
-            >
-              {slots.sidebar({ collapsed: false, onNavigate: closeSidebar })}
-            </aside>
+            props.sidebarCollapsible ? (
+              <aside
+                class="hk-sidebar-rail-host"
+                data-rail={railActive.value || undefined}
+                data-peeking={rail.peeking.value || undefined}
+                style={{ width: hostSidebarWidth.value, flexShrink: 0 }}
+                onPointerenter={rail.onPointerEnter}
+                onPointerleave={rail.onPointerLeave}
+                onKeydown={onSidebarHostKeydown}
+              >
+                {/* The visual panel — absolutely positioned over the host
+                    (HkSidebarRail.scss). Its width is the peek's slide-out
+                    lever; the host width above is the layout footprint and
+                    NEVER grows during a peek, so the <main> sibling keeps
+                    its exact width while the drawer covers it. */}
+                <div
+                  class="hk-sidebar-rail-panel"
+                  style={{
+                    width: peekPanelWidth.value,
+                    borderInlineEnd: "1px solid var(--border-faint, rgb(var(--color-border) / 10%))",
+                    background: "rgb(var(--color-surface))",
+                  }}
+                >
+                  {slots.sidebar({
+                    collapsed: railActive.value && !rail.peeking.value,
+                    onNavigate: onSidebarNavigate,
+                    peeking: rail.peeking.value,
+                  })}
+                  <HkSidebarRailToggle expanded={!railActive.value} onToggle={rail.toggle} />
+                </div>
+              </aside>
+            ) : (
+              <aside
+                style={{
+                  width: props.sidebarWidth,
+                  flexShrink: 0,
+                  borderRight: "1px solid var(--border-faint, rgb(var(--color-border) / 10%))",
+                  background: "rgb(var(--color-surface))",
+                  overflow: "hidden",
+                }}
+              >
+                {slots.sidebar({ collapsed: false, onNavigate: closeSidebar })}
+              </aside>
+            )
           )}
           <main class="s-admin-shell-main" data-content-mode={props.contentMode}>
             {props.contentMode === "stage" ? (