@celestia-island/hikari 0.43.18 → 0.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.43.18",
+  "version": "0.45.0",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkAdminHeader.test.tsx

@@ -1,39 +1,66 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, h } from "vue";
 
-// HPopover teleports to body — stubbing Teleport stringifies its vnode
-// children. Replace just HPopover with an inline passthrough that renders
-// its default slot while open; the rest of hikari stays real.
-vi.mock("@celestia-island/hikari", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("@celestia-island/hikari")>();
+// HkMenu renders its levels through HkSelectPanel, which teleports to
+// body — replace just HkMenu (imported by the component from
+// ./HkMenu) with an inline passthrough that renders the header slot
+// plus one flattened row per item (children included) while open,
+// wiring row clicks to the select handler; the rest of hikari stays
+// real. The select handler reaches the stub through attrs (it is not
+// re-declared as an emit, which would strip it from props).
+vi.mock("./HkMenu", async () => {
   const { defineComponent, h } = await import("vue");
-  const HPopoverStub = defineComponent({
-    name: "HPopover",
+  const HMenuStub = defineComponent({
+    name: "HMenu",
     props: {
-      modelValue: { type: Boolean, default: false },
-      placement: { type: String, default: "bottom" },
+      open: { type: Boolean, default: false },
+      items: { type: Array, default: () => [] },
+      title: { type: String, default: "" },
     },
-    setup(props, { slots }) {
-      return () =>
-        props.modelValue
-          ? h("div", { class: "popover-stub" }, slots.default?.())
-          : null;
+    setup(props, { slots, attrs }) {
+      return () => {
+        if (!props.open) return null;
+        const rows: ReturnType<typeof h>[] = [];
+        const flatten = (items: any[]) => {
+          for (const item of items ?? []) {
+            rows.push(
+              h(
+                "button",
+                {
+                  class: "menu-stub-row",
+                  "data-key": item.key,
+                  "data-checked": item.checked || undefined,
+                  "data-danger": item.danger || undefined,
+                  onClick: () => (attrs as any).onSelect?.(item.key),
+                },
+                item.label,
+              ),
+            );
+            if (item.children?.length) flatten(item.children);
+          }
+        };
+        flatten(props.items as any[]);
+        return h("div", { class: "menu-stub" }, [...(slots.header?.() ?? []), ...rows]);
+      };
     },
   });
-  return { ...actual, HPopover: HPopoverStub };
+  return { default: HMenuStub };
 });
 
 import { HkAdminHeader } from "./HkAdminHeader";
 
 /**
- * HkAdminHeader contract tests for the generalized avatar/identity
- * behaviors ported from the chest plana-legacy fork:
- * - avatarAction "menu" (default) toggles the user dropdown; "drawer"
- *   emits avatarClick so the shell can open its nav drawer.
- * - the identity block (name/email/groups) leads the menu; an empty
- *   identity renders the signing-in placeholder + force-sign-out escape.
- * - an empty title hides the context-title node entirely (pages carry
- *   their own in-page title in the HPageHeader convention).
+ * HkAdminHeader contract tests for the unified user dropdown:
+ * - the bar beside the avatar carries the PAGE TITLE, never the
+ *   nickname;
+ * - the avatar trigger toggles an HkMenu dropdown whose header slot is
+ *   the profile identity block (avatar chip + nickname + email) and
+ *   whose rows end in a danger logout;
+ * - avatarAction "drawer" emits avatarClick instead (bar text hidden);
+ * - an empty identity renders the signing-in placeholder + the
+ *   force-sign-out escape row;
+ * - Language children carry checked state and emit localeSelect;
+ * - the goToFrontend row sits directly above logout.
  *
  * (Repo test convention: raw createApp + container queries, no
  * @vue/test-utils dependency.)
@@ -66,6 +93,9 @@ function headerNode(props: HeaderProps = {}, slots?: Record<string, unknown>) {
 const avatarButton = (c: HTMLElement) =>
   c.querySelector('button[aria-haspopup]') as HTMLButtonElement | null;
 
+const menuRows = (c: HTMLElement) =>
+  [...c.querySelectorAll(".menu-stub-row")] as HTMLButtonElement[];
+
 async function click(el: Element | null) {
   el?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
   await Promise.resolve();
@@ -73,27 +103,60 @@ async function click(el: Element | null) {
 }
 
 describe("HkAdminHeader", () => {
-  it("toggles the user dropdown on avatar click in menu mode", async () => {
-    const c = mount(headerNode({ logoutLabel: "Log out" }));
+  it("shows the page title beside the avatar, never the nickname", () => {
+    const c = mount(headerNode({ title: "Providers", logoutLabel: "Log out" }));
+    const barText = c.querySelector("header > div")?.textContent ?? "";
+    expect(barText).toContain("Providers");
+    // The nickname must not render as bar text — identity lives in the
+    // dropdown's identity block only.
+    expect(barText).not.toContain("alice");
+  });
+
+  it("renders the letter fallback on the shared avatar primitive, no outline ring", () => {
+    const c = mount(headerNode({ title: "Providers" }));
+    const btn = avatarButton(c) as HTMLButtonElement;
+    // The old border-2 ring made the console avatar read as a different
+    // control from the chat frontend's (user report 2026-09-12).
+    expect(btn.className).not.toContain("border-2");
+    expect(btn.querySelector(".s-user-avatar")?.textContent).toBe("A");
+  });
+
+  it("hides the title node entirely when it is empty", () => {
+    const withTitle = mount(headerNode({ title: "Dashboard" }));
+    expect(withTitle.textContent).toContain("Dashboard");
+
+    const withoutTitle = mount(headerNode());
+    expect(withoutTitle.querySelector("header > div")?.textContent).not.toContain("Dashboard");
+  });
+
+  it("toggles the user dropdown with the profile identity header in menu mode", async () => {
+    const c = mount(headerNode({
+      userEmail: "alice@example.com",
+      logoutLabel: "Log out",
+    }));
     const btn = avatarButton(c);
     expect(btn?.getAttribute("aria-haspopup")).toBe("menu");
 
     await click(btn);
-    const menu = c.querySelector(".popover-stub");
-    // The dropdown leads with the identity block and ends with logout.
+    const menu = c.querySelector(".menu-stub");
+    // The dropdown leads with the identity block — avatar chip,
+    // nickname, email — and ends with a danger logout row.
+    expect(menu?.querySelector(".s-user-header--profile")).toBeTruthy();
+    expect(menu?.querySelector(".s-user-avatar-chip")).toBeTruthy();
     expect(menu?.textContent).toContain("alice");
-    expect(c.querySelector(".s-user-header")).toBeTruthy();
-    expect(menu?.textContent).toContain("Log out");
+    expect(menu?.textContent).toContain("alice@example.com");
+    expect(c.querySelector(".menu-stub-row[data-key='logout'][data-danger]")).toBeTruthy();
 
     await click(btn);
-    expect(c.querySelector(".s-user-header")).toBeNull();
+    expect(c.querySelector(".menu-stub")).toBeNull();
   });
 
   it("emits avatarClick instead of the dropdown in drawer mode", async () => {
     const clicks: number[] = [];
     const c = mount(headerNode({
       avatarAction: "drawer",
-      logoutLabel: "Log out",
+      title: "Providers",
+      userEmail: "alice@example.com",
       onAvatarClick: () => clicks.push(1),
     }));
     const btn = avatarButton(c);
@@ -101,9 +164,10 @@ describe("HkAdminHeader", () => {
 
     await click(btn);
     expect(clicks).toHaveLength(1);
-    // The dropdown must NOT open in drawer mode, and the username stays
-    // hidden — the identity block lives in the drawer footer.
-    expect(c.querySelector(".s-user-header")).toBeNull();
+    // The dropdown must NOT open in drawer mode, and neither the title
+    // nor the nickname renders — both live in the drawer footer.
+    expect(c.querySelector(".menu-stub")).toBeNull();
+    expect(c.textContent).not.toContain("Providers");
     expect(c.textContent).not.toContain("alice");
   });
 
@@ -123,63 +187,64 @@ describe("HkAdminHeader", () => {
     // No action items above an absent identity.
     expect(c.textContent).not.toContain("Avatar");
 
-    await click(c.querySelector(".s-popup-menu-item"));
+    await click(c.querySelector(".menu-stub-row"));
     expect(onForceSignOut).toHaveBeenCalledTimes(1);
   });
 
-  it("hides the context title entirely when it is empty", () => {
-    const withTitle = mount(headerNode({ title: "Dashboard" }));
-    expect(withTitle.querySelector("h2")?.textContent).toBe("Dashboard");
-
-    const withoutTitle = mount(headerNode());
-    expect(withoutTitle.querySelector("h2")).toBeNull();
-  });
-
-  it("renders no emergency-stop control by default", () => {
-    const c = mount(headerNode({ username: "alice" }));
-    expect(c.textContent.toLowerCase()).not.toContain("emergency");
-  });
-
   it("renders the goToFrontend row above logout and emits goToFrontend", async () => {
     const onGoToFrontend = vi.fn();
     const c = mount(headerNode({
+      userEmail: "alice@example.com",
       logoutLabel: "Log out",
       goToFrontendLabel: "Go to Frontend",
       onGoToFrontend,
     }));
     // Opt-in: absent without the label prop…
-    const bare = mount(headerNode({ logoutLabel: "Log out" }));
+    const bare = mount(headerNode({ userEmail: "alice@example.com", logoutLabel: "Log out" }));
     await click(avatarButton(bare));
-    expect(bare.textContent).not.toContain("Go to Frontend");
+    expect(bare.querySelector(".menu-stub-row[data-key='go-to-frontend']")).toBeNull();
 
     // …and present (directly above logout, mirroring the drawer user
     // panel's row order) with the label prop.
     await click(avatarButton(c));
-    const rows = [...c.querySelectorAll(".s-popup-menu-item")];
-    const labels = rows.map((r) => r.textContent?.trim());
-    expect(labels.indexOf("Go to Frontend")).toBeGreaterThan(-1);
-    expect(labels.indexOf("Log out")).toBe(labels.indexOf("Go to Frontend") + 1);
+    const keys = menuRows(c).map((r) => r.dataset.key);
+    expect(keys.indexOf("go-to-frontend")).toBeGreaterThan(-1);
+    expect(keys.indexOf("logout")).toBe(keys.indexOf("go-to-frontend") + 1);
 
-    await click(rows[labels.indexOf("Go to Frontend")]);
+    await click(menuRows(c)[keys.indexOf("go-to-frontend")]);
     expect(onGoToFrontend).toHaveBeenCalledTimes(1);
   });
 
-  it("passes the locale trigger ref OBJECT through the slot so the picker anchors to the button", async () => {
-    let captured: unknown = null;
-    const c = mount(headerNode(
-      { username: "alice" },
-      {
-        "locale-picker": (scope: { triggerRef: unknown }) => {
-          captured = scope.triggerRef;
-          return null;
-        },
-      },
-    ));
+  it("offers locales as a checked cascade and emits localeSelect with the code", async () => {
+    const onLocaleSelect = vi.fn();
+    const c = mount(headerNode({
+      userEmail: "alice@example.com",
+      localeOptions: [
+        { code: "en", label: "English" },
+        { code: "zh-Hans", label: "简体中文" },
+      ],
+      currentLocale: "zh-Hans",
+      onLocaleSelect,
+    }));
     await click(avatarButton(c));
-    // The slot must receive the ref object itself (reactive), not its
-    // frozen .value snapshot from the first render (null before the
-    // ref attached).
-    expect(captured).toBeTruthy();
-    expect((captured as { value?: unknown }).value).toBeInstanceOf(HTMLElement);
+
+    // Children flatten after the parent row with checked state on the
+    // active locale only.
+    const rows = menuRows(c);
+    const localeIdx = rows.findIndex((r) => r.dataset.key === "locale");
+    const en = rows[localeIdx + 1];
+    const zh = rows[localeIdx + 2];
+    expect(en.dataset.key).toBe("locale:en");
+    expect(zh.dataset.key).toBe("locale:zh-Hans");
+    expect(zh.dataset.checked).toBe("true");
+    expect(en.dataset.checked).toBeUndefined();
+
+    await click(en);
+    expect(onLocaleSelect).toHaveBeenCalledWith("en");
+  });
+
+  it("renders no emergency-stop control by default", () => {
+    const c = mount(headerNode({ username: "alice" }));
+    expect(c.textContent.toLowerCase()).not.toContain("emergency");
   });
 });

package/src/components/HkAdminHeader.tsx

@@ -1,7 +1,8 @@
-import { defineComponent, ref, type PropType, type VNode } from "vue";
+import { computed, defineComponent, ref, type PropType, type VNode } from "vue";
 import { Camera, ExternalLink, Languages, LogOut, Menu } from "lucide-vue-next";
-import { HBadge, HButton, HPopover, HSpinner } from "@celestia-island/hikari";
+import { HBadge, HButton, HSpinner } from "@celestia-island/hikari";
 import { useI18n } from "../i18n/context";
+import HkMenu, { type HkMenuItem } from "./HkMenu";
 
 export interface LocaleOption {
   code: string;
@@ -11,25 +12,30 @@ export interface LocaleOption {
 export const HkAdminHeader = defineComponent({
   name: "HkAdminHeader",
   props: {
-    /** Optional context title — empty (the default) hides the node
-     *  entirely, for layouts whose pages carry their own in-page title
-     *  (the HPageHeader convention). */
+    /** Page title rendered beside the avatar — the view the console is
+     *  currently ON (dashboard, providers, …). The signed-in nickname
+     *  deliberately does NOT go here: identity lives in the dropdown's
+     *  identity block, the bar labels WHERE you are. Empty hides the
+     *  node; long titles truncate. */
     title: { type: String, default: "" },
     showHamburger: { type: Boolean, default: false },
     compact: { type: Boolean, default: false },
     actions: { type: Array as PropType<VNode[]>, default: () => [] },
+    /** Signed-in identity. Drives the avatar fallback letter, the
+     *  dropdown identity block and the pending-state branch — it is
+     *  never rendered as bar text (the title slot above owns that). */
     username: { type: String, default: "" },
     avatarUrl: { type: String, default: "" },
     userEmail: { type: String, default: "" },
     userGroups: { type: Array as PropType<{ id: string; name: string }[]>, default: () => [] },
     /** What the avatar trigger does:
-     *  - "menu"   (default, desktop): toggle the user dropdown popover
+     *  - "menu"   (default, desktop): toggle the user dropdown
      *    (identity, avatar edit, language, logout).
      *  - "drawer" (mobile): emit `avatarClick` so the shell opens its nav
      *    drawer, whose `userPanel` footer carries the same user content.
-     *    The username stays hidden in this mode — the identity block
-     *    lives in the drawer, so a header username would read as a
-     *    duplicated stray control. */
+     *    Both the page title and the identity stay hidden in this mode —
+     *    they live in the drawer, so header copies read as duplicated
+     *    stray controls. */
     avatarAction: { type: String as PropType<"menu" | "drawer">, default: "menu" },
     /** Placeholder row shown while the identity is still loading (a
      *  fetchUser race on hard refresh) — the action items stay hidden
@@ -51,6 +57,13 @@ export const HkAdminHeader = defineComponent({
     /** Accessible label for the avatar trigger button. */
     avatarTriggerLabel: { type: String, default: undefined },
     localeMenuLabel: { type: String, default: undefined },
+    /** Offered locales for the Language cascade (the same shape the chat
+     *  frontend feeds its user menu). An empty list hides the row —
+     *  hosts without a locale concept simply omit it. Selecting a child
+     *  emits `localeSelect` with the code. */
+    localeOptions: { type: Array as PropType<LocaleOption[]>, default: () => [] },
+    /** Currently active locale code (the Language cascade's check). */
+    currentLocale: { type: String, default: undefined },
     logoutLabel: { type: String, default: undefined },
     adminGroupLabel: { type: String, default: undefined },
     /** "Go to frontend" menu row (external-face link, rendered directly
@@ -65,6 +78,7 @@ export const HkAdminHeader = defineComponent({
     hamburger: () => true,
     avatarClick: () => true,
     emergencyStop: () => true,
+    localeSelect: (_code: string) => true,
   },
   setup(props, { emit, slots }) {
     const { t } = useI18n();
@@ -72,8 +86,6 @@ export const HkAdminHeader = defineComponent({
     const userTriggerRef = ref<HTMLElement>();
     const avatarModalOpen = ref(false);
     const avatarFailed = ref(false);
-    const localeMenuOpen = ref(false);
-    const localeTriggerRef = ref<HTMLElement | null>(null);
 
     function onAvatarClick(e: MouseEvent) {
       e.stopPropagation();
@@ -84,6 +96,72 @@ export const HkAdminHeader = defineComponent({
       userMenuOpen.value = !userMenuOpen.value;
     }
 
+    /** The dropdown is the SAME engine as the chat frontend's user menu
+     *  (HkMenu): identity header via the header slot, cascading Language
+     *  children, danger logout row — every account surface (chat header,
+     *  console header, mobile drawer) reads identically. */
+    const userMenuItems = computed<HkMenuItem[]>(() => {
+      // Empty identity (fetchUser race on a hard refresh): a single
+      // force-sign-out escape row — action items floating above no
+      // identity read as a broken menu.
+      if (!props.username && !props.userEmail) {
+        return [
+          {
+            key: "force-signout",
+            label: props.forceSignOutLabel ?? t("hikari::adminHeader.forceSignOut", "Sign out"),
+          },
+        ];
+      }
+      const items: HkMenuItem[] = [
+        {
+          key: "avatar",
+          label: props.avatarMenuLabel ?? t("hikari::adminHeader.avatar", "Avatar"),
+          icon: Camera,
+        },
+      ];
+      if (props.localeOptions.length > 0) {
+        items.push({
+          key: "locale",
+          label: props.localeMenuLabel ?? t("hikari::adminHeader.language", "Language"),
+          icon: Languages,
+          children: props.localeOptions.map((o) => ({
+            key: `locale:${o.code}`,
+            label: o.label,
+            checked: o.code === props.currentLocale,
+          })),
+        });
+      }
+      // Frontend link — mirrors the drawer user panel's "go to frontend"
+      // row (same position: directly above logout). Opt-in via the label
+      // prop so admin-only panels keep the menu at avatar/language/logout.
+      if (props.goToFrontendLabel) {
+        items.push({ key: "go-to-frontend", label: props.goToFrontendLabel, icon: ExternalLink });
+      }
+      items.push({
+        key: "logout",
+        label: props.logoutLabel ?? t("hikari::adminHeader.logout", "Logout"),
+        icon: LogOut,
+        danger: true,
+      });
+      return items;
+    });
+
+    /** Leaf selection IS the action; HkMenu closes the menu around the
+     *  emit, so each branch only fires its own side effect. */
+    function onUserMenuSelect(key: string) {
+      if (key === "avatar") {
+        avatarModalOpen.value = true;
+      } else if (key.startsWith("locale:")) {
+        emit("localeSelect", key.slice("locale:".length));
+      } else if (key === "go-to-frontend") {
+        emit("goToFrontend");
+      } else if (key === "logout") {
+        emit("logout");
+      } else if (key === "force-signout") {
+        props.onForceSignOut?.();
+      }
+    }
+
     return () => (
       <header
         class={[
@@ -103,12 +181,7 @@ export const HkAdminHeader = defineComponent({
 
         <div ref={userTriggerRef} class="flex items-center gap-2 min-w-0">
           <button
-            class={[
-              "w-7 h-7 rounded-full overflow-hidden shrink-0 cursor-pointer transition-opacity relative group p-0 border-0",
-              props.avatarUrl
-                ? ""
-                : "bg-primary/10 border-2 border-primary/15 hover:border-primary/30",
-            ]}
+            class="w-7 h-7 rounded-full overflow-hidden shrink-0 cursor-pointer transition-opacity relative group p-0 border-0"
             aria-label={props.avatarTriggerLabel ?? t("hikari::adminHeader.avatarTrigger", "Account menu")}
             aria-haspopup={props.avatarAction === "drawer" ? "dialog" : "menu"}
             aria-expanded={props.avatarAction === "menu" ? userMenuOpen.value : undefined}
@@ -122,7 +195,12 @@ export const HkAdminHeader = defineComponent({
                 onError={() => { avatarFailed.value = true; }}
               />
             ) : (
-              <span class="text-xs font-bold text-primary/70">
+              // Letter fallback on the shared avatar primitive — the
+              // same filled-circle grammar as the chat frontend's
+              // trigger. The old border-2 ring made the console's
+              // avatar read as a different control (user report
+              // 2026-09-12: 前后台头像不一致).
+              <span class="s-user-avatar">
                 {props.username?.charAt(0).toUpperCase() || "?"}
               </span>
             )}
@@ -132,142 +210,85 @@ export const HkAdminHeader = defineComponent({
               </div>
             )}
           </button>
-          {props.avatarAction === "menu" && (
-            <span class="text-sm font-semibold text-text truncate max-w-[8rem]">
-              {props.username}
+          {/* WHERE am I — the open view's title, not the nickname. The
+              explicit 1.5 line-height keeps descenders (g, y, p) inside
+              the truncate clip box: the default text-sm box is exactly
+              the em advance, so zoom/subpixel rounding in a scaled root
+              shaves the ink off at the bottom (user report 2026-09-12:
+              the "g" tail of the nickname was visibly cut). */}
+          {props.avatarAction === "menu" && props.title && (
+            <span
+              class="text-sm font-semibold text-text truncate max-w-[8rem]"
+              style={{ lineHeight: "1.5" }}
+            >
+              {props.title}
             </span>
           )}
         </div>
 
-        <HPopover
-          modelValue={userMenuOpen.value}
-          onUpdate:modelValue={(v: boolean) => {
-            userMenuOpen.value = v;
-            // Closing the outer menu must also close the locale submenu,
-            // or it stays orphaned for the next open.
-            if (!v) localeMenuOpen.value = false;
-          }}
-          placement="bottom-start"
+        <HkMenu
+          open={userMenuOpen.value}
+          onUpdate:open={(v: boolean) => { userMenuOpen.value = v; }}
           anchorRef={userTriggerRef.value ?? null}
-          class="w-56"
-          sheetOnMobile
-          title={t("hikari::adminHeader.avatarTrigger")}
+          placement="bottom-start"
+          title={props.avatarTriggerLabel ?? t("hikari::adminHeader.avatarTrigger", "Account menu")}
+          items={userMenuItems.value}
+          onSelect={(key: string) => onUserMenuSelect(key)}
         >
-          {/* Empty identity (fetchUser race on a hard refresh): render a
-              single subtle placeholder row instead of the action items —
-              "Change Avatar"/"Logout" floating above no identity read as a
-              broken menu. The force-sign-out escape hatch lets the user
-              break out of a wedged session restore. */}
-          {!props.username && !props.userEmail ? (
-            <div>
-              <div class="s-user-header s-user-header--pending">
-                <HSpinner size="sm" />
-                <div class="s-user-header-email">{props.signingInLabel ?? t("hikari::adminHeader.signingIn", "Signing in…")}</div>
-              </div>
-              <button
-                class="s-popup-menu-item"
-                onClick={() => props.onForceSignOut?.()}
-              >
-                <span class="hk-menu-item-icon"><LogOut size={14} /></span>
-                {props.forceSignOutLabel ?? t("hikari::adminHeader.forceSignOut", "Sign out")}
-              </button>
-            </div>
-          ) : (
-            <div>
-              {/* Identity header FIRST — nickname, login email, permission
-                  badges — so every account surface reads identically. */}
-              <div class="s-user-header">
-                {props.username && <div class="s-user-header-name">{props.username}</div>}
-                {props.userEmail && <div class="s-user-header-email">{props.userEmail}</div>}
-                {props.userGroups && props.userGroups.length > 0 && (
-                  <div class="s-user-header-groups">
-                    {props.userGroups.map((g: { id: string; name: string }) => (
-                      <HBadge
-                        key={g.id}
-                        variant={g.name === "Administrators" ? "error" : "primary"}
-                        size="sm"
-                      >
-                        {g.name === "Administrators"
-                          ? (props.adminGroupLabel ?? t("hikari::adminHeader.adminGroup", "Administrators"))
-                          : g.name}
-                      </HBadge>
-                    ))}
+          {{
+            header: () => (
+              !props.username && !props.userEmail ? (
+                // Pending identity: a spinner beside the label reads as
+                // "actively working", not a frozen panel.
+                <div class="s-user-header s-user-header--pending">
+                  <HSpinner size="sm" />
+                  <div class="s-user-header-email">{props.signingInLabel ?? t("hikari::adminHeader.signingIn", "Signing in…")}</div>
+                </div>
+              ) : (
+                // Identity block FIRST — avatar, nickname, login email,
+                // permission badges — the same grammar the chat
+                // frontend's user-menu header uses (the shared
+                // s-user-header profile variant).
+                <div class="s-user-header s-user-header--profile">
+                  <span class="s-user-avatar-chip" aria-hidden="true">
+                    {props.avatarUrl && !avatarFailed.value ? (
+                      <img
+                        src={props.avatarUrl}
+                        alt=""
+                        class="s-user-avatar-img"
+                        onError={() => { avatarFailed.value = true; }}
+                      />
+                    ) : (
+                      <span class="s-user-avatar">
+                        {props.username?.charAt(0).toUpperCase() || "?"}
+                      </span>
+                    )}
+                  </span>
+                  <div class="s-user-header-body">
+                    {props.username && <div class="s-user-header-name">{props.username}</div>}
+                    {props.userEmail && <div class="s-user-header-email">{props.userEmail}</div>}
+                    {props.userGroups && props.userGroups.length > 0 && (
+                      <div class="s-user-header-groups">
+                        {props.userGroups.map((g: { id: string; name: string }) => (
+                          <HBadge
+                            key={g.id}
+                            variant={g.name === "Administrators" ? "error" : "primary"}
+                            size="sm"
+                          >
+                            {g.name === "Administrators"
+                              ? (props.adminGroupLabel ?? t("hikari::adminHeader.adminGroup", "Administrators"))
+                              : g.name}
+                          </HBadge>
+                        ))}
+                      </div>
+                    )}
                   </div>
-                )}
-              </div>
-              <button
-                class="s-popup-menu-item"
-                onClick={() => {
-                  userMenuOpen.value = false;
-                  avatarModalOpen.value = true;
-                }}
-              >
-                <span class="hk-menu-item-icon"><Camera size={14} /></span>
-                {props.avatarMenuLabel ?? t("hikari::adminHeader.avatar", "Avatar")}
-              </button>
-              {/* The language trigger owns the locale anchor: the ref sits
-                  on the BUTTON itself (not a wrapper div) so the picker
-                  popup anchors to it instead of falling back to inline
-                  rendering. The ref OBJECT is passed through the slot —
-                  reading .value here would freeze null from the first
-                  render before the ref attached. */}
-              <button
-                ref={localeTriggerRef}
-                class="s-popup-menu-item"
-                onClick={() => (localeMenuOpen.value = !localeMenuOpen.value)}
-              >
-                <span class="hk-menu-item-icon"><Languages size={14} /></span>
-                {props.localeMenuLabel ?? t("hikari::adminHeader.language", "Language")}
-              </button>
-              {slots["locale-picker"]?.({
-                open: localeMenuOpen.value,
-                onUpdateOpen: (v: boolean) => {
-                  localeMenuOpen.value = v;
-                  if (!v) userMenuOpen.value = false;
-                },
-                triggerRef: localeTriggerRef,
-              })}
-              {slots["user-menu-extra"]?.()}
-              {/* Frontend link — mirrors the drawer user panel's
-                  "go to frontend" row (same icon/position: directly
-                  above logout). Opt-in via the label prop so admin-only
-                  panels keep the menu at avatar/language/logout. */}
-              {props.goToFrontendLabel ? (
-                <button
-                  class="s-popup-menu-item"
-                  onClick={() => {
-                    userMenuOpen.value = false;
-                    emit("goToFrontend");
-                  }}
-                >
-                  <span class="hk-menu-item-icon"><ExternalLink size={14} /></span>
-                  {props.goToFrontendLabel}
-                </button>
-              ) : null}
-              <button
-                class="s-popup-menu-item"
-                onClick={() => {
-                  userMenuOpen.value = false;
-                  emit("logout");
-                }}
-              >
-                <span class="hk-menu-item-icon"><LogOut size={14} /></span>
-                {props.logoutLabel ?? t("hikari::adminHeader.logout", "Logout")}
-              </button>
-            </div>
-          )}
-        </HPopover>
+                </div>
+              )
+            ),
+          }}
+        </HkMenu>
 
-        {/* The page title lives INSIDE each page in the HPageHeader
-            convention (big title left, tool buttons right). The bar
-            renders an optional context title only when one is given —
-            empty hides the node, keeping the bar to identity + theme
-            controls. */}
-        {props.title && (
-          <h2 class="text-sm font-semibold text-text truncate min-w-0">
-            {props.title}
-          </h2>
-        )}
         <div class="ml-auto flex items-center gap-1.5 shrink-0">
           {props.showEmergencyStop && (
             <button

package/src/components/HkMenu.test.ts

@@ -789,6 +789,85 @@ describe("HkMenu sidebar variant", () => {
     expect(container.textContent).toContain("Products");
     expect(container.textContent).not.toContain("General");
   });
+
+  it("renders the header slot above the rows", () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const app = createApp({
+      render: () =>
+        h(
+          HkMenu,
+          { variant: "sidebar", open: true, items: navItems },
+          { header: () => h("div", { class: "sidebar-identity" }, "me@example.com") },
+        ),
+    });
+    mounts.push(app);
+    app.mount(container);
+
+    // The identity block leads the same inline surface (drawer account
+    // menu grammar) — first child of the nav, before any row.
+    const nav = container.querySelector(".hk-menu-sidebar");
+    const identity = nav?.querySelector(".sidebar-identity");
+    expect(identity).not.toBeNull();
+    expect(nav!.firstElementChild).toBe(identity);
+  });
+
+  it("renders the check column on rows that opt in (checked !== undefined)", async () => {
+    const selected: string[] = [];
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const app = createApp({
+      render: () =>
+        h(HkMenu, {
+          variant: "sidebar",
+          open: true,
+          items: [
+            {
+              key: "locale",
+              label: "Language",
+              children: [
+                { key: "en", label: "English", checked: false },
+                { key: "zh", label: "中文", checked: true },
+              ],
+            },
+            { key: "logout", label: "Log out", danger: true },
+          ],
+          onSelect: (key: string) => selected.push(key),
+        }),
+    });
+    mounts.push(app);
+    app.mount(container);
+    await settle();
+
+    // Groups default collapsed — expand the locale group.
+    const toggle = container.querySelector(
+      ".hk-menu-sidebar-group-toggle",
+    ) as HTMLButtonElement;
+    toggle.click();
+    await settle();
+
+    const rowOf = (label: string) =>
+      [...container.querySelectorAll(".hk-menu-sidebar-row")].find(
+        (r) => r.textContent?.includes(label),
+      ) as HTMLButtonElement;
+    const en = rowOf("English");
+    const zh = rowOf("中文");
+    const logout = rowOf("Log out");
+
+    // Checked rows carry the cell; true renders the mark, false keeps
+    // the empty placeholder so labels stay aligned. Rows without the
+    // opt-in get no cell at all.
+    expect(en.querySelector(".hk-menu-check")).not.toBeNull();
+    expect(en.querySelector(".hk-menu-check")?.hasAttribute("data-on")).toBe(false);
+    expect(zh.querySelector(".hk-menu-check")?.hasAttribute("data-on")).toBe(true);
+    expect(logout.querySelector(".hk-menu-check")).toBeNull();
+
+    en.click();
+    await settle();
+    expect(selected).toEqual(["en"]);
+  });
 });
 
 describe("HkMenu close linger (leave-transition window)", () => {

package/src/components/HkMenu.tsx

@@ -723,6 +723,7 @@ export default defineComponent({
           class="hk-menu-sidebar-row"
           data-depth={depth || undefined}
           data-active={active || undefined}
+          data-checked={item.checked || undefined}
           data-danger={item.danger || undefined}
           data-disabled={item.disabled || undefined}
           style={
@@ -735,6 +736,15 @@ export default defineComponent({
             emit("select", item.key, item);
           }}
         >
+          {/* Check column on opt-in rows (checked !== undefined): the
+              same fixed cell grammar the popup rows use, so a sidebar
+              locale/account picker shows its active entry in place.
+              false renders the empty placeholder to keep labels aligned. */}
+          {item.checked !== undefined && (
+            <span class="hk-menu-check" data-on={item.checked || undefined} aria-hidden="true">
+              {item.checked ? <Check size={12} /> : null}
+            </span>
+          )}
           {item.icon && (
             <span class="hk-menu-item-icon">{h(item.icon, { size: 16 })}</span>
           )}
@@ -782,6 +792,11 @@ export default defineComponent({
     function renderSidebar() {
       return (
         <nav class="hk-menu-sidebar" aria-label={props.title || "menu"}>
+          {/* Header slot (identity block, section label, …) above the
+              rows — mirrors the popup variant's level-0 header, so an
+              account menu renders the same grammar whether it pops up
+              on desktop or lives inside a drawer on mobile. */}
+          {slots.header?.()}
           {props.items.map((it) => renderSidebarItem(it, 0))}
         </nav>
       );

package/src/styles/admin-tokens.scss

@@ -364,6 +364,55 @@
   margin-bottom: var(--space-4);
 }
 
+/* Profile variant — avatar chip beside the identity column, the ONE
+   identity grammar the chat frontend's user menu and the admin
+   header's dropdown share (moved up from chest's ChatLayout so both
+   surfaces render from the same sheet). */
+.s-user-header--profile {
+  flex-direction: row;
+  align-items: center;
+  gap: var(--space-10);
+}
+
+/* Avatar primitives shared by the trigger button and the identity
+   chip: the letter fallback fills its box, images cover. */
+.s-user-avatar {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  border-radius: 50%;
+  background: var(--c-primary-medium);
+  color: rgb(var(--color-primary));
+  font-size: var(--text-xs);
+  font-weight: 700;
+  letter-spacing: 0.02em;
+}
+
+.s-user-avatar-img {
+  width: 100%;
+  height: 100%;
+  border-radius: 50%;
+  object-fit: cover;
+  display: block;
+}
+
+.s-user-avatar-chip {
+  flex-shrink: 0;
+  width: 32px;
+  height: 32px;
+  border-radius: 50%;
+  overflow: hidden;
+}
+
+.s-user-header-body {
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
 /* Pending variant (identity not yet hydrated): spinner beside the
    label reads as "actively working", not a frozen panel. */
 .s-user-header--pending {