@celestia-island/hikari 0.55.130 → 0.55.131

package/package.json

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

package/src/components/HkContextMenuProvider.quadrant.test.ts

@@ -0,0 +1,52 @@
+// Unit tests for the context-menu quadrant pick: the pointer's nearest
+// halves split the POPUP viewport (the window minus the app-chrome band
+// the host configured), so a menu opened over a reserved strip grows
+// into the usable space.
+//
+// AI disclosure: drafted by GLM via the ZCode agent, directed and
+// reviewed by langyo — SySL-1.0 §2.3.
+import { afterEach, describe, expect, it } from "vitest";
+
+import { configurePopupInsets } from "../runtime/popupBounds";
+import { quadrantPlacement } from "./HkContextMenuProvider";
+
+const PREV_INNER = { width: window.innerWidth, height: window.innerHeight };
+
+afterEach(() => {
+  configurePopupInsets(null);
+  window.innerWidth = PREV_INNER.width;
+  window.innerHeight = PREV_INNER.height;
+});
+
+describe("quadrantPlacement", () => {
+  it("splits the raw window in half when no band is configured", () => {
+    window.innerWidth = 800;
+    window.innerHeight = 600;
+    expect(quadrantPlacement(100, 100)).toBe("bottom-start");
+    expect(quadrantPlacement(700, 100)).toBe("bottom-end");
+    expect(quadrantPlacement(100, 500)).toBe("top-start");
+    expect(quadrantPlacement(700, 500)).toBe("top-end");
+    // On the midlines the lower/right halves win (<=), unchanged.
+    expect(quadrantPlacement(400, 300)).toBe("bottom-start");
+  });
+
+  it("splits the popup viewport when an app-chrome band is configured", () => {
+    window.innerWidth = 800;
+    window.innerHeight = 600;
+    // A 400px title-bar stack: popups live in y 400..600, so the frame
+    // midline is y=500 — a pointer at y=550 (raw-window TOP half) now
+    // grows UP, staying inside the frame's lower half.
+    configurePopupInsets({ top: 400 });
+    expect(quadrantPlacement(500, 550)).toBe("top-end");
+    expect(quadrantPlacement(100, 450)).toBe("bottom-start");
+    expect(quadrantPlacement(700, 450)).toBe("bottom-end");
+  });
+
+  it("honors a side band on the horizontal split", () => {
+    window.innerWidth = 800;
+    window.innerHeight = 600;
+    configurePopupInsets({ left: 600 }); // frame x 600..800, midline 700
+    expect(quadrantPlacement(650, 100)).toBe("bottom-start");
+    expect(quadrantPlacement(750, 100)).toBe("bottom-end");
+  });
+});

package/src/components/HkContextMenuProvider.tsx

@@ -24,6 +24,7 @@
 
 import { computed, defineComponent, provide, ref, shallowRef } from "vue";
 
