@celestia-island/hikari 0.55.110 → 0.55.112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.110",
+  "version": "0.55.112",
   "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/HkFab.test.tsx

@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vitest } from "vitest";
 import { createApp, defineComponent, h, nextTick, ref } from "vue";
 
 import HkFab from "./HkFab";
+import { POPUP_Z_BANDS } from "../runtime/usePopupManager";
 
 const mounts: ReturnType<typeof createApp>[] = [];
 const containers: HTMLElement[] = [];
@@ -41,8 +42,14 @@ function mountFab(props: Record<string, unknown> = {}): Harness {
   mounts.push(app);
   app.mount(container);
 
-  const root = container.querySelector<HTMLElement>(".hk-fab");
-  const button = container.querySelector<HTMLButtonElement>(".hk-fab-button");
+  // A layer="top" fab teleports into the floating layer on <body>;
+  // fall back to the document scope so both modes resolve.
+  const root =
+    container.querySelector<HTMLElement>(".hk-fab") ??
+    document.body.querySelector<HTMLElement>(".hk-fab");
+  const button =
+    container.querySelector<HTMLButtonElement>(".hk-fab-button") ??
+    document.body.querySelector<HTMLButtonElement>(".hk-fab-button");
   if (!root || !button) throw new Error("HkFab did not render its shell");
   harness.root = root;
   harness.button = button;
@@ -215,3 +222,28 @@ describe("HkFab speed dial", () => {
     expect(toggles).toEqual([true, false, true, false]);
   });
 });
+
+describe("HkFab layer", () => {
+  it("host (default) keeps the fab anchored in the host tree", () => {
+    const m = mountFab({ ariaLabel: "Host", positioning: "fixed" });
+    expect(document.body.querySelector(".hk-floating-layer")).toBeNull();
+    expect(m.root.getAttribute("data-positioning")).toBe("fixed");
+  });
+
+  it("top wraps the fab in an HkFloatingLayer above the window band", () => {
+    const m = mountFab({ ariaLabel: "Float", layer: "top", corner: "bottom-right" });
+    const layer = document.body.querySelector<HTMLElement>(".hk-floating-layer");
+    expect(layer).not.toBeNull();
+    expect(layer!.contains(m.root)).toBe(true);
+    // Geometry is owned by the layer alone once floated.
+    expect(m.root.getAttribute("data-positioning")).toBeNull();
+    expect(m.root.getAttribute("data-corner")).toBeNull();
+    // Offset vars hand off to the layer as well — the fab keeps none.
+    expect(m.root.style.getPropertyValue("--hk-fab-offset-x")).toBe("");
+    expect(m.root.style.getPropertyValue("--hk-fab-offset-y")).toBe("");
+    expect(layer!.getAttribute("data-corner")).toBe("bottom-right");
+    const z = Number(layer!.style.getPropertyValue("--hk-float-z"));
+    expect(z).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
+    expect(z).toBeLessThan(POPUP_Z_BANDS.toast);
+  });
+});

package/src/components/HkFab.tsx

@@ -6,6 +6,7 @@ import {
 } from "vue";
 
 import { iconByName } from "../composables/iconRegistry";
+import HkFloatingLayer from "./HkFloatingLayer";
 import "./HkFab.scss";
 
 /** One entry of the HkFab speed dial. */
@@ -21,6 +22,7 @@ type FabCorner = "bottom-right" | "bottom-left" | "top-right" | "top-left";
 type FabSize = "sm" | "md" | "lg";
 type FabVariant = "primary" | "glass";
 type FabExpandDirection = "up" | "down" | "left" | "right";
