@celestia-island/hikari 0.55.165 → 0.55.166

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.165",
+  "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/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) */