+import { popupViewportRect } from "../runtime/popupBounds";
 import HkMenu from "./HkMenu";
 import {
   CONTEXT_MENU_KEY,
@@ -33,10 +34,15 @@ import {
 
 /** Pick the HkMenu placement that grows away from the pointer's nearest
  * edges: `bottom-*` when there is more room below, `*-start` when there
- * is more room to the right. */
-function quadrantPlacement(x: number, y: number): "bottom-start" | "bottom-end" | "top-start" | "top-end" {
-  const below = y <= (typeof window !== "undefined" ? window.innerHeight : 0) / 2;
-  const right = x <= (typeof window !== "undefined" ? window.innerWidth : 0) / 2;
+ * is more room to the right. The halves split the POPUP viewport (the
+ * window minus the app-chrome band the host configured — popupBounds),
+ * so a menu opened over a desktop shell's reserved strip grows into the
+ * usable space like every other popup. */
+export function quadrantPlacement(x: number, y: number): "bottom-start" | "bottom-end" | "top-start" | "top-end" {
+  if (typeof window === "undefined") return "bottom-start";
+  const frame = popupViewportRect();
+  const below = y <= frame.y + frame.height / 2;
+  const right = x <= frame.x + frame.width / 2;
   if (below && right) return "bottom-start";
   if (below) return "bottom-end";
   return right ? "top-start" : "top-end";

package/src/components/HkMenu.test.ts

@@ -1,6 +1,7 @@
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, defineComponent, h, nextTick, ref, type ComponentPublicInstance } from "vue";
 
+import { configurePopupInsets } from "../runtime/popupBounds";
 import HkMenu, { type HkMenuItem } from "./HkMenu";
 
 /** Regional-indicator flag pair for an ISO 3166-1 alpha-2 code, built
@@ -186,6 +187,7 @@ afterEach(async () => {
     .querySelectorAll(".hk-select-popout, .hk-select-sheet-panel, .hk-select-sheet-scrim")
     .forEach((el) => el.remove());
   while (containers.length) containers.pop()?.remove();
+  configurePopupInsets(null);
   window.innerWidth = 1024;
 });
 
@@ -1081,3 +1083,45 @@ describe("HkMenu close linger (leave-transition window)", () => {
     expect(popouts().length).toBe(1);
   });
 });
+
+describe("HkMenu cascade against an app-chrome band", () => {
+  it("opens a right-start cascade on the side the band leaves room for", async () => {
+    // An 850px right-docked band on a 1200px window leaves the popup
+    // frame 0..350. The anchor's right edge sits at 130: the RAW window
+    // would host the 224px cascade beside it (130 + 6 + 224 = 360 ≤
+    // 1184), but the frame's gutter line is 350 - 16 = 334 — so the
+    // cascade flips to the anchor's left, pinned at the frame's leading
+    // gutter instead of the window's.
+    const rect = (x: number, y: number, w: number, h: number): DOMRect =>
+      ({ x, y, width: w, height: h, top: y, left: x, right: x + w, bottom: y + h, toJSON: () => ({}) }) as DOMRect;
+
+    window.innerWidth = 1200;
+    const openRef = ref(false);
+    const first = mountMenu(openRef, items, {}, { props: { placement: "right-start" } });
+    vi.spyOn(first.anchor, "getBoundingClientRect").mockReturnValue(rect(50, 100, 80, 40));
+    openRef.value = true;
+    await settle();
+    expect(popoutHosts()[0].style.left).toBe("136px"); // r.right + gap
+    first.unmount();
+
+    configurePopupInsets({ right: 850 });
+    const openRef2 = ref(false);
+    const second = mountMenu(openRef2, items, {}, { props: { placement: "right-start" } });
+    vi.spyOn(second.anchor, "getBoundingClientRect").mockReturnValue(rect(50, 100, 80, 40));
+    openRef2.value = true;
+    await settle();
+    expect(popoutHosts()[0]?.style.left).toBe("16px"); // frame.x + gutter
+    second.unmount();
+
+    // A LEFT band pins the flipped cascade at the frame's leading edge —
+    // max(frame.x + pad, …), not max(pad, …): a swapped origin would land
+    // this at 820 (16 would fail the frame's own leading gutter).
+    configurePopupInsets({ left: 1000 });
+    const openRef3 = ref(false);
+    const third = mountMenu(openRef3, items, {}, { props: { placement: "right-start" } });
+    vi.spyOn(third.anchor, "getBoundingClientRect").mockReturnValue(rect(1050, 100, 80, 40));
+    openRef3.value = true;
+    await settle();
+    expect(popoutHosts()[0]?.style.left).toBe("1016px"); // frame.x + gutter
+  });
+});

package/src/components/HkMenu.tsx

@@ -14,6 +14,7 @@ import { Check, ChevronRight } from "lucide-vue-next";
 
 import { useBreakpoint } from "../runtime/useBreakpoint";
 import { ancestorZoom } from "../runtime/cssZoom";
+import { popupViewportRect } from "../runtime/popupBounds";
 import { viewportGutterPx } from "../runtime/viewportGutter";
 import HkSelectPanel, { type SelectPanelPlacement } from "./HkSelectPanel";
 import "./HkMenu.scss";
@@ -426,8 +427,9 @@ export default defineComponent({
             const cascadeW = CASCADE_PANEL_W * ancestorZoom(document.body);
             // Shared viewport gutter (--viewport-gutter: 8 mobile / 16 desktop).
             const pad = viewportGutterPx();
-            const openRight = r.right + cascadeW <= window.innerWidth - pad;
-            const left = openRight ? r.right : Math.max(pad, r.left - cascadeW);
+            const frame = popupViewportRect();
+            const openRight = r.right + cascadeW <= frame.x + frame.width - pad;
+            const left = openRight ? r.right : Math.max(frame.x + pad, r.left - cascadeW);
             return pointRect(left, r.top);
           },
           contains: (node) => !!rowRefs.value[id]?.contains(node),
@@ -451,11 +453,12 @@ export default defineComponent({
           const cascadeW = CASCADE_PANEL_W * ancestorZoom(document.body);
           // Shared viewport gutter (--viewport-gutter: 8 mobile / 16 desktop).
           const pad = viewportGutterPx();
-          const openRight = r.right + gap + cascadeW <= window.innerWidth - pad;
+          const frame = popupViewportRect();
+          const openRight = r.right + gap + cascadeW <= frame.x + frame.width - pad;
           const left =
             side === "right" && openRight
               ? r.right + gap
-              : Math.max(pad, r.left - cascadeW - gap);
+              : Math.max(frame.x + pad, r.left - cascadeW - gap);
           return pointRect(left, r.top);
         },
         contains: (node) => !!props.anchorRef?.contains(node),

package/src/components/HkPopover.rootzoom.test.tsx

@@ -11,6 +11,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, defineComponent, h, nextTick, ref } from "vue";
 
+import { configurePopupInsets } from "../runtime/popupBounds";
 import HkPopover from "./HkPopover";
 
 const mounts: ReturnType<typeof createApp>[] = [];
@@ -64,7 +65,7 @@ async function flushFrames() {
   }
 }
 
-function mountPopover(anchor: HTMLElement, placement: "bottom" | "top-start" = "bottom") {
+function mountPopover(anchor: HTMLElement, placement: "bottom" | "top-start" | "bottom-start" = "bottom") {
   const container = document.createElement("div");
   document.body.appendChild(container);
   containers.push(container);
@@ -152,3 +153,72 @@ describe("HkPopover anchoring under root CSS zoom", () => {
     expect(parseFloat(host.style.left)).toBeCloseTo(20 / 3, 2);
   });
 });
+
+describe("HkPopover anchoring against an app-chrome band", () => {
+  const PREV_HEIGHT = window.innerHeight;
+
+  afterEach(() => {
+    configurePopupInsets(null);
+    window.innerHeight = PREV_HEIGHT;
+  });
+
+  it("clamps the panel inside the band's frame, not the raw window", async () => {
+    // The band reserves the BOTTOM 700px of the window — the popup frame
+    // is the top 100px strip. The anchor sits inside the band's territory
+    // (y=700): both sides are starved inside the frame, the flip picks
+    // top (more room), and the main-axis clamp pins the panel bottom at
+    // the FRAME's lower gutter (y=84) instead of the window's.
+    window.innerWidth = 1200;
+    window.innerHeight = 800;
+    patchRootZoom("1");
+
+    // Control, no band: the same anchor clamps against the WINDOW bottom
+    // edge — panel bottom 104px above it.
+    const anchor = document.createElement("button");
+    patchRects(anchor, rect(100, 700, 80, 32), rect(0, 0, 200, 60));
+    const open = mountPopover(anchor, "bottom");
+    open.value = true;
+    await flushFrames();
+    const panels = document.body.querySelectorAll<HTMLElement>(".hk-popover-panel");
+    const host = panels[panels.length - 1]!.parentElement!;
+    expect(host.style.bottom).toBe("104px");
+    open.value = false;
+    await flushFrames();
+
+    configurePopupInsets({ bottom: 700 });
+    const anchor2 = document.createElement("button");
+    patchRects(anchor2, rect(100, 700, 80, 32), rect(0, 0, 200, 60));
+    const open2 = mountPopover(anchor2, "bottom");
+    open2.value = true;
+    await flushFrames();
+    // happy-dom never fires transitionend, so the control panel may
+    // linger — the freshly positioned one is the LAST in the body.
+    const panels2 = document.body.querySelectorAll<HTMLElement>(".hk-popover-panel");
+    const host2 = panels2[panels2.length - 1]!.parentElement!;
+    // Panel bottom pinned at frame.y + frame.height - gutter = 100 - 16,
+    // written as the viewport-bottom distance 800 - 84 = 716.
+    expect(host2.style.bottom).toBe("716px");
+    // Cross axis stays HORIZONTAL: centered at 40, inside the frame's
+    // x-gutter as-is (an axis-swapped frame would pin it to 16).
+    expect(host2.style.left).toBe("40px");
+  });
+
+  it("keeps the no-band cross clamp on the horizontal axis of a landscape window", async () => {
+    // Regression pin for the cross-axis frame mapping: on a non-square
+    // window the cross clamp of a vertically-stacked panel must measure
+    // against the WIDTH (1440), not the height (900) — the swapped
+    // mapping clamped this start-aligned panel to 634px.
+    window.innerWidth = 1440;
+    window.innerHeight = 900;
+    patchRootZoom("1");
+    const anchor = document.createElement("button");
+    patchRects(anchor, rect(1300, 500, 40, 40), rect(0, 0, 250, 90));
+    const open = mountPopover(anchor, "bottom-start");
+    open.value = true;
+    await flushFrames();
+    const panels = document.body.querySelectorAll<HTMLElement>(".hk-popover-panel");
+    const host = panels[panels.length - 1]!.parentElement!;
+    expect(host.style.left).toBe("1174px"); // 1440 - 250 - 16
+    expect(host.style.top).toBe("544px"); // anchor bottom 540 + offset 4
+  });
+});

package/src/components/HkPopover.tsx

@@ -15,6 +15,7 @@ import {
 import { usePopupManager, type PopupHandle } from "../runtime/usePopupManager";
 import { useBreakpoint } from "../runtime/useBreakpoint";
 import { ancestorZoom } from "../runtime/cssZoom";
+import { popupViewportRect } from "../runtime/popupBounds";
 import { clampWithGutter, viewportGutterPx } from "../runtime/viewportGutter";
 import { useI18n } from "../i18n/context";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
@@ -342,6 +343,12 @@ export default defineComponent({
       }
       const vw = window.innerWidth;
       const vh = window.innerHeight;
+      // The popup viewport: the window minus the app-chrome band the host
+      // configured (popupBounds) — full-window when none, in which case
+      // every space check and clamp below is the raw-window math. vw/vh
+      // stay for the CSS-coordinate writes (`bottom`/`right` are measured
+      // from the VIEWPORT edges regardless of the band).
+      const frame = popupViewportRect();
       // The shared viewport gutter (--viewport-gutter: 8px mobile / 16px
       // desktop) — read per reposition so a viewport crossing the
       // breakpoint re-clamps with the right value on the next pass.
@@ -352,26 +359,26 @@ export default defineComponent({
 
       if (props.autoFlip) {
         if (side === "bottom") {
-          const spaceBelow = vh - anchorRect.bottom;
-          const spaceAbove = anchorRect.top;
+          const spaceBelow = frame.y + frame.height - anchorRect.bottom;
+          const spaceAbove = anchorRect.top - frame.y;
           if (spaceBelow < panelRect.height + pad && spaceAbove > spaceBelow) {
             side = "top";
           }
         } else if (side === "top") {
-          const spaceAbove = anchorRect.top;
-          const spaceBelow = vh - anchorRect.bottom;
+          const spaceAbove = anchorRect.top - frame.y;
+          const spaceBelow = frame.y + frame.height - anchorRect.bottom;
           if (spaceAbove < panelRect.height + pad && spaceBelow > spaceAbove) {
             side = "bottom";
           }
         } else if (side === "right") {
-          const spaceRight = vw - anchorRect.right;
-          const spaceLeft = anchorRect.left;
+          const spaceRight = frame.x + frame.width - anchorRect.right;
+          const spaceLeft = anchorRect.left - frame.x;
           if (spaceRight < panelRect.width + pad && spaceLeft > spaceRight) {
             side = "left";
           }
         } else if (side === "left") {
-          const spaceLeft = anchorRect.left;
-          const spaceRight = vw - anchorRect.right;
+          const spaceLeft = anchorRect.left - frame.x;
+          const spaceRight = frame.x + frame.width - anchorRect.right;
           if (spaceLeft < panelRect.width + pad && spaceRight > spaceLeft) {
             side = "right";
           }
@@ -387,7 +394,8 @@ export default defineComponent({
       const anchorStart = isVertical ? anchorRect.left : anchorRect.top;
       const anchorEnd = isVertical ? anchorRect.right : anchorRect.bottom;
       const anchorSize = isVertical ? anchorRect.width : anchorRect.height;
-      const viewportSize = isVertical ? vw : vh;
+      const frameSize = isVertical ? frame.width : frame.height;
+      const frameOrigin = isVertical ? frame.x : frame.y;
 
       let crossPos: number;
       if (align === "start") {
@@ -397,7 +405,10 @@ export default defineComponent({
       } else {
         crossPos = anchorStart + (anchorSize - panelSize) / 2;
       }
-      crossPos = clampWithGutter(crossPos, panelSize, viewportSize, pad);
+      // Clamps run against the popup viewport, frame-relative and re-based
+      // onto the frame origin — with no band configured the origin is 0
+      // and every clamp is the plain viewport-gutter clamp.
+      crossPos = clampWithGutter(crossPos - frameOrigin, panelSize, frameSize, pad) + frameOrigin;
 
       if (side === "bottom") {
         c.top = anchorRect.bottom + off;
@@ -414,13 +425,21 @@ export default defineComponent({
       }
 
       if (side === "bottom") {
-        c.top = clampWithGutter(c.top!, panelRect.height, vh, pad);
+        c.top = clampWithGutter(c.top! - frame.y, panelRect.height, frame.height, pad) + frame.y;
       } else if (side === "top") {
-        c.bottom = clampWithGutter(c.bottom ?? 0, panelRect.height, vh, pad);
+        // `bottom` counts from the viewport's bottom edge — shift it into
+        // frame-relative space (0 when no band is configured) and back.
+        const fromFrameBottom = vh - (frame.y + frame.height);
+        c.bottom =
+          clampWithGutter((c.bottom ?? 0) - fromFrameBottom, panelRect.height, frame.height, pad) +
+          fromFrameBottom;
       } else if (side === "right") {
-        c.left = clampWithGutter(c.left!, panelRect.width, vw, pad);
+        c.left = clampWithGutter(c.left! - frame.x, panelRect.width, frame.width, pad) + frame.x;
       } else {
-        c.right = clampWithGutter(c.right ?? 0, panelRect.width, vw, pad);
+        const fromFrameRight = vw - (frame.x + frame.width);
+        c.right =
+          clampWithGutter((c.right ?? 0) - fromFrameRight, panelRect.width, frame.width, pad) +
+          fromFrameRight;
       }
 
       coords.value = c;

package/src/components/HkSelectPanel.rootzoom.test.tsx

@@ -11,6 +11,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, defineComponent, h, nextTick, ref } from "vue";
 import type { ComponentPublicInstance } from "vue";
 
+import { configurePopupInsets } from "../runtime/popupBounds";
 import HkSelectPanel from "./HkSelectPanel";
 
 const mounts: ReturnType<typeof createApp>[] = [];
@@ -123,3 +124,34 @@ describe("HkSelectPanel popout under root CSS zoom", () => {
     expect(host.style.left).toBe("100px");
   });
 });
+
+describe("HkSelectPanel popout against an app-chrome band", () => {
+  const PREV_HEIGHT = window.innerHeight;
+
+  afterEach(() => {
+    configurePopupInsets(null);
+    window.innerHeight = PREV_HEIGHT;
+  });
+
+  it("flips a top-placed panel below its anchor when the band eats the space", async () => {
+    // A 260px band (a docked header stack) leaves frame 260..800. The
+    // anchor at y=300 with a top placement: the RAW-viewport top space
+    // (300 - 16) holds the 200px panel — the pre-bounds math pinned it
+    // at top 96, across the band. Inside the frame only 300 - 260 - 16 =
+    // 24 remains → flip below; the clamp keeps the flipped panel inside
+    // the frame (344 + 200 = 544 ≤ 800 - 16).
+    window.innerWidth = 1200;
+    window.innerHeight = 800;
+    patchRootZoom("1");
+    configurePopupInsets({ top: 260 });
+    const { button } = mountPanel();
+    vi.spyOn(button, "getBoundingClientRect").mockReturnValue(rect(200, 300, 100, 40));
+
+    button.click();
+    await flush();
+
+    const host = document.body.querySelector<HTMLElement>(".hk-select-popout-host")!;
+    expect(host.style.top).toBe("344px"); // anchor bottom 340 + offset 4
+    expect(host.style.left).toBe("200px"); // start, inside the frame as-is
+  });
+});

package/src/components/HkSelectPanel.tsx

@@ -14,6 +14,7 @@ import { useOverlay } from "../runtime/useOverlay";
 import { useBreakpoint } from "../runtime/useBreakpoint";
 import { createBackGuard } from "../runtime/backStack";
 import { ancestorZoom } from "../runtime/cssZoom";
+import { popupViewportRect } from "../runtime/popupBounds";
 import { clampWithGutter, viewportGutterPx } from "../runtime/viewportGutter";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { useSurfaceTransition } from "../composables/useSurfaceTransition";
@@ -547,16 +548,20 @@ export default defineComponent({
       // The shared viewport gutter (--viewport-gutter: 8px mobile / 16px
       // desktop), read per positioning pass.
       const pad = viewportGutterPx();
+      // The popup viewport: the window minus the app-chrome band the host
+      // configured (popupBounds) — full-window when none, in which case
+      // every flip and clamp below is the raw-window math.
+      const frame = popupViewportRect();
       let side: "top" | "bottom" = props.placement.startsWith("top-") ? "top" : "bottom";
       let top =
         side === "top"
           ? r.top - props.offset - ph
           : r.bottom + props.offset;
       // Auto-flip when the chosen side cannot host the panel.
-      if (side === "bottom" && top + ph > window.innerHeight - pad) {
+      if (side === "bottom" && top + ph > frame.y + frame.height - pad) {
         side = "top";
         top = r.top - props.offset - ph;
-      } else if (side === "top" && top < pad) {
+      } else if (side === "top" && top < frame.y + pad) {
         side = "bottom";
         top = r.bottom + props.offset;
       }
@@ -571,7 +576,7 @@ export default defineComponent({
       // bottom→top into a negative top that was applied verbatim. Clamp so
       // the whole panel stays on-screen; when content exceeds the CSS cap
       // the panel's own internal scroll takes over.
-      top = clampWithGutter(top, ph, window.innerHeight, pad);
+      top = clampWithGutter(top - frame.y, ph, frame.height, pad) + frame.y;
       // -center balances the panel on the anchor's horizontal midpoint
       // (still clamped, so a half-off-screen anchor keeps the panel
       // readable instead of mirroring the overflow to both edges).
@@ -581,7 +586,7 @@ export default defineComponent({
           : props.placement.endsWith("-end")
             ? r.right - pw
             : r.left;
-      const clampedLeft = clampWithGutter(left, pw, window.innerWidth, pad);
+      const clampedLeft = clampWithGutter(left - frame.x, pw, frame.width, pad) + frame.x;
       coords.value = {
         top: `${Math.round(top / z)}px`,
         left: `${Math.round(clampedLeft / z)}px`,

package/src/runtime/index.ts

@@ -19,6 +19,15 @@ export {
   TOOLTIP_GAP_PX,
   type TooltipPlacement,
 } from "./tooltipPosition";
+export {
+  configurePopupInsets,
+  popupInsets,
+  popupViewportRect,
+  POPUP_INSET_VARS,
+  type PopupInsets,
+  type ResolvedPopupInsets,
+  type PopupViewportRect,
+} from "./popupBounds";
 export {
   viewportGutterPx,
   clampWithGutter,

package/src/runtime/popupBounds.test.ts

@@ -0,0 +1,90 @@
+// Contract tests for the app-chrome popup bounds context.
+//
+// AI disclosure: drafted by GLM via the ZCode agent, directed and
+// reviewed by langyo — SySL-1.0 §2.3.
+import { afterEach, describe, expect, it } from "vitest";
+
+import { readHkRuntime, writeHkRuntime } from "./registry";
+import {
+  configurePopupInsets,
+  popupInsets,
+  popupViewportRect,
+  POPUP_INSET_VARS,
+} from "./popupBounds";
+
+const PREV_INNER = { width: window.innerWidth, height: window.innerHeight };
+
+afterEach(() => {
+  configurePopupInsets(null);
+  window.innerWidth = PREV_INNER.width;
+  window.innerHeight = PREV_INNER.height;
+});
+
+describe("popupBounds", () => {
+  it("defaults to a zero band and the full-window frame", () => {
+    window.innerWidth = 1280;
+    window.innerHeight = 800;
+    expect(popupInsets()).toEqual({ top: 0, right: 0, bottom: 0, left: 0 });
+    expect(popupViewportRect()).toEqual({ x: 0, y: 0, width: 1280, height: 800 });
+  });
+
+  it("shrinks the popup frame by the configured band", () => {
+    window.innerWidth = 1280;
+    window.innerHeight = 800;
+    configurePopupInsets({ top: 32, left: 48 });
+    expect(popupViewportRect()).toEqual({ x: 48, y: 32, width: 1232, height: 768 });
+  });
+
+  it("replaces the whole band on re-configure and clears on null", () => {
+    window.innerWidth = 1280;
+    window.innerHeight = 800;
+    configurePopupInsets({ top: 32, bottom: 10 });
+    configurePopupInsets({ left: 64 });
+    expect(popupInsets()).toEqual({ top: 0, right: 0, bottom: 0, left: 64 });
+    expect(popupViewportRect()).toEqual({ x: 64, y: 0, width: 1216, height: 800 });
+    configurePopupInsets(null);
+    expect(popupViewportRect()).toEqual({ x: 0, y: 0, width: 1280, height: 800 });
+  });
+
+  it("sanitizes non-finite and non-positive sides to 0", () => {
+    configurePopupInsets({ top: Number.NaN, right: -5, bottom: 12, left: 0 });
+    expect(popupInsets()).toEqual({ top: 0, right: 0, bottom: 12, left: 0 });
+  });
+
+  it("mirrors the band onto :root variables, zeroes included", () => {
+    configurePopupInsets({ top: 32 });
+    expect(document.documentElement.style.getPropertyValue(POPUP_INSET_VARS.top)).toBe("32px");
+    expect(document.documentElement.style.getPropertyValue(POPUP_INSET_VARS.left)).toBe("0px");
+    // Re-configure rewrites every side, so a dropped side cannot keep a
+    // stale larger value.
+    configurePopupInsets({ left: 64 });
+    expect(document.documentElement.style.getPropertyValue(POPUP_INSET_VARS.top)).toBe("0px");
+    expect(document.documentElement.style.getPropertyValue(POPUP_INSET_VARS.left)).toBe("64px");
+  });
+
+  it("collapses the frame when the band overruns the window", () => {
+    window.innerWidth = 800;
+    window.innerHeight = 600;
+    configurePopupInsets({ top: 500, bottom: 500 });
+    expect(popupViewportRect()).toEqual({ x: 0, y: 500, width: 800, height: 0 });
+    configurePopupInsets({ left: 900 });
+    expect(popupViewportRect()).toEqual({ x: 800, y: 0, width: 0, height: 600 });
+  });
+
+  it("reports its live band and frame to the runtime registry", () => {
+    window.innerWidth = 1280;
+    window.innerHeight = 800;
+    configurePopupInsets({ top: 32 });
+    expect(readHkRuntime("popupBounds")).toEqual({
+      insets: { top: 32, right: 0, bottom: 0, left: 0 },
+      viewport: { x: 0, y: 32, width: 1280, height: 768 },
+    });
+    // The write facet rides the same registry entry — exercise it through
+    // writeHkRuntime so the op contract stays honest.
+    expect(writeHkRuntime("popupBounds", { type: "configure", insets: { top: 8 } })).toBe(true);
+    expect(readHkRuntime("popupBounds")).toMatchObject({
+      insets: { top: 8, right: 0, bottom: 0, left: 0 },
+    });
+    expect(writeHkRuntime("popupBounds", { type: "nonsense" })).toBe(false);
+  });
+});

package/src/runtime/popupBounds.ts

@@ -0,0 +1,146 @@
+// App-chrome popup bounds — the developer-facing inset that shrinks the
+// region every JS-positioned popup may occupy.
+//
+// A desktop shell routinely reserves part of the window for chrome a
+// popup must never cover. The report that motivated this module: a
+// frameless Tauri app draws its own title bar and anchors tooltips on
+// the first row beneath it — every positioner here measured against the
+// raw window plus the gutter alone, so those tooltips pinned up over the
+// caption strip. The host declares the occupied band ONCE and every
+// positioner (both tooltip surfaces, HkPopover, HkSelectPanel / HkMenu
+// cascades, the context-menu quadrant pick) centers, flips and clamps
+// inside the remainder. The configuration is per JS realm — a Tauri
+// tray or overlay window is its own realm and simply configures nothing.
+//
+// The pattern is the one --viewport-gutter established: one magnitude
+// shared by declarative consumers and the JS math. configurePopupInsets
+// mirrors the four numbers onto :root as
+// `--hk-popup-inset-{top,right,bottom,left}` (the useSafeArea variable
+// convention), and popupViewportRect() is the JS side of the same
+// contract — the window rect inset by the band. Values are root visual
+// px (measure chrome with getBoundingClientRect), deliberately NOT
+// zoom-corrected — same story as the gutter.
+//
+// This is developer configuration, not user theming: the shell sets it
+// at bootstrap from its real layout and re-sets it when that layout
+// changes (maximize, a phone-layout bar raising). null clears the band.
+// Scope: the JS-positioned floating surfaces honor the band today
+// (tooltips, popovers, select/menu popouts, context-menu quadrants);
+// CSS-positioned overlays (modals, drawers, bottom sheets) do not yet —
+// a bottom band will underlap them until they read the mirrored vars.
+//
+// AI disclosure: drafted by GLM via the ZCode agent, directed and
+// reviewed by langyo — SySL-1.0 §2.3.
+import { reportHkRuntime } from "./registry";
+
+/** The app-chrome band: how much of the window each side reserves. */
+export interface PopupInsets {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
+
+/** The band with every side resolved (unset sides are 0). */
+export interface ResolvedPopupInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/** The :root variables the insets mirror onto (useSafeArea convention). */
+export const POPUP_INSET_VARS: Record<keyof ResolvedPopupInsets, string> = {
+  top: "--hk-popup-inset-top",
+  right: "--hk-popup-inset-right",
+  bottom: "--hk-popup-inset-bottom",
+  left: "--hk-popup-inset-left",
+};
+
+/** The region popups may occupy, in root visual px. */
+export interface PopupViewportRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+let current: Readonly<ResolvedPopupInsets> = { top: 0, right: 0, bottom: 0, left: 0 };
+let runtimeReport: ReturnType<typeof reportHkRuntime> | null = null;
+
+function sanitize(value: number | undefined): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function reportOnce(): void {
+  if (runtimeReport) return;
+  runtimeReport = reportHkRuntime("popupBounds", {
+    kind: "context",
+    description:
+      "App-chrome popup bounds — the inset band every popup positions inside",
+    read: () => ({ insets: { ...current }, viewport: popupViewportRect() }),
+    write: (op) => {
+      if (op.type === "configure") {
+        configurePopupInsets((op.insets as PopupInsets | null) ?? null);
+        return;
+      }
+      throw new Error(`unknown popupBounds write op: ${op.type}`);
+    },
+  });
+}
+
+/**
+ * Declare the app-chrome band popups must stay out of, in root visual px
+ * (measure the chrome with getBoundingClientRect). Re-callable — the new
+ * insets REPLACE the old ones wholesale, so a shell re-declares on every
+ * layout change; null clears the band. Non-finite and non-positive sides
+ * sanitize to 0, so a mis-measured bar degrades to "no band on that
+ * side" instead of corrupting the frame.
+ */
+export function configurePopupInsets(insets: PopupInsets | null): void {
+  current = Object.freeze(
+    insets
+      ? {
+          top: sanitize(insets.top),
+          right: sanitize(insets.right),
+          bottom: sanitize(insets.bottom),
+          left: sanitize(insets.left),
+        }
+      : { top: 0, right: 0, bottom: 0, left: 0 },
+  );
+  if (typeof document !== "undefined") {
+    const rootStyle = document.documentElement.style;
+    for (const side of Object.keys(POPUP_INSET_VARS) as Array<keyof ResolvedPopupInsets>) {
+      // Zeroes are WRITTEN, not removed, so re-configuring can never
+      // leave a stale larger value on a side the new band dropped.
+      rootStyle.setProperty(POPUP_INSET_VARS[side], `${current[side]}px`);
+    }
+  }
+  reportOnce();
+  runtimeReport?.pulse();
+}
+
+/** The currently configured band — zeros when nothing was configured. */
+export function popupInsets(): Readonly<ResolvedPopupInsets> {
+  return current;
+}
+
+/**
+ * The region popups may occupy: the window inset by the configured band.
+ * Width and height floor at 0 — an over-wide band collapses the frame,
+ * and every clamp then pins to its leading edge, the honest answer to
+ * an impossible configuration.
+ */
+export function popupViewportRect(win?: Window | null): PopupViewportRect {
+  reportOnce();
+  if (typeof window === "undefined") return { x: 0, y: 0, width: 0, height: 0 };
+  const w = win ?? window;
+  const x = Math.min(current.left, w.innerWidth);
+  const y = Math.min(current.top, w.innerHeight);
+  return {
+    x,
+    y,
+    width: Math.max(0, w.innerWidth - x - Math.min(current.right, w.innerWidth - x)),
+    height: Math.max(0, w.innerHeight - y - Math.min(current.bottom, w.innerHeight - y)),
+  };
+}

package/src/runtime/tooltipPosition.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 
+import { configurePopupInsets } from "./popupBounds";
 import {
   TOOLTIP_GAP_PX,
   applyTooltipPosition,
@@ -38,6 +39,7 @@ function probePopup(rects: DOMRect[]): HTMLElement {
 const PREV_INNER = { width: window.innerWidth, height: window.innerHeight };
 
 afterEach(() => {
+  configurePopupInsets(null);
   window.innerWidth = PREV_INNER.width;
   window.innerHeight = PREV_INNER.height;
   vi.restoreAllMocks();
@@ -227,26 +229,118 @@ describe("applyTooltipPosition viewport clamping", () => {
 });
 
 describe("resolveTooltipFlip", () => {
-  const vw = 375;
-  const vh = 667;
+  const frame = { x: 0, y: 0, width: 375, height: 667 };
   const gutter = 8;
 
   it("keeps the placement when the preferred side fits", () => {
     const trigger = box(100, 100, 40, 40);
-    expect(resolveTooltipFlip(trigger, "top", { width: 200, height: 32 }, vw, vh, gutter)).toBe("top");
+    expect(resolveTooltipFlip(trigger, "top", { width: 200, height: 32 }, frame, gutter)).toBe("top");
   });
 
   it("flips to the opposite side when it has more room", () => {
     const trigger = box(100, 2, 40, 18);
-    expect(resolveTooltipFlip(trigger, "top", { width: 200, height: 32 }, vw, vh, gutter)).toBe("bottom");
+    expect(resolveTooltipFlip(trigger, "top", { width: 200, height: 32 }, frame, gutter)).toBe("bottom");
     const floorTrigger = box(100, 640, 40, 20);
-    expect(resolveTooltipFlip(floorTrigger, "bottom", { width: 200, height: 32 }, vw, vh, gutter)).toBe("top");
+    expect(resolveTooltipFlip(floorTrigger, "bottom", { width: 200, height: 32 }, frame, gutter)).toBe("top");
   });
 
   it("keeps the placement when the opposite side is no better (the clamp handles it)", () => {
     // Both sides starved, opposite NOT strictly larger → keep the author's
     // placement; the gutter clamp pins the popup on-screen.
     const trigger = box(100, 2, 40, 663); // spaceAbove -6, spaceBelow -6
-    expect(resolveTooltipFlip(trigger, "top", { width: 200, height: 400 }, vw, vh, gutter)).toBe("top");
+    expect(resolveTooltipFlip(trigger, "top", { width: 200, height: 400 }, frame, gutter)).toBe("top");
+  });
+});
+
+describe("resolveTooltipFlip against an app-chrome band", () => {
+  // A 40px desktop title bar configured as the popup bounds.
+  const frame = { x: 0, y: 40, width: 375, height: 627 };
+  const gutter = 8;
+
+  it("flips down when the popup would cross the band but fits the raw viewport above", () => {
+    // Trigger top 84: the RAW-viewport top space (84 - 8 = 76) would hold
+    // a 32px popup, but inside the frame only 84 - 40 - 8 = 36 remains —
+    // the caption strip wins, the tooltip pops below the trigger.
+    const trigger = box(100, 84, 40, 18);
+    expect(resolveTooltipFlip(trigger, "top", { width: 200, height: 32 }, frame, gutter)).toBe("bottom");
+  });
+
+  it("keeps top when the space below the band edge still holds the popup", () => {
+    const trigger = box(100, 300, 40, 40);
+    expect(resolveTooltipFlip(trigger, "top", { width: 200, height: 32 }, frame, gutter)).toBe("top");
+  });
+
+  it("measures the horizontal sides against the band, not the window", () => {
+    const docked = { x: 200, y: 0, width: 175, height: 667 };
+    const trigger = box(210, 300, 40, 40);
+    // Right space inside the frame 117 < 120 + 8 → checks the left
+    // alternate (2), which is not larger → keeps the author's side.
+    expect(resolveTooltipFlip(trigger, "right", { width: 120, height: 32 }, docked, gutter)).toBe("right");
+  });
+});
+
+describe("applyTooltipPosition against an app-chrome band", () => {
+  it("pops a first-row tooltip down instead of over the configured band", () => {
+    window.innerWidth = 375;
+    window.innerHeight = 667;
+    configurePopupInsets({ top: 40 });
+    // Raw-viewport top space is 84 - 8 = 76 ≥ 40 — the pre-bounds math
+    // kept this popup UP (visual box 44..76, across the 40px band); the
+    // band-aware flip sends it below the trigger instead.
+    const trigger = box(100, 84, 40, 18);
+    // Measures: the base-top box, then the flipped-bottom box the real
+    // DOM would report after the base rewrite.
+    const popup = probePopup([box(120, 44, 200, 32), box(120, 110, 200, 32)]);
+    applyTooltipPosition(popup, trigger, "top");
+    expect(popup.style.transform).toBe("translate(-50%, 0)");
+    expect(popup.style.top).toBe("110px"); // rect.bottom + 8
+    expect(popup.style.left).toBe("120px"); // hcenter, unshifted
+  });
+
+  it("lands inside the band under root zoom (band + zoom combined)", () => {
+    // chest's root-level DPI zoom AND a title-bar band together: style
+    // px are local (divided by zoom 2), the band and the viewport are
+    // visual — the flip must clear the band in VISUAL space and the
+    // shift must be divided back to local.
+    window.innerWidth = 1200;
+    window.innerHeight = 800;
+    configurePopupInsets({ top: 32 });
+    const original = window.getComputedStyle.bind(window);
+    vi.spyOn(window, "getComputedStyle").mockImplementation(((el: Element) => {
+      const decl = original(el);
+      return new Proxy(decl, {
+        get(target, prop, recv) {
+          if (prop === "zoom") return el === document.documentElement ? "2" : undefined;
+          const v = Reflect.get(target, prop, recv);
+          return typeof v === "function" ? (v as (...a: unknown[]) => unknown).bind(target) : v;
+        },
+      });
+    }) as typeof window.getComputedStyle);
+    // Trigger top 100: frame space above is 100 - 32 - 8 = 60 < 48 + 16
+    // → flip below. Base-top visual box 136..184 crosses the band; the
+    // flipped-bottom box sits at 296..344, already inside the frame.
+    const trigger = box(600, 100, 40, 40);
+    const popup = probePopup([box(1120, 136, 240, 48), box(1120, 296, 240, 48)]);
+    applyTooltipPosition(popup, trigger, "top");
+    expect(popup.style.transform).toBe("translate(-50%, 0)");
+    expect(popup.style.top).toBe("74px"); // (140 + 8) visual, written /2
+    // Center 620 visual, written 310 local; visual box 1120..1360
+    // overruns the 1200-16 gutter by 176 visual → 88 local off:
+    // 310 - 88 = 222.
+    expect(popup.style.left).toBe("222px");
+  });
+
+  it("shifts a centered bubble inside the band's side gutter", () => {
+    window.innerWidth = 375;
+    window.innerHeight = 667;
+    configurePopupInsets({ left: 200 });
+    // A docked 200px sidebar: the centered 120px bubble spans 170..290,
+    // 38px into the band — the shift re-bases onto the frame origin and
+    // pins it at the frame's leading gutter (208).
+    const trigger = box(210, 300, 40, 40);
+    const popup = probePopup([box(170, 348, 120, 32)]);
+    applyTooltipPosition(popup, trigger, "bottom");
+    expect(popup.style.left).toBe("268px");
+    expect(popup.style.top).toBe("348px");
   });
 });

package/src/runtime/tooltipPosition.ts

@@ -4,6 +4,7 @@
 // positions it through this helper so the two surfaces can never drift.
 import type { CSSProperties } from "vue";
 import { ancestorZoom } from "./cssZoom";
+import { popupViewportRect, type PopupViewportRect } from "./popupBounds";
 import { clampWithGutter, viewportGutterPx } from "./viewportGutter";
 
 export type TooltipPlacement = "top" | "bottom" | "left" | "right";
@@ -70,22 +71,22 @@ export function tooltipPositionStyle(
   return style;
 }
 
-/** Space left on each side of the trigger rect, minus the trigger gap. */
+/** Space left on the given side of the trigger rect, inside the popup
+ *  viewport, minus the trigger gap. */
 function sideSpace(
   rect: DOMRect,
   side: TooltipPlacement,
-  vw: number,
-  vh: number,
+  frame: PopupViewportRect,
 ): number {
   switch (side) {
     case "top":
-      return rect.top - TOOLTIP_GAP_PX;
+      return rect.top - frame.y - TOOLTIP_GAP_PX;
     case "bottom":
-      return vh - rect.bottom - TOOLTIP_GAP_PX;
+      return frame.y + frame.height - rect.bottom - TOOLTIP_GAP_PX;
     case "left":
-      return rect.left - TOOLTIP_GAP_PX;
+      return rect.left - frame.x - TOOLTIP_GAP_PX;
     case "right":
-      return vw - rect.right - TOOLTIP_GAP_PX;
+      return frame.x + frame.width - rect.right - TOOLTIP_GAP_PX;
   }
 }
 
@@ -105,23 +106,26 @@ function oppositeSide(placement: TooltipPlacement): TooltipPlacement {
 
 /**
  * Flip a top↔bottom / left↔right preference when the requested side
- * cannot hold the measured popup inside the viewport gutter but the
- * opposite side can — same criterion as HkPopover's autoFlip, so the
- * surfaces rule their geometry identically. Returns the placement to use.
+ * cannot hold the measured popup inside the popup viewport's gutter but
+ * the opposite side can — same criterion as HkPopover's autoFlip, so the
+ * surfaces rule their geometry identically. The popup viewport is the
+ * full window minus the app-chrome band the host configured
+ * (popupBounds), so a tooltip anchored on the first row under a custom
+ * title bar flips below its trigger instead of pinning over the strip.
+ * Returns the placement to use.
  */
 export function resolveTooltipFlip(
   rect: DOMRect,
   placement: TooltipPlacement,
   popup: { width: number; height: number },
-  vw: number,
-  vh: number,
+  frame: PopupViewportRect,
   gutter: number,
 ): TooltipPlacement {
-  const preferred = sideSpace(rect, placement, vw, vh);
+  const preferred = sideSpace(rect, placement, frame);
   const need = (placement === "top" || placement === "bottom" ? popup.height : popup.width) + gutter;
   if (preferred >= need) return placement;
   const alternate = oppositeSide(placement);
-  const alternateSpace = sideSpace(rect, alternate, vw, vh);
+  const alternateSpace = sideSpace(rect, alternate, frame);
   return alternateSpace > preferred ? alternate : placement;
 }
 
@@ -156,8 +160,10 @@ export function applyTooltipPosition(
   const box = popup.getBoundingClientRect();
   if (!(box.width > 0 && box.height > 0)) return; // no layout — pure base stands
 
-  const vw = window.innerWidth;
-  const vh = window.innerHeight;
+  // The popup viewport: the window minus the app-chrome band the host
+  // configured (a frameless shell's title bar), full-window when none —
+  // in which case every number below is exactly the raw-window math.
+  const frame = popupViewportRect();
   const gutter = viewportGutterPx();
   const z = ancestorZoom(popup);
 
@@ -171,8 +177,11 @@ export function applyTooltipPosition(
   let capW = "";
   let capH = "";
   let clip = false;
-  const maxW = vw - 2 * gutter;
-  const maxH = vh - 2 * gutter;
+  // Floor at 0: a band so tight the gutters overrun the frame must not
+  // write negative (invalid) inline lengths — the cap degrades to 0 and
+  // collapses the bubble, the honest reading of an impossible frame.
+  const maxW = Math.max(0, frame.width - 2 * gutter);
+  const maxH = Math.max(0, frame.height - 2 * gutter);
   if (box.width > maxW) {
     capW = `${maxW / z}px`;
   }
@@ -194,7 +203,7 @@ export function applyTooltipPosition(
     measured = popup.getBoundingClientRect();
   }
 
-  const side = resolveTooltipFlip(rect, placement, measured, vw, vh, gutter);
+  const side = resolveTooltipFlip(rect, placement, measured, frame, gutter);
   let final = measured;
   if (side !== placement) {
     applyBase(side);
@@ -203,14 +212,20 @@ export function applyTooltipPosition(
   }
 
   // Shift whatever is left over (centered under a near-edge trigger, the
-  // flipped side, a cap) so both edges sit inside the gutter. The delta
-  // is measured in root visual px but the written coordinates are local
-  // (divided by the cumulative zoom) AND offset from the box edge by the
-  // placement transform (translate(-50%) makes style.left the box
-  // CENTER) — so the shift adds onto the current written value instead
-  // of the measured edge.
-  const dx = clampWithGutter(final.left, final.width, vw, gutter) - final.left;
-  const dy = clampWithGutter(final.top, final.height, vh, gutter) - final.top;
+  // flipped side, a cap) so both edges sit inside the gutter — measured
+  // against the popup viewport, so the gutter rides just inside the
+  // app-chrome band rather than inside the raw window edge. The clamp is
+  // computed frame-relative and re-based onto the frame origin (with no
+  // band configured the origin is 0 and this is the plain gutter clamp).
+  // The delta is measured in root visual px but the written coordinates
+  // are local (divided by the cumulative zoom) AND offset from the box
+  // edge by the placement transform (translate(-50%) makes style.left
+  // the box CENTER) — so the shift adds onto the current written value
+  // instead of the measured edge.
+  const dx =
+    clampWithGutter(final.left - frame.x, final.width, frame.width, gutter) - (final.left - frame.x);
+  const dy =
+    clampWithGutter(final.top - frame.y, final.height, frame.height, gutter) - (final.top - frame.y);
   if (dx !== 0 || dy !== 0) {
     const curLeft = Number.parseFloat(popup.style.left) || 0;
     const curTop = Number.parseFloat(popup.style.top) || 0;