@celestia-island/hikari 0.55.111 → 0.55.113

package/package.json

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

package/src/components/HkAdminShell.padding.test.ts

@@ -0,0 +1,205 @@
+import { describe, expect, it } from "vitest";
+
+import { mobileSideGutterFree, scanPaddingSides, splitPaddingSides } from "./HkAdminShell";
+
+/**
+ * Direct unit tests for the padding-shorthand helpers behind
+ * `HkAdminShell`'s `contentBleedOnMobile`.
+ *
+ * WHY THIS FILE EXISTS (and why the component-level suite cannot replace
+ * it): the DOM assertions in HkAdminShell.test.tsx run through
+ * happy-dom's CSS parser, which refuses to round-trip exactly the values
+ * these helpers exist to protect — `var(...)` with a fallback, `clamp()`,
+ * a quoted argument — and normalizes the ones it does keep, so a
+ * regression there is invisible at the component level (round-2 and
+ * round-3 verification both proved a surviving mutant that the DOM suite
+ * scored green). The helpers are exported for this file only: they are
+ * not re-exported from the package barrel.
+ *
+ * The contract, in one line each:
+ * - `splitPaddingSides` splits on TOP-LEVEL whitespace only (functions
+ *   and quoted arguments are one track), tolerates tabs/newlines and
+ *   surrounding whitespace, and never lets a stray `)` invert the depth;
+ * - `mobileSideGutterFree` keeps the vertical tracks, zeroes the
+ *   horizontal ones, and returns the value VERBATIM whenever the rewrite
+ *   could produce a declaration a browser would drop whole.
+ */
+describe("splitPaddingSides", () => {
+  it("splits a plain shorthand into its tracks", () => {
+    expect(splitPaddingSides("2rem")).toEqual(["2rem"]);
+    expect(splitPaddingSides("1rem 2rem")).toEqual(["1rem", "2rem"]);
+    expect(splitPaddingSides("1rem 2rem 3rem")).toEqual(["1rem", "2rem", "3rem"]);
+    expect(splitPaddingSides("1rem 2rem 3rem 4rem")).toEqual(["1rem", "2rem", "3rem", "4rem"]);
+  });
+
+  it("treats every CSS separator like a space and drops no empty track", () => {
+    expect(splitPaddingSides("1rem\t2rem")).toEqual(["1rem", "2rem"]);
+    expect(splitPaddingSides("1rem\n2rem")).toEqual(["1rem", "2rem"]);
+    expect(splitPaddingSides("1rem \n\t 2rem")).toEqual(["1rem", "2rem"]);
+    expect(splitPaddingSides("  1rem 2rem  ")).toEqual(["1rem", "2rem"]);
+    expect(splitPaddingSides("")).toEqual([]);
+    expect(splitPaddingSides("   ")).toEqual([]);
+  });
+
+  it("keeps a function value as ONE track, however many spaces it holds", () => {
+    expect(splitPaddingSides("calc(1rem + 2px)")).toEqual(["calc(1rem + 2px)"]);
+    expect(splitPaddingSides("calc(1rem + 2px) 1rem")).toEqual(["calc(1rem + 2px)", "1rem"]);
+    expect(splitPaddingSides("1rem calc(2px + 3px)")).toEqual(["1rem", "calc(2px + 3px)"]);
+    // A space directly after "(" is inside the function too.
+    expect(splitPaddingSides("calc( 1rem + 2px ) 1rem")).toEqual(["calc( 1rem + 2px )", "1rem"]);
+  });
+
+  it("balances nested parentheses", () => {
+    expect(splitPaddingSides("clamp(1rem, min(2vw, 3px), 4rem) 2rem"))
+      .toEqual(["clamp(1rem, min(2vw, 3px), 4rem)", "2rem"]);
+    expect(splitPaddingSides("calc(1rem + calc(2px * 2))"))
+      .toEqual(["calc(1rem + calc(2px * 2))"]);
+  });
+
+  it("keeps a quoted argument intact, its parens and spaces included", () => {
+    expect(splitPaddingSides("var(--pad, \") 1rem\") 2rem"))
+      .toEqual(["var(--pad, \") 1rem\")", "2rem"]);
+    expect(splitPaddingSides("var(--pad, ' + ')")).toEqual(["var(--pad, ' + ')"]);
+    // A paren inside a SINGLE-quoted argument, and the other quote char
+    // inside it: only the matching quote closes the string.
+    expect(splitPaddingSides("var(--pad, ') x') 2rem"))
+      .toEqual(["var(--pad, ') x')", "2rem"]);
+    expect(splitPaddingSides("var(--pad, 'a\") b') 2rem"))
+      .toEqual(["var(--pad, 'a\") b')", "2rem"]);
+  });
+
+  it("opens a quote at top level too (and reports it unterminated)", () => {
+    expect(splitPaddingSides("\"a b")).toEqual(["\u0022a b"]);
+    expect(scanPaddingSides("\"a b").balanced).toBe(false);
+  });
+
+  it("never lets a stray close paren invert the depth", () => {
+    // Malformed CSS in, but the tracks must not silently merge: without
+    // the clamp the `)` would drive the depth to -1 and swallow the next
+    // separator.
+    expect(splitPaddingSides("1rem ) 2rem")).toEqual(["1rem", ")", "2rem"]);
+  });
+
+  it("reports an unterminated function or quote as unbalanced", () => {
+    expect(scanPaddingSides("calc(1rem + 2px")).toEqual({
+      sides: ["calc(1rem + 2px"],
+      balanced: false,
+    });
+    expect(scanPaddingSides("1rem 2rem").balanced).toBe(true);
+    expect(scanPaddingSides("calc(1rem + 2px) 1rem").balanced).toBe(true);
+    expect(scanPaddingSides("var(--pad, ') x')").balanced).toBe(true);
+  });
+});
+
+describe("mobileSideGutterFree", () => {
+  it("keeps the vertical tracks and zeroes the horizontal ones", () => {
+    expect(mobileSideGutterFree("2rem")).toBe("2rem 0 2rem");
+    expect(mobileSideGutterFree("1rem 2rem")).toBe("1rem 0 1rem");
+    expect(mobileSideGutterFree("1rem 2rem 3rem")).toBe("1rem 0 3rem");
+    expect(mobileSideGutterFree("1rem 2rem 3rem 4rem")).toBe("1rem 0 3rem");
+    expect(mobileSideGutterFree("0")).toBe("0 0 0");
+    expect(mobileSideGutterFree(" 1rem\t2rem ")).toBe("1rem 0 1rem");
+  });
+
+  it("keeps a function value whole", () => {
+    expect(mobileSideGutterFree("calc(1rem + 2px)")).toBe("calc(1rem + 2px) 0 calc(1rem + 2px)");
+    expect(mobileSideGutterFree("calc(1rem + 2px) 1rem")).toBe("calc(1rem + 2px) 0 calc(1rem + 2px)");
+    expect(mobileSideGutterFree("5rem clamp(1rem, min(2vw, 3px), 4rem)")).toBe("5rem 0 5rem");
+  });
+
+  it("returns the value verbatim when the rewrite cannot be expressed", () => {
+    // Nothing to strip.
+    expect(mobileSideGutterFree("")).toBe("");
+    expect(mobileSideGutterFree("   ")).toBe("   ");
+    // A CSS-wide keyword cannot be combined per side: `inherit 0 inherit`
+    // is not a padding at all, so bleeding would cost the page its
+    // vertical clearance.
+    for (const keyword of ["inherit", "initial", "unset", "revert", "revert-layer"]) {
+      expect(mobileSideGutterFree(keyword), keyword).toBe(keyword);
+      expect(mobileSideGutterFree(keyword.toUpperCase()), keyword).toBe(keyword.toUpperCase());
+    }
+    // A comment's text is not a track; rebuilding would emit one
+    // ("1rem 0 x") that a browser drops whole. An UNCLOSED comment bails
+    // the same way, and so does a quoted `/*` — the guard reads the raw
+    // text and does not try to be clever about strings.
+    expect(mobileSideGutterFree("1rem /* x */ 2rem")).toBe("1rem /* x */ 2rem");
+    expect(mobileSideGutterFree("1rem /* x 2rem")).toBe("1rem /* x 2rem");
+    expect(mobileSideGutterFree("var(--pad, \"/*\") 2rem")).toBe("var(--pad, \"/*\") 2rem");
+  });
+
+  it("refuses any value carrying a backslash escape", () => {
+    // The scanner does not decode CSS escapes, and an escape can hide a
+    // quote, a paren or a whole keyword — `"\69 nherit"` IS `inherit` to
+    // an engine (measured in Chromium), so the literal text is not the
+    // value and no rewrite of it can be trusted. Round 4/5 verification
+    // measured every one of these losing all four sides to a dropped
+    // declaration.
+    const escaped = [
+      "\\69 nherit",
+      "var(--pad, \"a\\\"b\") 2rem",
+      "var(--pad, 'a\\'b') 2rem",
+      "var(--pad, a\\(b) 2rem",
+      "\"a\\\" b\" 1rem",
+    ];
+    for (const value of escaped) {
+      expect(mobileSideGutterFree(value), value).toBe(value);
+    }
+  });
+
+  it("refuses a value whose functions or quotes never close", () => {
+    // CSS auto-closes an open function at EOF, so the AUTHORED value can
+    // be a real padding (Chromium: 18px on all four sides for
+    // "calc(1rem + 2px") while the rewrite of it is not — the rewrite
+    // would cost the page every side, vertical included.
+    const unterminated = [
+      "calc(1rem + 2px",
+      "calc(1rem",
+      "min(1rem, 2rem",
+      "1rem calc(2px",
+      "\"a b",
+      "var(--pad, 'x",
+    ];
+    for (const value of unterminated) {
+      expect(mobileSideGutterFree(value), value).toBe(value);
+    }
+  });
+
+  it("refuses a value whose priority annotation cannot ride the rewrite", () => {
+    // `!important` annotates the DECLARATION, not a track. Rewriting it
+    // would either drop the priority (`2rem !important` -> `2rem 0 2rem`)
+    // or rebuild a declaration every engine drops (`inherit !important`
+    // -> `inherit 0 inherit`, measured in Chromium as rejected whole,
+    // with the page falling back to the cascade). Round 5 found the
+    // family; the value now passes through untouched.
+    const flagged = [
+      "2rem !important",
+      "1rem 2rem 3rem !important",
+      "inherit !important",
+      "unset !important",
+      "initial!important",
+      "revert-layer !important",
+      "2rem ! important",
+      "2rem !IMPORTANT",
+      "2rem !important ",
+    ];
+    for (const value of flagged) {
+      expect(mobileSideGutterFree(value), value).toBe(value);
+    }
+    // …and only a TRAILING annotation is one: mid-value text is just
+    // another track (the authored value is invalid CSS either way, so
+    // this guard makes no promise about it).
+    expect(mobileSideGutterFree("1rem !important 2rem")).toBe("1rem 0 2rem");
+  });
+
+  it("still rewrites a keyword-shaped track that is not alone", () => {
+    // A CSS-wide keyword is only valid as a declaration's SOLE value, so
+    // "inherit 2rem" is invalid CSS whatever we do with it, and its
+    // rewrite is dropped exactly like the authored value. The lone
+    // spelling above IS valid, which is why it bails instead. ("1rem
+    // inherit" is the looser case: the authored value is already
+    // invalid, while the rewrite happens to be valid — a repair, not a
+    // loss.)
+    expect(mobileSideGutterFree("inherit 2rem")).toBe("inherit 0 inherit");
+    expect(mobileSideGutterFree("1rem inherit")).toBe("1rem 0 1rem");
+  });
+});

