@celestia-island/hikari 0.55.164 → 0.55.166

package/package.json

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

package/src/components/HkFilterOperatorIcon.tsx

@@ -0,0 +1,69 @@
+import { defineComponent } from "vue";
+import { Equal, EqualApproximately, EqualNot } from "lucide-vue-next";
+
+import type { HkFilterOperator } from "./HkFilterPanel";
+
+/**
+ * The operator glyph as an ICON, never a text character (user direction
+ * 2026-10-15: font stacks render U+2249 ≉ unevenly — the operator
+ * buttons are UI chrome, so they draw like every other icon in the
+ * family). Lucide ships =, ≠ and ≈; the ordered four and ≉ are
+ * hikari-authored in lucide's exact stroke grammar (24×24, stroke 2,
+ * currentColor) — ≉ is lucide's own ≈ path pair with EqualNot's slash
+ * composed in, so the set reads as one family.
+ */
+
+// Lucide's EqualApproximately path pair (ISC, verbatim) + its EqualNot
+// slash — composed rather than reinvented.
+const NAPPROX_PATHS = [
+  "M5 15a6.5 6.5 0 0 1 7 0 6.5 6.5 0 0 0 7 0",
+  "M5 9a6.5 6.5 0 0 1 7 0 6.5 6.5 0 0 0 7 0",
+  "m5 19 14-14",
+];
+
+const CUSTOM: Partial<Record<HkFilterOperator, string[]>> = {
+  napprox: NAPPROX_PATHS,
+  lt: ["m19 6-11 6 11 6"],
+  lte: ["m19 5-11 6 11 6", "M8 20h11"],
+  gt: ["m5 6 11 6-11 6"],
+  gte: ["m5 5 11 6-11 6", "M5 20h11"],
+};
+
+const LUCIDE: Partial<Record<HkFilterOperator, typeof Equal>> = {
+  eq: Equal,
+  ne: EqualNot,
+  approx: EqualApproximately,
+};
+
+export default defineComponent({
+  name: "HkFilterOperatorIcon",
+  props: {
+    op: { type: String as () => HkFilterOperator, required: true },
+    size: { type: Number, default: 14 },
+  },
+  setup(props) {
+    return () => {
+      const Lucide = LUCIDE[props.op];
+      if (Lucide) return <Lucide size={props.size} aria-hidden="true" />;
+      const paths = CUSTOM[props.op]!;
+      return (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width={props.size}
+          height={props.size}
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          {paths.map((d) => (
+            <path key={d} d={d} />
+          ))}
+        </svg>
+      );
+    };
+  },
+});

package/src/components/HkFilterPanel.scss

@@ -42,6 +42,14 @@
   /* Minimum outer margins for every column (user direction
    * 2026-10-12): the rows never touch the panel edge. */
   padding: var(--space-8, 0.5rem) var(--space-12, 0.75rem);
