@celestia-island/hikari 0.40.9 → 0.40.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.40.9",
+  "version": "0.40.11",
   "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="close" size={16} />
+                    </HIconButton>
                   ) : null}
                 </div>
               ) : null}

package/src/components/HkIcon.functional.test.ts

@@ -0,0 +1,101 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h } from "vue";
+import { ChevronLeft, X } from "lucide-vue-next";
+
+import HkIcon from "./HkIcon";
+import {
+  functionalIconComponent,
+  functionalIconSvg,
+  hasFunctionalIconOverride,
+  registerFunctionalIconPack,
+  sanitizeSvg,
+} from "../composables/iconRegistry";
+
+const mounts: Array<ReturnType<typeof createApp>> = [];
+
+function mountIcon(name: string): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp(
+    defineComponent({ setup: () => () => h(HkIcon, { name, size: 16 }) }),
+  );
+  mounts.push(app);
+  app.mount(container);
+  return container;
+}
+
+afterEach(() => {
+  for (const app of mounts.splice(0)) app.unmount();
+  registerFunctionalIconPack(null);
+});
+
+describe("functional icon aliases and material packs", () => {
+  it("maps the semantic keys to the built-in family by default", () => {
+    // Identity with the lucide entries the aliases point at (lucide
+    // components carry no `.name` — identity is the honest check).
+    expect(functionalIconComponent("close")).toBe(X);
+    expect(functionalIconComponent("back")).toBe(ChevronLeft);
+    expect(hasFunctionalIconOverride("close")).toBe(false);
+    expect(functionalIconSvg("close")).toBeNull();
+  });
+
+  it("renders the alias glyph through HkIcon without a pack", () => {
+    const c = mountIcon("close");
+    // lucide X renders as .lucide-x inside the .hk-icon wrapper.
+    expect(c.querySelector(".lucide-x")).not.toBeNull();
+  });
+
+  it("renders a registered material-pack override instead of the alias", () => {
+    registerFunctionalIconPack({
+      close: '<svg viewBox="0 0 24 24" class="pack-close-mark"><path d="M4 4h16v16H4z"/></svg>',
+    });
+    expect(hasFunctionalIconOverride("close")).toBe(true);
+    const c = mountIcon("close");
+    expect(c.querySelector(".pack-close-mark")).not.toBeNull();
+    expect(c.querySelector(".lucide-x")).toBeNull();
+  });
+
+  it("leaves back untouched when the pack only carries close", () => {
+    registerFunctionalIconPack({
+      close: "<svg/>",
+    });
+    expect(hasFunctionalIconOverride("back")).toBe(false);
+    const c = mountIcon("back");
+    expect(c.querySelector(".lucide-chevron-left")).not.toBeNull();
+  });
+
+  it("sanitizes scripts and inline handlers out of pack markup", () => {
+    const dirty =
+      '<svg onload="alert(1)" onclick="x()"><script>alert(2)</script><path d="M4 4" onmouseover="y()"/></svg>';
+    const clean = sanitizeSvg(dirty);
+    expect(clean).not.toContain("script");
+    expect(clean).not.toContain("onload");
+    expect(clean).not.toContain("onclick");
+    expect(clean).not.toContain("onmouseover");
+    expect(clean).toContain("<path");
+    // sanitize applies on the functional render path too.
+    registerFunctionalIconPack({ close: dirty });
+    const c = mountIcon("close");
+    expect(c.querySelector("script")).toBeNull();
+  });
+
+  // Round-2 review vectors (slash separators, unquoted schemes, SMIL).
+  it("neutralizes the round-2 evasion vectors", () => {
+    expect(sanitizeSvg("<svg/onload=alert(1)>")).not.toContain("onload");
+    expect(sanitizeSvg('<svg onload=alert(1)>')).not.toContain("onload");
+    expect(sanitizeSvg('<a href=javascript:alert(1)>t</a>')).not.toContain("javascript:");
+    expect(sanitizeSvg('<a href="javascript:alert(1)">t</a>')).not.toContain("javascript:");
+    expect(sanitizeSvg('<animate attributeName="href" values="javascript:alert(1)"/>')).not.toContain("animate");
+    expect(sanitizeSvg('<set attributeName="onmouseover" to="alert(1)"/>')).not.toContain("set");
+    expect(sanitizeSvg('<iframe src="javascript:alert(1)"></iframe>')).not.toContain("iframe");
+    expect(sanitizeSvg('<foreignObject><body onload="x()"></body></foreignObject>')).not.toContain("foreignObject");
+  });
+
+  it("clearing the pack restores the built-in family", () => {
+    registerFunctionalIconPack({ close: '<svg class="pack"/><svg class="pack"/>' });
+    registerFunctionalIconPack(null);
+    expect(hasFunctionalIconOverride("close")).toBe(false);
+    const c = mountIcon("close");
+    expect(c.querySelector(".lucide-x")).not.toBeNull();
+  });
+});