+type FabLayer = "host" | "top";
 
 /**
  * Material-design-style floating action button with an optional
@@ -46,6 +48,13 @@ export default defineComponent({
     disabled: { type: Boolean, default: false },
     actions: { type: Array as PropType<HFabAction[]>, default: undefined },
     expandDirection: { type: String as PropType<FabExpandDirection>, default: "up" },
+    /** "top" floats the fab above every window (HkFloatingLayer — the
+     *  popup manager's tooltip band, teleported to <body>): dials stay
+     *  reachable no matter which modal/sheet opens over them. The layer
+     *  owns the geometry when floated — `positioning` is ignored, the
+     *  corner/offset props hand off to it. "host" keeps the classic
+     *  in-tree anchoring (the historical default, byte-identical). */
+    layer: { type: String as PropType<FabLayer>, default: "host" },
   },
   emits: {
     click: (_e: MouseEvent) => true,
@@ -116,6 +125,8 @@ export default defineComponent({
     }
 
     return () => {
+      const floated = props.layer === "top";
+
       // Icon precedence: slot > registry > inline chevron-down fallback.
       // `as any` matches HkIcon — the registry returns a loose Component.
       const RegistryIcon = props.icon ? (iconByName(props.icon) as any) : null;
@@ -144,19 +155,19 @@ export default defineComponent({
         </span>
       );
 
-      return (
+      const fab = (
         <div
           ref={rootRef}
           class="hk-fab"
-          data-positioning={props.positioning}
-          data-corner={props.corner}
+          data-positioning={floated ? undefined : props.positioning}
+          data-corner={floated ? undefined : props.corner}
           data-size={props.size}
           data-variant={props.variant}
           data-expand={props.expandDirection}
           data-expanded={isOpen.value ? "true" : undefined}
           style={{
-            "--hk-fab-offset-x": props.offsetX,
-            "--hk-fab-offset-y": props.offsetY,
+            "--hk-fab-offset-x": floated ? undefined : props.offsetX,
+            "--hk-fab-offset-y": floated ? undefined : props.offsetY,
           }}
         >
           {(props.actions?.length ?? 0) > 0 && (
@@ -196,6 +207,23 @@ export default defineComponent({
           </button>
         </div>
       );
+
+      // Floated: the HkFloatingLayer owns viewport anchoring (corner +
+      // safe-area + tooltip-band z); the fab itself renders bare inside
+      // it (data-positioning/corner stripped above so the geometry is
+      // owned by exactly one layer).
+      if (floated) {
+        return (
+          <HkFloatingLayer
+            corner={props.corner}
+            offsetX={props.offsetX}
+            offsetY={props.offsetY}
+          >
+            {fab}
+          </HkFloatingLayer>
+        );
+      }
+      return fab;
     };
   },
 });

package/src/components/HkFloatingLayer.scss

@@ -0,0 +1,58 @@
+// HkFloatingLayer.scss — top-layer floating chrome.
+//
+// Anchoring mirrors HkFab's safe-area-aware corner insets, extended per
+// instance by --hk-float-offset-*. The z rides the popup manager's
+// tooltip band via --hk-float-z (inline from the component once the
+// registration resolves); the fallback must stay in sync with
+// POPUP_Z_BANDS.tooltip in runtime/usePopupManager.ts.
+.hk-floating-layer {
+  position: fixed;
+  z-index: var(--hk-float-z, 3000);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-8, 0.5rem);
+  pointer-events: none;
+
+  --hk-float-inset-x: max(var(--space-14, 0.875rem), env(safe-area-inset-left, 0px));
+  --hk-float-inset-y: max(var(--space-14, 0.875rem), env(safe-area-inset-bottom, 0px));
+
+  &[data-corner$="-right"] {
+    --hk-float-inset-x: max(var(--space-14, 0.875rem), env(safe-area-inset-right, 0px));
+    right: calc(var(--hk-float-inset-x) + var(--hk-float-offset-x, 0px));
+  }
+
+  &[data-corner$="-left"] {
+    --hk-float-inset-x: max(var(--space-14, 0.875rem), env(safe-area-inset-left, 0px));
+    left: calc(var(--hk-float-inset-x) + var(--hk-float-offset-x, 0px));
+  }
+
+  &[data-corner^="top"] {
+    --hk-float-inset-y: max(var(--space-14, 0.875rem), env(safe-area-inset-top, 0px));
+    top: calc(var(--hk-float-inset-y) + var(--hk-float-offset-y, 0px));
+  }
+
+  &[data-corner^="bottom"] {
+    --hk-float-inset-y: max(var(--space-14, 0.875rem), env(safe-area-inset-bottom, 0px));
+    bottom: calc(var(--hk-float-inset-y) + var(--hk-float-offset-y, 0px));
+  }
+
+  // The layer never eats gestures; the widgets inside do. NOTE: for a
+  // floated HkFab this rule must LOSE to HkFab's own
+  // `.hk-fab { pointer-events: none }` (equal specificity — later sheet
+  // wins — and HkFab.tsx imports this component before its own sheet),
+  // so the fab root stays transparent while its button re-enables.
+  // Do not strengthen this selector or reorder those imports: the
+  // layer's gap boxes would start eating clicks.
+  > * {
+    pointer-events: auto;
+  }
+
+  // A floated HkFab (layer="top") hands viewport anchoring to this
+  // layer entirely: drop its own positioning so its corner lands in
+  // the layer's flow instead of double-resolving the insets.
+  > .hk-fab {
+    position: static;
+    inset: auto;
+    z-index: auto;
+  }
+}

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

@@ -0,0 +1,58 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compile } from "sass";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Compiled-stylesheet contract for HkFloatingLayer. The layer IS its
+ * CSS (fixed positioning, gesture transparency, the > .hk-fab
+ * positioning hand-off), none of which the runtime suite can see —
+ * vitest stubs CSS — so the sheet is compiled and asserted here.
+ */
+const componentDir = resolve(dirname(fileURLToPath(import.meta.url)));
+
+describe("HkFloatingLayer stylesheet contract", () => {
+  const tsx = readFileSync(resolve(componentDir, "HkFloatingLayer.tsx"), "utf8");
+  const css = compile(resolve(componentDir, "HkFloatingLayer.scss"), {
+    style: "expanded",
+  }).css;
+
+  it("compiles the fixed, gesture-transparent top-layer shell", () => {
+    expect(css).toContain(".hk-floating-layer {");
+    expect(css).toContain("position: fixed;");
+    expect(css).toContain("z-index: var(--hk-float-z, 3000);");
+    // The layer never eats gestures; the widgets inside do.
+    expect(css).toContain("pointer-events: none;");
+    expect(css).toContain(".hk-floating-layer > * {");
+    expect(css).toContain("pointer-events: auto;");
+  });
+
+  it("anchors all four corners with safe-area-aware insets", () => {
+    expect(css).toContain('[data-corner$=-right]');
+    expect(css).toContain('[data-corner$=-left]');
+    expect(css).toContain('[data-corner^=top]');
+    expect(css).toContain('[data-corner^=bottom]');
+    for (const side of ["right: calc", "left: calc", "top: calc", "bottom: calc"]) {
+      expect(css).toContain(side);
+    }
+    expect(css).toContain("env(safe-area-inset-left, 0px)");
+    expect(css).toContain("env(safe-area-inset-right, 0px)");
+    expect(css).toContain("env(safe-area-inset-top, 0px)");
+    expect(css).toContain("env(safe-area-inset-bottom, 0px)");
+  });
+
+  it("takes over a floated HkFab's positioning entirely", () => {
+    expect(css).toContain(".hk-floating-layer > .hk-fab {");
+    expect(css).toContain("position: static;");
+    expect(css).toContain("inset: auto;");
+    expect(css).toContain("z-index: auto;");
+  });
+
+  it("has no dead selectors: every rule the sheet emits is rendered", () => {
+    // The TSX must reference every state the sheet styles.
+    expect(tsx).toContain('class="hk-floating-layer"');
+    expect(tsx).toContain("data-corner={props.corner}");
+  });
+});

package/src/components/HkFloatingLayer.test.tsx

@@ -0,0 +1,145 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkFloatingLayer from "./HkFloatingLayer";
+import { POPUP_Z_BANDS, usePopupManager } from "../runtime/usePopupManager";
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+/** Mount an HkFloatingLayer through a wrapper app (mirrors the
+ *  HkFab.test.tsx harness). The layer teleports its node to <body>,
+ *  so queries go through document.body, not the host container. */
+function mountLayer(props: Record<string, unknown> = {}, slot?: () => unknown) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const Wrapper = defineComponent({
+    setup() {
+      return () => h(HkFloatingLayer, props, slot ? { default: slot } : undefined);
+    },
+  });
+  const app = createApp(Wrapper);
+  mounts.push(app);
+  app.mount(container);
+
+  return {
+    app,
+    root: () => document.body.querySelector<HTMLElement>(".hk-floating-layer"),
+  };
+}
+
+afterEach(() => {
+  for (const app of mounts.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+  document.body.innerHTML = "";
+});
+
+describe("HkFloatingLayer", () => {
+  it("teleports the corner layer to body with a tooltip-band z slot", () => {
+    const m = mountLayer({ ariaLabel: "Date dial" });
+    const root = m.root();
+    expect(root).not.toBeNull();
+    // Teleported: outside the wrapper's host subtree.
+    expect(containers[0].contains(root!)).toBe(false);
+    expect(root!.getAttribute("data-corner")).toBe("bottom-right");
+    expect(root!.getAttribute("role")).toBe("group");
+    expect(root!.getAttribute("aria-label")).toBe("Date dial");
+    // Inline z from the popup manager registration — inside the
+    // tooltip band, strictly below the toast band.
+    const z = Number(root!.style.getPropertyValue("--hk-float-z"));
+    expect(z).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
+    expect(z).toBeLessThan(POPUP_Z_BANDS.toast);
+  });
+
+  it("open=false renders nothing at all", () => {
+    const m = mountLayer({ open: false });
+    expect(m.root()).toBeNull();
+  });
+
+  it("registers exactly one tooltip entry and releases it on unmount", () => {
+    const manager = usePopupManager();
+    const tooltipCount = () => {
+      let n = 0;
+      for (const entry of manager.registry.value.values()) {
+        if (entry.kind === "tooltip") n++;
+      }
+      return n;
+    };
+    const before = tooltipCount();
+    // Non-blocking, untitled chrome must stay silent (a future
+    // warnUntitled change folding tooltip into the naming rule would
+    // dev-warn on every mount — that regression goes red here).
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const m = mountLayer();
+    expect(tooltipCount()).toBe(before + 1);
+    m.app.unmount();
+    mounts.splice(mounts.indexOf(m.app), 1);
+    expect(tooltipCount()).toBe(before);
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("hide releases the slot; re-show re-registers with a fresh band z", async () => {
+    const manager = usePopupManager();
+    const tooltipCount = () => {
+      let n = 0;
+      for (const entry of manager.registry.value.values()) {
+        if (entry.kind === "tooltip") n++;
+      }
+      return n;
+    };
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+
+    const visible = ref(true);
+    const Wrapper = defineComponent({
+      setup() {
+        return () => h(HkFloatingLayer, { open: visible.value });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+
+    const layer = () => document.body.querySelector<HTMLElement>(".hk-floating-layer");
+    const before = tooltipCount();
+    expect(before).toBeGreaterThanOrEqual(1);
+    const z1 = Number(layer()!.style.getPropertyValue("--hk-float-z"));
+    expect(z1).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
+
+    // Hide: the node leaves AND the band slot is released — the
+    // count test above cannot catch this branch on its own (unmount
+    // cleanup would mask it).
+    visible.value = false;
+    await nextTick();
+    expect(tooltipCount()).toBe(before - 1);
+    expect(layer()).toBeNull();
+
+    // Re-show: registered again, first paint already carries the z.
+    visible.value = true;
+    await nextTick();
+    expect(tooltipCount()).toBe(before);
+    const z2 = Number(layer()!.style.getPropertyValue("--hk-float-z"));
+    expect(z2).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
+
+    app.unmount();
+    mounts.splice(mounts.indexOf(app), 1);
+    expect(tooltipCount()).toBe(before - 1);
+  });
+
+  it("honours the corner and offset props", () => {
+    const m = mountLayer({ corner: "top-left", offsetX: "1rem", offsetY: "2rem" });
+    const root = m.root()!;
+    expect(root.getAttribute("data-corner")).toBe("top-left");
+    expect(root.style.getPropertyValue("--hk-float-offset-x")).toBe("1rem");
+    expect(root.style.getPropertyValue("--hk-float-offset-y")).toBe("2rem");
+  });
+
+  it("keeps slot content mounted inside the layer", () => {
+    const m = mountLayer({}, () => h("button", { class: "probe" }, "go"));
+    expect(m.root()!.querySelector(".probe")).not.toBeNull();
+  });
+});

package/src/components/HkFloatingLayer.tsx

@@ -0,0 +1,112 @@
+import {
+  defineComponent,
+  onBeforeUnmount,
+  ref,
+  Teleport,
+  watch,
+  type PropType,
+} from "vue";
+
+import { usePopupManager } from "../runtime/usePopupManager";
+import "./HkFloatingLayer.scss";
+
+type FloatCorner = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+
+/**
+ * HkFloatingLayer — viewport-fixed chrome that floats at the TOP layer.
+ *
+ * The dial/FAB problem this solves: always-reachable chrome anchored to
+ * a page (or a window) dies the moment a real window opens over it —
+ * either it is buried under the modal overlay (page pads), or it gets
+ * re-rendered as an in-window copy that no longer shares the page's
+ * geometry (the per-modal dial copies this layer replaces). Floating at
+ * the popup manager's tooltip band makes the chrome independent of the
+ * window stack, exactly like a tooltip: above every modal/drawer
+ * overlay, below toasts, present on its own merits.
+ *
+ * Mechanics:
+ *   - Teleported to <body>, so no transformed ancestor (morph tabs,
+ *     modal content frames) can re-anchor or clip a `position: fixed`
+ *     child, and the layer resolves against the viewport full stop.
+ *   - Registered with the popup manager (kind "tooltip", non-blocking,
+ *     no scroll lock, no breadcrumb title): the z slot derives from the
+ *     live registry instead of a magic constant, and the layer shows up
+ *     in `readHkRuntime("popupManager")` like every other surface.
+ *   - The layer itself is gesture-transparent (pointer-events: none);
+ *     the widgets inside catch their own pointers.
+ *   - Corner insets mirror HkFab's safe-area-aware math, extended per
+ *     instance by the offset props.
+ *
+ *   - Within the tooltip band, stacking is open-order (the manager's
+ *     rule): a tooltip that registered later paints above this chrome
+ *     near the corner, and a layer mounted after a live tooltip paints
+ *     above it — transient vs persistent chrome trades locally. Do not
+ *     "fix" this with a magic z. Two layers at one corner overlap;
+ *     pass offsets to stack them deliberately.
+ *   - While a modal is open, the modal's focus trap keeps this chrome
+ *     pointer-reachable but NOT keyboard-reachable — the standing
+ *     tradeoff for floating chrome; a focus relay is out of scope.
+ *
+ * Consumers: the shell's quick-action pad, a modal's detached date dial
+ * (via `HkFab layer="top"` or direct use) — anything that must survive
+ * the next window opening on top of it.
+ */
+export default defineComponent({
+  name: "HkFloatingLayer",
+  props: {
+    /** False unmounts the teleported layer and releases its band slot
+     *  (true = always shown). House `open` convention, like every other
+     *  hikari surface. */
+    open: { type: Boolean, default: true },
+    corner: { type: String as PropType<FloatCorner>, default: "bottom-right" },
+    offsetX: { type: String, default: undefined },
+    offsetY: { type: String, default: undefined },
+    /** Accessible group name for the chrome (e.g. "Date dial"). */
+    ariaLabel: { type: String, default: "" },
+  },
+  setup(props, { slots }) {
+    const { register, unregister } = usePopupManager();
+    const handle = ref<{ id: string; zIndex: number } | null>(null);
+
+    // 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.
+    watch(
+      () => props.open,
+      (show) => {
+        if (show && !handle.value) handle.value = register("tooltip", false);
+        else if (!show && handle.value) {
+          unregister(handle.value.id);
+          handle.value = null;
+        }
+      },
+      { immediate: true },
+    );
+    onBeforeUnmount(() => {
+      if (handle.value) unregister(handle.value.id);
+      handle.value = null;
+    });
+
+    return () => {
+      if (!props.open) return null;
+      return (
+        <Teleport to="body">
+          <div
+            class="hk-floating-layer"
+            data-corner={props.corner}
+            role={props.ariaLabel ? "group" : undefined}
+            aria-label={props.ariaLabel || undefined}
+            style={{
+              "--hk-float-z": handle.value ? String(handle.value.zIndex) : undefined,
+              "--hk-float-offset-x": props.offsetX,
+              "--hk-float-offset-y": props.offsetY,
+            }}
+          >
+            {slots.default?.()}
+          </div>
+        </Teleport>
+      );
+    };
+  },
+});

package/src/index.ts

@@ -689,6 +689,7 @@ export { default as HkDrawer } from "./components/HkDrawer";
 export { default as HkEmptyState } from "./components/HkEmptyState";
 export { default as HkExpansionPanel } from "./components/HkExpansionPanel";
 export { default as HkFab } from "./components/HkFab";
+export { default as HkFloatingLayer } from "./components/HkFloatingLayer";
 export { default as HkIcon } from "./components/HkIcon";
 export { default as HkIconButton } from "./components/HkIconButton";
 export { default as HkIconButtonGroup } from "./components/HkIconButtonGroup";