+  /* Empty panel collapses to the add verb's own width (user direction
+   * 2026-10-15): no rows means nothing to align columns against, so the
+   * popover hugs the 添加条件 button instead of holding the full-row
+   * width. Desktop only — the phone branch below re-widens to 100%. */
+  &[data-empty] {
+    width: max-content;
+    min-width: 0;
+  }
 }
 
 /* A row is not a box — it donates its three cells to the panel grid so

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

@@ -73,6 +73,12 @@ describe("HkFilterPanel stylesheet contract", () => {
     expect(rule).toContain("justify-self: start");
   });
 
+  it("the empty panel collapses to the add verb's own width", () => {
+    // 2026-10-15: no rows = nothing to align columns against — the
+    // desktop popover hugs the 添加条件 button (data-empty marker).
+    expect(css).toMatch(/\.hk-filter-panel\[data-empty\]\s*\{[^}]*width:\s*max-content/);
+  });
+
   it("the phone operator column keeps its widened cap (≥ the old 4.25rem)", () => {
     expect(css).toContain("@media (max-width: 767px)");
     const media = css.slice(css.indexOf("@media (max-width: 767px)"));

package/src/components/HkFilterPanel.test.tsx

@@ -45,6 +45,9 @@ describe("HkFilterPanel (array state, 2026-10-15)", () => {
     expect(c.querySelectorAll(".hk-filter-panel-row")).toHaveLength(0);
     expect(c.querySelector(".hk-filter-panel-add")).toBeTruthy();
     expect(c.querySelectorAll(".hk-filter-panel-field")).toHaveLength(0);
+    // The empty panel carries the collapse marker (width hugs the add
+    // verb on desktop — pinned in the styles contract test).
+    expect(c.querySelector(".hk-filter-panel")!.getAttribute("data-empty")).toBe("true");
 
     const state: HkFilterState = [
       { key: "tool", op: "approx", value: "web" },
@@ -188,13 +191,15 @@ describe("HkFilterPanel (array state, 2026-10-15)", () => {
     );
     const rows = [...c.querySelectorAll(".hk-filter-panel-row")];
     const opsOf = (row: Element) =>
-      [...row.querySelectorAll(".hk-filter-panel-op")].map((b) => b.textContent);
+      [...row.querySelectorAll(".hk-filter-panel-op")].map((b) => b.getAttribute("title"));
     // Text speaks ONLY the fuzzy pair (2026-10-15: 等于其实是模糊匹配 —
     // label it ≈, and the exclusion ≉).
-    expect(opsOf(rows[0]!)).toEqual(["≈", "≉"]);
-    expect(opsOf(rows[1]!)).toEqual(["<", "≤", "=", "≥", ">"]);
-    expect(opsOf(rows[2]!)).toEqual(["=", "≠"]);
-    expect(opsOf(rows[3]!)).toEqual(["≥", "≤"]);
+    expect(opsOf(rows[0]!)).toEqual(["fuzzy match", "fuzzy non-match"]);
+    expect(opsOf(rows[1]!)).toEqual(["less than", "at most", "equals", "at least", "greater than"]);
+    // Select speaks ONLY the eq/ne pair — rendered as the fuzzy pair
+    // glyphs (2026-10-15 follow-up: 等于/不等于 换成 ≈/≉).
+    expect(opsOf(rows[2]!)).toEqual(["fuzzy match", "fuzzy non-match"]);
+    expect(opsOf(rows[3]!)).toEqual(["at least", "at most"]);
   });
 
   it("emits a new state when an operator is picked (live, no confirm)", async () => {
@@ -207,7 +212,7 @@ describe("HkFilterPanel (array state, 2026-10-15)", () => {
       }),
     );
     const notMatch = [...c.querySelectorAll(".hk-filter-panel-row")[0]!.querySelectorAll(".hk-filter-panel-op")]
-      .find((b) => b.textContent === "≉")!;
+      .find((b) => b.getAttribute("title") === "fuzzy non-match")!;
     notMatch.dispatchEvent(new MouseEvent("click", { bubbles: true }));
     await Promise.resolve();
     expect(seen).toEqual([{ key: "tool", op: "napprox", value: "web" }]);

package/src/components/HkFilterPanel.tsx

@@ -5,6 +5,7 @@ import HkDatePicker from "./HkDatePicker";
 import HkInput from "./HkInput";
 import HkPopover from "./HkPopover";
 import HkPopupSelect, { type HkPopupSelectOption } from "./HkPopupSelect";
+import HkFilterOperatorIcon from "./HkFilterOperatorIcon";
 import HkScrollContainer from "./HkScrollContainer";
 import { useI18n } from "../i18n/context";
 import "./HkFilterPanel.scss";
@@ -53,16 +54,15 @@ export interface HkFilterCondition {
  * field chooser. */
 export type HkFilterState = HkFilterCondition[];
 