package/src/components/HkIcon.scss

@@ -26,6 +26,21 @@
   }
 }
 
+// ------
+// Functional icon-button glyph weight (theme-context driven)
+// ------
+// Inside the HkIconButton family — the HIGHLY FUNCTIONAL controls (window
+// close/back, compact action buttons) — the THEME CONTEXT decides how the
+// glyph is drawn, per user direction 2026-09-05: Blue Archive-styled themes
+// keep the bold small default (stroke 2, no scaling) while thin-stroke
+// themes (e.g. Endfield) publish --hk-func-icon-stroke-width / --hk-func-icon-scale
+// from their own layer. A CSS rule here overrides lucide's inline
+// stroke-width PRESENTATION ATTRIBUTE; scoping to .hk-icon-button keeps
+// every plain HkIcon elsewhere untouched.
+.hk-icon-button .hk-icon svg {
+  stroke-width: var(--hk-func-icon-stroke-width, 2);
+}
+
 // ------
 // Icon Size Variants
 // ------

package/src/components/HkIcon.tsx

@@ -1,7 +1,14 @@
 import { defineComponent, type PropType } from "vue";
-import { iconByName } from "../composables/iconRegistry";
+import {
+  functionalIconComponent,
+  functionalIconSvg,
+  iconByName,
+} from "../composables/iconRegistry";
 import "./HkIcon.scss";
 
+/** Semantic functional keys resolved through the alias/pack pipeline. */
+const FUNCTIONAL_KEYS = new Set(["close", "back"]);
+
 export default defineComponent({
   name: "HkIcon",
   props: {
@@ -17,9 +24,25 @@ export default defineComponent({
         props.color ? `hk-icon-${props.color}` : "",
       ];
 
-      // Resolve through the explicit registry: a wildcard import of
-      // lucide-vue-next here defeated tree-shaking and shipped the whole
-      // ~1500-icon library in the shared bundle of every consumer.
+      // Functional keys ("close", "back") resolve through the material-pack
+      // pipeline FIRST (a host theme layer can swap the whole glyph family
+      // at runtime — sanitized raw SVG from the registered pack), then fall
+      // back to the alias's lucide component (close→X, back→ChevronLeft).
+      // Everything else resolves through the explicit lucide registry: a
+      // wildcard import of lucide-vue-next here defeated tree-shaking and
+      // shipped the whole ~1500-icon library in the shared bundle of every
+      // consumer.
+      if (FUNCTIONAL_KEYS.has(props.name)) {
+        const svg = functionalIconSvg(props.name);
+        if (svg) {
+          return (
+            <span class={cls} v-html={svg} />
+          );
+        }
+        const FuncComp = functionalIconComponent(props.name) as any;
+        return <span class={cls}><FuncComp /></span>;
+      }
+
       const IconComp = iconByName(props.name) as any;
       return <span class={cls}><IconComp /></span>;
     };

package/src/components/HkIconButton.scss

@@ -151,6 +151,13 @@
       height: var(--hi-icon-button-icon-size);
       display: block;
     }
+
+    // Theme-context glyph size (user direction 2026-09-05): BA themes keep
+    // scale 1; thin-stroke themes publish a >1 scale for their slightly
+    // larger functional glyphs. transform keeps the 32px hit box intact.
+    .hk-icon {
+      transform: scale(var(--hk-func-icon-scale, 1));
+    }
   }
 
   // Active state for icon

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="close" 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

@@ -179,42 +179,12 @@
   -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;
-  }
 }
 
 // ------

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="close" 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

