@celestia-island/hikari 0.40.8 → 0.40.10

package/package.json

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

package/src/DemoApp.tsx

@@ -2,7 +2,7 @@
 // house rule: no SFCs in the tree). Render-only showcase of every exported
 // component; state is local and throwaway.
 import { computed, defineComponent, ref } from "vue";
-import { PackageOpen } from "lucide-vue-next";
+import { ChevronDown, ChevronUp, PackageOpen } from "lucide-vue-next";
 import { HIKARI_FONT_MONO } from "./theme/fontContext";
 import {
   HButton, HIconButton, HTooltip, HBadge, HTag, HIcon, HSpinner,
@@ -214,7 +214,7 @@ export default defineComponent({
           <div class="row">
             <HButton variant="primary" loading>Loading</HButton>
             <HButton variant="primary" disabled>Disabled</HButton>
-            <HButton variant="primary" shortcut="⌘K">Shortcut</HButton>
+            <HButton variant="primary" shortcut="Ctrl+K">Shortcut</HButton>
           </div>
         </section>
 
@@ -337,7 +337,7 @@ export default defineComponent({
           <div class="row">
             <span style="align-self:center;color:var(--color-muted, gray)">custom trigger + checkbox rows:</span>
             <span ref={panelAnchor} style="display:inline-flex">
-              <HButton onClick={() => (panel.value.open = !panel.value.open)}>Filter ▲</HButton>
+              <HButton onClick={() => (panel.value.open = !panel.value.open)}>Filter {panel.value.open ? <ChevronUp size={14} /> : <ChevronDown size={14} />}</HButton>
             </span>
             <HSelectPanel
               open={panel.value.open}
@@ -393,7 +393,7 @@ export default defineComponent({
 
         <section>
           <h2>HKbd</h2>
-          <div class="row"><HKbd keys="⌘" /><HKbd keys="⌥" /><HKbd keys="⇧" /><HKbd keys="⌃" /><HKbd keys="K" /><span> = open command palette</span></div>
+          <div class="row"><HKbd keys="Ctrl" /><HKbd keys="Alt" /><HKbd keys="Shift" /><HKbd keys="K" /><span> = open command palette</span></div>
         </section>
 
         <section>

package/src/components/HkAffixPicker.test.tsx

@@ -3,11 +3,19 @@ import { createApp, h, nextTick } from "vue";
 
 import HkAffixPicker, { type HkAffixOption } from "./HkAffixPicker";
 
+/** Regional-indicator flag pair for an ISO 3166-1 alpha-2 code, built
+ * from code points (same derivation as data/dialCodes flagEmoji) so the
+ * fixture source itself carries no literal emoji. */
+const flagOf = (iso: string): string =>
+  String.fromCodePoint(
+    ...Array.from(iso.toUpperCase(), (c) => 0x1f1e6 + c.charCodeAt(0) - 65),
+  );
+
 const OPTIONS: HkAffixOption[] = [
-  { key: "cn", label: "China", meta: "+86", flag: "🇨🇳", keywords: "zhongguo 中国 0086" },
-  { key: "cn-main", label: "中华人民共和国", meta: "+86", flag: "🇨🇳" },
-  { key: "jp", label: "Japan", meta: "+81", flag: "🇯🇵" },
-  { key: "us", label: "United States", meta: "+1", flag: "🇺🇸" },
+  { key: "cn", label: "China", meta: "+86", flag: flagOf("cn"), keywords: "zhongguo 中国 0086" },
+  { key: "cn-main", label: "中华人民共和国", meta: "+86", flag: flagOf("cn") },
+  { key: "jp", label: "Japan", meta: "+81", flag: flagOf("jp") },
+  { key: "us", label: "United States", meta: "+1", flag: flagOf("us") },
 ];
 
 const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
@@ -187,7 +195,7 @@ describe("HkAffixPicker", () => {
     const labels = rows().map((r) => r.textContent);
     // Both the China row (keyword substring match) and the renamed
     // cn-main row (fuzzy subsequence) surface.
-    expect(labels).toContain("🇨🇳China+86");
+    expect(labels).toContain(`${flagOf("cn")}China+86`);
     expect(labels.some((l) => l.includes("中华人民共和国"))).toBe(true);
   });
 

package/src/components/HkDrawer.scss

@@ -124,32 +124,11 @@
   color: var(--hi-color-text-primary, #333);
 }
 
+// Legacy placement hook — the chrome lives on the shared .hk-icon-button
+// / .hk-window-close rules (window-close.scss) since the unified-close
+// wave; only the header-flex placement stays here.
 .hk-drawer-close {
   flex-shrink: 0;
-  width: 2rem;
-  height: 2rem;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  padding: 0;
-  background: transparent;
-  border: none;
-  border-radius: var(--hi-radius-md, 0.5rem);
-  color: var(--hi-color-text-secondary, #666);
-  cursor: pointer;
-  transition:
-    background 0.15s ease,
-    color 0.15s ease;
-
-  &:hover {
-    background: var(--hi-secondary-bg, rgba(0, 0, 0, 0.06));
-    color: var(--hi-color-text-primary, #333);
-  }
-
-  &:focus-visible {
-    outline: 2px solid var(--hi-color-primary, #58a6ff);
-    outline-offset: 2px;
-  }
 }
 
 /* Track host for the body's overlay scrollbar — owns the flex slot in

package/src/components/HkDrawer.test.tsx

@@ -29,7 +29,7 @@ describe("HkDrawer back-guard (window-first back priority)", () => {
     }
   }
 
-  function mountDrawer(open: { value: boolean }, closable = true) {
+  function mountDrawer(open: { value: boolean }, closable = true, extra: Record<string, unknown> = {}) {
     const container = document.createElement("div");
     document.body.appendChild(container);
     containers.push(container);
@@ -39,6 +39,7 @@ describe("HkDrawer back-guard (window-first back priority)", () => {
           h(HkDrawer, {
             modelValue: open.value,
             closable,
+            ...extra,
             "onUpdate:modelValue": (v: boolean) => { open.value = v; },
           }, { default: () => h("div", "content") });
       },
@@ -62,6 +63,23 @@ describe("HkDrawer back-guard (window-first back priority)", () => {
     app.unmount();
   });
 
+  it("renders the unified icon-button close with the X glyph when titled", async () => {
+    const open = ref(true);
+    // The header (and thus the close) renders only with a title/header —
+    // pass one so the chrome exists to assert on.
+    const app = mountDrawer(open, true, { title: "Inspector" });
+    await settle();
+
+    const closeBtn = document.body.querySelector<HTMLButtonElement>(".hk-drawer-close")!;
+    expect(closeBtn).not.toBeNull();
+    expect(closeBtn.classList.contains("hk-window-close")).toBe(true);
+    // Unified close glyph: shared icon-button renders the registry X
+    // (default-slot branch, never the fallback placeholder circle).
+    expect(closeBtn.querySelector(".hk-icon")).not.toBeNull();
+    expect(closeBtn.querySelector("circle")).toBeNull();
+    app.unmount();
+  });
+
   it("a non-closable drawer never owns history", async () => {
     const open = ref(true);
     const app = mountDrawer(open, false);

package/src/components/HkDrawer.tsx

@@ -19,6 +19,9 @@ import { usePopupManager } from "../runtime/usePopupManager";
 import { createBackGuard } from "../runtime/backStack";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
+import HIconButton from "./HkIconButton";
+import HIcon from "./HkIcon";
+import "./window-close.scss";
 
 type DrawerSide = "left" | "right" | "top" | "bottom";
 
@@ -282,24 +285,15 @@ export default defineComponent({
                     <span class="hk-drawer-title">{props.title}</span>
                   )}
                   {props.closable ? (
-                    <button
-                      class="hk-drawer-close"
+                    <HIconButton
+                      class="hk-window-close hk-drawer-close"
+                      size={32}
+                      variant="ghost"
                       aria-label={t("hikari::drawer.close", "Close")}
                       onClick={close}
                     >
-                      <svg
-                        viewBox="0 0 24 24"
-                        fill="none"
-                        stroke="currentColor"
-                        stroke-width="2"
-                        stroke-linecap="round"
-                        width="16"
-                        height="16"
-                      >
-                        <line x1="18" y1="6" x2="6" y2="18" />
-                        <line x1="6" y1="6" x2="18" y2="18" />
-                      </svg>
-                    </button>
+                      <HIcon name="X" size={16} />
+                    </HIconButton>
                   ) : null}
                 </div>
               ) : null}

package/src/components/HkIconButton.test.tsx

@@ -72,4 +72,34 @@ describe("HkIconButton", () => {
     expect(btn.disabled).toBe(true);
     expect(btn.getAttribute("aria-label")).toBe("sync");
   });
+
+  // Unified window-close wave: children passed as the DEFAULT slot render
+  // as the icon (named `icon` slot still wins; no children at all keeps the
+  // placeholder circle). Without the default-slot branch, natural JSX usage
+  // `<HIconButton><HIcon name="X"/></HIconButton>` silently rendered the
+  // fallback circle instead of the consumer's glyph.
+  it("renders default-slot children as the icon", () => {
+    const c = mountComp(() =>
+      h(HkIconButton, { "aria-label": "close" }, { default: () => h("span", { class: "glyph-probe" }, "✕") }),
+    );
+    expect(c.querySelector(".glyph-probe")).not.toBeNull();
+    // The placeholder circle only renders when NEITHER slot is provided.
+    expect(c.querySelector("circle")).toBeNull();
+  });
+
+  it("prefers the named icon slot over default children", () => {
+    const c = mountComp(() =>
+      h(HkIconButton, { "aria-label": "close" }, {
+        icon: () => h("span", { class: "named-probe" }),
+        default: () => h("span", { class: "default-probe" }),
+      }),
+    );
+    expect(c.querySelector(".named-probe")).not.toBeNull();
+    expect(c.querySelector(".default-probe")).toBeNull();
+  });
+
+  it("keeps the placeholder circle when no slot content is given", () => {
+    const c = mountComp(() => h(HkIconButton, { "aria-label": "probe" }));
+    expect(c.querySelector("circle")).not.toBeNull();
+  });
 });

package/src/components/HkIconButton.tsx

@@ -29,13 +29,17 @@ export default defineComponent({
         {...attrs}
       >
         <span class="hk-icon-button-icon">
-          {slots.icon ? (
-            slots.icon()
-          ) : (
-            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-              <circle cx="12" cy="12" r="10" />
-            </svg>
-          )}
+          {slots.icon
+            ? slots.icon()
+            : slots.default
+              ? // Natural children usage: <HIconButton><HIcon .../></HIconButton>
+                // renders the child as the icon (unified window-close wave).
+                slots.default()
+              : (
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                  <circle cx="12" cy="12" r="10" />
+                </svg>
+              )}
         </span>
       </button>
     );

package/src/components/HkImageLightbox.test.tsx

@@ -61,6 +61,10 @@ describe("HkImageLightbox", () => {
 
     const btn = s.closeButton();
     expect(btn.getAttribute("aria-label")).toBe("Close");
+    // Unified close glyph: the shared icon-button renders the registry X
+    // (default-slot branch), never the fallback placeholder circle.
+    expect(btn.querySelector(".hk-icon")).not.toBeNull();
+    expect(btn.querySelector("circle")).toBeNull();
   });
 
   it("renders nothing while closed", () => {

package/src/components/HkImageLightbox.tsx

@@ -3,8 +3,10 @@ import { defineComponent, onBeforeUnmount, watch } from "vue";
 import { useI18n } from "../i18n/context";
 import "./HkImageLightbox.scss";
 import HIconButton from "./HkIconButton";
+import HIcon from "./HkIcon";
 import HImageViewer from "./HkImageViewer";
 import HModal from "./HkModal";
+import "./window-close.scss";
 
 /**
  * Immersive fullscreen viewer for a single image — the "special modal"
@@ -67,18 +69,13 @@ export default defineComponent({
         <div class="hk-image-lightbox-stage">
           <HImageViewer src={props.src} alt={props.alt} />
           <HIconButton
-            class="hk-image-lightbox-close"
+            class="hk-window-close hk-image-lightbox-close"
             size={32}
             variant="ghost"
             aria-label={t("hikari::imageLightbox.close", "Close")}
             onClick={close}
           >
-            {{ icon: () => (
-              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
-                <line x1="18" y1="6" x2="6" y2="18" />
-                <line x1="6" y1="6" x2="18" y2="18" />
-              </svg>
-            ) }}
+            <HIcon name="X" size={16} />
           </HIconButton>
         </div>
       </HModal>

package/src/components/HkLocalizedInput.test.tsx

@@ -3,6 +3,14 @@ import { createApp, h, nextTick } from "vue";
 
 import { HkLocalizedInput } from "./HkLocalizedInput";
 
+/** Regional-indicator flag pair for an ISO 3166-1 alpha-2 code, built
+ * from code points (same derivation as data/dialCodes flagEmoji) so the
+ * test source itself carries no literal emoji. */
+const flagOf = (iso: string): string =>
+  String.fromCodePoint(
+    ...Array.from(iso.toUpperCase(), (c) => 0x1f1e6 + c.charCodeAt(0) - 65),
+  );
+
 const LOCALES = [
   { code: "en", label: "English" },
   { code: "zh-Hans", label: "简体中文" },
@@ -504,15 +512,15 @@ describe("HkLocalizedInput", () => {
           sourceLang: "en",
           translations: { en: "Plant overview", "zh-Hans": "工厂总览" },
           localeOptions: [
-            { code: "en", label: "English", flag: "🇬🇧" },
-            { code: "zh-Hans", label: "简体中文", flag: "🇨🇳" },
+            { code: "en", label: "English", flag: flagOf("gb") },
+            { code: "zh-Hans", label: "简体中文", flag: flagOf("cn") },
           ],
         }),
     });
     app.mount(container);
     mounts.push({ app, container });
     await openPicker(container);
-    expect(tag("简体中文")?.querySelector(".hk-affix-tag-flag")?.textContent).toBe("🇨🇳");
+    expect(tag("简体中文")?.querySelector(".hk-affix-tag-flag")?.textContent).toBe(flagOf("cn"));
   });
 
   it("follows a sourceLang change without stealing focus", async () => {

package/src/components/HkMenu.scss

@@ -36,7 +36,7 @@
 /* Leading check column (selectMode). The cell is reserved on EVERY row
  * of a level while the column is on, so labels stay aligned; only
  * checked === true shows the mark — an SVG check inside the same fixed
- * cell grammar as leading icons (the old text "✓" carried its own
+ * cell grammar as leading icons (the old text glyph carried its own
  * baseline rhythm and sat off-center against svg icons). */
 .hk-menu-check {
   @include mi.icon;

package/src/components/HkMenu.test.ts

@@ -3,6 +3,14 @@ import { createApp, defineComponent, h, nextTick, ref, type ComponentPublicInsta
 
 import HkMenu, { type HkMenuItem } from "./HkMenu";
 
+/** Regional-indicator flag pair for an ISO 3166-1 alpha-2 code, built
+ * from code points (same derivation as data/dialCodes flagEmoji) so the
+ * fixture source itself carries no literal emoji. */
+const flagOf = (iso: string): string =>
+  String.fromCodePoint(
+    ...Array.from(iso.toUpperCase(), (c) => 0x1f1e6 + c.charCodeAt(0) - 65),
+  );
+
 const mounts: ReturnType<typeof createApp>[] = [];
 const containers: HTMLElement[] = [];
 
@@ -11,8 +19,8 @@ const items: HkMenuItem[] = [
     key: "lang",
     label: "Language",
     children: [
-      { key: "en", label: "English", flag: "🇬🇧" },
-      { key: "zh", label: "中文", flag: "🇨🇳", checked: true },
+      { key: "en", label: "English", flag: flagOf("gb") },
+      { key: "zh", label: "中文", flag: flagOf("cn"), checked: true },
     ],
   },
   { key: "logout", label: "Log out", danger: true },

package/src/components/HkModal.scss

@@ -173,44 +173,18 @@
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
+  // Window chrome, not content — titles never participate in text
+  // selection (2026-09-04 user report alongside the sheet chrome pass).
+  user-select: none;
+  -webkit-user-select: none;
 }
 
+// Legacy placement hook — the chrome (box, radius, colors, hover tint,
+// selection) lives on the shared .hk-icon-button / .hk-window-close rules
+// (window-close.scss) since the unified-close wave; only placement stays
+// here so the header flex keeps the button pinned right.
 .hk-modal-close {
   flex-shrink: 0;
-  width: 2rem;
-  height: 2rem;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  padding: 0;
-  background: transparent;
-  border: none;
-  border-radius: var(--hi-radius-md, 0.5rem);
-  color: var(--hk-modal-close-color, var(--hi-color-text-secondary, #666));
-  cursor: pointer;
-  transition:
-    background 0.15s ease,
-    color 0.15s ease;
-
-  &:hover {
-    background: var(
-      --hk-modal-close-hover-bg,
-      var(--hi-secondary-bg, rgba(0, 0, 0, 0.06))
-    );
-    color: var(
-      --hk-modal-close-hover-color,
-      var(--hi-color-text-primary, #333)
-    );
-  }
-
-  &:active {
-    transform: scale(0.92);
-  }
-
-  &:focus-visible {
-    outline: 2px solid var(--hi-color-primary, #ffc0cb);
-    outline-offset: 2px;
-  }
 }
 
 // ------
@@ -339,9 +313,10 @@
     // modal rendered ~60vh of blank body under three rows). The top inset
     // now only bounds the sheet via the max-height cap below.
     top: auto;
-    // --hk-sheet-bottom-gap keeps the docked sheet from touching the very
-    // bottom edge (host-tunable; chest narrows the default visual gap).
-    bottom: var(--hk-sheet-bottom-gap, 0.375rem);
+    // --hk-sheet-bottom-gap: hosts may lift the docked sheet off the very
+    // bottom edge; the family default sits flush on it (2026-09-04 user
+    // report: even the tightened 0.375rem default still read as a seam).
+    bottom: var(--hk-sheet-bottom-gap, 0px);
     left: 0;
     right: 0;
     transform: none;
@@ -356,10 +331,10 @@
     // Plain-vh fallback first: dvh-less engines (older Android WebView /
     // Tauri) would drop the whole dvh calc and leave the sheet uncapped.
     max-height: calc(
-      100vh - var(--hk-sheet-top-inset, 4.25rem) - var(--hk-sheet-bottom-gap, 0.375rem)
+      100vh - var(--hk-sheet-top-inset, 4.25rem) - var(--hk-sheet-bottom-gap, 0px)
     );
     max-height: calc(
-      100dvh - var(--hk-sheet-top-inset, 4.25rem) - var(--hk-sheet-bottom-gap, 0.375rem)
+      100dvh - var(--hk-sheet-top-inset, 4.25rem) - var(--hk-sheet-bottom-gap, 0px)
     );
   }
 

package/src/components/HkModal.sheetgap.test.ts

@@ -21,13 +21,14 @@ const here = dirname(fileURLToPath(import.meta.url));
 const src = readFileSync(join(here, "HkModal.scss"), "utf-8");
 
 describe("HkModal mobile sheet spacing contract", () => {
-  it("sizes the docked sheet from --hk-sheet-bottom-gap (not hard 0)", () => {
+  it("sizes the docked sheet from --hk-sheet-bottom-gap (host-tunable hook)", () => {
     const block = src.slice(src.indexOf("@media (max-width: 767px)"));
     expect(block).toContain("bottom: var(--hk-sheet-bottom-gap");
-    // Default keeps a small visible gap; hosts may narrow or zero it.
-    // (2026-08-29 user request: the docked sheet sat too far off the
-    // bottom — default tightened from 0.5rem to 0.375rem.)
-    expect(block).toMatch(/--hk-sheet-bottom-gap,\s*0\.375rem/);
+    // Family default sits flush on the bottom edge; hosts may re-add a
+    // gap via the same custom property. (History: 2026-08-29 tightened
+    // 0.5rem → 0.375rem; 2026-09-04 user report — the remaining sliver
+    // still read as a visible seam, so the default settled on 0.)
+    expect(block).toMatch(/--hk-sheet-bottom-gap,\s*0px/);
   });
 
   it("keeps the footer gap host-tunable and stacks the safe-area inset", () => {

package/src/components/HkModal.test.tsx

@@ -139,6 +139,13 @@ describe("HkModal back-guard (window-first back priority)", () => {
     await settle();
     expect((window.history.state as Record<string, unknown>)?.__hkBack).toEqual(expect.any(String));
 
+    // Unified close chrome: the header close is the shared icon-button X
+    // (default-slot glyph, never the fallback placeholder circle).
+    const closeBtn = document.querySelector<HTMLButtonElement>(".hk-modal-close")!;
+    expect(closeBtn.classList.contains("hk-window-close")).toBe(true);
+    expect(closeBtn.querySelector(".hk-icon")).not.toBeNull();
+    expect(closeBtn.querySelector("circle")).toBeNull();
+
     (document.querySelector(".hk-modal-close") as HTMLButtonElement).click();
     await until(() => open.value === false);
     // History rewound to the page base — a subsequent back leaves the page,

package/src/components/HkModal.tsx

@@ -25,6 +25,9 @@ import { useSizeMorph } from "../composables/useSizeMorph";
 import HButton from "./HkButton";
 import HFab from "./HkFab";
 import HSpinner from "./HkSpinner";
+import HIconButton from "./HkIconButton";
+import HIcon from "./HkIcon";
+import "./window-close.scss";
 
 export interface ModalAction {
   label: string;
@@ -738,24 +741,19 @@ export default defineComponent({
                           {slots.header ? (props.title ?? "") : (props.title ?? "")}
                         </h2>
                         {props.closable && (
-                          <button
-                            class="hk-modal-close"
+                          // Unified window-close affordance: the shared
+                          // icon button + registry X glyph (see
+                          // window-close.scss) — no per-component ✕ SVG.
+                          // `hk-modal-close` stays as the placement hook.
+                          <HIconButton
+                            class="hk-window-close hk-modal-close"
+                            size={32}
+                            variant="ghost"
                             aria-label={t("hikari::modal.close", "Close")}
                             onClick={close}
                           >
-                            <svg
-                              viewBox="0 0 24 24"
-                              fill="none"
-                              stroke="currentColor"
-                              stroke-width="2"
-                              stroke-linecap="round"
-                              width="16"
-                              height="16"
-                            >
-                              <line x1="18" y1="6" x2="6" y2="18" />
-                              <line x1="6" y1="6" x2="18" y2="18" />
-                            </svg>
-                          </button>
+                            <HIcon name="X" size={16} />
+                          </HIconButton>
                         )}
                       </div>
                       {slots.header && (

package/src/components/HkPasswordInput.test.ts

@@ -220,14 +220,14 @@ describe("HkPasswordInput variants and icons", () => {
       "",
       { icon: "custom" },
       {
-        icon: () => [h("span", { class: "custom-icon" }, "custom-✓")],
+        icon: () => [h("span", { class: "custom-icon" }, "custom-mark")],
       },
     );
     expect(
       container.querySelector(".hk-pwd-lock")?.getAttribute("data-icon"),
     ).toBe("custom");
     expect(container.querySelector(".custom-icon")?.textContent).toBe(
-      "custom-✓",
+      "custom-mark",
     );
     expect(container.querySelector(".hk-pwd-lock svg")).toBeNull();
   });

package/src/components/HkPopover.scss

@@ -100,7 +100,7 @@
     72vh,
     calc(
       100vh - var(--hk-sheet-top-inset, 4.25rem) -
-        var(--hk-sheet-bottom-gap, 0.375rem)
+        var(--hk-sheet-bottom-gap, 0px)
     )
   );
   display: flex;
@@ -137,6 +137,10 @@
   cursor: pointer;
   display: flex;
   justify-content: center;
+  // Window chrome, not content — a long-press must never start a text
+  // selection over the drag handle.
+  user-select: none;
+  -webkit-user-select: none;
 
   &::before {
     content: "";
@@ -147,17 +151,46 @@
   }
 }
 
-.hk-popover-sheet-title {
+/* Sheet heading row — title on the left, explicit close on the right,
+ * one vertically-centered flex line (2026-09-04 user report: the bare
+ * title band read too small, hung right of the content it named, and
+ * long-press selected it; every other window in the app carries an ✕).
+ * The title aligns to the CONTENT edge: the leading inset defaults to
+ * --space-12, matching the padded content blocks popover sheets host
+ * (e.g. HkContextRing's 0.75rem body). Hosts tune it via
+ * --hk-sheet-title-inset; the trailing inset hugs the close button. */
+.hk-popover-sheet-header {
   flex-shrink: 0;
-  // Same heading grammar as the select sheet title: small, semibold,
-  // slightly letterspaced, inset to the content edge. Hosts tune the
-  // leading inset via --hk-sheet-title-inset.
-  padding: 0 var(--space-16, 1rem) var(--space-8, 0.5rem)
-    var(--hk-sheet-title-inset, calc(var(--space-16, 1rem) * 2));
-  font-size: var(--text-xs, 0.75rem);
+  display: flex;
+  align-items: center;
+  gap: var(--space-8, 0.5rem);
+  padding: 0 var(--space-8, 0.5rem) var(--space-8, 0.5rem)
+    var(--hk-sheet-title-inset, var(--space-12, 0.75rem));
+}
+
+.hk-popover-sheet-title {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  // Same heading grammar as the select sheet title: semibold, slightly
+  // letterspaced — one step up from the old 0.75rem so the sheet names
+  // itself at body-text size, and window chrome never participates in
+  // text selection.
+  font-size: var(--text-base, 0.875rem);
   font-weight: 600;
   letter-spacing: 0.02em;
   color: rgb(var(--color-muted, 140 140 140));
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+.hk-popover-sheet-close {
+  // Legacy placement hook — the chrome lives on the shared .hk-icon-button
+  // / .hk-window-close rules (window-close.scss) since the unified-close
+  // wave. Only the right-edge pinning stays here.
+  margin-left: auto;
 }
 
 .hk-popover-sheet-enter-active {

package/src/components/HkPopover.sheetdock.test.ts

@@ -17,11 +17,13 @@ const tsx = readFileSync(join(here, "HkPopover.tsx"), "utf-8");
 const scss = readFileSync(join(here, "HkPopover.scss"), "utf-8");
 
 describe("HkPopover mobile sheet docking contract", () => {
-  it("docks the sheet above the shared bottom gap (inline sheet style)", () => {
+  it("docks the sheet at the shared bottom-gap hook (inline sheet style)", () => {
     const block = tsx.slice(tsx.indexOf("panelStyle"));
     expect(block).toContain("var(--hk-sheet-bottom-gap");
-    // Same default as the HkModal sheet contract.
-    expect(block).toMatch(/--hk-sheet-bottom-gap,\s*0\.375rem/);
+    // Family default sits flush on the bottom edge (2026-09-04 user
+    // report: even the tightened 0.375rem lift read as a visible seam);
+    // hosts may re-add a gap via the same custom property.
+    expect(block).toMatch(/--hk-sheet-bottom-gap,\s*0px/);
   });
 
   it("keeps sheet content clear of the home bar via the safe-area inset", () => {

package/src/components/HkPopover.tsx

@@ -15,9 +15,13 @@ import {
 
 import { usePopupManager, type PopupHandle } from "../runtime/usePopupManager";
 import { useBreakpoint } from "../runtime/useBreakpoint";
+import { useI18n } from "../i18n/context";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { onceFrame } from "../runtime/animationBus";
+import HIconButton from "./HkIconButton";
+import HIcon from "./HkIcon";
+import "./window-close.scss";
 import "./HkPopover.scss";
 
 export type PopupPlacement =
@@ -76,6 +80,7 @@ export default defineComponent({
   setup(props, { emit, slots }) {
     const attrs = useAttrs();
     const manager = usePopupManager();
+    const { t } = useI18n();
     const handle = ref<PopupHandle | null>(null);
     const panelRef = ref<HTMLElement>();
     const resolvedPlacement = ref<PopupPlacement>(props.placement);
@@ -489,15 +494,17 @@ export default defineComponent({
 
     const panelStyle = computed(() => {
       if (sheetMode.value) {
-        // Bottom sheet: pinned above the bottom edge with the SAME
-        // host-tunable gap as the HkModal mobile docking
-        // (--hk-sheet-bottom-gap) so every bottom-up window belongs to
-        // one sheet family; full width, inside the top inset reserved
-        // for the secondary-window breadcrumb strip.
+        // Bottom sheet: sits flush on the viewport bottom edge (the
+        // host-tunable --hk-sheet-bottom-gap lift is still honored so the
+        // sheet belongs to the HkModal/HkSelect sheet family — the family
+        // default is 0 since the 2026-09-04 report: even a 0.375rem lift
+        // read as a visible seam under the docked sheet); full width,
+        // inside the top inset reserved for the secondary-window
+        // breadcrumb strip.
         return {
           left: "0",
           right: "0",
-          bottom: "var(--hk-sheet-bottom-gap, 0.375rem)",
+          bottom: "var(--hk-sheet-bottom-gap, 0px)",
           top: "auto" as const,
           position: "fixed" as const,
           pointerEvents: "auto" as const,
@@ -568,11 +575,27 @@ export default defineComponent({
                 {sheetMode.value && (
                   <div class="hk-popover-sheet-grabber" aria-hidden="true" onClick={() => close()} />
                 )}
-                {sheetMode.value && props.title && (
-                  // Sheet heading band — opt-in via the `title` prop so
-                  // anchored-desktop consumers are untouched; keeps the
-                  // docked sheet naming itself like every other window.
-                  <div class="hk-popover-sheet-title">{props.title}</div>
+                {sheetMode.value && (
+                  // Sheet heading row — the title and the close button on
+                  // one vertically-centered line (2026-09-04 user report:
+                  // the bare title band read too small and hung right of
+                  // the content it named, and every other window in the
+                  // app carries an explicit ✕). Same header grammar as the
+                  // HkModal header: title left, close on the right edge.
+                  <div class="hk-popover-sheet-header">
+                    {props.title && (
+                      <div class="hk-popover-sheet-title">{props.title}</div>
+                    )}
+                    <HIconButton
+                      class="hk-window-close hk-popover-sheet-close"
+                      size={32}
+                      variant="ghost"
+                      aria-label={t("hikari::modal.close", "Close")}
+                      onClick={close}
+                    >
+                      <HIcon name="X" size={16} />
+                    </HIconButton>
+                  </div>
                 )}
                 {slots.default?.()}
               </div>

package/src/components/HkPopoverSheet.test.tsx

@@ -127,4 +127,54 @@ describe("HkPopover sheetOnMobile", () => {
     expect(document.body.querySelector(".hk-popover-panel")!.classList.contains("hk-is-sheet")).toBe(true);
     expect(document.body.querySelector(".hk-popover-scrim")).toBeNull();
   });
+
+  // 2026-09-04 user report: the sheet heading was a bare small band —
+  // the sheet now names itself with a title + explicit close button on
+  // one vertically-centered line, like every other window in the app.
+  it("renders a title + close heading row when titled, close alone when not", async () => {
+    setViewport(375);
+    mountPopover({ sheetOnMobile: true, title: "Context usage" });
+    await nextTick();
+
+    const panel = document.body.querySelector<HTMLElement>(".hk-popover-panel")!;
+    const header = panel.querySelector<HTMLElement>(".hk-popover-sheet-header")!;
+    expect(header).toBeTruthy();
+    expect(header.querySelector(".hk-popover-sheet-title")!.textContent).toBe("Context usage");
+    const close = header.querySelector<HTMLButtonElement>(".hk-popover-sheet-close")!;
+    expect(close).toBeTruthy();
+    expect(close.getAttribute("aria-label")).toBeTruthy();
+    // The X glyph renders through the default-slot branch of HkIconButton
+    // (the fallback placeholder circle must never appear in a window close).
+    expect(close.querySelector(".hk-icon")).not.toBeNull();
+    expect(close.querySelector("circle")).toBeNull();
+  });
+
+  it("closes the sheet from the heading close button", async () => {
+    setViewport(375);
+    const { open } = mountPopover({ sheetOnMobile: true, title: "Context usage" });
+    await nextTick();
+    const close = document.body.querySelector<HTMLButtonElement>(".hk-popover-sheet-close")!;
+    close.click();
+    await nextTick();
+    expect(open.value).toBe(false);
+  });
+
+  it("renders the close button even without a title, right-aligned", async () => {
+    setViewport(375);
+    mountPopover({ sheetOnMobile: true });
+    await nextTick();
+    const header = document.body.querySelector<HTMLElement>(".hk-popover-sheet-header")!;
+    expect(header.querySelector(".hk-popover-sheet-title")).toBeNull();
+    expect(header.querySelector(".hk-popover-sheet-close")).toBeTruthy();
+  });
+
+  it("keeps the heading row out of anchored desktop mode", async () => {
+    setViewport(1200);
+    mountPopover({ sheetOnMobile: true, title: "Context usage" });
+    await nextTick();
+    const panel = document.body.querySelector<HTMLElement>(".hk-popover-panel")!;
+    expect(panel.querySelector(".hk-popover-sheet-header")).toBeNull();
+    expect(panel.querySelector(".hk-popover-sheet-title")).toBeNull();
+    expect(panel.querySelector(".hk-popover-sheet-close")).toBeNull();
+  });
 });

package/src/components/HkSelect.scss

@@ -244,11 +244,12 @@
   position: fixed;
   left: 0;
   right: 0;
-  /* Float off the bottom edge with the SAME host-tunable gap as the
-   * HkModal mobile docking (--hk-sheet-bottom-gap) — every bottom-up
-   * window reads as one sheet family; was glued to bottom: 0, which is
-   * exactly why dropdown sheets read as "not the standard modal". */
-  bottom: var(--hk-sheet-bottom-gap, 0.375rem);
+  /* Sit flush on the bottom edge; the host-tunable --hk-sheet-bottom-gap
+   * lift (shared with the HkModal mobile docking) stays available so
+   * every bottom-up window reads as one sheet family. Was glued to
+   * bottom: 0, then floated at the 0.375rem family default — both wrong
+   * for someone; the 2026-09-04 report settles the family on flush. */
+  bottom: var(--hk-sheet-bottom-gap, 0px);
   display: flex;
   flex-direction: column;
   /* The panel height hugs its content (up to the cap below); the sheet
@@ -266,7 +267,7 @@
     72vh,
     calc(
       100vh - var(--hk-sheet-top-inset, 4.25rem) -
-        var(--hk-sheet-bottom-gap, 0.375rem)
+        var(--hk-sheet-bottom-gap, 0px)
     )
   );
   background: rgb(var(--color-surface));
@@ -285,6 +286,10 @@
   cursor: pointer;
   display: flex;
   justify-content: center;
+  /* Window chrome — never a text-selection start (matches the popover
+   * sheet grabber). */
+  user-select: none;
+  -webkit-user-select: none;
 
   &::before {
     content: "";
@@ -295,20 +300,46 @@
   }
 }
 
-.hk-select-sheet-title {
+/* Sheet heading row — same unified grammar as the popover sheet header
+ * (title left, shared icon-button ✕ on the right edge, one vertically
+ * centered line). The select sheet previously had NO explicit close
+ * affordance at all: dismissal was grabber-tap/scrim only. */
+.hk-select-sheet-header {
   flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  padding: 0 var(--space-8) var(--space-8) 0;
+}
+
+.hk-select-sheet-close {
+  // Right-edge pinning with or without a title beside it; the chrome lives
+  // on the shared .hk-icon-button / .hk-window-close rules
+  // (window-close.scss) since the unified-close wave.
+  margin-left: auto;
+}
+
+.hk-select-sheet-title {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
   /* Left inset tracks the sheet ENTRIES' text edge, not their card
    * edge: the list pads option blocks in by --space-16 and rows carry
    * roughly another --space-16 of leading padding inside, so the old
    * single --space-16 left the title hanging left of every row it
    * named instead of reading as the list's heading. Hosts tune it via
-   * --hk-sheet-title-inset; the trailing inset stays --space-16. */
-  padding: 0 var(--space-16) var(--space-8)
-    var(--hk-sheet-title-inset, calc(var(--space-16) * 2));
-  font-size: var(--text-xs);
+   * --hk-sheet-title-inset. Size/weight match the popover sheet heading
+   * (--text-base, window chrome never text-selectable). The trailing
+   * inset doubles as the gap to the close button; the vertical rhythm
+   * moved to the header row. */
+  padding: 0 var(--space-16) 0 var(--hk-sheet-title-inset, calc(var(--space-16) * 2));
+  font-size: var(--text-base);
   font-weight: 600;
   letter-spacing: 0.02em;
   color: rgb(var(--color-muted));
+  user-select: none;
+  -webkit-user-select: none;
 }
 
 /* Track host for the sheet list's overlay scrollbar — owns the flex

package/src/components/HkSelect.sheetdock.test.ts

@@ -16,11 +16,13 @@ const here = dirname(fileURLToPath(import.meta.url));
 const src = readFileSync(join(here, "HkSelect.scss"), "utf-8");
 
 describe("HkSelectPanel mobile sheet docking contract", () => {
-  it("floats the sheet on --hk-sheet-bottom-gap (not hard 0)", () => {
+  it("docks the sheet on the --hk-sheet-bottom-gap hook (flush family default)", () => {
     const block = src.match(/\.hk-select-sheet-panel\s*{[^}]*}/)?.[0] ?? "";
     expect(block).toContain("bottom: var(--hk-sheet-bottom-gap");
-    // Same default as the HkModal sheet contract.
-    expect(block).toMatch(/--hk-sheet-bottom-gap,\s*0\.375rem/);
+    // Family default sits flush on the bottom edge (2026-09-04 user
+    // report: the 0.375rem family default read as a seam); hosts may
+    // re-add a gap via the same custom property.
+    expect(block).toMatch(/--hk-sheet-bottom-gap,\s*0px/);
   });
 
   it("stacks the safe-area inset on the sheet list bottom padding", () => {

package/src/components/HkSelectPanel.tsx

@@ -17,6 +17,10 @@ import { createBackGuard } from "../runtime/backStack";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
 import { useSizeMorph } from "../composables/useSizeMorph";
+import { useI18n } from "../i18n/context";
+import HIconButton from "./HkIconButton";
+import HIcon from "./HkIcon";
+import "./window-close.scss";
 import "./HkSelect.scss";
 
 /**
@@ -86,6 +90,7 @@ export default defineComponent({
   },
   setup(props, { emit, slots, expose }) {
     const manager = usePopupManager();
+    const { t } = useI18n();
     const handle = ref<PopupHandle | null>(null);
     /** z of the last live registration — the leave transition keeps
      *  painting at this z after the registry entry is dropped, so a
@@ -541,9 +546,26 @@ export default defineComponent({
                     aria-hidden="true"
                     onClick={close}
                   />
-                  {props.title ? (
-                    <div class="hk-select-sheet-title">{props.title}</div>
-                  ) : null}
+                  {/*
+                    Unified sheet heading row — same grammar as the popover
+                    sheet header (title left, shared icon-button ✕ on the
+                    right edge). The select sheet previously had no explicit
+                    close affordance at all (grabber/scrim only).
+                  */}
+                  <div class="hk-select-sheet-header">
+                    {props.title ? (
+                      <div class="hk-select-sheet-title">{props.title}</div>
+                    ) : null}
+                    <HIconButton
+                      class="hk-window-close hk-select-sheet-close"
+                      size={32}
+                      variant="ghost"
+                      aria-label={t("hikari::modal.close", "Close")}
+                      onClick={close}
+                    >
+                      <HIcon name="X" size={16} />
+                    </HIconButton>
+                  </div>
                   <div class="hk-select-sheet-body" ref={sheetBodyRef}>
                     <div class="hk-select-sheet-list" ref={sheetListRef}>
                       <div class="hk-select-sheet-content" ref={sheetContentRef}>

package/src/components/HkSelectSheet.test.tsx

@@ -103,6 +103,37 @@ describe("HkSelect mobile sheet", () => {
     expect(container.querySelector<HTMLElement>(".hk-select-trigger")!.dataset.state).toBe("closed");
   });
 
+  // Unified window-close wave: the select sheet previously had no explicit
+  // close affordance (grabber/scrim only). It now carries the same heading
+  // row as the popover sheet — title left, shared icon-button ✕ right.
+  it("closes the sheet via the heading close button", async () => {
+    setViewport(375);
+    const { container } = mountSelect();
+    await nextTick();
+
+    container.querySelector<HTMLButtonElement>(".hk-select-trigger")!.click();
+    await nextTick();
+    const panel = document.body.querySelector<HTMLElement>(".hk-select-sheet-panel")!;
+    const header = panel.querySelector<HTMLElement>(".hk-select-sheet-header")!;
+    expect(header).toBeTruthy();
+    expect(header.querySelector(".hk-select-sheet-title")!.textContent).toBe("Channel");
+    const close = header.querySelector<HTMLButtonElement>(".hk-select-sheet-close")!;
+    expect(close).toBeTruthy();
+    expect(close.getAttribute("aria-label")).toBeTruthy();
+    // attrs merging through HkIconButton keeps BOTH the shared icon-button
+    // chrome classes and the consumer's close hooks on the same element.
+    expect(close.classList.contains("hk-icon-button")).toBe(true);
+    expect(close.classList.contains("hk-icon-button-ghost")).toBe(true);
+    expect(close.classList.contains("hk-window-close")).toBe(true);
+    // The X glyph actually renders (default-slot branch, not the fallback
+    // placeholder circle).
+    expect(close.querySelector(".hk-icon")).not.toBeNull();
+    expect(close.querySelector("circle")).toBeNull();
+    close.click();
+    await nextTick();
+    expect(container.querySelector<HTMLElement>(".hk-select-trigger")!.dataset.state).toBe("closed");
+  });
+
   it("keeps the anchored popout on desktop widths", async () => {
     setViewport(1200);
     const { container } = mountSelect();

package/src/components/window-close.contract.test.ts

@@ -0,0 +1,52 @@
+/**
+ * Source contract for the unified window-close affordance (user directive:
+ * unify on the shared icon button + one close glyph, not per-component ✕
+ * SVG copies).
+ *
+ * Every window chrome close control — modal header, drawer header,
+ * popover/select mobile-sheet heading row — must be an HkIconButton
+ * carrying the registry's X glyph and the shared `hk-window-close`
+ * grammar class (window-close.scss). No window component keeps its own
+ * inline ✕ line-SVG any more: one glyph, one chrome, many windows.
+ *
+ * Pinned here so a refactor cannot silently re-sprout per-component close
+ * SVG copies — the same "looks unified but drifted" failure class the
+ * sheet-dock contracts guard against.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const WINDOW_FILES = [
+  "HkModal.tsx",
+  "HkPopover.tsx",
+  "HkDrawer.tsx",
+  "HkSelectPanel.tsx",
+  "HkImageLightbox.tsx",
+];
+
+describe("unified window-close contract", () => {
+  it("renders every close control as HkIconButton + the X glyph", () => {
+    for (const f of WINDOW_FILES) {
+      const src = readFileSync(join(here, f), "utf-8");
+      expect(src, `${f} must carry the shared grammar class`).toContain(
+        "hk-window-close",
+      );
+      expect(src, `${f} must render the registry X glyph`).toContain(
+        'HIcon name="X"',
+      );
+      expect(src, `${f} must close via HkIconButton`).toContain("HIconButton");
+    }
+  });
+
+  it("keeps no per-component inline ✕ SVG duplicates", () => {
+    for (const f of WINDOW_FILES) {
+      const src = readFileSync(join(here, f), "utf-8");
+      expect(src, `${f} must not re-inline the ✕ line SVG`).not.toContain(
+        'x1="18"',
+      );
+    }
+  });
+});

package/src/components/window-close.scss

@@ -0,0 +1,31 @@
+// ------
+// Unified window-close affordance grammar.
+//
+// Every window chrome close control — modal header, drawer header,
+// popover/select mobile-sheet heading row — renders the SAME thing: an
+// HkIconButton (ghost, 32px box) carrying the registry's X glyph
+// (HkIcon name="X"). No component keeps its own inline ✕ SVG any more;
+// the glyph comes from the shared lucide registry and the chrome comes
+// from the icon-button, so there is exactly one source for each.
+//
+// This partial only carries the window-chrome grammar ON TOP of the icon
+// button: a close control never participates in text selection, and it
+// gets the hover tint HkIconButton intentionally leaves to the Glow
+// wrapper (window headers render no Glow). The `--hk-modal-close-hover-*`
+// custom properties stay the shared host tunables for that tint.
+// ------
+.hk-icon-button.hk-window-close {
+  user-select: none;
+  -webkit-user-select: none;
+
+  &:hover {
+    background: var(
+      --hk-modal-close-hover-bg,
+      var(--hi-secondary-bg, rgba(0, 0, 0, 0.06))
+    );
+    color: var(
+      --hk-modal-close-hover-color,
+      var(--hi-color-text-primary, #333)
+    );
+  }
+}

package/src/data/dialCodes.test.ts

@@ -32,9 +32,16 @@ describe("dialCodes catalog", () => {
   });
 
   it("derives flag emoji from ISO codes", () => {
-    expect(flagEmoji("cn")).toBe("🇨🇳");
-    expect(flagEmoji("us")).toBe("🇺🇸");
-    expect(flagEmoji("zz")).toBe("🇿🇿"); // any two letters map
+    // Expected regional-indicator pair built from code points so the
+    // test source carries no literal emoji while still pinning the
+    // exact runtime output byte-for-byte.
+    const expectedFlag = (iso: string): string =>
+      String.fromCodePoint(
+        ...Array.from(iso.toUpperCase(), (c) => 0x1f1e6 + c.charCodeAt(0) - 65),
+      );
+    expect(flagEmoji("cn")).toBe(expectedFlag("cn"));
+    expect(flagEmoji("us")).toBe(expectedFlag("us"));
+    expect(flagEmoji("zz")).toBe(expectedFlag("zz")); // any two letters map
     expect(flagEmoji("")).toBe("");
   });
 });