package/src/components/HkAdminShell.test.tsx

@@ -42,7 +42,9 @@ import { HkAdminShell } from "./HkAdminShell";
  * 3. The header slot receives `onOpenDrawer` so a header trigger (the
  *    avatar in drawer action mode) can open the nav drawer.
  * 4. Content padding rides an inner wrapper inside the scroll viewport
- *    (card box-shadows are never clipped at the viewport edges).
+ *    (card box-shadows are never clipped at the viewport edges), and the
+ *    mobile side-gutter drop happens ONLY for a page that declares
+ *    `contentBleedOnMobile` — an ordinary page keeps its phone gutters.
  *
  * (Repo test convention: raw createApp + container queries, no
  * @vue/test-utils dependency.)
@@ -246,15 +248,86 @@ describe("HkAdminShell", () => {
     expect(inner?.style.padding).toBe("2rem");
   });
 
-  it("drops the horizontal half of the content padding below the mobile breakpoint", async () => {
-    // Phone width: side gutters must vanish; vertical clearance survives.
+  it("keeps the content padding on phones unless the page declares a bleed", async () => {
+    // 2026-10-04 regression: the shell used to drop the side gutters on
+    // EVERY page below the breakpoint, so an ordinary roster / overview
+    // page rendered flush against the phone edges. The drop is opt-in.
     // Asserted via longhands: happy-dom's shorthand parser collapses
     // 3-value paddings, so style.padding cannot distinguish them here.
     setWidth(390);
-    const mobileShell = mount(shellNode(
+    const plain = mount(shellNode(
       { navTitle: "Navigation", contentPadding: "2rem" },
       { header: () => null, sidebar: NAV, content: CONTENT },
     ));
+    const plainInner = paddingInner(plain);
+    expect(plainInner?.style.paddingTop).toBe("2rem");
+    expect(plainInner?.style.paddingBottom).toBe("2rem");
+    expect(plainInner?.style.paddingLeft).toBe("2rem");
+    expect(plainInner?.style.paddingRight).toBe("2rem");
+
+    // A multi-value value stays verbatim too — no per-side rewriting of
+    // a page that never asked for the bleed.
+    const plainMulti = mount(shellNode(
+      { navTitle: "Navigation", contentPadding: "1rem 2rem" },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
+    const plainMultiInner = paddingInner(plainMulti);
+    expect(plainMultiInner?.style.paddingTop).toBe("1rem");
+    expect(plainMultiInner?.style.paddingLeft).toBe("2rem");
+    expect(plainMultiInner?.style.paddingRight).toBe("2rem");
+
+    // Resizing within the sub-breakpoint range never changes it either —
+    // asserted across the WHOLE range, not at hand-picked widths. The
+    // regression is "an ordinary page loses its gutters on phones", and
+    // rounds 2 and 3 both escaped guards that sampled a few widths by
+    // moving the leak into a band those widths miss (a mutant confined to
+    // [400, 499] would strip the gutters of a Pixel 412 / iPhone 430
+    // while the suite stayed green).
+    for (const width of [320, 360, 390, 412, 430, 500, 640, 700, 768, 900, 1023]) {
+      setWidth(width);
+      await nextTick();
+      expect(plainInner?.style.paddingLeft, `at ${width}px`).toBe("2rem");
+      expect(plainInner?.style.paddingRight, `at ${width}px`).toBe("2rem");
+      // …VERTICAL included: the regression is not only "the sides moved".
+      expect(plainInner?.style.paddingTop, `at ${width}px`).toBe("2rem");
+      expect(plainInner?.style.paddingBottom, `at ${width}px`).toBe("2rem");
+      expect(plainMultiInner?.style.paddingLeft, `at ${width}px (multi)`).toBe("2rem");
+    }
+
+    // A custom breakpoint on an UNDECLARED page must not move its gutters
+    // either (round 4 mutated the guard to depend on the 1024 default and
+    // every custom-breakpoint mount in this file declared a bleed).
+    const plainNarrow = mount(shellNode(
+      { navTitle: "Navigation", contentPadding: "2rem", mobileBreakpoint: 768 },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
+    setWidth(500);
+    await nextTick();
+    expect(paddingInner(plainNarrow)?.style.paddingLeft).toBe("2rem");
+    expect(paddingInner(plainNarrow)?.style.paddingRight).toBe("2rem");
+
+    // An explicit `false` reads exactly like an absent prop.
+    const declaredOff = mount(shellNode(
+      { navTitle: "Navigation", contentPadding: "1rem 2rem", contentBleedOnMobile: false },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
+    expect(paddingInner(declaredOff)?.style.paddingLeft).toBe("2rem");
+
+    // Above the breakpoint it is verbatim for the declared page too.
+    setWidth(1280);
+    await nextTick();
+    expect(mobileInnerPadding(plain)).toBe("2rem");
+  });
+
+  it("drops the horizontal half of the content padding below the mobile breakpoint when the page declares a bleed", async () => {
+    // A page that declares `contentBleedOnMobile` (a 2D board or the 3D
+    // scene) loses the side gutters on phones; vertical clearance
+    // survives. Asserted via longhands — see the note above.
+    setWidth(390);
+    const mobileShell = mount(shellNode(
+      { navTitle: "Navigation", contentPadding: "2rem", contentBleedOnMobile: true },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
     const inner = paddingInner(mobileShell);
     expect(inner?.style.paddingTop).toBe("2rem");
     expect(inner?.style.paddingBottom).toBe("2rem");
@@ -264,7 +337,7 @@ describe("HkAdminShell", () => {
     // Multi-value shorthand keeps per-side meaning: vertical survives,
     // horizontal is zeroed (never the inverted "1rem 2rem 0").
     const multi = mount(shellNode(
-      { navTitle: "Navigation", contentPadding: "1rem 2rem" },
+      { navTitle: "Navigation", contentPadding: "1rem 2rem", contentBleedOnMobile: true },
       { header: () => null, sidebar: NAV, content: CONTENT },
     ));
     const multiInner = paddingInner(multi);
@@ -273,9 +346,196 @@ describe("HkAdminShell", () => {
     expect(multiInner?.style.paddingLeft).toBe("0px");
     expect(multiInner?.style.paddingRight).toBe("0px");
 
-    // Crossing back to desktop restores the verbatim padding.
+    // Three-value shorthand: the vertical tracks are the FIRST and the
+    // THIRD, so the parser has to keep top and bottom in order. The
+    // 1- and 2-value cases above cannot see a swapped pair — with ≤2
+    // values the bottom track defaults to the top one, which makes the
+    // correct and the transposed string identical (round-1 verification
+    // mutation (e) survived on exactly that hole).
+    const triple = mount(shellNode(
+      { navTitle: "Navigation", contentPadding: "1rem 2rem 3rem", contentBleedOnMobile: true },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
+    const tripleInner = paddingInner(triple);
+    expect(tripleInner?.style.paddingTop).toBe("1rem");
+    expect(tripleInner?.style.paddingBottom).toBe("3rem");
+    expect(tripleInner?.style.paddingLeft).toBe("0px");
+    expect(tripleInner?.style.paddingRight).toBe("0px");
+
+    // Four-value shorthand: right and left are DIFFERENT tracks, and the
+    // rebuilt declaration has no horizontal track at all — both sides
+    // must read zero. A parser that lands a horizontal value in the wrong
+    // slot is invisible to the shorter cases (round-2 verification
+    // mutated "1rem 2rem 3rem 4rem" into "1rem 0 3rem 2rem" and the suite
+    // stayed green).
+    const quad = mount(shellNode(
+      { navTitle: "Navigation", contentPadding: "1rem 2rem 3rem 4rem", contentBleedOnMobile: true },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
+    const quadInner = paddingInner(quad);
+    expect(quadInner?.style.paddingTop).toBe("1rem");
+    expect(quadInner?.style.paddingBottom).toBe("3rem");
+    expect(quadInner?.style.paddingLeft).toBe("0px");
+    expect(quadInner?.style.paddingRight).toBe("0px");
+
+    // A function value is ONE track: whitespace inside `calc(...)` belongs
+    // to the value, not to the shorthand. Splitting on plain whitespace
+    // shreds it into three tracks and rebuilds an invalid declaration,
+    // which a real browser drops WHOLE — taking the vertical clearance
+    // this prop promises to keep with it (rounds 2 and 3 both hit this on
+    // the shell as it shipped). happy-dom stores calc() values, so the
+    // longhands are readable here; it cannot round-trip var()/min(), which
+    // is why calc() is the probe.
+    const fn = mount(shellNode(
+      { navTitle: "Navigation", contentPadding: "calc(1rem + 2px) 1rem", contentBleedOnMobile: true },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
+    const fnInner = paddingInner(fn);
+    expect(fnInner?.style.paddingTop).toBe("calc(1rem + 2px)");
+    expect(fnInner?.style.paddingBottom).toBe("calc(1rem + 2px)");
+    expect(fnInner?.style.paddingLeft).toBe("0px");
+    expect(fnInner?.style.paddingRight).toBe("0px");
+
+    // NESTED functions are one track as well (the depth counter, not a
+    // single-level check): a bare `clamp()` cannot be the probe because
+    // happy-dom rejects it outright, so the function rides in the second
+    // track of a plain length.
+    const nested = mount(shellNode(
+      { navTitle: "Navigation", contentPadding: "5rem clamp(1rem, min(2vw, 3px), 4rem)", contentBleedOnMobile: true },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
+    const nestedInner = paddingInner(nested);
+    expect(nestedInner?.style.paddingTop).toBe("5rem");
+    expect(nestedInner?.style.paddingBottom).toBe("5rem");
+    expect(nestedInner?.style.paddingLeft).toBe("0px");
+    expect(nestedInner?.style.paddingRight).toBe("0px");
+
+    // …and so is a space directly after the opening parenthesis.
+    const spacedFn = mount(shellNode(
+      { navTitle: "Navigation", contentPadding: "calc( 1rem + 2px ) 1rem", contentBleedOnMobile: true },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
+    const spacedFnInner = paddingInner(spacedFn);
+    expect(spacedFnInner?.style.paddingTop).toBe("calc( 1rem + 2px )");
+    expect(spacedFnInner?.style.paddingBottom).toBe("calc( 1rem + 2px )");
+    expect(spacedFnInner?.style.paddingLeft).toBe("0px");
+
+    // A lone CSS-wide keyword cannot be rewritten per side (`inherit 0
+    // inherit` is not a padding — every engine rejects it), so the value
+    // passes through VERBATIM: the page keeps its padding instead of
+    // losing all four sides to a dropped declaration. (The comment case
+    // behaves the same way; it is pinned in HkAdminShell.padding.test.ts
+    // because happy-dom refuses to store a comment-bearing value at all.)
+    for (const keyword of ["inherit", "unset"]) {
+      const wide = mount(shellNode(
+        { navTitle: "Navigation", contentPadding: keyword, contentBleedOnMobile: true },
+        { header: () => null, sidebar: NAV, content: CONTENT },
+      ));
+      expect(paddingInner(wide)?.style.padding, keyword).toBe(keyword);
+    }
+
+    // Tabs and newlines are valid CSS separators, and the whitespace
+    // around a shorthand is not a track of its own ("\t1rem 2rem" must
+    // read exactly like "1rem 2rem", never like a three-track value).
+    for (const padded of ["1rem\t2rem", "1rem\n2rem", " 1rem 2rem ", "\t1rem 2rem"]) {
+      const ws = mount(shellNode(
+        { navTitle: "Navigation", contentPadding: padded, contentBleedOnMobile: true },
+        { header: () => null, sidebar: NAV, content: CONTENT },
+      ));
+      const wsInner = paddingInner(ws);
+      expect(wsInner?.style.paddingTop, JSON.stringify(padded)).toBe("1rem");
+      expect(wsInner?.style.paddingBottom, JSON.stringify(padded)).toBe("1rem");
+      expect(wsInner?.style.paddingLeft, JSON.stringify(padded)).toBe("0px");
+      expect(wsInner?.style.paddingRight, JSON.stringify(padded)).toBe("0px");
+    }
+
+    // Nothing to strip: an empty value passes through untouched, it does
+    // NOT become a zero padding of its own.
+    const blank = mount(shellNode(
+      { navTitle: "Navigation", contentPadding: "", contentBleedOnMobile: true },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
+    expect(paddingInner(blank)?.style.padding).toBe("");
+
+    // The declared page bleeds across the WHOLE sub-breakpoint range, not
+    // just at the hand-picked widths above: round 4 mutated the bleed to
+    // stop inside [400, 499) and nothing in this file sampled a declared
+    // page in that band (412 / 430 px phones included).
+    for (const width of [320, 360, 390, 412, 430, 500, 640, 700, 768, 900, 1023]) {
+      setWidth(width);
+      await nextTick();
+      expect(paddingInner(mobileShell)?.style.paddingLeft, `declared at ${width}px`).toBe("0px");
+      expect(paddingInner(mobileShell)?.style.paddingRight, `declared at ${width}px`).toBe("0px");
+      expect(paddingInner(mobileShell)?.style.paddingTop, `declared at ${width}px`).toBe("2rem");
+    }
+
+    // The shell's own default padding (1.5rem) is what a consumer that
+    // passes nothing actually gets — pinned here because this file
+    // otherwise only ever exercises explicit values.
+    const defaulted = mount(shellNode(
+      { navTitle: "Navigation", contentBleedOnMobile: true },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
+    setWidth(390);
+    await nextTick();
+    expect(paddingInner(defaulted)?.style.paddingTop).toBe("1.5rem");
+    expect(paddingInner(defaulted)?.style.paddingBottom).toBe("1.5rem");
+    expect(paddingInner(defaulted)?.style.paddingLeft).toBe("0px");
+    expect(paddingInner(defaulted)?.style.paddingRight).toBe("0px");
+
+    // The gate follows THIS shell's breakpoint, and the boundary is the
+    // breakpoint itself: 1023 is still mobile (bleed), 1024 is desktop
+    // (verbatim) — the same `>=` the sidebar takes over on.
+    setWidth(1023);
+    await nextTick();
+    expect(paddingInner(mobileShell)?.style.paddingLeft).toBe("0px");
+    setWidth(1024);
+    await nextTick();
+    expect(paddingInner(mobileShell)?.style.paddingLeft).toBe("2rem");
+
+    // …and a custom breakpoint moves it: the padding gate must read the
+    // same `isDesktop` the layout does, not the 1024 default (round 3
+    // mutated it to a hardcoded 1024 and the suite stayed green).
+    const narrow = mount(shellNode(
+      { navTitle: "Navigation", contentPadding: "2rem", contentBleedOnMobile: true, mobileBreakpoint: 768 },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
+    setWidth(767);
+    await nextTick();
+    expect(paddingInner(narrow)?.style.paddingLeft).toBe("0px");
+    setWidth(768);
+    await nextTick();
+    expect(paddingInner(narrow)?.style.paddingLeft).toBe("2rem");
+    setWidth(800);
+    await nextTick();
+    expect(paddingInner(narrow)?.style.paddingLeft).toBe("2rem");
+
+    // …in BOTH directions: a breakpoint raised above the 1024 default must
+    // move the padding gate too. Round 3 mutated the gate to saturate at
+    // 1024 and only a downward custom breakpoint was covered, so the
+    // mirror image survived.
+    const tablet = mount(shellNode(
+      { navTitle: "Navigation", contentPadding: "2rem", contentBleedOnMobile: true, mobileBreakpoint: 1440 },
+      { header: () => null, sidebar: NAV, content: CONTENT },
+    ));
+    setWidth(1200);
+    await nextTick();
+    expect(paddingInner(tablet)?.style.paddingLeft).toBe("0px");
+    setWidth(1440);
+    await nextTick();
+    expect(paddingInner(tablet)?.style.paddingLeft).toBe("2rem");
+
+    // The declaration never reaches desktop: crossing back above the
+    // breakpoint restores the verbatim padding.
     setWidth(1280);
     await nextTick();
     expect(mobileInnerPadding(mobileShell)).toBe("2rem");
+    expect(mobileInnerPadding(multi)).toBe("1rem 2rem");
+    // …per side, too: the restored shorthand must not be a collapsed
+    // approximation of the three tracks it came from.
+    expect(tripleInner?.style.paddingTop).toBe("1rem");
+    expect(tripleInner?.style.paddingBottom).toBe("3rem");
+    expect(tripleInner?.style.paddingLeft).toBe("2rem");
+    expect(tripleInner?.style.paddingRight).toBe("2rem");
   });
 });

package/src/components/HkAdminShell.tsx

@@ -3,6 +3,133 @@ import { HDrawer, HScrollContainer, useBreakpoint } from "@celestia-island/hikar
 import { provideActionBar } from "../composables/useActionBar";
 import { useI18n } from "../i18n/context";
 
+/** CSS-wide keywords. A shorthand rebuilt from one of them is NOT a
+ *  padding (`inherit 0 inherit` is rejected by every engine, measured in
+ *  Chromium), so the declaration would be dropped WHOLE and the page
+ *  would lose the vertical clearance too — worse than not bleeding. */
+const CSS_WIDE_KEYWORDS = new Set(["inherit", "initial", "unset", "revert", "revert-layer"]);
+
+/**
+ * A scanned padding shorthand: the top-level `sides` plus whether the
+ * value ENDED with every function closed and every quote terminated.
+ * `balanced: false` means the scan cannot know where the value ends —
+ * CSS closes an open function at EOF, so the authored declaration can
+ * still be valid while a rewrite of it cannot be.
+ */
+export interface PaddingSidesScan {
+  sides: string[];
+  balanced: boolean;
+}
+
+/**
+ * Scan a CSS padding shorthand into its top-level tracks: split on
+ * TOP-LEVEL whitespace, quote- and function-aware, so whitespace inside
+ * a function belongs to that value — `calc(1rem + 2px)`,
+ * `var(--pad, 1rem)` and a quoted argument are ONE track. A plain
+ * `split(/\s+/)` shreds them (`["calc(1rem", "+", "2px)"]`), and the
+ * rebuilt shorthand is invalid CSS — a browser drops the whole
+ * declaration, taking with it the vertical clearance
+ * `contentBleedOnMobile` promises to keep (rounds 2 and 3 of this change
+ * hit exactly that; rounds 4 and 5 the escape and EOF variants). The
+ * depth counter balances parentheses, so nested functions
+ * (`clamp(1rem, min(2vw, 3px), 4rem)`) survive; a stray `)` never drives
+ * the depth negative. Tabs and newlines are valid CSS separators and
+ * split like spaces, and the whitespace around a shorthand yields no
+ * empty tracks.
+ *
+ * Exported for its own unit test: happy-dom cannot round-trip
+ * `var()`/`clamp()` values or the hostile inputs below, so the
+ * component-level suite cannot observe them.
+ */
+export function scanPaddingSides(value: string): PaddingSidesScan {
+  const sides: string[] = [];
+  let current = "";
+  let depth = 0;
+  let quote = "";
+  for (const ch of value) {
+    if (quote) {
+      current += ch;
+      if (ch === quote) quote = "";
+      continue;
+    }
+    if (ch === "\"" || ch === "'") {
+      quote = ch;
+      current += ch;
+      continue;
+    }
+    if (ch === "(") depth += 1;
+    else if (ch === ")") depth = Math.max(0, depth - 1);
+    if (depth === 0 && /\s/.test(ch)) {
+      if (current) sides.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current) sides.push(current);
+  return { sides, balanced: depth === 0 && quote === "" };
+}
+
+/** The tracks of {@link scanPaddingSides} — for callers that only need
+ *  the split, and for the unit test that pins the splitting rules. */
+export function splitPaddingSides(value: string): string[] {
+  return scanPaddingSides(value).sides;
+}
+
+/**
+ * The side-gutter-free form of a padding shorthand: the vertical tracks
+ * survive, the horizontal ones become zero (`"1rem 2rem"` -> `"1rem 0
+ * 1rem"`). The value is returned VERBATIM — the page keeps its padding
+ * and simply does not bleed — whenever the shorthand cannot be rewritten
+ * safely. That fallback IS the contract: emitting a declaration a browser
+ * drops costs the page ALL FOUR sides, including the vertical clearance
+ * this prop exists to keep.
+ *
+ * Verbatim cases:
+ *
+ * - an empty / whitespace-only value has nothing to strip;
+ * - a LONE CSS-wide keyword cannot be combined per side (`inherit 0
+ *   inherit` is not a padding — every engine rejects it);
+ * - the value contains a CSS comment, whose text would land in the
+ *   rebuilt declaration as a garbage track (`1rem 0 x`, measured in
+ *   Chromium: dropped, all four sides lost);
+ * - the value contains a backslash: this scanner does not decode CSS
+ *   escapes, and an escape can hide a quote, a parenthesis or a whole
+ *   keyword (`\69 nherit` IS `inherit` to an engine) — the literal text
+ *   is not the value, so no rewrite of it is trustworthy (round 5);
+ * - the value ends with a `!important` annotation: the annotation
+ *   belongs to the DECLARATION, so a per-side rewrite would either
+ *   silently lose the priority (`2rem !important`) or rebuild the
+ *   `inherit 0 inherit` every engine rejects (`inherit !important`,
+ *   measured in Chromium, round 5);
+ * - the scan ends inside an open function or an unterminated quote: CSS
+ *   auto-closes a function at EOF, so `"calc(1rem + 2px"` IS a real
+ *   padding (measured: all four sides) while its rewrite is not; an
+ *   unterminated quote is invalid at both ends, and bailing keeps the
+ *   two paths identical (round 5).
+ *
+ * Known residual (documented, not fixable at string level): a `var()`
+ * whose custom property resolves to MORE than one track cannot keep its
+ * vertical half — `padding: var(--multi) 0 var(--multi)` is valid at
+ * parse time and invalid at computed-value time, and all four sides
+ * collapse. No consumer passes a multi-track custom property today.
+ */
+export function mobileSideGutterFree(value: string): string {
+  if (value.includes("/*") || value.includes("\\")) return value;
+  // `!important` is an annotation on the DECLARATION, not a track — it
+  // cannot ride a per-side rewrite: `2rem !important` would silently lose
+  // its priority, and `inherit !important` would rebuild into the
+  // `inherit 0 inherit` every engine drops (measured in Chromium, round
+  // 5). Bail out and let the authored padding stand.
+  if (/!\s*important\s*$/i.test(value)) return value;
+  const { sides, balanced } = scanPaddingSides(value);
+  if (!balanced) return value;
+  if (sides.length === 0) return value;
+  if (sides.length === 1 && CSS_WIDE_KEYWORDS.has(sides[0].toLowerCase())) return value;
+  const [top, , bottom] = sides;
+  return `${top} 0 ${bottom ?? top}`;
+}
+
 export const HkAdminShell = defineComponent({
   name: "HkAdminShell",
   props: {
@@ -21,12 +148,29 @@ export const HkAdminShell = defineComponent({
     drawerPanelClass: { type: String, default: undefined },
     /** Content-area padding (inside the scroll viewport). Padding is
      *  applied to an inner wrapper rather than the scroll container so
-     *  card box-shadows are never clipped at the viewport edges. Below
-     *  the mobile breakpoint the horizontal half is dropped
-     *  automatically (2026-10-03 user direction: on phones the content
-     *  area must span the full width for 2D panels and the 3D scene —
-     *  only the vertical clearance survives). */
+     *  card box-shadows are never clipped at the viewport edges. Applied
+     *  verbatim at every width unless the page opts into
+     *  `contentBleedOnMobile`. */
     contentPadding: { type: String, default: "1.5rem" },
+    /** Whether the content on screen is a CANVAS — a 2D board or the 3D
+     *  scene — that must span the full phone width. OPT-IN, declared by
+     *  the page that renders the canvas (2026-10-04 user direction: the
+     *  side-gutter drop is a PER-PAGE declaration, never a shell-wide
+     *  rule — an ordinary page keeps its side gutters on phones).
+     *
+     *  When true, below `mobileBreakpoint` the horizontal half of
+     *  `contentPadding` is dropped while the vertical clearance
+     *  survives; desktop is never affected and the verbatim padding is
+     *  restored when the viewport crosses back above the breakpoint.
+     *  A `contentPadding` that cannot be rewritten per side (empty, a
+     *  lone CSS-wide keyword, or a value this scanner cannot trust: one
+     *  carrying a CSS comment or a backslash escape, one ending in a
+     *  `!important` annotation, or one whose functions/quotes never
+     *  close) falls back to the verbatim value — see
+     *  `mobileSideGutterFree`; the page then keeps its gutters instead
+     *  of risking a declaration a browser would drop whole.
+     *  Default false: the padding reads the same at every width. */
+    contentBleedOnMobile: { type: Boolean, default: false },
   },
   setup(props, { slots }) {
     const { t } = useI18n();
@@ -34,20 +178,10 @@ export const HkAdminShell = defineComponent({
     const isDesktop = computed(() => viewportWidth.value >= props.mobileBreakpoint);
     const sidebarOpen = ref(false);
 
-    // Content padding with the mobile side-gutter rule applied: desktop
-    // gets the value verbatim; below the breakpoint the horizontal
-    // tracks become zero while the vertical tracks survive. The CSS
-    // padding shorthand is parsed per side so multi-value values keep
-    // their meaning ("1rem 2rem" -> "1rem 0", not the invalid or
-    // inverted "1rem 2rem 0"). An empty value passes through untouched.
-    const mobileSideGutterFree = (value: string): string => {
-      const sides = value.trim().split(/\s+/).filter(Boolean);
-      if (sides.length === 0) return value;
-      const [top, , bottom] = sides;
-      return `${top} 0 ${bottom ?? top}`;
-    };
     const contentStyle = computed(() => ({
-      padding: isDesktop.value ? props.contentPadding : mobileSideGutterFree(props.contentPadding),
+      padding: isDesktop.value || !props.contentBleedOnMobile
+        ? props.contentPadding
+        : mobileSideGutterFree(props.contentPadding),
     }));
 
     const actionBar = provideActionBar();

package/src/components/HkFloatingLayer.test.tsx

@@ -143,3 +143,24 @@ describe("HkFloatingLayer", () => {
     expect(m.root()!.querySelector(".probe")).not.toBeNull();
   });
 });
+
+describe("HkFloatingLayer yieldToWindows", () => {
+  it("hides while any window is open and returns when the last window closes", async () => {
+    const manager = usePopupManager();
+    const win = manager.register("modal", true, "Blocking");
+    const m = mountLayer({ yieldToWindows: true });
+    expect(m.root()).toBeNull();
+    manager.unregister(win.id);
+    await nextTick();
+    expect(m.root()).not.toBeNull();
+  });
+
+  it("default layers keep floating over windows (opt-in only)", async () => {
+    const manager = usePopupManager();
+    const win = manager.register("modal", true, "Blocking");
+    const m = mountLayer({});
+    expect(m.root()).not.toBeNull();
+    manager.unregister(win.id);
+    await nextTick();
+  });
+});

package/src/components/HkFloatingLayer.tsx

@@ -7,7 +7,7 @@ import {
   type PropType,
 } from "vue";
 
-import { usePopupManager } from "../runtime/usePopupManager";
+import { hasLiveWindow, usePopupManager } from "../runtime/usePopupManager";
 import "./HkFloatingLayer.scss";
 
 type FloatCorner = "bottom-right" | "bottom-left" | "top-right" | "top-left";
@@ -63,6 +63,11 @@ export default defineComponent({
     offsetY: { type: String, default: undefined },
     /** Accessible group name for the chrome (e.g. "Date dial"). */
     ariaLabel: { type: String, default: "" },
+    /** Stack priority (user direction 2026-10-04): when true the layer
+     *  yields the screen while ANY window is open - page-level dial
+     *  chrome disappears under the top window instead of floating over
+     *  it, and returns when the last window closes. */
+    yieldToWindows: { type: Boolean, default: false },
   },
   setup(props, { slots }) {
     const { register, unregister } = usePopupManager();
@@ -71,7 +76,10 @@ export default defineComponent({
     // Annotation-band chrome, not a breadcrumb level: non-blocking,
     // untitled, no scroll lock, no outside-dismiss channel. Registered
     // exactly while shown (immediate, so the first paint already
-    // carries the band z); a hidden layer holds no slot.
+    // carries the band z); a hidden layer holds no slot. (A
+    // yielded layer keeps its slot held while hidden — constant chrome
+    // flipping a registered slot on every window open/close would churn
+    // the band for no visual effect.)
     watch(
       () => props.open,
       (show) => {
@@ -89,7 +97,7 @@ export default defineComponent({
     });
 
     return () => {
-      if (!props.open) return null;
+      if (!props.open || (props.yieldToWindows && hasLiveWindow.value)) return null;
       return (
         <Teleport to="body">
           <div

package/src/components/HkModal.test.tsx

@@ -415,3 +415,64 @@ describe("HkModal autoFollow", () => {
     expect(s.jump()).toBeNull();
   });
 });
+
+// Stack-priority dial slot (user direction 2026-10-04): the window owns
+// its dial while it is the topmost window, yields while another window
+// stacks above, and the page dial returns on close. The surface machine
+// runs on macrotask timers, so every stack transition below is staged
+// through vi.waitFor, never bare ticks.
+describe("HkModal dial slot (stack priority)", () => {
+  async function mountDialModal(withDial: boolean) {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const open = ref(true);
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkModal, {
+            modelValue: open.value,
+            title: "Window",
+            "onUpdate:modelValue": (v: boolean) => { open.value = v; },
+          }, withDial
+            ? {
+                default: () => h("div", "body content"),
+                dial: () => h("button", { class: "dial-probe" }, "dial"),
+              }
+            : { default: () => h("div", "body content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    return { open };
+  }
+  const dialLayer = () => document.body.querySelector(".hk-floating-layer");
+
+  it("mounts its dial slot on the top layer while the window is topmost", async () => {
+    await mountDialModal(true);
+    await vi.waitFor(() => {
+      const layer = dialLayer();
+      expect(layer).not.toBeNull();
+      expect(layer!.querySelector(".dial-probe")).not.toBeNull();
+    });
+  });
+
+  it("yields while another window stacks above and returns when it closes", async () => {
+    const m = await mountDialModal(true);
+    await vi.waitFor(() => expect(dialLayer()).not.toBeNull());
+    const { register, unregister } = usePopupManager();
+    const above = register("modal", true, "Above");
+    await vi.waitFor(() => expect(dialLayer()).toBeNull());
+    unregister(above.id);
+    await vi.waitFor(() => expect(dialLayer()).not.toBeNull());
+    m.open.value = false;
+    await vi.waitFor(() => expect(dialLayer()).toBeNull());
+  });
+
+  it("renders no dial layer when the window declares none", async () => {
+    await mountDialModal(false);
+    await vi.waitFor(() => expect(document.body.querySelector(".hk-modal-root")).not.toBeNull());
+    expect(dialLayer()).toBeNull();
+  });
+});

package/src/components/HkModal.tsx

@@ -2,9 +2,10 @@ import { computed, defineComponent, nextTick, onBeforeUnmount, onMounted, ref, s
 
 import { useI18n } from "../i18n/context";
 import "./HkModal.scss";
+import HkFloatingLayer from "./HkFloatingLayer";
 import { focusFirst, trapFocus } from "../utils/dom";
 import { useOverlay } from "../runtime/useOverlay";
-import { usePopupManager } from "../runtime/usePopupManager";
+import { topWindowZ, usePopupManager } from "../runtime/usePopupManager";
 import { createBackGuard } from "../runtime/backStack";
 import { scheduleFrame, type AnimationHandle } from "../runtime/animationBus";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
@@ -936,12 +937,24 @@ export default defineComponent({
 
     const contentHold = useSurfaceContentHold(machine.phase);
 
+    // Stack-priority dial chrome (user direction 2026-10-04): the
+    // window's own dial replaces the page's while this window is the
+    // topmost one, yields while another window stacks above it (dial
+    // or not), and the page dial returns when the last window closes.
+    const dialVisible = computed(() =>
+      Boolean(
+        machine.mounted.value &&
+          handle.value &&
+          (topWindowZ.value === null || topWindowZ.value <= handle.value.zIndex),
+      ),
+    );
+
     return () => {
       if (!machine.mounted.value) return null;
 
       const headerShown = props.title || props.closable || slots.header || slots.headerLead;
 
-      return (
+      const windowSurface = (
         <Teleport to="body">
           <div
             class="hk-modal-root"
@@ -1066,6 +1079,19 @@ export default defineComponent({
           </div>
         </Teleport>
       );
+
+      // The dial rides the top layer beside its window (stack
+      // priority): mounted with the window, yielded above, retired
+      // when the window closes so the page dial can return.
+      if (!slots.dial) return windowSurface;
+      return (
+        <>
+          {windowSurface}
+          <HkFloatingLayer open={dialVisible.value} corner="bottom-right">
+            {slots.dial()}
+          </HkFloatingLayer>
+        </>
+      );
     };
 
     function renderWindowedBody() {

package/src/index.ts

@@ -348,6 +348,9 @@ export {
   setReducedMotion,
   notifyScrollStart,
   useOverlay,
+  hasLiveWindow,
+  isWindowEntry,
+  topWindowZ,
   usePopupManager,
   POPUP_Z_BANDS,
   POPUP_Z_STEP,

package/src/runtime/index.ts

@@ -56,7 +56,16 @@ export {
 } from "./backStack";
 export { useMediaQuery, releaseMediaQuery } from "./useMediaQuery";
 export { useOverlay, closeAll, isOverlayOpen, type OverlayHandle, type UseOverlayOptions } from "./useOverlay";
-export { usePopupManager, POPUP_Z_BANDS, POPUP_Z_STEP, type PopupHandle, type PopupKind } from "./usePopupManager";
+export {
+  hasLiveWindow,
+  isWindowEntry,
+  topWindowZ,
+  usePopupManager,
+  POPUP_Z_BANDS,
+  POPUP_Z_STEP,
+  type PopupHandle,
+  type PopupKind,
+} from "./usePopupManager";
 export { useToast, TOAST_DURATION, type ToastItem, type ToastMessage, type ToastType } from "./useToast";
 export { useConfirm } from "./useConfirm";
 export { useBlockingToast, showBlockingToast, resolveBlockingToast, clearBlockingToasts, type BlockingToastItem, type BlockingToastOptions, type BlockingToastVariant } from "./useBlockingToast";

package/src/runtime/usePopupManager.test.ts

@@ -1,7 +1,13 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { watch } from "vue";
 
-import { POPUP_Z_BANDS, POPUP_Z_STEP, usePopupManager } from "./usePopupManager";
+import {
+  hasLiveWindow,
+  POPUP_Z_BANDS,
+  POPUP_Z_STEP,
+  topWindowZ,
+  usePopupManager,
+} from "./usePopupManager";
 
 const managers: ReturnType<typeof usePopupManager>[] = [];
 
@@ -338,3 +344,43 @@ describe("usePopupManager closeAbove", () => {
     }
   });
 });
+
+describe("usePopupManager window-stack signals", () => {
+  it("derived signals track the live window band (page chrome's yield rule)", () => {
+    const m = usePopupManager();
+    const win = m.register("modal", true, "Window");
+    expect(hasLiveWindow.value).toBe(true);
+    expect(topWindowZ.value).toBe(win.zIndex);
+    // Tooltip-band entries are not windows: they must not flip the signals.
+    const tip = m.register("tooltip", false);
+    expect(hasLiveWindow.value).toBe(true);
+    expect(topWindowZ.value).toBe(win.zIndex);
+    m.unregister(tip.id);
+    m.unregister(win.id);
+    expect(hasLiveWindow.value).toBe(false);
+    expect(topWindowZ.value).toBeNull();
+  });
+
+  it("only window-band entries count: anchored dropdowns no, docked sheets yes", () => {
+    const m = usePopupManager();
+    const dd = m.register("dropdown", false);
+    expect(hasLiveWindow.value).toBe(false);
+    m.unregister(dd.id);
+    const sheet = m.register("dropdown", true, "Sheet", true);
+    expect(hasLiveWindow.value).toBe(true);
+    expect(topWindowZ.value).toBe(sheet.zIndex);
+    m.unregister(sheet.id);
+    expect(hasLiveWindow.value).toBe(false);
+  });
+
+  it("topWindowZ follows the topmost of stacked windows", () => {
+    const m = usePopupManager();
+    const low = m.register("modal", true, "Low");
+    const high = m.register("modal", true, "High");
+    expect(topWindowZ.value).toBe(high.zIndex);
+    expect(topWindowZ.value).toBeGreaterThan(low.zIndex);
+    m.unregister(high.id);
+    expect(topWindowZ.value).toBe(low.zIndex);
+    m.unregister(low.id);
+  });
+});

package/src/runtime/usePopupManager.ts

@@ -1,4 +1,4 @@
-import { readonly, ref } from "vue";
+import { computed, readonly, ref } from "vue";
 
 import { reportHkRuntime, type HkRuntimeHandle } from "./registry";
 
@@ -70,6 +70,14 @@ function effectiveBand(kind: PopupKind, blocking: boolean): number {
   return POPUP_Z_BANDS[kind];
 }
 
+/** True when a live entry is a WINDOW (blocks the page like one):
+ *  modal/drawer by kind, or a dropdown-kind surface docked as a
+ *  blocking mobile sheet. Page chrome (dials, floating pads) uses
+ *  this to yield the screen to whatever window is on top. */
+export function isWindowEntry(kind: PopupKind, blocking: boolean): boolean {
+  return effectiveBand(kind, blocking) === POPUP_Z_BANDS.modal;
+}
+
 /** In-band stacking step. Even numbers leave the odd slot free for the
  * +1 content/panel layer each overlay puts above its own root. */
 export const POPUP_Z_STEP = 2;
@@ -132,6 +140,27 @@ function uid(): string {
 }
 
 const registry = ref<Map<string, PopupEntry>>(new Map());
+
+// Derived window-stack signals (reactive over the live registry):
+// whether ANY window is open, and the topmost window's z slot. Stack
+// priority for dial chrome rides these — a window's own dial replaces
+// the page's while it is topmost; close the window and the page's
+// dial returns.
+export const hasLiveWindow = computed<boolean>(() => {
+  for (const entry of registry.value.values()) {
+    if (isWindowEntry(entry.kind, entry.blocking)) return true;
+  }
+  return false;
+});
+
+export const topWindowZ = computed<number | null>(() => {
+  let top: number | null = null;
+  for (const entry of registry.value.values()) {
+    if (!isWindowEntry(entry.kind, entry.blocking)) continue;
+    if (top === null || entry.zIndex > top) top = entry.zIndex;
+  }
+  return top;
+});
 let scrollLockCount = 0;
 
 // Runtime-registry reporting (the "context of contexts"). Lazy: the