-const OPERATOR_SYMBOL: Record<HkFilterOperator, string> = {
-  eq: "=",
-  ne: "≠",
-  approx: "≈",
-  napprox: "≉",
-  lt: "<",
-  lte: "≤",
-  gte: "≥",
-  gt: ">",
-};
+/** Which ICON the operator renders as: fields that speak ONLY the
+ * eq/ne pair (select) render the fuzzy pair ≈/≉ (2026-10-15 — 等于
+ * 其实是模糊匹配 applies to them too); number's exact = keeps the
+ * plain equals icon inside the ordered five. */
+function glyphOpFor(kind: HkFilterFieldDef["kind"], op: HkFilterOperator): HkFilterOperator {
+  if (kind === "select" && op === "eq") return "approx";
+  if (kind === "select" && op === "ne") return "napprox";
+  return op;
+}
 
 const OPERATOR_LABEL: Record<HkFilterOperator, { key: string; fallback: string }> = {
   eq: { key: "hikari::filterPanel.op.eq", fallback: "equals" },
@@ -309,7 +309,7 @@ export default defineComponent({
     return () => {
       const label = props.label ?? t("hikari::filterBar.trigger", "Filters");
       return (
-        <div class="hk-filter-panel" data-testid="hk-filter-panel" data-active={activeCount.value > 0 || undefined} aria-label={label}>
+        <div class="hk-filter-panel" data-testid="hk-filter-panel" data-active={activeCount.value > 0 || undefined} data-empty={rows.value.length === 0 || undefined} aria-label={label}>
           {rows.value.map((cond, index) => {
             const field = fieldByKey(cond.key);
             // An undeclared key (the page renamed a field under live
@@ -322,20 +322,23 @@ export default defineComponent({
               <div key={index} class="hk-filter-panel-row" data-kind={kind}>
                 <span class="hk-filter-panel-field">{labelText}</span>
                 <div class="hk-filter-panel-ops" role="group" aria-label={`${labelText} — ${label}`}>
-                  {ops.map((op) => (
+                  {ops.map((op) => {
+                    const glyph = glyphOpFor(kind, op);
+                    return (
                     <button
                       key={op}
                       type="button"
                       class="hk-filter-panel-op"
                       aria-pressed={cond.op === op}
-                      aria-label={t(OPERATOR_LABEL[op].key, OPERATOR_LABEL[op].fallback)}
-                      title={t(OPERATOR_LABEL[op].key, OPERATOR_LABEL[op].fallback)}
+                      aria-label={t(OPERATOR_LABEL[glyph].key, OPERATOR_LABEL[glyph].fallback)}
+                      title={t(OPERATOR_LABEL[glyph].key, OPERATOR_LABEL[glyph].fallback)}
                       disabled={props.disabled || !field}
                       onClick={() => emitCondition(index, { op })}
                     >
-                      {OPERATOR_SYMBOL[op]}
+                      <HkFilterOperatorIcon op={glyph} />
                     </button>
-                  ))}
+                    );
+                  })}
                 </div>
                 <div class="hk-filter-panel-value">
                   <div class="hk-filter-panel-control">

package/src/components/HkFilterTrigger.test.tsx

@@ -319,7 +319,7 @@ describe("HkFilterTrigger", () => {
     // stand down for it, not swallow it. (Pick the ≈ toggle; the first
     // op button is the already-pressed =.)
     const op = [...document.body.querySelectorAll<HTMLButtonElement>(".hk-filter-panel .hk-filter-panel-op")].find(
-      (b) => b.textContent === "≈",
+      (b) => b.getAttribute("title") === "fuzzy match",
     )!;
     op.dispatchEvent(new MouseEvent("click", { bubbles: true }));
     await Promise.resolve();

package/src/components/HkFilterTrigger.tsx

@@ -1,5 +1,5 @@
 import { computed, defineComponent, ref, type PropType } from "vue";
-import { SlidersHorizontal } from "lucide-vue-next";
+import { Filter } from "lucide-vue-next";
 
 import HkButton from "./HkButton";
 import HkCornerBadge from "./HkCornerBadge";
@@ -74,7 +74,7 @@ export default defineComponent({
                 open.value = !open.value;
               }}
             >
-              {{ icon: () => <SlidersHorizontal size={16} /> }}
+              {{ icon: () => <Filter size={16} /> }}
             </HkIconButton>
           </HkCornerBadge>
           <HkPopover

package/src/errorReporting/HkErrorReportingOverlay.scss

@@ -1,9 +1,12 @@
 // HkErrorReportingOverlay — fixed full-viewport host for the error landing.
-// Sits above every popup band (modal 1000 / dropdown 2000 / tooltip 3000 /
-// toast 4000): an uncaught-error takeover must never be covered.
+// Mounts on document.body (NOT the overlay root — the takeover must survive
+// even a broken floating tree) and sits on --hk-z-error, ABOVE the fenced
+// overlay root (--hk-z-overlay-root): an uncaught-error takeover must never
+// be covered — not by app chrome, not by any floating layer. Only the
+// window titlebar (--hk-z-titlebar) stays above it in the Tauri shell.
 
 .hk-error-reporting-overlay {
   position: fixed;
   inset: 0;
-  z-index: var(--hk-z-modal);
+  z-index: var(--hk-z-error);
 }

package/src/overlay/overlayRoot.scss

@@ -9,9 +9,21 @@
  */
 #hk-overlay-root {
   /* Fences the root's z-index space from the global stacking order —
-   * the entire reason this container exists. */
+   * the entire reason this container exists. The fence disciplines the
+   * root's INTERNALS only; the elevation below is what lifts the root
+   * itself above app chrome. */
   isolation: isolate;
 
+  /* Document-space elevation — without it, any fixed/sticky chrome with
+   * a positive z-index (the admin status bar sits at
+   * --hk-z-toolbar: 50) painted over EVERY floating layer: the
+   * connection popover rendered behind the panel footer (2026-10-15
+   * defect report). The band lives in scale.scss between the old
+   * floating bands and --hk-z-error, preserving the pre-isolation
+   * order: content chrome < floating layers < error landing < titlebar.
+   * The fallback must match overlayRoot.ts's OVERLAY_ROOT_DOCUMENT_Z. */
+  z-index: var(--hk-z-overlay-root, 90000);
+
   /* The root itself doesn't intercept pointer events; each teleported
    * child restores its own pointer-events. */
   pointer-events: none;

package/src/overlay/overlayRoot.styles.test.ts

@@ -0,0 +1,185 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compile } from "sass";
+import { describe, expect, it } from "vitest";
+
+import { OVERLAY_ROOT_DOCUMENT_Z, ensureOverlayRoot } from "./overlayRoot";
+
+/**
+ * Compiled-stylesheet + cross-file contract for the overlay root's
+ * document-space elevation. `isolation` fences the root's INTERNAL
+ * ordinals but does not lift the root above app chrome — without the
+ * elevation, any fixed/sticky bar with a positive z-index (the admin
+ * status bar's --hk-z-toolbar: 50) painted over every floating layer
+ * and the connection popover ended up behind the panel footer
+ * (2026-10-15 defect report). These assertions pin the elevation in
+ * all three places it must agree: scale.scss (the band), the compiled
+ * sheet, and the inline self-sufficient cssText.
+ */
+const overlayDir = resolve(dirname(fileURLToPath(import.meta.url)));
+const vueSrc = resolve(overlayDir, "..");
+
+function sourcesIn(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    if (entry === "node_modules" || entry === "__tests__") continue;
+    const path = join(dir, entry);
+    if (statSync(path).isDirectory()) out.push(...sourcesIn(path));
+    else if (/\.(scss|tsx)$/.test(entry)) out.push(path);
+  }
+  return out;
+}
+
+describe("overlay root document-space elevation contract", () => {
+  const css = compile(resolve(overlayDir, "overlayRoot.scss"), {
+    style: "expanded",
+  }).css;
+  const scale = readFileSync(resolve(vueSrc, "scale.scss"), "utf8");
+  const source = readFileSync(resolve(overlayDir, "overlayRoot.ts"), "utf8");
+
+  it("declares the elevation in the sheet, with the fence kept", () => {
+    expect(css).toContain("z-index: var(--hk-z-overlay-root, 90000);");
+    expect(css).toContain("isolation: isolate;");
+    expect(css).toContain("position: relative;");
+  });
+
+  it("keeps scale.scss, the sheet fallback and the TS fallback on one value", () => {
+    const band = scale.match(/--hk-z-overlay-root:\s*(\d+)/);
+    // A missing match is a broken contract, not an empty pass.
+    expect(band).not.toBeNull();
+    expect(Number(band![1])).toBe(OVERLAY_ROOT_DOCUMENT_Z);
+    // The inline cssText interpolates the same constant.
+    expect(source).toContain(
+      "z-index:var(--hk-z-overlay-root,${OVERLAY_ROOT_DOCUMENT_Z})",
+    );
+  });
+
+  it("parks the band between the floating bands and error/titlebar", () => {
+    const value = (name: string) => {
+      const m = scale.match(new RegExp(`--hk-z-${name}:\\s*(\\d+)`));
+      expect(m, `--hk-z-${name} must stay defined in scale.scss`).not.toBeNull();
+      return Number(m![1]);
+    };
+    const band = value("overlay-root");
+    // Above every content-chrome band (the defect: footer at 50 won).
+    expect(band).toBeGreaterThan(value("tooltip"));
+    expect(band).toBeGreaterThan(value("modal"));
+    expect(band).toBeGreaterThan(value("toolbar"));
+    // Below the two surfaces that intentionally stay on top, exactly as
+    // in the pre-isolation global scale.
+    expect(band).toBeLessThan(value("error"));
+    expect(band).toBeLessThan(value("titlebar"));
+  });
+
+  it("inlines a self-sufficient pre-stylesheet elevation", () => {
+    const root = ensureOverlayRoot();
+    expect(root.id).toBe("hk-overlay-root");
+    expect(root.style.getPropertyValue("z-index")).toContain(
+      "var(--hk-z-overlay-root",
+    );
+    expect(root.style.getPropertyValue("position")).toBe("relative");
+  });
+
+  it("lets no z-index consumer land between the root band and the error band", () => {
+    // The exact gap class the 2026-10-15 fix closed: a document-space
+    // surface that must own the top (hikari's error landing) sat at
+    // --hk-z-modal = 5000, and the elevated root silently jumped over
+    // it. Every --hk-z-* consumer must resolve STRICTLY below the root
+    // band (content chrome) or be one of the two intentional
+    // top-owners, which must stay ABOVE it — nothing ties the band
+    // (a tie would be DOM-order roulette) and nothing lands between
+    // the two bands. Consumers are matched anywhere INSIDE a
+    // z-index-bearing line, so calc()/nested-fallback wrappers
+    // (`var(--x, var(--hk-z-scrollbar))`) are still inventoried; their
+    // ARITHMETIC is not evaluated (a calc() offset off a top-owner
+    // token is textual guessing — same out-of-scope class as raw
+    // numbers, audited by hand at ≤ 51 in this package). Single-line
+    // declarations only.
+    const bandValues = new Map<string, number>();
+    for (const [, name, num] of scale.matchAll(/--hk-z-([a-z-]+):\s*(\d+)/g)) {
+      bandValues.set(name, Number(num));
+    }
+    // The ladder itself must be present — a broken parse must not
+    // masquerade as an empty pass.
+    expect(bandValues.size).toBeGreaterThanOrEqual(10);
+    expect(bandValues.get("overlay-root")).toBe(OVERLAY_ROOT_DOCUMENT_Z);
+
+    const sources = sourcesIn(vueSrc);
+    // Positive floor for the walk: hundreds of sheets/components live
+    // under src/ — fewer means the glob broke, not that the code did.
+    expect(sources.length).toBeGreaterThanOrEqual(200);
+
+    const found = new Map<string, Set<string>>(); // token name -> files
+    for (const file of sources) {
+      for (const line of readFileSync(file, "utf8").split("\n")) {
+        if (!/\bz-index\s*[:=]|\bzIndex\s*[:=]/.test(line)) continue;
+        for (const [, name] of line.matchAll(/var\(\s*--hk-z-([a-z-]+)/g)) {
+          if (!found.has(name)) found.set(name, new Set());
+          found.get(name)!.add(file);
+        }
+      }
+    }
+    // Positive controls: the scan must see the known top-owners and the
+    // root itself, or the line patterns stopped matching.
+    for (const required of ["overlay-root", "error", "titlebar", "toolbar"]) {
+      expect(
+        found.has(required),
+        `scan lost the --hk-z-${required} consumer — patterns rotted`,
+      ).toBe(true);
+    }
+
+    // File binding, not just name presence: the error takeover's
+    // "never covered" promise lives in ONE sheet — assert IT consumes
+    // the top-owner band, so the promise survives even if a second
+    // --hk-z-error consumer appears elsewhere.
+    const errorSheet = join(vueSrc, "errorReporting", "HkErrorReportingOverlay.scss");
+    expect(readFileSync(errorSheet, "utf8")).toMatch(
+      /z-index:\s*var\(\s*--hk-z-error[\s,)]/,
+    );
+    const titlebarSheet = join(vueSrc, "components", "HkTitleBar.scss");
+    expect(readFileSync(titlebarSheet, "utf8")).toMatch(
+      /z-index:\s*var\(\s*--hk-z-titlebar[\s,)]/,
+    );
+
+    const topOwners = new Set(["error", "titlebar"]);
+    const rootSheet = resolve(overlayDir, "overlayRoot.scss");
+    for (const [name, files] of found) {
+      const value = bandValues.get(name);
+      expect(
+        value,
+        `--hk-z-${name} consumed (e.g. ${files.values().next().value}) but not defined in scale.scss`,
+      ).not.toBeUndefined();
+      if (topOwners.has(name)) {
+        // A top-owner demoted to/below the root band would be painted
+        // over by the floating tree (the error landing sat at
+        // --hk-z-modal = 5000 when this guard was born).
+        expect(
+          value!,
+          `--hk-z-${name} (${value}) must stay above the overlay root band ` +
+            `(${OVERLAY_ROOT_DOCUMENT_Z}) — consumers: ${[...files].join(", ")}`,
+        ).toBeGreaterThan(OVERLAY_ROOT_DOCUMENT_Z);
+      } else if (name === "overlay-root") {
+        // The band itself: ONLY the root's own sheet may sit at it —
+        // any other consumer at exactly 90000 races the root by DOM
+        // order.
+        for (const file of files) {
+          expect(
+            file,
+            `--hk-z-overlay-root consumed at ${file} — only ${rootSheet} may tie the band`,
+          ).toBe(rootSheet);
+        }
+      } else {
+        expect(
+          value!,
+          `--hk-z-${name} (${value}) at ${[...files].join(", ")} must resolve ` +
+            `strictly below the overlay root band (${OVERLAY_ROOT_DOCUMENT_Z}) ` +
+            `or above the error band — ties and in-between values get painted ` +
+            `over by (or paint over) the floating tree`,
+        ).toBeLessThan(OVERLAY_ROOT_DOCUMENT_Z);
+      }
+    }
+  });
+});
+

package/src/overlay/overlayRoot.ts

@@ -5,10 +5,21 @@
  *
  * 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.
+ * use simple ordinal bands instead of the old global thousand-scale. A
+ * tooltip at ordinal 300 inside the root always paints above a modal at
+ * ordinal 10 inside the root, regardless of what the global stacking
+ * space looks like outside.
+ *
+ * The fence only disciplines the root's INTERNALS, though — by itself
+ * `isolation` does not lift the root above app chrome. A fixed/sticky
+ * bar with a positive document-space z-index (the admin status bar sits
+ * at `--hk-z-toolbar: 50`) painted over EVERY floating layer, dropping
+ * the connection popover behind the panel footer (2026-10-15 defect
+ * report). The root therefore carries ONE document-space z-index of its
+ * own — `--hk-z-overlay-root` (fallback 90000) — parked between the old
+ * floating bands and `--hk-z-error`, so the pre-isolation global order
+ * is preserved: content chrome < floating layers < error landing <
+ * window titlebar.
  *
  * The root is created lazily on first use (`ensureOverlayRoot()`), so
  * consumers don't need to include a bootstrap component — any Teleport
@@ -19,14 +30,14 @@
  *
  * | 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)             |
+ * |    5    | modal backdrop | HkModal's fixed backdrop              |
+ * |   10    | modal frame    | HkModal body, dialogs                 |
+ * |   50    | blocking toast | HkBlockingToast                       |
+ * |  100    | toast          | HkToast, persistent toasts            |
+ * |  150    | loading veil   | HkLoadingVeil                         |
+ * |  200    | anchored popup | HkSelectPanel popout, menus, popover  |
+ * |  250    | breadcrumb     | HkModalBreadcrumb strip               |
+ * |  300    | 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
@@ -48,6 +59,15 @@ export const OVERLAY_Z = {
   tooltip: 300,
 } as const;
 
+/**
+ * The root's document-space elevation fallback — must match the
+ * `--hk-z-overlay-root` value in `scale.scss` (kept honest by
+ * overlayRoot.styles.test.ts). Inlined because the root is created
+ * before any stylesheet loads; the var() indirection lets the sheet
+ * retune the band without touching this file.
+ */
+export const OVERLAY_ROOT_DOCUMENT_Z = 90000;
+
 /**
  * Idempotently create and append the overlay root to `<body>`.
  * Called on module load — the first `import` of this module guarantees
@@ -61,10 +81,16 @@ export function ensureOverlayRoot(): HTMLElement {
     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;";
+    // loads, so it must be self-sufficient. `isolation` fences the
+    // root's internal z-index space from the document's global stacking
+    // order; `position` + `z-index` then lift the fenced root above
+    // every content-chrome band (see the module doc) — `position` is
+    // repeated here so the elevation also applies pre-stylesheet. The
+    // var() name is the sheet's retuning path; the fallback constant
+    // must equal scale.scss's --hk-z-overlay-root.
+    root.style.cssText =
+      "isolation:isolate;pointer-events:none;position:relative;" +
+      `z-index:var(--hk-z-overlay-root,${OVERLAY_ROOT_DOCUMENT_Z});`;
     document.body.appendChild(root);
   }
   return root;

package/src/scale.scss

@@ -69,7 +69,11 @@
    * 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). */
+   * is showing (user direction 2026-10-15). --hk-z-overlay-root is the
+   * ONE band consumed by the fenced floating-layer root itself rather
+   * than by a component: it lifts #hk-overlay-root above every
+   * content-chrome band while keeping the pre-isolation order (floating
+   * layers < error landing < window titlebar). */
   --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 */
@@ -85,6 +89,9 @@
   --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-overlay-root: 90000; /* #hk-overlay-root — every floating layer's
+                                 document-space elevation (overlay/overlayRoot.ts);
+                                 above all content chrome, below error + titlebar */
   --hk-z-error: 95000;       /* error landing overlay (covers everything) */
   --hk-z-titlebar: 100001;   /* window titlebar (Tauri shell) */
 

package/src/styles/theme/scale.scss

@@ -71,7 +71,11 @@
    * 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). */
+   * is showing (user direction 2026-10-15). --hk-z-overlay-root is the
+   * ONE band consumed by the fenced floating-layer root itself rather
+   * than by a component: it lifts #hk-overlay-root above every
+   * content-chrome band while keeping the pre-isolation order (floating
+   * layers < error landing < window titlebar). */
   --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 */
@@ -87,6 +91,9 @@
   --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-overlay-root: 90000; /* #hk-overlay-root — every floating layer's
+                                 document-space elevation (overlay/overlayRoot.ts);
+                                 above all content chrome, below error + titlebar */
   --hk-z-error: 95000;       /* error landing overlay (covers everything) */
   --hk-z-titlebar: 100001;   /* window titlebar (Tauri shell) */