@celestia-island/hikari 0.55.162 → 0.55.163

package/package.json

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

package/src/components/HkAdminShell.tsx

@@ -268,7 +268,7 @@ export const HkAdminShell = defineComponent({
 
         {slots.footer && (
           <footer class="s-status-bar" style={{ position: "fixed", bottom: 0, left: 0, right: 0, // Footer band (was a bare 40 — the pre-band chrome value).
-            zIndex: "var(--z-footer, 110)" }}>
+            zIndex: "var(--hk-z-toolbar)" }}>
             {slots.footer()}
           </footer>
         )}

package/src/components/HkBlockingToast.scss

@@ -12,7 +12,7 @@
   /* Same viewport gutter the anchored popups clamp to (16px desktop /
    * 8px mobile) — the toast stack is a floating layer too. */
   inset-inline-end: var(--viewport-gutter, 16px);
-  z-index: var(--hk-z-toast, 4000);
+  z-index: var(--hk-overlay-z-blocking-toast, 50);
   max-width: 24rem;
   pointer-events: none;
 }

package/src/components/HkBlockingToast.tsx

@@ -45,6 +45,7 @@ import {
 } from "../runtime/useBlockingToast";
 import "./HkBlockingToast.scss";
 import HButton from "./HkButton";
+import { ensureOverlayRoot } from "../overlay/overlayRoot";
 
 const ICON_SIZE = 18;
 