@@ -187,45 +187,10 @@
 }
 
 .hk-popover-sheet-close {
-  flex-shrink: 0;
-  // Pushes to the right edge with or without a title beside it.
+  // 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;
-  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;
-  user-select: none;
-  -webkit-user-select: none;
-  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;
-  }
 }
 
 .hk-popover-sheet-enter-active {

package/src/components/HkPopover.tsx

@@ -19,6 +19,9 @@ 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 =
@@ -583,24 +586,15 @@ export default defineComponent({
                     {props.title && (
                       <div class="hk-popover-sheet-title">{props.title}</div>
                     )}
-                    <button
-                      class="hk-popover-sheet-close"
+                    <HIconButton
+                      class="hk-window-close hk-popover-sheet-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="close" size={16} />
+                    </HIconButton>
                   </div>
                 )}
                 {slots.default?.()}

package/src/components/HkPopoverSheet.test.tsx

@@ -143,6 +143,10 @@ describe("HkPopover sheetOnMobile", () => {
     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 () => {

package/src/components/HkSelect.scss

@@ -300,18 +300,40 @@
   }
 }
 
-.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.
-   * Size/weight match the popover sheet heading (--text-base, window
-   * chrome never text-selectable — 2026-09-04 sheet chrome pass). */
-  padding: 0 var(--space-16) var(--space-8)
-    var(--hk-sheet-title-inset, calc(var(--space-16) * 2));
+   * --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;

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="close" 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/func-icon-theme.contract.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Source contract for the theme-context-driven functional icon rendering
+ * (user direction 2026-09-05: the close/back functional controls are drawn
+ * BY THE THEME CONTEXT — Blue Archive themes keep the bold small default,
+ * thin-stroke themes like Endfield publish their own weight/size/motion).
+ *
+ * The mechanism is a pure custom-property family: a theme layer publishes
+ * --hk-func-icon-* on any root and every HkIconButton glyph + window-close
+ * hover picks it up. No JS plumbing, no per-theme component forks.
+ *
+ * Pinned here so the consumption points cannot silently disappear (the
+ * same "looks themed but never shipped" failure class as the sheet-dock
+ * contracts).
+ */
+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 read = (f: string): string => readFileSync(join(here, f), "utf-8");
+
+describe("functional icon theme-context contract", () => {
+  it("draws icon-button glyphs with the theme stroke width", () => {
+    const css = read("HkIcon.scss");
+    // Scoped to the functional family: plain HkIcons elsewhere must keep
+    // the lucide default weight.
+    expect(css).toContain(".hk-icon-button .hk-icon svg");
+    expect(css).toContain("var(--hk-func-icon-stroke-width, 2)");
+  });
+
+  it("scales icon-button glyphs with the theme size factor", () => {
+    const css = read("HkIconButton.scss");
+    expect(css).toContain("var(--hk-func-icon-scale, 1)");
+  });
+
+  it("expresses the window-close hover motion through the var family", () => {
+    const css = read("window-close.scss");
+    expect(css).toContain("var(--hk-func-icon-hover-duration, 0.15s)");
+    expect(css).toContain("var(--hk-func-icon-hover-ease, ease)");
+    expect(css).toContain("--hk-func-icon-hover-bg,");
+    expect(css).toContain("--hk-func-icon-hover-color,");
+  });
+});

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

@@ -0,0 +1,54 @@
+/**
+ * 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 functional close key", () => {
+    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",
+      );
+      // Semantic key: the theme context's material pack can swap the glyph
+      // family at runtime (iconRegistry resolves close → X by default).
+      expect(src, `${f} must render the functional close key`).toContain(
+        'HIcon name="close"',
+      );
+      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,58 @@
+// ------
+// 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.
+//
+// THE THEME CONTEXT DECIDES THE MOTION (user direction 2026-09-05): the
+// hover choreography is expressed entirely through the --hk-func-icon-*
+// custom properties, so a theme layer restyles every functional control
+// without touching this file:
+//   --hk-func-icon-stroke-width   glyph weight (consumed in HkIcon.scss)
+//   --hk-func-icon-scale          glyph size scale (HkIconButton.scss)
+//   --hk-func-icon-hover-duration hover transition length
+//   --hk-func-icon-hover-ease     hover transition curve
+//   --hk-func-icon-hover-bg       hover background (transparent = snap)
+//   --hk-func-icon-hover-color    hover glyph color
+// Defaults below are the Blue Archive grammar: soft tint fade. A thin-
+// stroke theme (Endfield) publishes a transparent background, a snap
+// duration and an accent glyph color instead.
+// ------
+.hk-icon-button.hk-window-close {
+  user-select: none;
+  -webkit-user-select: none;
+  transition:
+    background
+      var(--hk-func-icon-hover-duration, 0.15s)
+      var(--hk-func-icon-hover-ease, ease),
+    color
+      var(--hk-func-icon-hover-duration, 0.15s)
+      var(--hk-func-icon-hover-ease, ease);
+
+  &:hover {
+    background: var(
+      --hk-func-icon-hover-bg,
+      var(
+        --hk-modal-close-hover-bg,
+        var(--hi-secondary-bg, rgba(0, 0, 0, 0.06))
+      )
+    );
+    color: var(
+      --hk-func-icon-hover-color,
+      var(
+        --hk-modal-close-hover-color,
+        var(--hi-color-text-primary, #333)
+      )
+    );
+  }
+}

package/src/composables/iconRegistry.ts

@@ -125,3 +125,103 @@ export function iconByName(name: string | undefined | null): Component {
   }
   return Info;
 }
+
+// ------
+// Functional icon aliases + host-provided material packs (材质包).
+//
+// Window chrome renders SEMANTIC names ("close", "back") instead of
+// literal lucide names, so a host theme layer can swap the whole glyph
+// family at runtime — user direction 2026-09-05. Resolution order in
+// functionalIconSvg():
+//   1. host material-pack override for the semantic key (raw SVG string,
+//      sanitized at render time),
+//   2. the semantic alias's default lucide component,
+//   3. `Info` (never reached for the built-in keys).
+// `registerFunctionalIconPack(null)` clears the pack and restores the
+// built-in family. Packs ride the module singleton: applications register
+// once at theme-apply time, exactly like the CSS-var publication.
+// ------
+
+/** Semantic key → default lucide component for the built-in family. */
+const FUNCTIONAL_ALIASES: Record<string, Component> = {
+  close: X,
+  back: ChevronLeft,
+};
+
+let functionalPack: Record<string, string> | null = null;
+
+/**
+ * Install (or clear with `null`) the host's material pack: semantic key →
+ * raw SVG markup. The SVG string is sanitized when rendered (script blocks
+ * and event-handler attributes stripped); callers own upload validation.
+ */
+export function registerFunctionalIconPack(
+  pack: Record<string, string> | null,
+): void {
+  functionalPack = pack && Object.keys(pack).length > 0 ? pack : null;
+}
+
+/** True when a material pack carries an override for `key`. */
+export function hasFunctionalIconOverride(key: string): boolean {
+  return !!functionalPack && !!functionalPack[key];
+}
+
+/**
+ * Hardened sanitizer for host-provided SVG markup (render path is v-html).
+ *
+ * Deterministic + synchronous by design — the render path cannot await a
+ * lazy DOMPurify chunk. Hardened against the classic evasion classes
+ * (round-2 review vectors): slash-separated event attributes
+ * (`<svg/onload=…>`), unquoted `javascript:` URLs, dangerous element
+ * families (script/iframe/object/embed/foreignObject/animate/set/base/
+ * meta/form) and SMIL attribute-mutation primitives. NOT an HTML/SVG
+ * allowlist parser: material packs are user-local configuration today —
+ * if they ever become shareable files, switch to the DOMPurify allowlist
+ * (the dependency already ships for HkMarkdownRenderer) before doing so.
+ */
+const SVG_DENIED_TAGS =
+  /<(\/?)(script|iframe|object|embed|foreignObject|animate|set|base|meta|form)\b[^>]*>/gi;
+const SVG_SCRIPT_BLOCKS = /<script\b[\s\S]*?<\/script\s*>/gi;
+// Value groups deliberately STOP at their own closing quote — a greedy
+// any-char alternation would swallow the rest of the tag and let later
+// event attributes survive.
+const SVG_EVENT_ATTRS =
+  /[\s/]on[a-z-]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi;
+const SVG_SCHEME_ATTRS =
+  /(\s(?:xlink:)?(?:href|src)\s*=\s*)("[^"]*"|'[^']*'|[^\s>]+)/gi;
+const SVG_DANGEROUS_SCHEME = /^\s*(?:javascript|vbscript|data:text\/html)/i;
+
+export function sanitizeSvg(svg: string): string {
+  // 1. Script blocks and whole dangerous element families are removed
+  //    (SMIL mutation primitives like <animate>/<set> included).
+  // 2. Event handler attributes — slash separators included — are renamed
+  //    to an inert attribute; the handler can never fire again.
+  // 3. URL-carrying attributes with script-ish schemes are dropped whole.
+  let out = svg
+    .replace(SVG_SCRIPT_BLOCKS, "")
+    .replace(SVG_DENIED_TAGS, "<$1nothing>");
+  out = out.replace(SVG_EVENT_ATTRS, (_m, value: string) => ` data-stripped=${value}`);
+  out = out.replace(SVG_SCHEME_ATTRS, (match, _prefix: string, value: string) =>
+    SVG_DANGEROUS_SCHEME.test(value.replace(/^["']/, "").replace(/["']$/, ""))
+      ? ""
+      : match,
+  );
+  return out;
+}
+
+/**
+ * Render payload for a functional icon key: a raw-SVG string when the
+ * material pack overrides it, `null` when the caller should fall back to
+ * the alias's lucide component.
+ */
+export function functionalIconSvg(key: string): string | null {
+  if (functionalPack && functionalPack[key]) {
+    return sanitizeSvg(functionalPack[key]);
+  }
+  return null;
+}
+
+/** Default lucide component for a functional key (alias lookup). */
+export function functionalIconComponent(key: string): Component {
+  return FUNCTIONAL_ALIASES[key] ?? Info;
+}

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("");
   });
 });

package/src/index.ts

@@ -269,7 +269,12 @@ export type { HealthProbeBody, HealthProbeResult } from "./utils/healthProbe";
 
 export { highlight, useHighlight } from "./composables/useHighlight";
 export { LANGUAGE_LOADERS } from "./composables/highlightLanguages";
-export { iconByName } from "./composables/iconRegistry";
+export {
+  iconByName,
+  registerFunctionalIconPack,
+  functionalIconSvg,
+  sanitizeSvg,
+} from "./composables/iconRegistry";
 export { useMessaging, registerTransport, registerNativeBridge } from "./composables/messaging";
 export type { MessagePayload, MessageSeverity, MessageTransport, NotifyOptions, TransportName } from "./composables/messaging";