@@ -175,7 +176,7 @@ export default defineComponent({
     }
 
     return () => (
-      <Teleport to="body">
+      <Teleport to={ensureOverlayRoot()}>
         <div class="hk-blocking-toast-container">
           <TransitionGroup
             ref={hostRef}

package/src/components/HkBreadcrumb.scss

@@ -212,7 +212,7 @@
     top: calc(100% + 4px);
     left: 0;
     min-width: 200px;
-    z-index: 100;
+    z-index: var(--hk-z-header);
 
     // Appearance
     border-radius: vars.$hikari-radius-fui-md;

package/src/components/HkCheckbox.scss

@@ -103,7 +103,7 @@
 
 .hk-checkbox-icon {
   position: relative;
-  z-index: var(--hi-z-above, 1);
+  z-index: var(--hk-z-above);
   color: rgb(var(--color-on-solid-icon, 255 255 255));
   width: 14px;
   height: 14px;
@@ -124,7 +124,7 @@
   height: 6px;
   border-radius: 50%;
   background: rgb(var(--color-on-solid-icon, 255 255 255));
-  z-index: var(--hi-z-above, 1);
+  z-index: var(--hk-z-above);
 
   .hk-checkbox-sm & {
     width: 5px;
@@ -142,7 +142,7 @@
   height: 2px;
   border-radius: 1px;
   background: rgb(var(--color-on-solid-icon, 255 255 255));
-  z-index: var(--hi-z-above, 1);
+  z-index: var(--hk-z-above);
 
   .hk-checkbox-sm & {
     width: 6px;

package/src/components/HkDraggableGrid.scss

@@ -136,7 +136,7 @@
   /* Drag ghost: above page chrome (--z-sidebar 900) but below every
      popup band (overlay 1000 < dropdown 2000 < tooltip 3000 < toast 4000)
      so a drag never buries toasts or open panels. */
-  z-index: var(--hk-z-drag, 950);
+  z-index: var(--hk-z-drag);
   will-change: transform;
 
   > .hk-draggable-grid-cell {

package/src/components/HkDraggableList.scss

@@ -110,7 +110,7 @@
   /* Drag ghost: above page chrome (--z-sidebar 900) but below every
      popup band (overlay 1000 < dropdown 2000 < tooltip 3000 < toast 4000)
      so a drag never buries toasts or open panels. */
-  z-index: var(--hk-z-drag, 950);
+  z-index: var(--hk-z-drag);
   will-change: transform;
 
   > .hk-draggable-list-item {

package/src/components/HkDrawer.tsx

@@ -23,6 +23,7 @@ import { useSurfaceContentHold } from "../composables/useSurfaceContentHold";
 import HIconButton from "./HkIconButton";
 import HIcon from "./HkIcon";
 import "./window-close.scss";
+import { ensureOverlayRoot } from "../overlay/overlayRoot";
 
 type DrawerSide = "left" | "right" | "top" | "bottom";
 
@@ -276,7 +277,7 @@ export default defineComponent({
       if (!machine.mounted.value) return null;
       const panelPrefix = `hk-drawer-${props.side}`;
       return (
-      <Teleport to="body">
+      <Teleport to={ensureOverlayRoot()}>
         {props.overlay ? (
           <div
             ref={overlayEl}

package/src/components/HkFab.scss

@@ -4,7 +4,7 @@
 // safe-area-aware base per instance (set from offsetX / offsetY).
 .hk-fab {
   position: absolute;
-  z-index: var(--hk-fab-z, 40);
+  z-index: var(--hk-z-fab);
   display: flex;
   align-items: center;
   gap: var(--space-8, 0.5rem);

package/src/components/HkFab.test.tsx

@@ -46,10 +46,10 @@ function mountFab(props: Record<string, unknown> = {}): Harness {
   // fall back to the document scope so both modes resolve.
   const root =
     container.querySelector<HTMLElement>(".hk-fab") ??
-    document.body.querySelector<HTMLElement>(".hk-fab");
+    document.querySelector<HTMLElement>(".hk-fab");
   const button =
     container.querySelector<HTMLButtonElement>(".hk-fab-button") ??
-    document.body.querySelector<HTMLButtonElement>(".hk-fab-button");
+    document.querySelector<HTMLButtonElement>(".hk-fab-button");
   if (!root || !button) throw new Error("HkFab did not render its shell");
   harness.root = root;
   harness.button = button;
@@ -226,13 +226,13 @@ describe("HkFab speed dial", () => {
 describe("HkFab layer", () => {
   it("host (default) keeps the fab anchored in the host tree", () => {
     const m = mountFab({ ariaLabel: "Host", positioning: "fixed" });
-    expect(document.body.querySelector(".hk-floating-layer")).toBeNull();
+    expect(document.querySelector(".hk-floating-layer")).toBeNull();
     expect(m.root.getAttribute("data-positioning")).toBe("fixed");
   });
 
   it("top wraps the fab in an HkFloatingLayer above the window band", () => {
     const m = mountFab({ ariaLabel: "Float", layer: "top", corner: "bottom-right" });
-    const layer = document.body.querySelector<HTMLElement>(".hk-floating-layer");
+    const layer = document.querySelector<HTMLElement>(".hk-floating-layer");
     expect(layer).not.toBeNull();
     expect(layer!.contains(m.root)).toBe(true);
     // Geometry is owned by the layer alone once floated.
@@ -244,6 +244,6 @@ describe("HkFab layer", () => {
     expect(layer!.getAttribute("data-corner")).toBe("bottom-right");
     const z = Number(layer!.style.getPropertyValue("--hk-float-z"));
     expect(z).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
-    expect(z).toBeLessThan(POPUP_Z_BANDS.toast);
+    // Tooltip is the topmost band (2026-10-15): no upper bound.
   });
 });

package/src/components/HkFloatingLayer.scss

@@ -7,7 +7,7 @@
 // POPUP_Z_BANDS.tooltip in runtime/usePopupManager.ts.
 .hk-floating-layer {
   position: fixed;
-  z-index: var(--hk-float-z, 3000);
+  z-index: var(--hk-overlay-z-popup, 200);
   display: flex;
   flex-direction: column;
   gap: var(--space-8, 0.5rem);

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

@@ -22,7 +22,7 @@ describe("HkFloatingLayer stylesheet contract", () => {
   it("compiles the fixed, gesture-transparent top-layer shell", () => {
     expect(css).toContain(".hk-floating-layer {");
     expect(css).toContain("position: fixed;");
-    expect(css).toContain("z-index: var(--hk-float-z, 3000);");
+    expect(css).toContain("z-index: var(--hk-overlay-z-popup, 200);");
     // The layer never eats gestures; the widgets inside do.
     expect(css).toContain("pointer-events: none;");
     expect(css).toContain(".hk-floating-layer > * {");

package/src/components/HkFloatingLayer.test.tsx

@@ -50,7 +50,7 @@ describe("HkFloatingLayer", () => {
     // tooltip band, strictly below the toast band.
     const z = Number(root!.style.getPropertyValue("--hk-float-z"));
     expect(z).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
-    expect(z).toBeLessThan(POPUP_Z_BANDS.toast);
+    // Tooltip is the topmost band (2026-10-15): no upper bound.
   });
 
   it("open=false renders nothing at all", () => {

package/src/components/HkFloatingLayer.tsx

@@ -9,6 +9,7 @@ import {
 
 import { hasLiveWindow, usePopupManager } from "../runtime/usePopupManager";
 import "./HkFloatingLayer.scss";
+import { ensureOverlayRoot } from "../overlay/overlayRoot";
 
 type FloatCorner = "bottom-right" | "bottom-left" | "top-right" | "top-left";
 
@@ -99,7 +100,7 @@ export default defineComponent({
     return () => {
       if (!props.open || (props.yieldToWindows && hasLiveWindow.value)) return null;
       return (
-        <Teleport to="body">
+        <Teleport to={ensureOverlayRoot()}>
           <div
             class="hk-floating-layer"
             data-corner={props.corner}

package/src/components/HkLoadingVeil.scss

@@ -5,7 +5,7 @@
 .hk-loading-veil {
   position: fixed;
   inset: 0;
-  z-index: calc(var(--hk-z-toast, 4000) + 100);
+  z-index: var(--hk-overlay-z-veil, 150);
   display: flex;
   align-items: center;
   justify-content: center;

package/src/components/HkLocalePicker.tsx

@@ -82,7 +82,7 @@ export const HkLocalePicker = defineComponent({
               // Local stacking inside the header's own context — the
               // app-chrome header-popup band documents the intent (this
               // value is scoped, it never races the popup stack).
-              zIndex: "var(--z-header-popup, 150)",
+              zIndex: "var(--hk-z-float)",
               overflow: "hidden",
               padding: "4px",
             }}

package/src/components/HkMarkdownRenderer.tsx

@@ -65,8 +65,12 @@ async function renderMarkdown(content: string): Promise<string> {
 
   (renderer as Record<string, unknown>).code = function (tok: { text: string; lang?: string }) {
     const highlighted = tryHighlight(tok.text, tok.lang);
-    const langAttr = tok.lang ? ` language-${tok.lang}` : "";
-    const langLabel = tok.lang ? `<span class="hk-md-code-lang">${tok.lang}</span>` : "";
+    // Audit hikari-R1-5: whitelist the language tag before interpolation
+    // (depth-in-defence — the final DOMPurify pass remains the primary
+    // guard, but this keeps the raw template injection safe on its own).
+    const lang = tok.lang && /^[a-zA-Z0-9+#._-]{1,32}$/.test(tok.lang) ? tok.lang : "";
+    const langAttr = lang ? ` language-${lang}` : "";
+    const langLabel = lang ? `<span class="hk-md-code-lang">${lang}</span>` : "";
     return `<div class="hk-md-code-wrap"><div class="hk-md-code">${langLabel}<pre><code class="hljs${langAttr}">${highlighted}</code></pre></div></div>`;
   };
 

package/src/components/HkModal.tsx

@@ -30,6 +30,7 @@ import HSpinner from "./HkSpinner";
 import HIconButton from "./HkIconButton";
 import HIcon from "./HkIcon";
 import "./window-close.scss";
+import { ensureOverlayRoot } from "../overlay/overlayRoot";
 
 export interface ModalAction {
   label: string;
@@ -1029,7 +1030,7 @@ export default defineComponent({
       const headerShown = props.title || props.closable || slots.header || slots.headerLead;
 
       const windowSurface = (
-        <Teleport to="body">
+        <Teleport to={ensureOverlayRoot()}>
           <div
             class="hk-modal-root"
             style={{ zIndex: overlayZ.value }}

package/src/components/HkModalBreadcrumb.overflow.contract.test.ts

@@ -75,10 +75,9 @@ describe("HkModalBreadcrumb overflow fence", () => {
     // The strip reaches over an anchored dropdown's panel on purpose (it
     // must stay readable over the window it annotates); dropping it into
     // the window band would bury it under every open sheet instead.
-    const z = Number(scss.match(/z-index:\s*var\(--hk-breadcrumb-z,\s*(\d+)\)/)?.[1]);
-    expect(Number.isFinite(z), "the strip declares a z fallback").toBe(true);
-    expect(z).toBeGreaterThan(POPUP_Z_BANDS.dropdown);
-    expect(z).toBeLessThan(POPUP_Z_BANDS.tooltip);
+    // The canonical variable carries the band value (no inline fallback).
+    const hasVar = scss.includes("z-index: var(--hk-overlay-z-breadcrumb");
+    expect(hasVar, "the strip declares its z via the canonical variable").toBe(true);
   });
 
   it("opens the menu clear of the strip's own bar", () => {

package/src/components/HkModalBreadcrumb.scss

@@ -5,7 +5,7 @@
   /* Above every popup band's scrim (modal 1000+, dropdown 2000+; in-band
      steps of 2 keep real stacks far below this) so multi-layer windows
      never bury the strip; still below tooltip (3000) / toast (4000). */
-  z-index: var(--hk-breadcrumb-z, 2500);
+  z-index: var(--hk-overlay-z-breadcrumb, 250);
   display: flex;
   align-items: center;
   // --space-N contract tokens are N px across the library (HkTable,

package/src/components/HkModalBreadcrumb.tsx

@@ -20,6 +20,7 @@ import HkPopover from "./HkPopover";
 import HkMenuPanel from "./HkMenuPanel";
 import HkMenuActionItem from "./HkMenuActionItem";
 import "./HkModalBreadcrumb.scss";
+import { ensureOverlayRoot } from "../overlay/overlayRoot";
 
 /** Window kinds always participate in the stack: modals and drawers block
  *  the page on every form factor, desktop and mobile alike. */
@@ -609,7 +610,7 @@ export default defineComponent({
 
     return () =>
       visible.value ? (
-        <Teleport to="body">
+        <Teleport to={ensureOverlayRoot()}>
           <nav
             ref={navRef}
             class="hk-modal-breadcrumb"

package/src/components/HkPersistentToast.tsx

@@ -13,6 +13,7 @@ import {
 import { usePopupManager, type PopupHandle } from "../runtime/usePopupManager";
 import { useI18n } from "../i18n/context";
 import "./HkPersistentToast.scss";
+import { ensureOverlayRoot } from "../overlay/overlayRoot";
 
 export type PersistentToastTone = "loading" | "info" | "warning" | "error";
 
@@ -266,7 +267,7 @@ export default defineComponent({
             </button>
           )}
           {slots.detail && open.value && (
-            <Teleport to="body">
+            <Teleport to={ensureOverlayRoot()}>
               <div
                 ref={cardRef}
                 id={popupId}

package/src/components/HkPopover.tsx

@@ -26,6 +26,7 @@ import HIconButton from "./HkIconButton";
 import HIcon from "./HkIcon";
 import "./window-close.scss";
 import "./HkPopover.scss";
+import { ensureOverlayRoot } from "../overlay/overlayRoot";
 
 export type PopupPlacement =
   | "top" | "top-start" | "top-end"
@@ -664,7 +665,7 @@ export default defineComponent({
       const sheetBranch = activeBranch.value === "sheet";
       const panelPrefix = sheetBranch ? "hk-popover-sheet" : "hk-popover";
       return (
-      <Teleport to="body">
+      <Teleport to={ensureOverlayRoot()}>
         {/* Window-layer contract (./_scrim-fade.scss): the sheet scrim
             fades in place under its own transition name (machine output)
             — it never mounts bare, so the dim curtain never snaps on or

package/src/components/HkScrollPin.scrollcontract.test.ts

@@ -58,7 +58,7 @@ describe("scroll-pin whitespace contract", () => {
   it("the pin base is sticky with a floating-chrome surface", () => {
     const base = cssBlock(pinScss, ".hk-scroll-pin {");
     expect(base).toMatch(/position: sticky/);
-    expect(base).toMatch(/z-index: var\(--hk-scroll-pin-z/);
+    expect(base).toMatch(/z-index: var\(--hk-scroll-pin-z, var\(--hk-z-scrollbar/);
     expect(base).toMatch(/background: var\(\s*--hk-scroll-pin-bg/);
   });
 

package/src/components/HkScrollPin.scss

@@ -17,7 +17,7 @@
 
 .hk-scroll-pin {
   position: sticky;
-  z-index: var(--hk-scroll-pin-z, 10);
+  z-index: var(--hk-scroll-pin-z, var(--hk-z-scrollbar));
   // Floating-chrome surface: near-opaque surface tint + blur so scrolled
   // content never bleeds through the pinned row (same look the step-flow
   // sticky header introduced; hosts retune through --hk-scroll-pin-bg).

package/src/components/HkSelectPanel.test.tsx

@@ -3,7 +3,7 @@ import { createApp, defineComponent, h, nextTick, ref } from "vue";
 import type { ComponentPublicInstance } from "vue";
 
 import HkSelectPanel from "./HkSelectPanel";
-import { usePopupManager } from "../runtime/usePopupManager";
+import { usePopupManager, POPUP_Z_BANDS } from "../runtime/usePopupManager";
 
 const mounts: ReturnType<typeof createApp>[] = [];
 const containers: HTMLElement[] = [];
@@ -274,7 +274,7 @@ describe("HkSelectPanel custom invocation", () => {
     const host = document.body.querySelector<HTMLElement>(".hk-select-popout-host")!;
     expect(host).toBeTruthy();
     const z = Number.parseInt(host.style.zIndex, 10);
-    expect(z).toBeGreaterThanOrEqual(1000);
+    expect(z).toBeGreaterThanOrEqual(POPUP_Z_BANDS.dropdown);
   });
 
   it("places a top-start popout above the anchor and flips when cramped", async () => {

package/src/components/HkSelectPanel.tsx

@@ -25,6 +25,7 @@ import HIconButton from "./HkIconButton";
 import HIcon from "./HkIcon";
 import "./window-close.scss";
 import "./HkSelect.scss";
+import { ensureOverlayRoot } from "../overlay/overlayRoot";
 
 /**
  * The dropdown panel of HkSelect, detached from the select's trigger so it
@@ -657,7 +658,7 @@ export default defineComponent({
       if (!machine.mounted.value) return null;
       if (activeBranch.value === "sheet") {
         return (
-          <Teleport to="body">
+          <Teleport to={ensureOverlayRoot()}>
             {/* Window-layer contract (./_scrim-fade.scss): the scrim fades
                 in place under its OWN transition name. It once shared the
                 panel's `hk-select-sheet` name, so the panel's
@@ -729,7 +730,7 @@ export default defineComponent({
       // pop grows out of the edge the panel actually sits on (including
       // after an auto-flip).
       return (
-        <Teleport to="body">
+        <Teleport to={ensureOverlayRoot()}>
           <div
                 ref={popoutHostRef}
                 class={["hk-select-popout-host", ...machine.classesFor("hk-select-popout")]}

package/src/components/HkSidebar.scss

@@ -98,7 +98,7 @@
 .hk-sidebar[data-mobile] {
   position: fixed;
   inset: 0;
-  z-index: var(--hk-sidebar-z, 900);
+  z-index: var(--hk-z-sidebar);
   background-color: var(--hk-drawer-overlay-bg, rgba(0, 0, 0, 0.45));
   width: 100%;
 

package/src/components/HkStatusBar.test.tsx

@@ -732,3 +732,29 @@ describe("HkStatusBar", () => {
     expect(scss).not.toMatch(/\.s-status-bar-version,\s*\n\s*\.s-status-bar-version-sep\s*\{/);
   });
 });
+
+// ── tier "none": a local panel has no transport facts to show ────────────
+describe("HkStatusBar tier none", () => {
+  it("hides the protocol and network rows for the local sentinel", async () => {
+    const container = mountBar({
+      connectionStatus: "connected",
+      connectionInfo: { ...INFO, tier: "none", region: "CN", latencyMs: 3 },
+      latencyMs: 3,
+      version: "0.1.0",
+    });
+    await nextTick();
+    const tag = tagOf(container);
+    tag.dispatchEvent(new MouseEvent("mouseenter"));
+    await nextTick();
+    const panel = document.body.querySelector<HTMLElement>(".hk-popover-panel");
+    expect(panel, "popover opens on hover").toBeTruthy();
+    const text = panel?.textContent ?? "";
+    // Vacuity guard first: the connected status text renders in the panel.
+    expect(text).toContain("Connected");
+    // A local panel has no transport protocol nor a network region —
+    // those rows must not render at all for the sentinel tier.
+    expect(text).not.toContain("Protocol");
+    expect(text).not.toContain("Network");
+    expect(text).not.toContain("HTTP");
+  });
+});

package/src/components/HkStatusBar.tsx

@@ -196,6 +196,10 @@ export const HkStatusBar = defineComponent({
     compact: { type: Boolean, default: false },
     onRetry: { type: Function as PropType<() => void>, default: undefined },
     latencyMs: { type: Number, default: null },
+    // The sentinel tier "none" suppresses BOTH the protocol and the
+    // network rows — for hosts whose panel is local (the desktop shell:
+    // "connected" there only means the local face is up, so neither a
+    // transport protocol nor a network region is a fact about the link).
     transportTier: { type: String as PropType<string>, default: undefined },
     attemptNumber: { type: Number, default: undefined },
     countdown: { type: Number, default: undefined },
@@ -569,6 +573,8 @@ export const HkStatusBar = defineComponent({
                       )}
                     </>
                   )}
+                  {tier !== "none" && (
+                    <>
                   <div style={{ display: "flex", alignItems: "center", gap: "6px" }}>
                     <Plug size={12} style={{ opacity: 0.5, flexShrink: 0 }} />
                     <span style={{ opacity: 0.5, marginRight: "auto" }}>{t("hikari::statusBar.protocol", "Protocol")}</span>
@@ -585,6 +591,8 @@ export const HkStatusBar = defineComponent({
                     <span style={{ opacity: 0.5, marginRight: "auto" }}>{t("hikari::statusBar.network", "Network")}</span>
                     <span>{regionDisplayName(info.region, locale, t)}{info.asn != null ? ` · AS${info.asn}` : ""}{info.isLocalhost ? " · " + t("hikari::statusBar.local", "Local") : ""}</span>
                   </div>
+                    </>
+                  )}
                   {(props.extraDetails ?? []).map((row) => (
                     <div key={row.key} data-extra-detail={row.key} style={{ display: "flex", alignItems: "center", justifyContent: "space-between", gap: "6px", maxWidth: "400px" }}>
                       <span style={{ opacity: 0.5, flexShrink: 0, display: "inline-flex" }}>{row.icon}</span>

package/src/components/HkTable.drag.test.tsx

@@ -763,7 +763,7 @@ describe("HkTable grip CSS (source contract)", () => {
     expect(scss).toMatch(/\.hk-table-drag-ghost\s*\{/);
     expect(scss).toMatch(/position: fixed;/);
     expect(scss).toMatch(/border-radius: var\(--radius-md/);
-    expect(scss).toMatch(/z-index: var\(--hk-z-drag, 950\)/);
+    expect(scss).toMatch(/z-index: var\(--hk-z-drag\)/);
     // The settle is a fade, driven by data-fading.
     expect(scss).toMatch(/&\[data-fading]\s*\{/);
   });

package/src/components/HkTable.scss

@@ -280,7 +280,7 @@
   /* Drag ghost: above page chrome (--z-sidebar 900) but below every
      popup band (overlay 1000 < dropdown 2000 < tooltip 3000 < toast 4000)
      so a drag never buries toasts or open panels. */
-  z-index: var(--hk-z-drag, 950);
+  z-index: var(--hk-z-drag);
   will-change: transform;
   transition: opacity 150ms cubic-bezier(0.16, 1, 0.3, 1);
 

package/src/components/HkTitleBar.scss

@@ -25,7 +25,7 @@
   height: var(--hk-tb-height);
   display: flex;
   align-items: center;
-  z-index: var(--z-titlebar, 100001);
+  z-index: var(--hk-z-titlebar);
   user-select: none;
   -webkit-user-select: none;
   background: var(--hk-tb-bg);

package/src/components/HkToast.scss

@@ -6,7 +6,7 @@
   inset-inline-end: var(--viewport-gutter, 16px);
   /* Toast band — the topmost popup z band (POPUP_Z_BANDS.toast; mirror in
      theme.scss). The live value arrives inline from the popup manager. */
-  z-index: var(--hk-z-toast, 4000);
+  z-index: var(--hk-overlay-z-toast, 100);
   max-width: 24rem;
   pointer-events: none;
 }

package/src/components/HkToast.tsx

@@ -10,6 +10,7 @@ import { useI18n } from "../i18n/context";
 import { clearLeaveGeometry, pinLeaveGeometry, type LeaveBoxSnapshot } from "../utils/dom";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
 import "./HkToast.scss";
+import { ensureOverlayRoot } from "../overlay/overlayRoot";
 
 const LONG_THRESHOLD = 50;
 
@@ -246,7 +247,7 @@ export default defineComponent({
     );
 
     return () => (
-      <Teleport to="body">
+      <Teleport to={ensureOverlayRoot()}>
         <div class="hk-toast-container" style={containerStyle.value}>
           <TransitionGroup
             ref={hostRef}

package/src/components/HkTooltip.scss

@@ -12,7 +12,7 @@
 
 .hk-tooltip-popup {
   position: fixed;
-  z-index: var(--hi-z-tooltip, 3000);
+  z-index: var(--hk-overlay-z-tooltip, 300);
   padding: var(--space-4) var(--space-8);
   border: none;
   border-radius: var(--radius-sm);

package/src/components/HkTooltip.test.tsx

@@ -29,7 +29,7 @@ const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement
 
 function mount(props: Record<string, unknown> = {}) {
   const container = document.createElement("div");
-  document.body.appendChild(container);
+  (document.querySelector('#hk-overlay-root') ?? document.body).appendChild(container);
   const app = createApp({
     render: () =>
       h(HkTooltip, props as never, () => h("span", { class: "anchor-probe" }, "anchor")),
@@ -152,7 +152,7 @@ describe("HkTooltip show/hide", () => {
     await nextTick();
     const el = popup();
     expect(document.body.contains(el)).toBe(true);
-    expect(el.parentElement).toBe(document.body);
+    // The tooltip teleports into the overlay root (a child of body).
     expect(el.className).not.toContain("hk-tooltip-visible");
     expect(el.querySelector(".hk-tooltip-content")!.textContent).toBe("the tip");
     // The anchor slot renders inside the wrapper's trigger span.
@@ -175,7 +175,7 @@ describe("HkTooltip show/hide", () => {
 
   it("hands { popupId, visible } to the default slot for focus-target wiring", async () => {
     const container = document.createElement("div");
-    document.body.appendChild(container);
+    (document.querySelector('#hk-overlay-root') ?? document.body).appendChild(container);
     let seen: Partial<HkTooltipSlotProps> = {};
     const app = createApp({
       render: () =>

package/src/components/HkTooltip.tsx

@@ -2,6 +2,7 @@ import { computed, defineComponent, onBeforeUnmount, ref, Teleport, type CSSProp
 import { usePopupManager, type PopupHandle } from "../runtime/usePopupManager";
 import { applyTooltipPosition, type TooltipPlacement } from "../runtime/tooltipPosition";
 import "./HkTooltip.scss";
+import { ensureOverlayRoot } from "../overlay/overlayRoot";
 
 /**
  * The default-slot payload, handed to every render of the trigger. An
@@ -183,7 +184,7 @@ export default defineComponent({
         <span class="hk-tooltip-trigger">
           {slots.default?.({ popupId, visible: visible.value })}
         </span>
-        <Teleport to="body">
+        <Teleport to={ensureOverlayRoot()}>
           {everShown.value && (
             <div
               ref={popupRef}

package/src/components/__tests__/hkMarkdownLang.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+
+// Audit hikari-R1-5: the lang whitelist pattern used by HkMarkdownRenderer.
+const LANG_OK = /^[a-zA-Z0-9+#._-]{1,32}$/;
+
+describe("markdown lang whitelist", () => {
+  it("accepts common language tags", () => {
+    for (const lang of ["rust", "ts", "c++", "c#", "objective-c", "json5", "node.v2"]) {
+      expect(LANG_OK.test(lang)).toBe(true);
+    }
+  });
+
+  it("rejects injection-shaped tags", () => {
+    for (const lang of [
+      "<script>alert(1)</script>",
+      '" onload="alert(1)',
+      "<img src=x onerror=alert(1)>",
+      "a b",
+      "a=b",
+    ]) {
+      expect(LANG_OK.test(lang)).toBe(false);
+    }
+  });
+
+  it("caps length", () => {
+    expect(LANG_OK.test("a".repeat(33))).toBe(false);
+    expect(LANG_OK.test("a".repeat(32))).toBe(true);
+  });
+});

package/src/errorReporting/HkErrorReportingOverlay.scss

@@ -5,5 +5,5 @@
 .hk-error-reporting-overlay {
   position: fixed;
   inset: 0;
-  z-index: 5000;
+  z-index: var(--hk-z-modal);
 }

package/src/index.ts

@@ -799,3 +799,4 @@ export { type HAboutLinkFace as HkAboutLinkFace } from "./components/HkAboutModa
 export { type HAboutLinkIcon as HkAboutLinkIcon } from "./components/HkAboutModal";
 export { type HAboutComponentVersion as HkAboutComponentVersion } from "./components/HkAboutModal";
 export { type HCustomTheme as HkCustomTheme } from "./components/HkColorSchemeDialog";
+export { OVERLAY_ROOT_SELECTOR, OVERLAY_Z, ensureOverlayRoot } from "./overlay/overlayRoot";

package/src/overlay/overlayRoot.scss

@@ -0,0 +1,35 @@
+/**
+ * Overlay root styles — the isolated stacking context and its internal
+ * ordinal z-index bands. These values NEVER compete with the document's
+ * global stacking space; the `isolation: isolate` fence guarantees it.
+ *
+ * The ordinal variables are defined on the root so every Teleported
+ * child inherits them — components use `var(--hk-overlay-z-toast)` etc.
+ * inside their sheets and never need to know the numeric value.
+ */
+#hk-overlay-root {
+  /* Fences the root's z-index space from the global stacking order —
+   * the entire reason this container exists. */
+  isolation: isolate;
+
+  /* The root itself doesn't intercept pointer events; each teleported
+   * child restores its own pointer-events. */
+  pointer-events: none;
+
+  /* Children are position: fixed overlays — the root itself is a
+   * zero-size anchor, not a visible surface. */
+  position: relative;
+  width: 0;
+  height: 0;
+  overflow: visible;
+
+  /* ── Internal ordinal bands (overlayRoot.ts is the source of truth) ── */
+  --hk-overlay-z-modal-backdrop: 5;
+  --hk-overlay-z-modal-frame: 10;
+  --hk-overlay-z-blocking-toast: 50;
+  --hk-overlay-z-toast: 100;
+  --hk-overlay-z-veil: 150;
+  --hk-overlay-z-popup: 200;
+  --hk-overlay-z-breadcrumb: 250;
+  --hk-overlay-z-tooltip: 300;
+}

package/src/overlay/overlayRoot.ts

@@ -0,0 +1,74 @@
+/**
+ * The overlay root — a single `isolation: isolate` container appended to
+ * `<body>` that every floating layer (modal, toast, tooltip, select
+ * popout, context menu) Teleports into.
+ *
+ * Inside this root, z-index values only compete with each other (the
+ * `isolation` property creates a new stacking context), so overlay types
+ * use simple ordinals (1 = lowest … 10 = highest) instead of the old
+ * global thousand-scale bands. A tooltip at z-index 8 inside the root
+ * always paints above a modal at z-index 3 inside the root, regardless
+ * of what the global stacking space looks like outside.
+ *
+ * The root is created lazily on first use (`ensureOverlayRoot()`), so
+ * consumers don't need to include a bootstrap component — any Teleport
+ * target reference triggers creation via the module-level side effect
+ * in `OVERLAY_ROOT_SELECTOR`.
+ *
+ * ## Ordinal bands (internal to the root — never leak out)
+ *
+ * | z-index | Layer          | Examples                              |
+ * |---------|----------------|---------------------------------------|
+ * |    1    | modal backdrop | HkModal's fixed backdrop              |
+ * |    2    | modal frame    | HkModal body, dialogs                 |
+ * |    3    | blocking toast | HkBlockingToast                       |
+ * |    4    | toast          | HkToast, persistent toasts            |
+ * |    5    | loading veil   | HkLoadingVeil                         |
+ * |    6    | anchored popup | HkSelectPanel popout, menus, popover  |
+ * |    7    | breadcrumb     | HkModalBreadcrumb strip               |
+ * |    8    | tooltip        | HkTooltip (always on top)             |
+ *
+ * Components that need to layer within the SAME band (e.g. multiple
+ * stacked modals) use their own local stacking mechanisms (the modal
+ * popup manager already assigns incremental z-values).
+ */
+
+/** The CSS selector for Teleport `to` attributes. */
+export const OVERLAY_ROOT_SELECTOR = "#hk-overlay-root";
+
+/** Ordinal z-index bands — the ONLY z-index values inside the root. */
+export const OVERLAY_Z = {
+  modalBackdrop: 5,
+  modalFrame: 10,
+  blockingToast: 50,
+  toast: 100,
+  loadingVeil: 150,
+  anchoredPopup: 200,
+  breadcrumb: 250,
+  tooltip: 300,
+} as const;
+
+/**
+ * Idempotently create and append the overlay root to `<body>`.
+ * Called on module load — the first `import` of this module guarantees
+ * the DOM node exists before any Teleport resolves its target.
+ */
+export function ensureOverlayRoot(): HTMLElement {
+  if (typeof document === "undefined") return null as unknown as HTMLElement;
+  let root = document.querySelector<HTMLElement>(OVERLAY_ROOT_SELECTOR);
+  if (!root) {
+    root = document.createElement("div");
+    root.id = "hk-overlay-root";
+    root.setAttribute("aria-hidden", "true");
+    // Inline styles — this element is created BEFORE any stylesheet
+    // loads, so it must be self-sufficient. The `isolation` is the
+    // whole point: it fences the root's internal z-index space from
+    // the document's global stacking order.
+    root.style.cssText = "isolation:isolate;pointer-events:none;";
+    document.body.appendChild(root);
+  }
+  return root;
+}
+
+// Module-level side effect: any import of this module ensures the root.
+ensureOverlayRoot();

package/src/runtime/usePopupManager.test.ts

@@ -29,28 +29,31 @@ afterEach(() => {
 });
 
 describe("usePopupManager z bands", () => {
-  it("bands are ordered overlay < dropdown < tooltip < toast", () => {
+  it("bands are ordered modal < toast < dropdown < tooltip", () => {
+    // 2026-10-15 overlay-root ordinal bands: tooltips sit ABOVE toasts
+    // (user direction — tooltip text must be copyable while toasts show),
+    // and toasts sit above modals (notifications visible over dialogs).
     expect(POPUP_Z_BANDS.modal).toBe(POPUP_Z_BANDS.drawer);
-    expect(POPUP_Z_BANDS.modal).toBeLessThan(POPUP_Z_BANDS.dropdown);
+    expect(POPUP_Z_BANDS.modal).toBeLessThan(POPUP_Z_BANDS.toast);
+    expect(POPUP_Z_BANDS.toast).toBeLessThan(POPUP_Z_BANDS.dropdown);
     expect(POPUP_Z_BANDS.dropdown).toBeLessThan(POPUP_Z_BANDS.tooltip);
-    expect(POPUP_Z_BANDS.tooltip).toBeLessThan(POPUP_Z_BANDS.toast);
   });
 
   it("keeps a toast registered first above overlays opened later", () => {
     // The mobile regression: HkToast mounts once at shell level, so the
     // old registration-order ladder gave every later modal a higher z and
     // buried the toast under the phone bottom sheet. Bands must hold the
-    // toast on top regardless of registration order.
+    // toast on top of WINDOW kinds (modal/drawer) regardless of
+    // registration order. Anchored popups (dropdown) sit above toasts
+    // by design (2026-10-15: the user is interacting with them).
     const m = freshManager();
     const toast = m.register("toast", false);
     expect(toast.zIndex).toBe(POPUP_Z_BANDS.toast);
 
     const modal = m.register("modal", true);
     const drawer = m.register("drawer", true);
-    const dropdown = m.register("dropdown", false);
     expect(modal.zIndex).toBeLessThan(toast.zIndex);
     expect(drawer.zIndex).toBeLessThan(toast.zIndex);
-    expect(dropdown.zIndex).toBeLessThan(toast.zIndex);
   });
 
   it("stacks in open order within a band and reclaims freed slots", () => {
@@ -108,14 +111,15 @@ describe("usePopupManager z bands", () => {
     expect(modal2.zIndex).toBeLessThan(dropdown.zIndex);
   });
 
-  it("keeps tooltips above overlays and below toasts", () => {
+  it("keeps tooltips above overlays and toasts", () => {
     const m = freshManager();
     const modal = m.register("modal", true);
     const tooltip = m.register("tooltip", false);
     const toast = m.register("toast", false);
     expect(tooltip.zIndex).toBe(POPUP_Z_BANDS.tooltip);
     expect(tooltip.zIndex).toBeGreaterThan(modal.zIndex);
-    expect(toast.zIndex).toBeGreaterThan(tooltip.zIndex);
+    expect(tooltip.zIndex).toBeGreaterThan(toast.zIndex);
+    // Removed: toast is BELOW tooltip in the 2026-10-15 band layout.
   });
 
   it("keeps the scroll lock counter balanced across register/unregister", () => {

package/src/runtime/usePopupManager.ts

@@ -1,6 +1,8 @@
 import { computed, readonly, ref } from "vue";
 
 import { reportHkRuntime, type HkRuntimeHandle } from "./registry";
+// Side effect: ensures #hk-overlay-root exists before any popup registers.
+import { ensureOverlayRoot } from "../overlay/overlayRoot";
 
 export type PopupKind = "dropdown" | "modal" | "drawer" | "tooltip" | "toast";
 
@@ -51,12 +53,20 @@ export type PopupKind = "dropdown" | "modal" | "drawer" | "tooltip" | "toast";
  * Keep the SCSS fallbacks (`--hi-z-*` / `--hk-z-*` in theme.scss and the
  * component sheets) in sync with these numbers.
  */
+/**
+ * The band each popup KIND stacks in. These are ORDINAL values inside
+ * the overlay root's `isolation: isolate` fence — they never compete
+ * with the document's global stacking space. The overlay root module
+ * (`overlay/overlayRoot.ts`) is the single source of truth; these
+ * constants mirror `OVERLAY_Z` so the popup manager's arithmetic
+ * (band + slot × step) stays local.
+ */
 export const POPUP_Z_BANDS: Record<PopupKind, number> = {
-  modal: 1000,
-  drawer: 1000,
-  dropdown: 2000,
-  tooltip: 3000,
-  toast: 4000,
+  modal: 10,      // window band (modals + drawers) — STEP=2 gives 45 stack slots
+  drawer: 10,     // drawers share the window band (same stacking semantics)
+  toast: 100,     // toast band — far above any conceivable window stack
+  dropdown: 200,  // anchored popup band — above toasts (user is interacting)
+  tooltip: 300,   // tooltip band — always on top
 };
 
 /**

package/src/scale.scss

@@ -64,10 +64,29 @@
   --hi-duration-fast: 0.15s;
   --hi-ease-default: cubic-bezier(0.4, 0, 0.2, 1);
 
-  /* Z-index bands */
-  --z-base: 0;
-  --z-header: 100;
-  --z-sidebar: 900;
+  /* Z-index bands — ONE definition per name; every component that needs
+   * a stacking layer consumes these variables. The bands are ordered from
+   * base content (0) to the window titlebar (100001); a higher band
+   * always paints above a lower one. Tooltips sit above toasts AND
+   * modals so their text stays readable and copyable while any overlay
+   * is showing (user direction 2026-10-15). */
+  --hk-z-base: 0;            /* base content stacking context */
+  --hk-z-above: 1;           /* local bump: checkbox marks, switch thumbs */
+  --hk-z-scrollbar: 10;      /* scrollbar tracks and corner rulers */
+  --hk-z-fab: 40;            /* floating action button */
+  --hk-z-toolbar: 50;        /* zoom toolbar / local overlay strips */
+  --hk-z-header: 100;        /* sticky header */
+  --hk-z-sidebar: 900;       /* sidebar drawer */
+  --hk-z-drag: 950;          /* element being dragged floats above its row */
+  --hk-z-breadcrumb: 2500;   /* modal breadcrumb bar */
+  --hk-z-float: 3000;        /* floating panels: select popout, popover, anchored layer */
+  --hk-z-toast: 4000;        /* toast notifications */
+  --hk-z-veil: 4100;         /* full-screen loading veil (above toast) */
+  --hk-z-modal: 5000;        /* modal backdrop + frame */
+  --hk-z-tooltip: 6000;      /* tooltip — above toasts and modals so its text
+                                 is always readable and copyable */
+  --hk-z-error: 95000;       /* error landing overlay (covers everything) */
+  --hk-z-titlebar: 100001;   /* window titlebar (Tauri shell) */
 
   /* Viewport gutter — the minimum distance every floating layer (tooltip,
    * popover, menu, select popout, modal frame, toasts) keeps from the

package/src/styles/admin-tokens.scss

@@ -86,7 +86,7 @@
   background: rgb(var(--color-surface));
   backdrop-filter: blur(var(--blur-md));
   border-top: 1px solid var(--border-faint, rgb(var(--color-border) / 10%));
-  z-index: var(--z-footer, 110);
+  z-index: var(--hk-z-toolbar);
   flex-shrink: 0;
 }
 
@@ -391,7 +391,7 @@
 /* ── Glass header ─ */
 .s-glass-header {
   position: relative;
-  z-index: var(--z-header);
+  z-index: var(--hk-z-header);
   display: flex;
   align-items: center;
   /* Horizontal rhythm + gap live in the class (not in host utilities):

package/src/styles/index.scss

@@ -30,6 +30,7 @@
 @use "./reset.scss";
 @use "./theme/channels.scss";
 @use "./theme/scale.scss";
+@use "../overlay/overlayRoot.scss";
 @use "./theme/scrollbar.scss";
 @use "./theme/highlight.scss";
 @use "./admin-tokens.scss";

package/src/styles/theme/scale.scss

@@ -66,10 +66,29 @@
   --hi-duration-fast: 0.15s;
   --hi-ease-default: cubic-bezier(0.4, 0, 0.2, 1);
 
-  /* Z-index bands */
-  --z-base: 0;
-  --z-header: 100;
-  --z-sidebar: 900;
+  /* Z-index bands — ONE definition per name; every component that needs
+   * a stacking layer consumes these variables. The bands are ordered from
+   * base content (0) to the window titlebar (100001); a higher band
+   * always paints above a lower one. Tooltips sit above toasts AND
+   * modals so their text stays readable and copyable while any overlay
+   * is showing (user direction 2026-10-15). */
+  --hk-z-base: 0;            /* base content stacking context */
+  --hk-z-above: 1;           /* local bump: checkbox marks, switch thumbs */
+  --hk-z-scrollbar: 10;      /* scrollbar tracks and corner rulers */
+  --hk-z-fab: 40;            /* floating action button */
+  --hk-z-toolbar: 50;        /* zoom toolbar / local overlay strips */
+  --hk-z-header: 100;        /* sticky header */
+  --hk-z-sidebar: 900;       /* sidebar drawer */
+  --hk-z-drag: 950;          /* element being dragged floats above its row */
+  --hk-z-breadcrumb: 2500;   /* modal breadcrumb bar */
+  --hk-z-float: 3000;        /* floating panels: select popout, popover, anchored layer */
+  --hk-z-toast: 4000;        /* toast notifications */
+  --hk-z-veil: 4100;         /* full-screen loading veil (above toast) */
+  --hk-z-modal: 5000;        /* modal backdrop + frame */
+  --hk-z-tooltip: 6000;      /* tooltip — above toasts and modals so its text
+                                 is always readable and copyable */
+  --hk-z-error: 95000;       /* error landing overlay (covers everything) */
+  --hk-z-titlebar: 100001;   /* window titlebar (Tauri shell) */
 
   /* Viewport gutter — the minimum distance every floating layer (tooltip,
    * popover, menu, select popout, modal frame, toasts) keeps from the

package/src/theme/theme.scss

@@ -11,9 +11,6 @@
   // values inline; these tokens are the static fallbacks used before a
   // handle resolves or when a host renders the sheets without JS).
   // overlay (modal/drawer) < dropdown < tooltip < toast (topmost).
-  --hi-z-overlay: 1000;
-  --hi-z-dropdown: 2000;
-  --hi-z-tooltip: 3000;
   --hk-z-toast: 4000;
   // Drag ghosts float above page chrome (--z-sidebar 900) but below
   // every popup band.